Configure OIDC authentication with Okta

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

Prerequisites

An Okta account.
Administrator access to Boundary.

Create an Okta app integration

Registering Boundary as an app integration in Okta lets Okta authenticate Boundary users and redirect them back to Boundary after a successful login.

In the Okta Admin Console, select Applications and Resources, and then select Applications again from the sidebar.
Select Create App Integration.
Select OIDC - OpenID Connect and Web Application, and then select Next.
Name the integration.
Under Sign-in redirect URIs, replace the default value with the following URL, replacing BOUNDARY_ADDR with the address of your Boundary controller:
```
https://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
```
Under Sign-out redirect URIs, add your Boundary address:
```
https://BOUNDARY_ADDR
```
Under Assignments, select the users or groups that should be able to authenticate to Boundary, or select Skip group assignment for now and assign access later.
Select Save.
From the app integration's General tab, record the Client ID and Client secret. These fields map to the auth method's client-id and client-secret attributes.
Locate your Okta domain by selecting the account menu in the top-right corner of the page. The domain is listed beneath your username, for example dev-12345678.okta.com. This string maps to the auth method's issuer attribute.

Note

Unlike some providers, the Okta issuer value must not have a trailing / at the end of the domain, for example https://dev-12345678.okta.com.

Create an OIDC auth method for Okta

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) Your Okta domain, without a trailing /.
- Client ID: (Required) The app integration's Client ID.
- Client Secret: (Required) The app integration's Client secret.
- API URL Prefix: (Required) The address where your Boundary controller is reachable by Okta, 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://YOUR_OKTA_DOMAIN.okta.com" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "https://BOUNDARY_ADDR" \
  -name "okta"

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

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               = "Okta"
  description        = "OIDC auth method for Okta"
  scope_id           = "SCOPE_ID"
  issuer             = "https://YOUR_OKTA_DOMAIN.okta.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 Okta app integration.

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 add a trailing / to the Okta 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_OKTA_DOMAIN.okta.com/" got "https://YOUR_OKTA_DOMAIN.okta.com"

Update the auth method's issuer attribute to remove 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 Okta users based on claims returned by Okta, such as group membership.
Refer to the Okta documentation for information about configuring app integrations and custom authorization server claims.