Enable single sign-on (SSO) with SAML authentication

18min
|
Enterprise
Vault

Note

The SAML auth method requires a Vault Enterprise license.

Challenge

Organizations have a wide range of identity sources for both humans and machines. Secure integration and exchange of identity information between systems is a common challenge. Open standards have been created to address this challenge and increase interoperability.

One such standard is Security Assertion Markup Language (SAML). SAML is an XML-based open standard for exchanging identity information between parties.

Many identity providers (IdP) support SAML to offer a single sign-on (SSO) experience for human users.

Solution

Vault Enterprise version 1.15.0 introduces the SAML Auth Method. This auth method enables human users to authenticate with Vault using the identity from a SAML V2.0 compliant Identity Provider.

Personas

The hands-on lab described in this tutorial involves two personas:

alice a security operator with privileged permissions to administer Vault auth methods, secrets engines, ACL policies, and the organization's Okta IdP.
dan a user who needs to authenticate to Vault with their SAML credentials.

Prerequisites

To perform the tasks described in the tutorial hands-on lab, you need the following.

Okta account.
Vault Enterprise binary installed and in your system PATH.
curl installed and in your system PATH for API steps.
jq installed and in your system PATH for API output examples.

Versions used for this tutorial

This tutorial was last tested 21 Sep 2023 on macOS using the following software versions.

Operating System

$ sw_vers --productVersion
13.5.2

Vault

$ vault version
Vault v1.15.0-rc1+ent (d7e7b24dbf5f06fe8b3ba29cfcf4d8f7d961ed45), built 2023-09-11T17:44:31Z

Curl

$ curl --version | head -n 1 | awk '{print $2}'
8.1.2

$ jq --version                                                          
jq-1.7

Scenario introduction

Diagram for scenario introduction

Alice is the Vault administrator for a fitness app startup who needs to onboard a development team (Aqua Team)to Vault so that this team can access relevant project secrets.
Vault is used to store several of Aqua Team's secrets. For example, one such secret kept in Vault is an API token for a dashboard service. Dan is a member of Aqua Team, and needs access to this API token throughout the duration of the project, which is expected to be completed in 5 weeks time.
Dan does not have direct access to Vault authentication methods, such as the username and password auth method that the quality assurance team uses for access to project secrets. Dan does have an identity from the organization's Okta IdP to authenticate with other services.
Alice can enable the SAML auth method in Vault, then define a role and policy which allows Dan and other users to authenticate with Vault using their IdP identities and gain access to the secrets they need.
Dan can authenticate to Vault with the SAML auth method.
Vault communicates with the IdP to validate the authentication.
If the authentication is valid, Dan gets a Vault token.
Dan can use the Vault token to access secrets in Vault, including the dashboard service API token secret.

Lab setup

Your goal for this section is to prepare your Okta and Vault environments for the steps to follow.

Okta identity provider

Before you can use Vault with your identity provider, you must first ensure that it is configured and ready for use.

For the purposes of this hands-on lab in this tutorial, you can create an Okta example group, example user, and SAML application.

As the Alice persona, you can use a web browser with your Okta account to configure the SAML application.

Add a new group named Aqua Team.

Sign in to developer.okta.com
Click Directory.
Click Groups.
Click Add group.
In the Add group dialog, enter Aqua Team for Name, and optionally enter a description.
Click Save.

Add a person named Dan Developer.

Click People.
Click Add person.
Enter Dan in First name.
Enter Developer in Last name.
Enter dan@example.com in Username.
Begin typing Aqua into Groups, and the UI will autocomplete Aqua Team; select that value.
Select Set by admin for Password.
Enter c0ff33-Password! into the Enter password field.
Click Save.

Create the example SAML application.

