Why does Vault integration require VAULT_AUTH_ROLE?

My background

I am relatively new to Vault and therefore may lack some basic understanding about how that tool works; however, it seems like the way GitLab Vault integration (at least the Premium method and possible the Free method as well) works is unnecessarily narrow.

Role-based access control (RBAC)

Vault has the concept of policies and (for JWT) roles. A policy is a specification of a subset of permissions: “The ability to read and write all objects under the path /abc/xyz”. It’s what other RBAC systems tend to call roles. A policy would have a name like “abc_xyz_admin”.

A role is a way of filtering subjects based on their validated JWT tokens and declaring that such-and-such policies apply to them. “All subjects whose email is one of and who kicked off a CI/CD pipeline from a branch called ‘main’ have abc_xyz_admin privileges.” It’s what other RBAC systems tend to call role bindings.

There’s a many-to-many relationship between subjects and roles. A subject can do ghi_admin and also jkl_read. Likewise, many different subjects may all have jkl_read capabilities.


In an RBAC system, I don’t need to tell the server what role I’m being. The server knows who I am, or enough about who I am, and then it goes and looks up what I can do. That’s not my job. I authenticate and then I optimistically try to do something; if I’m not authorized, server says nope.

Instead, the GitLab Vault integration doesn’t seem to work unless I specify what role(s) I’m acting in via VAULT_AUTH_ROLE. If I’m a pipeline and I need to admin abc_def and also read something from jkl, I can’t, unless there’s a binding that specifically enables both of those and I point to it explicitly in my repo config. Almost as if Vault can’t figure it out, so I need to tell it.


Given this surprising constraint of exactly-one-role-binding-per-project, the only way I can think to organize GitLab JWT roles (i.e. role bindings) in Vault is to have a separate one for each repo. If my org has 150 repos, I need to essentially copy-paste the same role 150 times in Vault. Now you might say, “well if they have the same requirements then you can all point to the same one, you don’t have copy them,” I agree, but as soon as a repo needs one tiny little more permission, I need to copy-paste and tweak. In short, roles are not composable.

Here’s another consequence of this non-composability. Suppose I want every repo in my org to have a certain level of cloud access, but I want the main branch for each one to have extra cloud access. I need separate filters with separate lists of policies. I can’t point to both of them!


Am I wrong in thinking the only way to manage JWT roles is to create one per repo?

What am I supposed to do about that last problem I described?

What am I supposed to do in general?

What am I missing?

Curious about your setup of the default role when you created the JWT. This is optional when creating it according to their docs. GitLab’s docs for Vault also say that VAULT_ALT_ROLE is optional, that GitLab will use the default role from the JWT without this variable being set.

No default role was set when the JWT was created (I assume you mean the JWT engine mounted). I just configured the JWT mount with the two properties per the docs for Vault you linked to.

Re: VAULT_AUTH_ROLE, the error I got was something like “role not found” or “role doesn’t exist”, until I set it explicitly.

Maybe all this suggests my problem is with Vault and not specifically with GitLab. Can a subject authenticating against Vault’s JWT engine not have multiple roles?

My understanding is that a subject authenticating against Vault can have access to multiple roles, and I know of people currently doing this for CI/CD. Unfortunately, my Vault instance is pretty basic at the moment, and I don’t have time today to mock this up and test it (but I am VERY interested in what you learn). I found references in Vault’s docs to AppRole, which given users have roles too, implies the functionality you are looking for. When you get a few minutes, this is the section that I found: https://learn.hashicorp.com/tutorials/vault/pattern-approle?in=vault/recommended-patterns#vault-approle-overview

1 Like