How to configure HCP Boundary to Display User Email Instead of Username with OIDC Authentication

Introduction

This article guides you through the steps to configure HCP Boundary to display a user's email address, rather than their username, when using OIDC authentication. This is done by leveraging claims scopes and account claim maps, allowing the email to be used as the user identifier.

Expected Outcome

By leveraging claims scopes and account claim maps, you can configure HCP Boundary to display a user’s email address during login. This is particularly useful in cases where external tools or processes rely on email identifiers for authentication or access control.

Prerequisites (if applicable)

• An HCP Boundary environment.
• An OIDC provider (e.g., Okta, Google, Azure AD) configured and integrated with Boundary.
• Administrative access to Boundary and your OIDC provider.
• Access to the HCP CLI.

Use Case

This setup is especially useful when integrating with tools like Sailpoint for Just-In-Time (JIT) access provisioning, as it requires email addresses for identifying users. By mapping the email to the login_name, you ensure compatibility with these systems.

Procedure

• 1. Set Up OIDC Authentication in HCP Boundary

  Before modifying the claim mappings, ensure that OIDC is set up and configured in HCP Boundary. This includes:

  • Creating an OIDC authentication method.
  • Registering your Boundary instance as a client with your OIDC provider.

  To create an OIDC authentication method in Boundary, we can use either Boundary CLI or Admin Console:
  
  Using Boundary CLI:

  boundary auth-method create oidc \
  
    -name "oidc-auth" \
  
    -scope-id "global" \
  
    -issuer "https://your-oidc-provider.com" \
  
    -client-id "your-client-id" \
  
    -client-secret "your-client-secret" \
  
    -scope "openid email"

  
  

  Using Boundary Admin Console:
  
  https://developer.hashicorp.com/boundary/tutorials/identity-management/oidc-auth0
  
  Ensure you include the email scope, as this requests the user's email address in the token provided by the OIDC provider.
  
  2. Verify Email Claim in OIDC Provider

  Make sure that your OIDC provider is configured to include the email claim in the token. Most providers (Okta, Google, Azure AD) automatically include this in the default claim set, but it’s essential to verify.

  • For Okta: Ensure the email scope is included in the authorization request.
  • For Google: The email claim is part of the default scopes when openid is included.
  • For Azure AD: The email claim is included in the token by default, but it can be customized in the Azure AD App registration settings.

  Ensure your OIDC provider is configured to include the email claim in the SAML token. Most OIDC providers include the email claim by default, but you'll need to confirm that this is enabled. This can be done with the help of https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?tabs=appui. (for AzureAD).
  
  

  3. Configure Account Claim Maps in HCP Boundary

  Once the OIDC provider is correctly configured, you need to map the email claim from the OIDC token to the user's login identifier in Boundary. Use the account_claim_maps option to map the email claim to the login_name field.

  Using CLI:

  boundary auth-method update oidc \
  
    -id "oidc-auth-method-id" \
  
    -account-claim-maps "email:login_name"

  
  This command tells Boundary to use the email address as the login name by mapping the email claim to the login_name field.

   

  Using Boundary Admin Console:
  
  

  
  
  4. Test the Configuration

  1. Log in to Boundary using OIDC: Use the OIDC authentication method you configured.
  2. Verify the User Identifier: Once logged in, confirm that the user’s email address is displayed instead of the username.
  
  

  

Troubleshooting:

• If the email is not displaying as expected, ensure that:
  • The email claim is present in the OIDC token (use a token decoder to check).
  • The account_claim_maps configuration is correct.
  • The OIDC provider is correctly configured to pass the email claim.

Conclusion:

For further assistance, refer to the HCP Boundary Documentation or contact your OIDC provider's support.