Configure OIDC user_claim parameter for user friendly output

Avatar
Gabe Knell
  • Updated

 

Introduction

The user_claim claim is used to uniquely identify the user; this will be used as the name for the Identity entity alias created due to a successful login. The claim value must be a string.

 

Auth Method Configuration

When configuring a role for the OIDC auth method, a required parameter is the user_claim. Depending on the IdP and claims that Vault receives back, this can be set to claims such as sub, email, name, etc. This claim can help easily identify the identity when authenticated into Vault.

 

Looking at the example from the Vault tutorial, the user_claim parameter is set to sub, which is the principal associated to the access token. 
vault write auth/oidc/role/reader \
    bound_audiences="$AUTH0_CLIENT_ID" \
    allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback" \
    allowed_redirect_uris="http://localhost:8250/oidc/callback" \
    user_claim="sub" \
    token_policies="reader"

 

Token Display Name and Identity Name Examples

When setting user_claim to sub the display name for the Vault token is not very user friendly. Below is an example for a token after a successful login to Vault. In these outputs we see the display_name for the token and name for the identity showing the sub claim that was provided by the IdP during the authentication process: 
Vault Token Lookup:
$ vault token lookup hvs.CAESICP0Xa3...

Key                 Value
---                 -----
accessor            tBwF0eB9u4mgBS9DpnPPvPei
creation_time       1692276610
creation_ttl        768h
display_name        oidc-alqOyopjjkhuMcI8l4G6fL7RjdvUskQsebQTBTPuiCI
entity_id           7e2bd7c2-8744-3cf3-cfeb-ddd7c7e3c293
expire_time         2023-09-18T08:50:10.474912-04:00
explicit_max_ttl    0s
id                  hvs.CAESICP0Xa3...
issue_time          2023-08-17T08:50:10.474929-04:00
meta                map[role:default]
num_uses            0
orphan              true
path                auth/oidc/oidc/callback
policies            [admin default]
renewable           true
ttl                 767h56m42s
type                service


Vault Read Identity:
$ vault read identity/entity-alias/id/ca4b3ab4-e784-ef94-a95d-dc7d2193472a

Key                          Value
---                          -----
canonical_id                 7e2bd7c2-8744-3cf3-cfeb-ddd7c7e3c293
creation_time                2023-08-17T12:50:10.15397Z
custom_metadata              <nil>
id                           ca4b3ab4-e784-ef94-a95d-dc7d2193472a
last_update_time             2023-08-17T12:50:10.15397Z
local                        false
merged_from_canonical_ids    <nil>
metadata                     map[]
mount_accessor               auth_oidc_b3e93416
mount_path                   auth/oidc/
mount_type                   oidc
name                         alqOyopjjkhuMcI8l4G6fL7RjdvUskQsebQTBTPuiCI
namespace_id                 root

 

Whereas if we set the user_claim to email, we see a more user friendly name for the identity in Vault. Below is an example when looking up the token and reading the identity. The outputs now have a more user friendly display_name and name on the token and identity: 
Vault Token Lookup:
$ vault token lookup hvs.CAESIIqX1JP...

Key                 Value
---                 -----
accessor            QCQvw9DhjT3XjrOo9SKQi2B1
creation_time       1692276627
creation_ttl        768h
display_name        oidc-gabe@hashicorp.com
entity_id           bc357d73-8a0d-4ee6-fcdf-04fbbcba7959
expire_time         2023-09-18T08:50:27.968721-04:00
explicit_max_ttl    0s
id                  hvs.CAESIIqX1JP...
issue_time          2023-08-17T08:50:27.968729-04:00
meta                map[role:default]
num_uses            0
orphan              true
path                auth/oidc/oidc/callback
policies            [admin default]
renewable           true
ttl                 767h56m51s
type                service


Vault Read Identity:
$ vault read identity/entity-alias/id/1393f17d-1d4c-9ce8-fef0-4f0e5c60b2b2

Key                          Value
---                          -----
canonical_id                 bc357d73-8a0d-4ee6-fcdf-04fbbcba7959
creation_time                2023-08-17T12:50:27.70252Z
custom_metadata              <nil>
id                           1393f17d-1d4c-9ce8-fef0-4f0e5c60b2b2
last_update_time             2023-08-17T12:50:27.70252Z
local                        false
merged_from_canonical_ids    <nil>
metadata                     map[]
mount_accessor               auth_oidc_b3e93416
mount_path                   auth/oidc/
mount_type                   oidc
name                         gabe@hashicorp.com
namespace_id                 root

 

Depending on the configuration on the IdP that Vault is interacting with, different user claims will be sent in the access token. These claims will dictate what values can be set in Vault for user_claim. Some IdPs do not have an email claim by default, and a custom claim may need to be created on the IdP side. Enabling verbose_oidc_logging on the OIDC role could assist configuration as claims sent from the IdP are logged in Vault operational logs.

 

Related Links:

Articles in this section

See more

Related articles