SAML auth method
This feature requires Vault Enterprise(opens in new tab).
saml auth method allows users to authentication with Vault using their identity
within a SAML V2.0 identity provider.
Authentication is suited for human users by requiring interaction with a web browser.
The CLI login defaults to the
/saml path. If this auth method was enabled at a
different path, specify
-path=/my-path in the CLI.
$ vault login -method=saml role=admin Complete the login via your SAML provider. Launching browser to: https://company.okta.com/app/vault/abc123eb9xnIfzlaf697/sso/saml?SAMLRequest=fJI9b9swEIZ3%2FwqBu0SJ%2FpBDRAZce4iBtDViN0MX40Sda...
The CLI opens the default browser to the generated URL where users must authenticate with the configured SAML identity provider. The URL may be manually entered into the browser if it cannot be automatically opened.
The CLI login behavior may be customized with the following optional parameters:
false): If set to
true, automatic launching of the default browser will be skipped. The SAML identity provider URL must be manually entered in a browser to complete the authentication flow.
false): If set to
true, the CLI returns an error and exits with a non-zero value if it cannot launch the default browser.
Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.
Enable the SAML authentication method with the
auth enableCLI command:
$ vault auth enable saml
/configendpoint to save the configuration of your SAML identity provider and set the default role. You can configure the trust relationship with the SAML Identity Provider by either providing a URL for its Metadata document:
$ vault write auth/saml/config \ default_role=admin \ idp_metadata_url=https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata \ entity_id="https://my.vault/v1/auth/saml" \ acs_urls="https://my.vault/v1/auth/saml/callback"
or by setting the configuration Metadata manually:
$ vault write auth/saml/config \ default_role=admin \ idp_sso_url=https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml \ idp_entity_id=https://www.okta.com/abc123eb9xnIfzlaf697 \ idp_cert=@path/to/cert.pem \ entity_id="https://my.vault/v1/auth/saml" \ acs_urls="https://my.vault/v1/auth/saml/callback"
Create a named role:
$ vault write auth/saml/role/admin \ bound_subjects="*@hashicorp.com" \ bound_subjects_type="glob" \ token_policies="writer" \ bound_attributes=group="admin" \ ttl=1h
This role authorizes users that have a subject with an
@hashicorp.comsuffix and are in the
admingroup to authenticate. It also gives the resulting Vault token a time-to-live of 1 hour and the
Refer to the SAML API documentation for a complete list of configuration options.
acs_urls configuration parameter determines
where the SAML response will be sent after users authenticate with the configured SAML
identity provider in their browser.
The values provided to Vault must:
- Match or be a subset of the configured values for the SAML application within the configured identity provider.
- Be directed to the auth method's assertion consumer service callback API.
NoteIt is highly recommended and enforced by some identity providers to TLS-protect the assertion consumer service URLs. A warning will be returned from Vault if any of the configured assertion consumer service URLs are not protected by TLS.
To support a single auth method mount being used across Vault replication
acs_urls supports configuration of multiple values. For example, to support
SAML authentication on a primary and secondary Vault cluster, the following
configuration could be given:
$ vault write auth/saml/config \ acs_urls="https://primary.vault/v1/auth/saml/callback,https://secondary.vault/v1/auth/saml/callback"
The Vault UI and CLI will automatically request the proper assertion consumer service URL for the cluster they're configured to communicate with. This means that the entirety of the authentication flow will stay within the targeted cluster.
The SAML auth method can be used within Vault namespaces. The assertion consumer service URLs configured in both Vault and the identity provider must include the namespace path segment.
The following table provides assertion consumer service URLs given different namespace paths:
|Namespace path||Assertion consumer service URL|
Once the user has been authenticated the authorization flow will validate
that both the
bound_attributes match expected
values configured for the role. This can be used to restrict access to Vault for
a subset of users in the SAML identity provider.
For example, a role with
bound_attributes=groups=support,engineering will only authorize users whose subject has
@hashicorp.com suffix and that are in either the
The SAML authentication plugin has a full HTTP API. Refer to the SAML API documentation for more details.