Resolving OIDC Authentication Issues in HashiCorp Vault Dedicated with Microsoft Entra ID

Introduction

This article outlines the resolution process for some common issues encountered while configuring the OIDC authentication method in HashiCorp Vault Dedicated (HVD) using Microsoft Entra ID. It also highlights best practices and considerations for similar configurations.

Problem

Error Message:

HVD login using OIDC failed with the following errors:

Error exchanging oidc code: "Provider.Exchange: unable to exchange auth code with provider: oauth2: \"invalid_grant\" \"AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token"".

"claim \"email\" not found in token".

Impact:

Sub-users attempting to authenticate to HVD using OIDC with Microsoft Entra ID were unable to sign in, resulting in a high-impact issue for operations.

Solutions:

• Step 1: Setting acceptMappedClaims to true

  • Updated the application manifest in Microsoft Entra ID to set acceptMappedClaims to true.
  • This allowed the optional claims to pass the sAMAccountName attributes from the Azure application back to Vault.
  • Reference: Microsoft documentation specifies that acceptMappedClaims should not be set to true for multi-tenant apps due to potential security risks. In this case, as the application was non-multi-tenant, the change was safe and effective.

• Step 2: Resolving Secondary Error

  • Encountered a secondary error: "claim \"email\" not found in token".
  • Resolution steps:
    1. Added the "email" field information to the user properties in the Azure application.
    2. Configured the optional claim id.email for the application in Microsoft Entra ID.

Considerations:

Microsoft’s Warning on acceptMappedClaims:

Per Microsoft documentation:

"Do not set acceptMappedClaims property to true for multi-tenant apps, which can allow malicious actors to create claims-mapping policies for your app."

• This change is safe for non-multi-tenant applications.
• Ensure to verify the tenant type before applying this configuration.

Optional Claims in Application Registration:

• Optional claims are essential for passing additional user attributes (e.g., id.email, sAMAccountName) required for authentication.
• Verify that the correct claims are configured in the application manifest to avoid errors.

Summary:

By adjusting the acceptMappedClaims property and correctly configuring optional claims, the OIDC authentication issue with HCP Vault was resolved. This approach ensures the seamless passing of user attributes between Microsoft Entra ID and Vault. Always consider the tenant type and Microsoft’s security guidelines when making these changes.

References:

• General OIDC Authentication: This provides foundational information on how OIDC authentication works within Vault.

  • https://developer.hashicorp.com/vault/tutorials/auth-methods/oidc-auth

• AzureAD OIDC Provider: This section specifically focuses on configuring Azure AD as an OIDC provider for Vault.

  • https://developer.hashicorp.com/vault/docs/auth/jwt/oidc-providers/azuread

2. Microsoft Entra ID Documentation:

• App Registrations: This guide explains how to register an application within Azure AD, which is crucial for OIDC integration.  

  • https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app

• OpenID Connect (OIDC) Overview: This provides an overview of OIDC and its key concepts, which can be helpful for understanding the underlying technology.

  • https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc