Skip to main content

Auth Role

An auth role is a configuration entity that defines the authentication behavior and permissions associated with a specific category or group of users. An auth role determines how users authenticate and the level of access they have within Vault.

When setting up authentication in Vault, an administrator creates auth roles to define the authentication method and associated policies for a particular group of users. Each role is typically associated with a specific authentication method, such as username/password or token-based authentication.

Auth roles define various parameters and attributes, such as allowed authentication methods, token TTL (Time To Live), token policies, and token metadata. These parameters determine how users authenticate, the lifespan of the tokens issued to them, and the permissions granted to those tokens.

When a user attempts to authenticate with Vault, they specify the role they belong to along with their authentication credentials. Vault verifies the user's credentials and checks if they belong to the specified role. If the authentication is successful, Vault issues a token with the associated policies and permissions defined in the role.

Auth roles provide a flexible way to manage authentication and access control within Vault. They allow administrators to define different sets of permissions and policies for different user groups, ensuring that users have the appropriate level of access to secrets and resources based on their role.

Setting up Auth Role in Terraform

Gitlab Docs - JWT Claims

The role is required to login with the token. It has the

  • login path (jwt-v2)
  • user_claim
  • Policies
  • Claim Type
  • Bound Claims

login path - the auth method to attatch the role to

User Claim gets the ID of the user off the tokens claim

  • Gitlab -- iss
  • Scalr -- scalr_environment_id

Policies - Set the permissions of the token and what secrets/namespaces they can access

Claim Type - Glob or String, Glob allows a pattern match while String does not and must be exact match

Bound Claims - What the token claims must have and match to authenticate correctly

Glob Path (Gitlab)

Match Pattern on Claim

resource "vault_jwt_auth_backend_role" "demo_gitlab" {
provider = vault
backend = "jwt-v2"
role_name = "demo"
token_policies = [
"default",
vault_policy.demo.name,
]
user_claim = "iss"
role_type = "jwt"
bound_claims_type = "glob"
bound_claims = {
"project_path" = "spakl/platform/*"
}
}

String Path (Scalr)

Match Claim String

resource "vault_jwt_auth_backend_role" "demo_scalr" {
provider = vault
backend = "scalr-jwt"
role_name = "demo"
token_policies = [
"default",
vault_policy.demo.name,
]
token_type = "batch"
user_claim = "scalr_environment_id"
role_type = "jwt"
bound_claims_type = "string"
bound_claims = {
"scalr_environment_id" = "env-v0odsujeln2mlfasd,"
}
}