Configure OIDC authentication with Microsoft Entra ID (Azure AD)

Boundary delegates authentication to Microsoft Entra ID (formerly Azure Active Directory) using the OIDC (OpenID Connect) auth method, a common single sign-on (SSO) integration. You can register Boundary as either a HashiCorp Boundary enterprise application or a generic web application, then create the matching OIDC auth method in Boundary.

Prerequisites

An Azure account with access to Microsoft Entra ID.
Administrator access to Boundary.

Register a Boundary application in Entra ID

You can register Boundary in Microsoft Entra ID using either the HashiCorp Boundary enterprise application from the Entra ID gallery, or by registering a generic web application. Both methods let Entra ID authenticate Boundary users and redirect them back to Boundary after a successful login.

In the Azure Portal, navigate to Microsoft Entra ID, Click +Add, and then select Enterprise application.
Search for hashicorp boundary, and select the HashiCorp Boundary gallery application.
Name the application and select Create.
From the application's Overview page, select Single sign-on, and then select Go to application on the OIDC-based Sign-on page.
Select Authentication from the sidebar.
Under Redirect URIs, add the following URL to the Web platform, replacing BOUNDARY_ADDR with the address of your Boundary controller:
```
https://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
```
Under Front-channel logout URL, add your Boundary address:
```
https://BOUNDARY_ADDR
```
Select Save.
Select Certificates & secrets from the sidebar, select New client secret, and provide a description. Select an expiration for the secret, or specify a custom lifetime. Entra ID limits client secret lifetimes to 24 months or less, and Microsoft recommends an expiration of less than 12 months. Select Add. Copy the secret's Value, not its Secret ID. Entra ID does not display the value again after you leave the page. This secret maps to the auth method's client-secret attribute.
Return to the application's Overview page and record the Application (Client) ID and the Directory (Tenant) ID.
Select Endpoints, and copy the OpenID Connect metadata document URL up to and including /v2.0, for example https://login.microsoftonline.com/TENANT_ID/v2.0. This string maps to the auth method's issuer attribute.
(Optional) If you configure the application to require user assignment, only the users and groups you assign can log in to Boundary. To assign them, navigate to Entra ID > Enterprise apps > All applications, select the application, and then select Users and groups > Add user/group.
Group-based assignment requires a Microsoft Entra ID P1 or P2 license, and Entra ID does not support nested group memberships for application assignment.

In the Azure Portal, navigate to Microsoft Entra ID, click +Add, and then select App registration.
Select New registration.
Name the application and select Single tenant.
Under Redirect URI, select Web and enter the following URL, replacing BOUNDARY_ADDR with the address of your Boundary controller:
```
https://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
```
Select Register.
Select Certificates & secrets from the sidebar, select New client secret, and provide a description. Select an expiration for the secret, or specify a custom lifetime. Entra ID limits client secret lifetimes to 24 months or less, and Microsoft recommends an expiration of less than 12 months. Select Add. Copy the secret's Value, not its Secret ID. Entra ID does not display the value again after you leave the page. This secret maps to the auth method's client-secret attribute.
Select Authentication from the sidebar. Under Front-channel logout URL, add your Boundary address:
```
https://BOUNDARY_ADDR
```
Select Save.
Return to the application's Overview page and record the Application (Client) ID and the Directory (Tenant) ID.
Select Endpoints, and copy the OpenID Connect metadata document URL up to and including /v2.0, for example https://login.microsoftonline.com/TENANT_ID/v2.0. This string maps to the auth method's issuer attribute.

Note

Refer to the Microsoft Entra ID OIDC documentation for the latest OIDC endpoint formats, since they can vary by tenant configuration.

Create an OIDC auth method for Entra ID

Log in to Boundary.
Select the scope in which you want to create the auth method.
Select Auth Methods, then click New.
Select OIDC, and complete the following fields:
- Name: (Optional) An optional name for identification purposes.
- Description: (Optional) An optional description of the auth method.
- Issuer: (Required) The OpenID Connect metadata document URL, up to and including /v2.0.
- Client ID: (Required) The application's Application (Client) ID.
- Client Secret: (Required) The application's client secret Value.
- API URL Prefix: (Required) The address where your Boundary controller is reachable by Entra ID, for example https://BOUNDARY_ADDR.
Other optional fields you can provide include:
- Account Claim Maps: Account claim maps from custom claims to the standard claims of sub, name and email. You can click Add to specify multiple values.
- Allowed Audiences: Acceptable allowed audience ("aud") claim. You can click Add to specify multiple values.
- Claims Scopes: Claims scopes requested. You can click Add to specify multiple values.
- Certificates: PEM-encoded X.509 CA certificate to use as trust anchors for the OIDC provider. You can click Add to specify multiple values.
- Maximum Age: OIDC "max_age" parameter that is sent to the provider.
- Prompts: Whether the OIDC authorization server should display reauthentication, account selection, or consent user interface prompts. You can optionally configure one or more of the following types of prompts to customize the behavior of the authentication process: Skip Prompts, Consent, Select Account, Login.
Click Save.
Select Edit Form, scroll to Signing Algorithms, add RS256, and select Add.
Click Save.

$ boundary auth-methods create oidc \
  -scope-id $SCOPE_ID \
  -issuer "https://login.microsoftonline.com/$TENANT_ID/v2.0" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "https://BOUNDARY_ADDR" \
  -name "azure"

The scope-id determines which scope contains the auth method. Set it to global or to an org scope ID. If you omit scope-id, Boundary uses the BOUNDARY_SCOPE_ID environment variable, or defaults to global.

The issuer, client-id, and client-secret values come from the Entra ID application settings. The api-url-prefix must match the address where your Boundary controller is reachable by Entra ID.

