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