Hashicorp Vault

The Vault backend allows authentication against the OIDC provider in Hashicorp Vault version 1.9 and later.

The backend class is VaultOpenIdConnect with name vault. A minimum configuration is:

SOCIAL_AUTH_VAULT_OIDC_ENDPOINT = 'https://vault.example.net:8200/v1/identity/oidc/provider/default'
SOCIAL_AUTH_VAULT_KEY = '<client_id>'
SOCIAL_AUTH_VAULT_SECRET = '<client_secret>'

The remaining configuration will be auto-detected, by fetching:

<SOCIAL_AUTH_VAULT_OIDC_ENDPOINT>/.well-known/openid-configuration

You may need to set SOCIAL_AUTH_VAULT_VERIFY_SSL = False if your Vault server does not have its certificate signed by a trusted CA (e.g. with LetsEncrypt), although this should only be used for testing and not in production.

Vault OIDC configuration

Vault 1.10 onwards includes a pre-defined provider “default”, key “default” and assignment “allow_all”. With Vault 1.9 you will need to create these objects explicitly.

You can then create an OIDC client, and read it back to get the auto-generated client ID and secret:

vault write identity/oidc/client/my-app \
    redirect_uris="https://www.example.com/callback" \
    assignments="allow_all" \
    key="default" \
    id_token_ttl="30m" \
    access_token_ttl="1h"

vault read identity/oidc/client/my-app

Scopes

Vault is very flexible with regard to configuring claims and scopes, so it’s up to you how you map entity and/or alias metadata to OIDC claims. Here is a suggestion, which exposes the entity name as “preferred_username” and takes the other claims from entity metadata:

vault write identity/oidc/scope/profile \
  description="Provides user info" \
  template='{
    "preferred_username": {{identity.entity.name}},
    "name": {{identity.entity.metadata.name}},
    "given_name": {{identity.entity.metadata.given_name}},
    "family_name": {{identity.entity.metadata.family_name}}
}'

vault write identity/oidc/scope/email \
  description="Provides email address" \
  template='{
    "email": {{identity.entity.metadata.email}}
}'

vault write identity/oidc/scope/groups \
  description="Provides a list of group names" \
  template='{
    "groups": {{identity.entity.groups.names}}
}'

The Vault backend inherits defaults from open_id_connect.py. In particular, it looks for the username in the preferred_username claim. If you need to choose a different claim then you can do so:

SOCIAL_AUTH_VAULT_USERNAME_KEY = 'nickname'

The default set of scopes requested are “openid”, “profile” and “email”. You can request additional claims like this:

SOCIAL_AUTH_VAULT_SCOPE = ['groups']

and you can remove the default scopes using:

SOCIAL_AUTH_VAULT_IGNORE_DEFAULT_SCOPE = True