Configure OIDC authentication with Auth0

Boundary delegates authentication to Auth0 using the OIDC (OpenID Connect) auth method, a common single sign-on (SSO) integration. Registering Boundary as an Auth0 application takes two steps: configure the application in Auth0, then create the matching OIDC auth method in Boundary.

Prerequisites

An Auth0 account.
Administrator access to Boundary.

Create an Auth0 application

Registering Boundary as an application in Auth0 lets Auth0 authenticate Boundary users and redirect them back to Boundary after a successful login.

In the Auth0 dashboard, select Applications, and then select Create Application.
Select Regular Web Application, name the application, and select Create.
From the application's Settings tab, scroll to Application URIs.
Under Allowed Callback URLs, add the following URL, replacing BOUNDARY_ADDR with the address of your Boundary controller:
```
https://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
```
Under Allowed Logout URLs, add your Boundary address:
```
https://BOUNDARY_ADDR
```
Select Save to save the changes.
From the top of the Settings tab, record the following values. You need them to create the OIDC auth method in Boundary:
- Domain: maps to the auth method's issuer attribute.
- Client ID: maps to the auth method's client-id attribute.
- Client Secret: maps to the auth method's client-secret attribute.

Note

The Boundary issuer value must have a trailing / at the end of the Auth0 domain, for example https://YOUR_DOMAIN.auth0.com/. If you omit the trailing slash, Boundary cannot validate the auth method's configuration against the Auth0 discovery document.

Any Auth0 user assigned to the application can authenticate to Boundary. Refer to the Auth0 user management documentation to create and assign users.

Create an OIDC auth method for Auth0

Log in to Boundary.
Select the scope in which you want to create the auth method, or create a new one.
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 Auth0 application's Domain, including a trailing /.
- Client ID: (Required) The Auth0 application's Client ID.
- Client Secret: (Required) The Auth0 application's Client Secret.
- API URL Prefix: (Required) The address where your Boundary controller is reachable by Auth0, 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.
Click Edit Form, scroll to Signing Algorithms, add RS256, and select Add.
Click Save.

$ boundary auth-methods create oidc \
  -scope-id $SCOPE_ID \
  -issuer "https://YOUR_DOMAIN.auth0.com/" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "https://BOUNDARY_ADDR" \
  -name "auth0"

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 Auth0 application settings. The api-url-prefix must match the address where your Boundary controller is reachable by Auth0.

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               = "Auth0"
  description        = "OIDC auth method for Auth0"
  scope_id           = "SCOPE_ID"
  issuer             = "https://YOUR_DOMAIN.auth0.com/"
  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 Auth0 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 you omit the trailing / from the Auth0 domain, activating the auth method fails with an error similar to the following:

oidc: issuer did not match the issuer returned by provider, expected "https://YOUR_DOMAIN.auth0.com" got "https://YOUR_DOMAIN.auth0.com/"

Update the auth method's issuer attribute to include the trailing /, and try again.

`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 Auth0 users based on claims returned by Auth0, such as group membership.
Refer to the Auth0 documentation for information about configuring Auth0 applications, rules, and custom claims.