Introduction:
SAML authentication is a widely adopted standard for enabling SSO across disparate systems. At its core, SAML relies on assertions exchanged between an Identity Provider (IdP) and a Service Provider (SP) to authenticate users. The IdP, such as Microsoft Entra ID, validates the user's identity and issues an assertion containing authentication information. The SP, in this case, HCP Vault, consumes the assertion to grant or deny access based on predefined policies.
Steps:
Step 1: Obtain Configuration from Microsoft Azure Portal
- Log in to the Microsoft Azure portal.
- Navigate to the Entra ID service.
- Under "Manage," select "App registrations" and then click on "New registration."
- Enter a name for your application and choose the appropriate Supported account types.
- Set up single sign on -> select SAML
- Specify the Redirect URI for Vault to receive SAML assertions. This typically follows the format: https://<vault-address>/ui/vault/auth/saml/acs.
- After registration, note down the Application (client) ID, Directory (tenant) ID, and Issuer URL.
- Please validate Entra ID group is in place and groups claim need to be configured from Entra ID Portal.
- Go to Entra ID and choose your Vault application.
- Go to Token configuration and Add groups claim. Select "All" or "SecurityGroup" based on which groups for a user you want returned in the claim.
Step 2: Configure HCP Vault for SAML Authentication
Command to enable SAML auth:
vault auth enable -path=sys_admin saml
Command for SAML auth config:
-
*Note - for HCP, acs_urls must include
adminin the path.
vault write auth/saml/config \
default_role="default" \
idp_metadata_url="https://login.microsoftonline.com/c68a39c2-7245-47d2-ba3d-713aec609ac4/federationmetadata[…]nmetadata.xml?appid=90678966-4997-44c5-8f39-041fe48bd0ca" \
entity_id="https://kratos-vault-cluster-public-vault-51dd16de.46d0d1d2.z1.hashicorp.cloud:8200/v1/auth/saml" \
acs_urls="https://kratos-vault-cluster-public-vault-51dd16de.46d0d1d2.z1.hashicorp.cloud:8200/v1/admin/auth/saml/callback"
Command for SAML auth role:
To set bound_attributes value for Microsoft Identity platform, please refer to the doc.
vault write auth/saml/role/saml_role \
bound_subjects="*" \
bound_subjects_type="glob" \
groups_attribute="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
bound_attributes=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups="6a830494-cebd-42d5-afbc-d0d8b4149a6b"
token_policies="kv-reader" \
ttl=1h
Step 3: Mapping Users/Groups to Vault Policies
Command for SAML auth to create an external group:
vault write identity/group name="sys_admin" \
policies="sys_admin" \
type="external"
Step 4 : Map Microsoft Enterprise ID users or groups to these Vault policies based on their roles and responsibilities.
vault write identity/group-alias \
name="e3ff9f99-f7ec-4d50-828d-6f931f44db03" \ << Entra ID's Group ID
mount_accessor="auth_saml_08500f0e" \ << SAML Auth mount_accessor
canonical_id="2fea237d-8195-76d2-4688-fafeff5b433a" << Vault's group ID
Step 4: Test the SAML Setup:
Access the Vault UI or CLI and initiate the SAML authentication flow.
vault login -method=saml role=saml_role
You should be redirected to the Microsoft Entra ID login page.
Enter valid credentials associated with Microsoft Entra ID user/group.
Upon successful authentication, HCP Vault should issue a token based on the user's mapped policies.
Issues and Challenges:
Despite careful configuration, SAML authentication setup may encounter challenges. Common issues and their solutions include:
Assertion Validation Errors: Troubleshoot misconfigured SAML settings, such as incorrect URLs or certificate mismatches.
Attribute Mapping Issues: Ensure accurate mapping of SAML attributes to Vault policies to avoid access discrepancies.
Token Expiration: Address token expiration issues by adjusting SAML token lifetimes and implementing token renewal mechanisms.
References:
HashiCorp Vault documentation: https://developer.hashicorp.com/vault/docs/auth/saml
Microsoft Azure documentation: https://learn.microsoft.com/en-us/entra/identity-platform/reference-saml-tokens