What's a "role" when logging in using the CLI?


The Vault documentation about integrating OIDC mentions that a user can login on the CLI thus:

vault login -method=oidc role=test

The documentation does not say what the “role” is. Is it an alias? Or something else?

Thanks for your help!

In general, a “role” in Vault is a configuration profile within a secrets engine or auth method - the terminology comes up in many places.

In this case, it’s a “role” in the OIDC auth method, i.e. a configuration profile that has been defined using the JWT/OIDC - Auth Methods - HTTP API | Vault by HashiCorp API.

All right, thanks @maxb . It would be really helpful if the first doc could link to the second doc.

Hi @maxb ,

The documentation you pointed to is incomprehensible to a newbie like myself:

Registers a role in the method. Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login. At least one of the bound values must be set.

Here are some initial questions I would have:

  • What is a “role type”? I searched the whole Vault documentation for “role type”, and nothing came out…
  • Are the “specific entities” the same as what’s described here?
  • Does “endpoint” mean the Vault server itself? Or a path, possibly within a given namespace?
  • What are the “constraints specific to the role type”? I guess it’s not the policy, since the policy applies to a “role”, not a “role type”?..

Alternatively, is there a page dedicated to explaining in depth roles related to auth methods?

Thanks a lot!

That’s fair, sadly a lot of the details of Vault rely on pulling together information from multiple sources to truly build an understanding.

“role type” is simply the value of the role_type parameter on that page - the OIDC/JWT auth method is (rather confusingly) a single auth method with two different names (oidc and jwt). But it doesn’t matter which name you use, as actually there is the role_type parameter on each role, which also takes values oidc and jwt.

Its function is to specify whether the role is intended to be used with an interactive web browser flow (oidc) or code that directly presents an OIDC-style JWT to the Vault API (jwt).

“specific entities” …

Role types have specific entities that can perform login operations against this endpoint.

Yeah, honestly I don’t understand what this sentence is even trying to say.

“endpoint” just means a particular HTTP API within Vault.

The constraints referred to are mostly the various role parameters which start with bound_, which specify that the JWT presented needs to have certain fields set to certain values, or it wil be rejected.

There is no page explaining in depth roles related to auth methods, because “role” just means “configuration profile”, and the details of what kind of configuration profile makes sense, can be different for each auth method. So you have to look to each individual auth method’s documentation for this.

Hi @maxb ,

All right, thanks for these details.

I am a bit confused because this page shows an example of creating a role, and it includes a policies parameter. But that page does not list policies as a parameter for creating a role…

There are two ways of assigning policies to tokens:

  • Directly to the token
  • A token is linked to an identity, the policies are assigned to the identity

In the olden days of Vault, there was only the first.

Since identity policies were added, legacy policies parameters in many APIs have been renamed to token_policies to clarify they’re talking about the first kind (with compatibility support for the old deprecated name.)

All right, thanks @maxb . It would be good to update the documentation, then…

Hi @maxb ,

I can see here that a role requires a user_claim parameter, which must match an alias for the identity the user will assume once the authentication process completes.

Does that mean I have to create one role for each user?

Many thanks for your help!

user_claim is the name of the field within the JWT payload, which contains the username.

So, no, you don’t need 1 role per user, this configuration tells Vault how to identify the user from the particular Identity Provider’s JWT format. Common values for the user_claim field would be sub (short for “subject”) or email (if it can be trusted to be unique, and you want to use email addresses as usernames).