Other optional fields you can provide include:

-account-claim-maps: Account claim maps from custom claims to the standard claims of sub, name and email. You may specify this multiple times.
-allowed-audience: Acceptable allowed audience ("aud") claim. You may specify this multiple times.
-claims-scopes: Claims scopes requested. You may specify this multiple times.
-idp-ca-cert: PEM-encoded X.509 CA certificate to use as trust anchors for the OIDC provider. You may specify this multiple times.
-max-age: OIDC "max_age" parameter that is sent to the provider.
-prompts: Whether the OIDC authorization server should display reauthentication, account selection, or consent user interface prompts. You can optionally configure one or more of the following types of prompts to customize the behavior of the authentication process: none, login, consent, select_account.

Refer to the auth-methods create command documentation for additional fields that you can use when you create OIDC auth methods.

Apply the following Terraform configuration:

resource "boundary_auth_method_oidc" "provider" {
  name               = "Azure"
  description        = "OIDC auth method for Microsoft Entra ID"
  scope_id           = "SCOPE_ID"
  issuer             = "https://login.microsoftonline.com/TENANT_ID/v2.0"
  client_id          = "CLIENT_ID"
  client_secret      = "CLIENT_SECRET"
  signing_algorithms = ["RS256"]
  api_url_prefix     = "https://BOUNDARY_ADDR"
}

Replace scope_id, issuer, client_id, client_secret, and api_url_prefix with the values for your scope and Entra ID application.

Other optional fields you can provide include:

account_claim_maps: (List of String) Account claim maps for the to_claim of sub.
allowed_audiences: (List of String) Audiences for which the provider responses will be allowed
claims_scopes: (List of String) Claims scopes.
idp_ca_certs: (List of String) A list of CA certificates to trust when validating the IdP's token signatures.
max_age: (Number) The max age to provide to the provider, indicating how much time is allowed to have passed since the last authentication before the user is challenged again.
prompts: (List of String) The prompts passed to the identity provider to determine whether to prompt the end-user for reauthentication, account selection or consent. Please note the values passed are case-sensitive. The valid values are: none, login, consent and select_account.

Refer to the boundary_auth_method_oidc resource documentation for additional fields that you can use when you create OIDC auth methods.

Activate the auth method

Boundary creates new OIDC auth methods in an inactive state. You must activate the auth method before users can log in with it.

Log in to Boundary.
Select Auth Methods, then select the OIDC auth method you created.
Select Manage, then select Change State.
Select Active Public to allow unauthenticated users to see and use the auth method to log in, or select Active Private to allow login without listing the auth method on the login page.

Use the auth-methods change-state command to activate the auth method:

$ boundary auth-methods change-state oidc \
  -id $OIDC_AUTH_METHOD_ID \
  -state active-public

Before Boundary changes the state of an auth method, it retrieves the provider's discovery document for the auth method's issuer and validates the auth method's configuration against it. If Boundary cannot validate the configuration, it returns an error and does not change the state.

Refer to the auth-methods change-state command documentation for more information about auth method states.

Set the state attribute on the boundary_auth_method_oidc resource so that Terraform activates the auth method when it applies the configuration:

resource "boundary_auth_method_oidc" "provider" {
  # ...
  state = "active-public"
}

Set the auth method as primary

Each scope has one primary auth method. Boundary automatically creates a user the first time someone authenticates successfully using the scope's primary auth method.

If the auth method is not primary for its scope, Boundary creates an account when a user first logs in, but it refuses to create the matching user, and the login fails. Either set the auth method as primary, as described in this section, or manually create a user and link it to the account.

Select Auth Methods, then select the OIDC auth method.
Select Manage, then select Make Primary.
Click OK to confirm. Boundary automatically creates a user for anyone who authenticates using this auth method for the first time.

Troubleshooting

`oidc: issuer did not match the issuer returned by provider`

If the issuer attribute does not exactly match the OpenID Connect metadata document URL, including the /v2.0 suffix and tenant ID, activating the auth method fails with an error similar to the following:

oidc: issuer did not match the issuer returned by provider, expected "https://login.microsoftonline.com/TENANT_ID/" got "https://login.microsoftonline.com/TENANT_ID/v2.0"

Update the auth method's issuer attribute to match the OpenID Connect metadata document URL exactly, and try again.

`AADSTS50105`

If you configure the application to require user assignment, Entra ID refuses to authenticate anyone you have not assigned to it, and returns the following error:

AADSTS50105: EntitlementGrantsNotFound - The signed in user isn't assigned to a role for the signed in app.

Assign the user, or a group the user belongs to, to the application. Refer to the Microsoft documentation for managing user and group assignment and requiring user assignment.

`auth method is not primary for the scope so refusing to auto-create user`

If the auth method is not primary for its scope and the account is not linked to a user, the provider authenticates the user, but Boundary fails to complete the login. The browser redirects to an /authentication-error page, and the error contains the following message:

authmethod_service.(Service).authenticateOidcCallback: Callback validation failed.:
parameter violation: error #100: oidc.Callback:
iam.(Repository).LookupUserWithLogin: user not found for account acctoidc_1234567890
and auth method is not primary for the scope so refusing to auto-create user:
search issue: error #1100

Boundary creates the account on the first login attempt, so the account exists even though the login failed. To resolve the error, either set the auth method as primary for its scope, or create a user and link it to the account that Boundary created.

More information

Refer to the Auth method domain model topic for the full list of OIDC auth method attributes.
Refer to Filter managed groups to assign roles to Entra ID users based on claims returned by Entra ID, such as group membership.
Refer to the Microsoft Entra ID documentation for information about configuring applications and optional claims.