OpenID Connect (OIDC) is an internet-scale federated identity and authentication protocol built on top of the OAuth 2.0 authorization framework and the JSON Object Signing and Encryption (JOSE) cryptographic system. OIDC builds on top of the OAuth 2.0 authorization protocol to enable a user to authorize a third-party application to access the user’s identity and authentication information.
The OIDC authentication method allows Boundary users to delegate authentication to an OIDC provider. This feature allows Boundary to integrate with popular identity providers like Okta, cloud-hosted active directory services with an OIDC frontend, and cloud identity management systems such as AWS IAM.
Boundary users can create, read, update, and delete new OIDC authentication methods using the Boundary CLI, Admin Console UI or Boundary Terraform provider to enable login. OIDC auth methods can also be utilized for logging into the Admin Console and Desktop applications.
This tutorial provides an example of setting up OIDC with Auth0, Okta, or Azure Active Directory providers and managing those authentication methods from Boundary's Dev mode.
- Authentication workflow
- Provider configuration
- Auth method creation
- Authentication states
- OIDC authentication
A Boundary binary greater than 0.8.0 in your
Installing Terraform 0.13.0 or greater provides an optional workflow for this tutorial. The binary must be available in your
In this tutorial, you will test OIDC integrations using HCP Boundary or by running a Boundary controller locally using dev mode.
The HCP Quickstart tutorials provide an overview of getting started with an HCP Boundary cluster.
If you have an HCP Boundary cluster deployed, the Access HCP Boundary tutorial provides an overview of configuring your local machine to authenticate with your HCP cluster.
This tutorial provides both CLI and UI workflows for setting up OIDC authentication.
To proceed with the CLI workflow:
Log in to the Boundary web UI and copy your org ID by clicking the copy icon.
Open a terminal session and set a environment variable for the org ID.
$ export ORG_ID=<org-id>
In the Boundary web UI, click Orgs in the left navigation menu to return to the global scope, and then click Auth Methods.
Click the copy icon for the Password auth method.
In your terminal set an environment variable named
BOUNDARY_AUTH_METHOD_IDto the copied ID.
$ export BOUNDARY_AUTH_METHOD_ID=<auth-method-id>
Close the Boundary web UI.
Return to the HCP web Portal Boundary page, then click the copy icon for the Cluster URL in the Getting started with Boundary section.
In your terminal, set the
BOUNDARY_ADDRenvironment variable to the copied URL.
$ export BOUNDARY_ADDR=<actual-boundary-address>
Log in with the administrator credentials you created when you deployed the HCP Boundary instance. Enter your password at the
Please enter the password (it will be hidden):prompt.
$ boundary authenticate password -auth-method-id $BOUNDARY_AUTH_METHOD_ID -login-name admin Please enter the password (it will be hidden): Authentication information: Account ID: acctpw_FfOfCS1d5K Auth Method ID: ampw_YfIUt060sp Expiration Time: Fri, 30 Sep 2022 11:25:48 MDT User ID: u_RapeEBo5Uf The token was successfully stored in the chosen keyring and is not displayed here.
You are now logged into your HCP Boundary instance's Global scope via the CLI. This is the default scope for all new Boundary clusters.
To enable an OIDC auth method an administrator must first configure their OIDC provider, and then Boundary. The administrator registers Boundary as a new client with their OIDC provider by providing some values unique to their Boundary deployment. The administrator then configures Boundary with unique client information provided by their OIDC provider during registration. These values must match up for OIDC to work.
The administrator will need to provide a list of Boundary callback URLs when configuring the OIDC provider. The callback URLs route to one of the controllers and must begin with 'https', unless Boundary is in dev mode, where the URLs will route to localhost.
This tutorial will demonstrate working with Auth0, Okta, and Azure Active Directory (Azure AD), three popular providers for OIDC. Many OIDC providers can be integrated with Boundary, and the process outlined in this guide should map to your provider of choice.
A developer account and sample application are required to setup Auth0 as an OIDC provider for Boundary. If you don't have a developer account, sign up for Auth0. It is recommended to use a personal account for testing, and to avoid integrating an account that might already be associated with Auth0. A free account is suitable for testing OIDC integration with Boundary.
First, create an Auth0 user that will be permitted to log into the application that authorizes Boundary.
Once signed up, the Auth0 Dashboard is displayed. Navigate to the User Management view using the sidebar on the left side of the page.
Click + Create User.
Enter the user Email and Password, then Click Create.
The new user's details should be displayed in the User Management Dashboard.
If using Terraform to provision Boundary, copy the user_id value under the Identity Provider Attributes section. Save this value for defining the
An application is what authorizes Auth0 users added in the previous step to connect with Boundary. After creating an application, its configuration details are used to add the OIDC auth method to Boundary.
Navigate to the Applications view using the sidebar on the left side of the page.
From the Applications view, click the + Create Application button.
Select Regular Web Application and give your application a name. This tutorial calls the application Boundary OIDC Test. Click Create.
Once created the browser should redirect to the application settings view. If not, visit Applications using the navigation bar on the left, select the new application and visit its Settings view.
Scroll down to the Application URIs section.
Create a callback URL by entering the HCP Boundary cluster address, followed by
/v1/auth-methods/oidc:authenticate:callbackunder the Allowed Callback URLs field. For example,
This value is also printed later on when creating the OIDC method with the Boundary CLI, but is fixed and can be entered into the Auth0 provider settings ahead of time.
Lastly, locate the Allowed Logout URLs section directly below, and enter the HCP Boundary Cluster address followed by
Make sure your config matches the image shown below.
Three important values are listed at the top of the Settings view for use when configuring OIDC with Boundary.
- Client ID
- Client Secret
Keep this page open to refer to these values in the next steps.
Authentication is the process of establishing a user's identity. The user initiates this process by selecting an auth method.
When the user selects an OIDC auth method, the user's client sends a request to the system and includes additional data about the client itself. The system then returns two URLs: an OIDC authentication request URL and a Boundary token request URL.
If the user's client is a web browser, the client stores the Boundary token request URL in local storage then redirects the page to the OIDC authentication request URL. If the user's client is not a web browser, the client opens a web browser to the OIDC authentication request URL and begins polling the Boundary token request URL.
The user interacts with the OIDC provider to prove their identity using the browser window opened by the user's client. Once the OIDC provider has authenticated the user's identity, it redirects the browser window back to Boundary. The user's client then retrieves a Boundary token from the request URL.
To get started, an authentication method must be created for the provider of choice.
To set up a new auth method for your provider you will need the following from your provider's application settings:
Auth methods can be created via the CLI, the Admin Console, or using Terraform.
Start by ensuring you are logged in to Boundary as the admin user.
For Auth0, these settings map to the following:
With these values you gathered from the Auth0 application settings above a new OIDC auth method can be created.
Start by setting the Client ID and Client Secret as environment variables.
$ export CLIENT_ID=<COPIED-CLIENT-ID>; \ export CLIENT_SECRET=<COPIED-CLIENT-SECRET>
$ export CLIENT_ID=zaxJLTZh3n14WqSQ7qQ9onuIVRDaZdzz; \ export CLIENT_SECRET=t35c9NNw1aZ8haEKFJbJF0lauMOSp5UNPovUJXo8Ea2sPZAR1DszEowX-6-lg-Xr
These values will be passed to Boundary when creating the new OIDC auth method.
api-url-prefix must be set to the URL of your Boundary
cluster. Select HCP or Dev mode to see an example.
For HCP the
api-url-prefix is set to the HCP cluster's address found in the
HCP cloud portal. This value is identical to the
variable set when logging in to the CLI (for example,
following example passes this shell variable to the
create oidc command, but the cluster address can also be passed directly.
$ boundary auth-methods create oidc \ -issuer "https://ISSUER_URL" \ -client-id "$CLIENT_ID" \ -client-secret "$CLIENT_SECRET" \ -signing-algorithm RS256 \ -api-url-prefix "$BOUNDARY_ADDR" \ -name "auth0"
signing-algorithmis commonly set to
api-url-prefixis used by the OIDC provider in the authentication flow, and should match the HCP Boundary cluster's address. The
BOUNDARY_ADDRvariable is passed in this example.
$ boundary auth-methods create oidc \ -issuer "https://dev-1sdl8c0z.us.auth0.com" \ -client-id "$CLIENT_ID" \ -client-secret "$CLIENT_SECRET" \ -signing-algorithm RS256 \ -api-url-prefix "$BOUNDARY_ADDR" \ -name "auth0" Auth Method information: Created Time: Fri, 09 Sep 2022 11:11:55 MDT ID: amoidc_40fr5jkLpk Name: auth0 Type: oidc Updated Time: Fri, 09 Sep 2022 11:11:55 MDT Version: 1 Scope: ID: global Name: global Type: global Authorized Actions: no-op read update delete change-state authenticate Authorized Actions on Auth Method's Collections: accounts: create list managed-groups: create list Attributes: api_url_prefix: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud callback_url: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback client_id: zaxJLTZh3n14WqSQ7qQ9onuIVRDaZdzz client_secret_hmac: Qc3i8NdnTP6rl4JANIg-a2GXgRW5rEKTp2ReIK_BOng issuer: https://dev-1sdl8c0z.us.auth0.com signing_algorithms: [RS256] state: inactive
The new authentication method has now been created. Under the Attributes output, notice the state is set to inactive. Before it can be used the new auth method must be switched to an active state.
Copy the new OIDC Auth Method ID from the output.
Next we will review the available authentication states and activate the new OIDC auth method.
An OIDC auth method can be in one of several different states: Inactive, Active Private, and Active Public. The current state of an OIDC auth method affects how endpoints respond to requests and, in some cases, whether access to an endpoint requires authentication.
- MakeInactive transitions an OIDC auth method from either the Active Private or the Active Public state into the Inactive state.
- MakePrivate transitions an OIDC auth method from either the Inactive or the Active Public state into the Active Private state. If transitioning from the Inactive state, the transition will only succeed if the configuration is valid.
- MakePublic transitions an OIDC auth method from either the Inactive or the Active Private state into the Active Public state. If transitioning from the Inactive state, the transition will only succeed if the configuration is valid.
Three different states exist for an authentication method:
inactiveusers can not authenticate with inactive auth methods and are not be listed for unauthenticated users.
active-privateusers can authenticate with active-private auth methods and are not be listed for unauthenticated users.
active-publicusers can authenticate active-public auth methods and are listed for unauthenticated users.
Before changing the state of an auth-method, Boundary will retrieve the Provider’s discovery document for the auth method’s issuer and attempt to validate the auth-method’s configuration against this published information. If Boundary is unable to validate the configuration an error is returned and the state change is not made.
If a change is made from active-public or active-private to inactive, all in-flight authentications will succeed unless the auth method’s configuration is modified while the request is in-flight.
When changing an auth method's state using
boundary auth-methods change-state
-disable-discovered-config-validation flag is used to disable validation
against the provider’s published discovery document. This allows for the very
rare occurrence when the Provider has published an invalid discovery document.
Now that a new OIDC method has been created, it can be activated and assigned as the default login type for the global scope.
Currently the login type is set as inactive, and won't allow authentication.
$ boundary authenticate oidc -auth-method-id amoidc_oHt4HQFCrN Error from controller when performing authentication start Error information: Kind: Internal Message: authmethod_service.(Service).authenticateOidcStart: Error generating parameters for starting the OIDC flow.: unknown: error #500 Status: 500 context: Error from controller when performing authentication start
Auth methods can be activated via the CLI, Admin Console, or using Terraform.
If you attempt to enable the the auth method by updating its state to public, an error will be produced.
$ boundary auth-methods change-state oidc -id amoidc_oHt4HQFCrN -state active-public Error from controller when performing change-state on oidc-type auth method Error information: Kind: Internal Message: oidc.(Repository).MakePublic: oidc.(Repository).transitionAuthMethodTo: oidc.(Repository).ValidateDiscoveryInfo: oidc.convertToProvider: AuthMethod cannot be converted to a valid OIDC Provider: parameter violation: error #100: NewProvider: unable to create provider: oidc: issuer did not match the issuer returned by provider, expected "https://dev-1vdl8c0q.us.auth0.com" got "https://dev-1vdl8c0q.us.auth0.com/" Status: 500 context: Error from controller when performing change-state on oidc-type auth method
Notice the 500 error, and the discrepancy between the expected URLs. The issuer
URL needs to be updated to include a
/ at the end.
Additionally, set the
-max-age option to
0, which will force the user to
re-authenticate if they are already logged in with the current browser session.
$ boundary auth-methods update oidc -id amoidc_oHt4HQFCrN -issuer "https://ISSUER_URL/" -max-age 0
$ boundary auth-methods update oidc -id amoidc_oHt4HQFCrN -issuer "https://dev-1vdl8c0q.us.auth0.com/" -max-age 0 Auth Method information: Created Time: Thu, 06 May 2021 16:39:33 MDT ID: amoidc_oHt4HQFCrN Name: auth0 Type: oidc Updated Time: Thu, 06 May 2021 16:58:21 MDT Version: 2 Scope: ID: global Name: global Type: global Authorized Actions: no-op read update delete change-state authenticate Authorized Actions on Auth Method's Collections: accounts: create list Attributes: api_url_prefix: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud callback_url: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback client_id: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx client_secret_hmac: ayJRYSCphzxcHiKJvBrnDVtz1yiR958ejQuRGdQJMeM issuer: https://dev-1vdl8c0q.us.auth0.com/ max_age: 0 signing_algorithms: [RS256] state: inactive
The auth method's state can now be set to active-public.
$ boundary auth-methods change-state oidc -id amoidc_oHt4HQFCrN -state active-public Auth Method information: Created Time: Fri, 09 Sep 2022 11:11:55 MDT ID: amoidc_oHt4HQFCrN Name: auth0 Type: oidc Updated Time: Fri, 09 Sep 2022 11:41:33 MDT Version: 3 Scope: ID: global Name: global Type: global Authorized Actions: no-op read update delete change-state authenticate Authorized Actions on Auth Method's Collections: accounts: create list managed-groups: create list Attributes: api_url_prefix: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud callback_url: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback client_id: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx client_secret_hmac: Qc3i8NdnTP6rl4JANIg-a2GXgRW5rEKTp2ReIK_BOng issuer: https://dev-1vdl8c0q.us.auth0.com/ max_age: 0 signing_algorithms: [RS256] state: active-public
And the login type will now allow be allowed.
Global and organization scopes may have auth methods in Boundary, and each scope has one primary auth-method ID. Boundary will automatically create a user upon first successful authentication via the scope’s primary auth method, which will be used by scopes with only one auth method available.
When migrating the database, Boundary will produce a log of any auth methods which resulted in no primary auth method being set for the scope.
Set the new OIDC auth method as the primary auth method for the global scope.
$ boundary scopes update -primary-auth-method-id amoidc_q7jAdI1QgA -id global Scope information: Created Time: Thu, 18 Aug 2022 10:55:18 MDT Description: Global Scope ID: global Name: global Primary Auth Method ID: amoidc_q7jAdI1QgA Updated Time: Mon, 12 Sep 2022 14:44:54 MDT Version: 5 Scope (parent): ID: global Name: global Type: global Authorized Actions: no-op read update delete Authorized Actions on Scope's Collections: auth-methods: create list auth-tokens: list groups: create list roles: create list scopes: create list users: create list workers: create:worker-led list
Now try authenticating using the newly created OIDC auth method.
$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgA Opening returned authentication URL in your browser...
A browser tab should automatically open and prompt you to log in with your Auth0 user account credentials.
After successful authentication, return to your terminal and notice the Authentication information that is printed.
$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgA Opening returned authentication URL in your browser... Authentication information: Account ID: acctoidc_oztPFBFesH Auth Method ID: amoidc_oHt4HQFCrN Expiration Time: Thu, 13 May 2021 17:01:11 MDT User ID: u_JCRQP3ID7l The token was successfully stored in the chosen keyring and is not displayed here.
With the OIDC provider configured, Boundary users can authenticate via the CLI, Admin Console or Boundary Desktop app. Boundary administrators will usually follow a CLI or Admin Console workflow, while clients and end-users can use the CLI or Desktop application.
boundary authenticate oidc command will launch a browser session to enable
authentication via the configured provider.
$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgA Opening returned authentication URL in your browser...
The provider's login page should open in a browser tab, prompting for the username and password for the account used to configure the Boundary OIDC Test application. Below is an example of the Auth0 provider's login prompt.
Trouble logging in? If you receive an Unsuccessful authentication
message from Boundary, try logging out of the provider in your browser, then run
boundary authenticate oidc again and re-authenticate. This is especially
important if you created a new provider user in the Create a
user section. Ensure you are logging in as the correct user.
After logging in your terminal should confirm the Account and User IDs.
$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgA Opening returned authentication URL in your browser... Authentication information: Account ID: acctoidc_f0wWsno9jQ Auth Method ID: amoidc_q7jAdI1QgA Expiration Time: Wed, 21 Apr 2021 15:02:38 MDT User ID: u_zAfnbL9b7y The token was successfully stored in the chosen keyring and is not displayed here.
The user is now authenticated via OIDC. Listing various scope items would show this user is not able to access most resources by default. The OIDC user could be updated to include new privileges if an admin user assigns it to a role.
You have now completed OIDC integration via the CLI!
If you plan on completing the Manage IdP Groups tutorial, leave the current configuration running. Successful completion of this tutorial is a pre-requisite for the Manage IdP Groups tutorial.
If you are not continuing on to the next tutorial, tear down the environment:
1. Remove any unwanted test auth methods from your HCP Boundary Cluster. This can be done by deleting the auth method in the Admin Console UI, or by providing your auth method ID using the CLI:
$ boundary auth-methods delete -id amoidc_40fr5jkLpk
2. Delete any sample applications from your OIDC provider.
This tutorial provided steps for configuring Auth0, Okta, or Azure AD sample applications as Boundary auth methods. Revisit those providers and delete any sample applications you no longer need.
3. Delete any test users from your OIDC provider.
This tutorial created sample users within Auth0, Okta or Azure AD to authenticate via the CLI, Admin Console or Desktop app. Revisit the provider settings and remove any test users created for this tutorial.
4. Delete any test client secrets from your OIDC provider.
This tutorial may have created client secrets within Auth0, Okta or Azure AD. Revisit the provider settings and remove any client secrets created for this tutorial.
This tutorial demonstrated the steps to add an OIDC authentication method and create a new user. You set up a provider application to authenticate with Boundary, and verified that you can authenticate using the newly created user.
Next, check out the Manage IdP Groups tutorial to learn about automatically managing group membership claims with OIDC auth methods.