Before a client can interact with Vault, it must authenticate against an auth method to acquire a token. This token has policies attached so that the behavior of the client can be governed.
NOTE: To learn the basics of Vault tokens, go through the Tokens tutorial.
Auth methods perform authentication to verify the user or machine-supplied information. Some of the supported auth methods are targeted towards users while others are targeted toward machines or apps.
»Challenge
Vault supports a number of auth methods for users or system to prove their identity so that a token with appropriate policies can be obtained. Delegated authorization methods based on OAuth 2.0 are convenient for users and have become increasingly common, but the identity semantics are vague and vary between providers.
»Solution
Vault 1.1 introduced its support for OpenID Connect (OIDC). OIDC provides an identity layer on top of OAuth 2.0 to address the shortcomings of using OAuth 2.0 for establishing identity. The OIDC auth method allows a user's browser to be redirected to a configured identity provider, complete login, and then be routed back to Vault's UI with a newly-created Vault token.
This method is familiar for most users. For operators, the types of identity data that can be provided as part of OIDC allow for flexible mapping to Vault's identity system.
»Prerequisites
To perform the tasks described in this tutorial, you need to have a Vault 1.1 or later. Refer to the Getting Started tutorial to install Vault. Make sure that your Vault server has been initialized and unsealed.
»Auth0 Account
To demonstrate an end-to-end workflow, this tutorial uses Auth0, so create an account if you don't have one.
NOTE: If you prefer to try the OIDC auth method using Google OAuth, refer to Vault OpenID Demo. For other provider configuration steps, refer to the OIDC Provider Setup documentation.
»Policy requirements
NOTE: For the purpose of this tutorial, you can use the root
token to
work with Vault. However, it is recommended that root tokens are only used for
just enough initial setup or in emergencies. As a best practice, use tokens with
an appropriate set of policies based on your role in the organization.
To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:
# Mount the OIDC auth method
path "sys/auth/oidc" {
capabilities = [ "create", "read", "update", "delete", "sudo" ]
}
# Configure the OIDC auth method
path "auth/oidc/*" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
# Write ACL policies
path "sys/policies/acl/*" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
# List available secrets engines to retrieve accessor ID
path "sys/mounts" {
capabilities = [ "read" ]
}
If you are not familiar with policies, complete the policies tutorial.
»Start Vault
In another terminal, start a Vault dev server with root
as the root token.
$ vault server -dev -dev-root-token-id root
The Vault dev server defaults to running at 127.0.0.1:8200
. The server is
initialized and unsealed.
Insecure operation: Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and runs in an insecure way.
Export an environment variable for the vault
CLI to address the Vault server.
$ export VAULT_ADDR=http://127.0.0.1:8200
Export an environment variable for the vault
CLI to address the Vault server
through the OIDC interface.
$ export VAULT_OIDC_ADDR=http://127.0.0.1:8250
Export an environment variable for the vault
CLI to authenticate with the
Vault server.
$ export VAULT_TOKEN=root
NOTE: For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use an authentication method or token that meets the policy requirements.
The Vault server is ready.
»Get Auth0 credentials
If you do not have an account with Auth0, sign up to create one first.
In the Auth0 dashboard, select Applications.
Select Default App and Settings.
Copy the Domain.
In a terminal, set the variable
AUTH0_DOMAIN
to the Domain.$ export AUTH0_DOMAIN=<Domain>
Copy the Client ID.
In a terminal, set the variable
AUTH0_CLIENT_ID
to the Client ID.$ export AUTH0_CLIENT_ID=<Client ID>
Copy the Client Secret.
In a terminal, set the variable
AUTH0_CLIENT_SECRET
to the Client Secret.$ export AUTH0_CLIENT_SECRET=<Client Secret>
In the Allowed Callback URLs field, enter the following:
https://localhost:8250/oidc/callback https://localhost:8200/ui/vault/auth/oidc/oidc/callback,
The
https://localhost:8250/oidc/callback
address enables the Vault CLI to login via the OIDC method. Thehttps://localhost:8200/ui/vault/auth/oidc/oidc/callback
address enables the Vault web UI to login via the OIDC method.NOTE: The callback URLs must be comma-separated.
For example, if you are running your Vault server locally:
»Create Vault policies
Within an organization personas with different capabilities are required to interact with the secrets stored in Vault. Each persona requires a different set of capabilities. These are expressed in policies. If you are not familiar with policies, complete the policies tutorial.
Create the policy file named manager.hcl
.
$ tee manager.hcl <<EOF
# Manage k/v secrets
path "/secret/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
EOF
This policy grants almost all capabilities to all paths in KV secrets engine
enabled at the secret
path.
Create the policy file named reader.hcl
.
$ tee reader.hcl <<EOF
# Read permission on the k/v secrets
path "/secret/*" {
capabilities = ["read", "list"]
}
EOF
This policy grants read
and list
capabilities to all paths in the KV
secrets engine enabled at the secret
path.
Create a policy named manager
with the policy defined in manager.hcl
.
$ vault policy write manager manager.hcl
Create a policy named reader
with the policy defined in reader.hcl
.
$ vault policy write reader reader.hcl
List all the policies.
$ vault policy list
default
manager
reader
root
The manager
and reader
policies are present in the list alongside the
policies that Vault automatically creates.
»Enable OIDC auth method
OIDC must be enabled and configured before it can be used.
Enable the oidc
auth method at the default path.
$ vault auth enable oidc
The OIDC auth method is enabled at the path oidc
.
Configure the oidc
auth method.
$ vault write auth/oidc/config \
oidc_discovery_url="https://$AUTH0_DOMAIN/" \
oidc_client_id="$AUTH0_CLIENT_ID" \
oidc_client_secret="$AUTH0_CLIENT_SECRET" \
default_role="reader"
The oidc_discovery_url
, oidc_client_id
, and oidc_client_secret
are set
to the variables defined in the Get Auth0
credentials step.
The default_role
is set to reader
. This is a role defined for the
authentication method that assigns the reader
policy.
Create the reader
role.
$ 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" \
policies="reader"
The allowed_redirect_uris
and allowed_redirect_uris
use the Allowed
Callback URLs defined in the Get Auth0
credentials step. The user_claim
sets the
claim
to use to uniquely identify the user.
»Login with OIDC
Log in with the oidc
method as role of a reader
.
$ vault login -method=oidc role="reader"
When prompted, accept and authorize the Vault access to your Default App.
Expected output looks like:
Complete the login via your OIDC provider. Launching browser to:
https://dev-2i513orw.auth0.com/authorize?client_id=FFXlsY2atr_wfNaF_hMtsE-zTAeTZnu8&nonce=73fe4c11828d3c4eb8c2c270aa1b3ab45ebda490&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid&state=965d81adcfad9d83a29659891cee37358c8d45cc
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.mefxZpkwUzGirhakGtQZoez0
token_accessor oGB9LqtSGxiEWp2zz4DLlIBD
token_duration 768h
token_renewable true
token_policies ["default" "reader"]
identity_policies []
policies ["default" "reader"]
token_meta_role reader
»Unauthorized Redirect URI Error
If you received unauthorized redirect_uri: redirect_uri=http://127.0.0.1:8250/oidc/callback
error, update the oidc
configuration for the reader
role.
Update the reader
role.
$ 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://127.0.0.1:8250/oidc/callback" \
user_claim="sub" \
policies="reader"
The user logs in to Vault through OIDC vith Auth0. The token issued to the user
is assigned through the reader
role which grants it the capabilities defined
in the reader
role.
»Create an Auth0 group
A user that authenticates through OIDC with Auth0 may also have their Vault role assigned through metadata defined in Auth0.
In the Auth0 dashboard, select Users & Roles > Users.
Click on your user name.
Enter the following metatada in the app_metadata.
{ "roles": ["kv-mgr"] }
When this user authenticates, this metadata is provided to Vault in the callback. Vault requests a token from the Vault group named
kv-mgr
.Click SAVE.
From the side navigation, select Rules.
Click CREATE RULE.
Select empty rule.
Enter
Set user role
in the Name field.Enter the following script in the Script field.
function (user, context, callback) { user.app_metadata = user.app_metadata || {}; context.idToken["https://example.com/roles"] = user.app_metadata.roles || []; callback(null, user, context); }
This script ensures that the user has the
app_metadata
field; creating one if none exists. Then assigns to thecontext.idToken
all of the roles defined for the user; or an empty list if none exist.Click SAVE CHANGES.
NOTE: The use of
example.com
is used here for demonstration.For an extended details about creating and managing roles in Auth0, refer to the online documentation.
»Create an external Vault group
A group claim is used to uniquely identify a set of groups to which the user belongs (this will be used as the names for the identity group aliases created after a successful login).
NOTE: If you are unfamiliar with Vault Identity, refer to the Identity: Entities and Groups tutorial.
The Login with OIDC step has you authenticate with the
capabilites of the reader
policy. This token is unable to configure the OIDC
auth method.
Login as the root
user.
$ vault login $VAULT_TOKEN
Create a role named kv-mgr
.
$ vault write auth/oidc/role/kv-mgr \
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" \
policies="reader" \
groups_claim="https://example.com/roles"
This role is defined similarly to the previously created role. The reader
capapbility is assigned to the token. Additional policies are assigned through
any groups that the user claims to belong. The groups_claim
field defines the
value of https://example.com/roles
. This value is the key in the
context.idToken
that stores all the roles defined in the metadata for the
user.
Create an external group, named manager
with the manager
policy.
$ vault write identity/group name="manager" type="external" \
policies="manager" \
metadata=responsibility="Manage K/V Secrets"
Example output:
Key Value
--- -----
id 1713c9c1-42c1-de6a-5d13-44f7c06f113f
name manager
Create a variable named GROUP_ID
to store the id
of the manager
group.
$ GROUP_ID=$(vault write -field=id identity/group name="manager" type="external" \
policies="manager" \
metadata=responsibility="Manage K/V Secrets")
Create a variable named OIDC_AUTH_ACCESSOR
to store the accessor of the
oidc
authentication method.
$ OIDC_AUTH_ACCESSOR=$(vault auth list -format=json | jq -r '."oidc/".accessor')
This displays all authentication methods in JSON and then parses that list,
throught jq
, to extract the accessor
field of the oidc
authentication
method.
Create a group alias named kv-mgr
.
$ vault write identity/group-alias name="kv-mgr" \
mount_accessor="$OIDC_AUTH_ACCESSOR" \
canonical_id="$GROUP_ID"
The kv-mgr
group alias connects the oidc
authentication method and the
manager
group with the manager
policy.
Log in with the oidc
method as role of a kv-mgr
.
$ vault login -method=oidc role="kv-mgr"
Complete the login via your OIDC provider. Launching browser to:
https://dev-2i513orw.auth0.com/authorize?client_id=FFXlsY2atr_wfNaF_hMtsE-zTAeTZnu8&nonce=5ad8af6eab5146d355ab5b25712b0d7776b384f7&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid&state=721184bf8d5abe295a617d1cb98ab75c1a7d39fc
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.WlmlH2yPid7sSKYbBlimD4MD
token_accessor zd4MBqI9HD4YVhIWQKU6tz0b
token_duration 768h
token_renewable true
token_policies ["default" "reader"]
identity_policies ["manager"]
policies ["default" "manager" "reader"]
token_meta_role kv-mgr
The returned token inherits the default
, manager
and reader
policies. The
manager
policy is assigned because the value kv-mgr
, defined in the
metadata, has an alias that belongs to the manager
group. The reader
policy
is assigned to the kv-mgr
role.
»Leveraging Social Accounts
To enable your users login with their Google OAuth or any other social connections, select Connections > Social from the Auth0 dashboard to configure them.
Select your application, and under the Connections tab, you can select which social connection to enable for the particular application.
NOTE: The client ID and client secret are unique to each application that you configured OIDC auth method with.