Click Applications → Applications.
Click Create App Integration.
Select SAML 2.0.
Click Next.
Enter Aqua Team SAML into App name under General Settings.
Click Next.
Enter the SAML auth method Assertion Consumer Service (ACS) URL into Single sign-on URL. The example you can use for your Vault dev mode server is http://127.0.0.1:8200/v1/auth/saml/callback. You later specify this value in the auth method configuration in the acs_urls parameter parameter.
Enter a unique URI based identifier as the value for Audience URI (SP Entity ID). The example you can use for your Vault dev mode server is http://127.0.0.1:8200/v1/auth/saml. This can take any value but uniqueness is a recommended property. You later specify this in the auth method configuration as the entity_id parameter parameter value.
Select EmailAddress for Name ID Format.
Add Attribute Statements. For example, add the name first_name, and select the value user.firstName from the dropdown menu. Name format is optional.
Add Group Attribute Statements. For example, add the name groups with a filter of "Matches regex" equal to .*.. The values returned will be used for Vault identity group aliasing when the auth method is configured with groups_attribute=groups. Name format is optional.
Click Next.
Click Next.
Click Finish.
In the Metadata details section, click the Copy button to copy the metadata URL to your system clipboard. Paste this value someplace where you can retrieve later when you configure the Vault auth method.

Assign the SAML application to the Dan user.

Click Applications.
Click Assign Users to App.
Click Next.
Click Confirm Assignments.

You have completed configuration of the Okta identity provider user, group, and SAML application.

Vault dev mode server

Run a Vault dev mode server as a background process from your terminal session, and prepare it for use.

Export an environment variable with a valid Vault Enterprise license.
```
$ export VAULT_LICENSE=02MC0FFEEBK5....
```
Update example value
Use your actual Vault Enterprise license string in place of the example value shown.
Open a terminal and start a Vault dev server using the Vault Enterprise binary with root as the initial root token value.
```
$ vault server -dev -dev-root-token-id root > "$PWD"/vault-server.log 2>&1 &
```
The Vault dev server defaults to running at 127.0.0.1:8200. The server logs to the file vault-server.log in the present working directory, and gets automatically initialized and unsealed.
Dev mode is not for production
Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and all contents are lost when the Vault server process is stopped.
Export the environment variable for the vault CLI to address the Vault server.
```
$ export VAULT_ADDR=http://127.0.0.1:8200
```

Check Vault status.

$ vault status

Example output:

Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    1
Threshold       1
Version         1.15.0+ent
Build Date      2023-09-11T17:44:31Z
Storage Type    inmem
Cluster Name    vault-cluster-040c159e
Cluster ID      78d63616-f8ac-ef95-bcea-05387a693771
HA Enabled      false

The Vault server is ready for you to proceed with the hands-on lab.

Step 1: configure Vault

For this section, you assume the role of Alice to perform some configuration tasks, which you can accomplish with the Vault CLI or API.

You'll authenticate to Vault using the initial root token value to complete these tasks. While this is not recommended in production settings, you can use the initial root token in this hands-on lab to emulate a privileged token for the sake of simplicity.

The ACL policies you need as Alice to perform these tasks without the root token are shown in the example.

Example Alice persona token ACL policies

# Write and manage secrets in the key-value secrets engine
path "secret" {
  capabilities = [ "create", "read", "update", "delete", "list", "patch" ]
}

# Enable auth methods
path "sys/auth/*" {
  capabilities = [ "create", "read", "update", "delete" ]
}

# Configure and manage the SAML auth method
path "saml" {
  capabilities = [ "create", "read", "update", "delete", "list", "patch" ]
}

Then, you'll create an example API token secret for the scenario in the automatically-enabled KV secrets engine.

You'll also create an ACL policy for access to the example API token secret.

Lastly, you'll enable and configure the SAML auth method for Okta IdP.

Create secret

Create the example API token that Dan needs to access in this scenario.

Authenticate to Vault with the initial root token.
```
$ vault login -no-print root
```

Write the example API token secret to the KV secrets engine.

$ vault kv put secret/aqua-team-dashboard token=23C30859-C0C5-4F13-AA2B-C0FFEE8F7B46

Example output:

=========== Secret Path ===========
secret/data/aqua-team-dashboard

======= Metadata =======
Key                Value
---                -----
created_time       2023-09-19T18:11:08.198264Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Read the token value.

$ vault kv get -field=token secret/aqua-team-dashboard

Example output:

23C30859-C0C5-4F13-AA2B-C0FFEE8F7B46

Create a JSON payload for the aqua-team-dashboard secret.

$ cat > kv-secret-payload.json << EOF
{
  "data": {
    "token": "23C30859-C0C5-4F13-AA2B-C0FFEE8F7B46"
    }
}
EOF

Write the example API token secret to the secrets engine.

$ curl \
    --header "X-Vault-Token: root" \
    --silent \
    --request POST \
    --data @kv-secret-payload.json \
    $VAULT_ADDR/v1/secret/data/aqua-team-dashboard \
    | jq

Example output:

{
  "request_id": "125fc4b8-6778-0242-0812-287f55ac2270",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2023-09-22T15:06:15.019697Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Read the token value.

$ curl \
 --header "X-Vault-Token: root" \
 --silent \
 $VAULT_ADDR/v1/secret/data/aqua-team-dashboard \
 | jq -r '.data.data.token'

Example output:

23C30859-C0C5-4F13-AA2B-C0FFEE8F7B46

The example API token secret is ready.

You must also create a Vault ACL policy that provides the capabilities for listing and reading this secret. This policy is attached to tokens which Vault gives users who authenticate with the project-aqua-developers role.

This ACL policy is named aqua-team-secrets and gives list and read capabilities for the api-tokens/aqua-team-dashboard secret.

Create the policy.

$ vault policy write aqua-team-secrets - << EOF
path "secret/+/aqua-team-dashboard" {
  capabilities = ["read", "list"]
}
path "secret/metadata" {
  capabilities = ["list"]
}
EOF

Example output:

Success! Uploaded policy: aqua-team-secrets

Export an environment variable to hold the base64-encoded policy string.

$ export ACL_POLICY=$(printf 'path "secret/+/aqua-team-dashboard" {capabilities = ["read", "list"]} path "secret/metadata" {capabilities = [ "list"]}'| base64)

Create a JSON ACL policy payload in the file aqua-team-secrets-policy.json.

$ cat > aqua-team-secrets-policy.json << EOF
{
  "policy": "$ACL_POLICY"
}
EOF

Write the policy to Vault.

$ curl \
   --header "X-Vault-Token: root" \
   --request POST \
   --data @aqua-team-secrets-policy.json \
   $VAULT_ADDR/v1/sys/policies/acl/aqua-team-secrets

This command is expected to produce no output.

You can read the policy to verify.

$ curl \
   --header "X-Vault-Token: root" \
   --silent \
   --request GET \
   $VAULT_ADDR/v1/sys/policies/acl/aqua-team-secrets \
   | jq

Example output:

{
  "request_id": "67d061f8-b5a6-188b-e3e6-2afffd21a449",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "name": "aqua-team-secrets",
    "policy": "path \"secret/+/aqua-team-dashboard\" {capabilities = [\"read\", \"list\"]} path \"secret/metadata\" {capabilities = [ \"list\"]}"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Enable and configure SAML auth method

Enable and configure the SAML auth method using information from the Okta SAML application you defined earlier.

Note

You can enable and configure auth method in the Vault UI, but you can't create a role for the auth method in the UI, so the UI workflow is not covered in the hands-on lab.

Enable the SAML auth method.

$ vault auth enable saml

Example output:

Success! Enabled saml auth method at: saml/

Configure the SAML auth method by specifying the IDP metadata URL from Okta, providing Vault endpoint URLs for the ACS URLs and entity ID values, and naming the default role.
Update example value
Be sure to update the example value for idp_metadata_url to match your actual value from Okta.
```
$ vault write auth/saml/config \
    idp_metadata_url="https://dev-08675309.okta.com/app/exkbg3rawclc0ff335d7/sso/saml/metadata" \
    acs_urls="http://127.0.0.1:8200/v1/auth/saml/callback" \
    entity_id="http://127.0.0.1:8200/v1/auth/saml" \
    default_role="project-aqua-developers"
```
Example output:
```
WARNING! The following warnings were returned from Vault:

  * 'acs_urls' value "http://127.0.0.1:8200/v1/auth/saml/callback" is not
  protected by TLS
```
Because you are not using TLS with Vault in this hands-on lab, a warning is output about the callback URL unprotected by TLS. In production usage, you operated Vault with TLs and typically do not meet with this warning.
Create a role named project-aqua-developers. This role defines groups, a glob type bound subject matching the example.com domain used in Okta. The role also specifies that users authenticating with this role get a token that lives for 5 weeks (expressed here as 840 hours), and that it has the ACL policy aqua-team-secrets attached.
```
$ vault write auth/saml/role/project-aqua-developers \
    groups_attribute="groups" \
    bound_subjects="*example.com" \
    bound_subjects_type="glob" \
    token_policies="aqua-team-secrets" \
    token_ttl="840h"
```
Example output:
```
Success! Data written to: auth/saml/role/project-aqua-developers
```

Create a JSON payload to enable the auth method named enable-saml-auth-method.json.

$ cat > enable-saml-auth-method.json << EOF
{
    "description": "SAML auth method",
    "type": "saml"
}
EOF

Enable the SAML auth method.

$ curl \
    --header "X-Vault-Token: root" \
    --silent \
    --request POST \
    --data @enable-saml-auth-method.json \
    $VAULT_ADDR/v1/sys/auth/saml

This command is expected to produce no output.

You can list details about the SAML auth method to ensure it is enabled.

$ curl \
    --header "X-Vault-Token: root" \
    --silent \
    --request GET \
    $VAULT_ADDR/v1/sys/auth \
    | jq '.data."saml/"'

Example output:

{
"accessor": "auth_saml_4b4261ef",
"config": {
   "default_lease_ttl": 0,
   "force_no_cache": false,
   "max_lease_ttl": 0,
   "token_type": "default-service"
},
"description": "SAML auth method",
"external_entropy_access": false,
"local": false,
"options": {},
"plugin_version": "",
"running_plugin_version": "v0.1.0+builtin",
"running_sha256": "",
"seal_wrap": false,
"type": "saml",
"uuid": "3727892c-99ca-9c5d-a99b-c7bb449135c7"
}

Create a JSON payload to configure the auth method named configure-saml-auth-method.json specifying the IDP metadata URL from Okta, providing Vault endpoint URLs for the ACS URLs and entity ID values, and naming the default role.
```
$ cat > configure-saml-auth-method.json << EOF
{
    "acs_urls": "https://127.0.0.1:8200/v1/auth/saml/callback",
    "default_role": "project-aqua-developers",
    "entity_id": "https://127.0.0.1:8200/v1/auth/saml",
   "idp_metadata_url": "https://dev-08675309.okta.com/app/exkbg3rawclc0ff335d7/sso/saml/metadata"
}
EOF
```
Update example value
Be sure to update the value for idp_metadata_url to match your actual value from the Okta application metadata that you copied earlier.

Configure the auth method.

$ curl \
    --header "X-Vault-Token: root" \
    --silent \
    --request PUT \
    --data @configure-saml-auth-method.json \
    $VAULT_ADDR/v1/auth/saml/config \
    | jq

Example output:

{
  "request_id": "ad06b782-e1cb-4922-1d9c-e397b07721e0",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Create a JSON payload to define the role named project-aqua-developers in saml-auth-method-role.json.

$ cat > saml-auth-method-role.json << EOF
{
    "bound_attributes": "group=admin",
    "bound_subjects": "*@example.com",
    "bound_subjects_type": "glob",
    "token_policies": "aqua-team-secrets",
    "ttl": "840h"
}
EOF

Create the role.

$ curl \
    --header "X-Vault-Token: root" \
    --silent \
    --request PUT \
    --data @saml-auth-method-role.json \
    $VAULT_ADDR/v1/auth/saml/role/project-aqua-developers

This command is expected to produce no output.

You can read the role to verify.

$ curl \
    --header "X-Vault-Token: root" \
    --silent \
    --request GET \
    $VAULT_ADDR/v1/auth/saml/role/project-aqua-developers \
    | jq

{
  "request_id": "6174272b-aa16-e02c-a753-bb6aa1ccf612",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "bound_attributes": {
      "group": [
        "admin"
      ]
    },
    "bound_attributes_type": "string",
    "bound_subjects": [
      "*@example.com"
    ],
    "bound_subjects_type": "glob",
    "groups_attribute": "groups",
    "token_bound_cidrs": [],
    "token_explicit_max_ttl": 0,
    "token_max_ttl": 0,
    "token_no_default_policy": false,
    "token_num_uses": 0,
    "token_period": 0,
    "token_policies": [
      "aqua-team-secrets"
    ],
    "token_ttl": 3024000,
    "token_type": "default"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Step 2: authenticate to Vault

Your goal in this section is to assume the role of Dan and authenticate to Vault with your Okta identity using the Vault CLI or UI.

Sign out first

If you are still signed into Okta as the Alice persona, be sure to sign out before completing the steps in this section.

Authenticate to Vault using the SAML auth method and project-aqua-developers role.

$ vault login -method=saml role="project-aqua-developers"

Example output:

Complete the login via your SAML provider. Launching browser to:

    https://dev-38556941.okta.com/app/dev-38556941_aquateamsaml_1/exkbg3rawclrcQo8e5d7/sso/saml?RelayState=c9c0ff33-98b6-ed66-be7b-006dcf2796cb&SAMLRequest=jJHNbtswEIRfReCdv4oiibAFuM2hBlLUjdUeejFW1CYWLJEKl3Lz%2BEWcFm0vgc%2BzOzP4ZrVZ0tE%2F4POClLKXafS0Zkv0NgANZD1MSDY5u998vrdGKDvHkIILI8u2C0FFEE9vlauh491jqXhf98DLvKp41WHZGYVKmZ5l3zHSEPyaGaFYtiVacOspgU9rZpTJuaq50a2u7U1ti0JoXRmT%2F2DZHVIaPKTL8zGlmayUPZ55XhXFbX2jRTglEC5MEub5P%2BUAzwskhIlgGg9a4supe8oj%2FHRjdF9DhUVfSqIgX3WWbYgwvuZ8DJ6WCeMe43lw%2BO3h%2Fm%2ByNqVQQgltK6OUPGsJSzpeHKSDcezAnVi2%2B43ow%2BD7wT%2B9z7N7OyL7qW13fPdl37JmdSEUr5kD%2FtRmzRUlV%2FLNuVnJf3dvfgUAAP%2F%2F

Your browser opens the Okta sign in URL, and you complete the authentication flow by signing in to Okta.
Sign in to Okta with username dan@example.com and password c0ff33-Password!.
You should observe the callback from Okta to Vault in your web browser.

Return to your terminal session, where Vault notifies you that your authentication succeeded and prints a token and its details.

Waiting for SAML authentication to complete...
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                  hvs.CAESILwZC0FFEE4Rj2IToxwk_JKW6JujyjILAS2ArPBFhX4xGh4KHGh2cy5GdlllZmU2c3Jld2k1cnJXU1JEVkxWdmE
token_accessor         NPWgx03Vkdcsie8sdAo950R3
token_duration         840h
token_renewable        true
token_policies         ["default" "aqua-team-secrets"]
identity_policies      []
policies               ["default" "aqua-team-secrets"]
token_meta_role        aqua-team-secrets

Access the Vault dev mode server UI at http://127.0.0.1:8200.
If you are already signed in with the initial root token, log out of Vault.
At the sign in dialog, select SAML in the Method dropdown.
Enter project-aqua-developers into Role.
Click Sign in with SAML provider
Your browser directs you to the Okta sign in URL, and you complete the authentication flow by signing in to Okta.
Sign in to Okta with username dan@example.com and password c0ff33-Password!.
You should observe the callback from Okta to Vault and get signed in to Vault.

Step 3: access API token secret

Now that you are authenticated with Vault, your goal for this section is to assume the Dan persona, and access the API token value with the Vault CLI or UI.

Read the token value.

$ vault kv get -field=token secret/aqua-team-dashboard

Example output:

23C30859-C0C5-4F13-AA2B-C0FFEE8F7B46

You've read the API token secret as the Dan persona after authenticating with Vault using the SAML auth method.

Summary

You learned how to enable and configure the SAML auth method for a basic use case, which allows a user to authenticate to Vault with their SAML identity and access a secret.

You also learned about authenticating to Vault with a SAML identity using the Vault CLI or UI.

Cleanup

Unset the environment variables.
```
$ unset VAULT_ADDR
```

Remove the JSON payload files if you followed any of the API instructions.

$ rm -f enable-saml-auth-method.json \
    configure-saml-auth-method.json \
    saml-auth-method-role.json

You can stop the Vault dev server by executing the following command in your terminal session.
```
$ pgrep -f vault | xargs kill
```
Remove the Vault server log.
```
$ rm -f vault-server.log
```

Next steps

Now that you've learned about configuring and using the SAML auth method, you can learn about using multi-factor authentication to secure Vault logins with the Enable login multi factor authentication tutorial.

Help and reference

HSM integration - seal wrap

Use PKI with external policy services

This tutorial also appears in:

18 tutorials

Archived content
Archive of Vault tutorials that are scheduled to be converted into documentation or deleted.
- Vault