• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Boundary
  • Install
  • Tutorials
  • Documentation
  • API
  • Try Cloud(opens in new tab)
  • Sign up
Secure Access Management

Skip to main content
8 tutorials
  • HCP Credential Injection with Private Vault
  • OIDC Authentication
  • Manage OIDC IdP Groups
  • HCP Boundary Vault Credential Brokering Quickstart
  • OSS Vault Credential Brokering Quickstart
  • Dynamic Host Catalogs on AWS
  • Dynamic Host Catalogs on Azure
  • Securing Access to Azure SQL Database

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Boundary
  3. Tutorials
  4. Secure Access Management
  5. OIDC Authentication

OIDC Authentication

  • 18min

  • TerraformTerraform
  • BoundaryBoundary

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.

OIDC authentication methods overview

  1. Authentication workflow
  2. Provider configuration
  3. Auth method creation
  4. Authentication states
  5. OIDC authentication

Prerequisites

  • A Boundary binary greater than 0.8.0 in your PATH

  • This tutorial assumes you can connect to an HCP Boundary cluster or launch Boundary in dev mode.

  • An Auth0, Okta, or Azure test account. The associated email address should not be tied to another SSO method, so use of a personal account is recommended.

  • Installing the Boundary Desktop App provides an optional workflow for this tutorial. The 1.2.0 version or above is required for OIDC support.

  • Installing Terraform 0.13.0 or greater provides an optional workflow for this tutorial. The binary must be available in your PATH.

Get setup

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:

  1. 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>
    
  2. 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_ID to the copied ID.

    $ export BOUNDARY_AUTH_METHOD_ID=<auth-method-id>
    

    Close the Boundary web UI.

  3. 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_ADDR environment variable to the copied URL.

    $ export BOUNDARY_ADDR=<actual-boundary-address>
    
  4. 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 proceed with the UI workflow:

  1. Open the Admin Console UI by entering your HCP Boundary Cluster URL into a browser (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud).

  2. Enter the admin username and password you created when you deployed the new instance and click Authenticate.

HCP Admin UI

You are now logged into your HCP Boundary instance's Global scope via the web UI. This is the default scope for all new Boundary clusters. You can now proceed to the Providers section to proceed with the Admin Console UI workflow.

To proceed with the Terraform workflow:

The following values are needed to set up the Boundary Terraform provider. The password_auth_method_login_name and password_auth_method_password are created when first setting up HCP Boundary, and the others can be gathered from the HCP portal or the Boundary Admin Console UI.

  • addr (from HCP portal)
  • auth_method_id (from Boundary Admin Console UI)
  • password_auth_method_login_name (from initial Boundary Cluster creation)
  • password_auth_method_password (from initial Boundary Cluster creation)
  • scope_id (global scope from Boundary Admin Console UI)

Locate these values and have them ready for setting up the Terraform config files later on.

Start Boundary in dev mode:

$ boundary dev
==> Boundary server configuration:

        [Controller] AEAD Key Bytes: hdcjQ5gegRbttzQ66D5GJjcxB+xtdHzL
          [Recovery] AEAD Key Bytes: E1/gdhTuDyhsvIm+tkQR0i4m/uSRrd5A
       [Worker-Auth] AEAD Key Bytes: gwo86AYxBlbPCLsw9lsBzZ4Fd7adcydw
               [Recovery] AEAD Type: aes-gcm
                   [Root] AEAD Type: aes-gcm
    [Worker-Auth-Storage] AEAD Type: aes-gcm
            [Worker-Auth] AEAD Type: aes-gcm
                                Cgo: disabled
     Controller Public Cluster Addr: 127.0.0.1:9201
             Dev Database Container: hardcore_keller
                   Dev Database Url: postgres://postgres:password@localhost:55000/boundary?sslmode=disable
         Generated Admin Login Name: admin
           Generated Admin Password: password
          Generated Host Catalog Id: hcst_1234567890
                  Generated Host Id: hst_1234567890
              Generated Host Set Id: hsst_1234567890
      Generated Oidc Auth Method Id: amoidc_1234567890
             Generated Org Scope Id: o_1234567890
  Generated Password Auth Method Id: ampw_1234567890
         Generated Project Scope Id: p_1234567890
                Generated Target Id: ttcp_1234567890
  Generated Unprivileged Login Name: user
    Generated Unprivileged Password: password
                         Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")
                         Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")
                         Listener 3: tcp (addr: "127.0.0.1:9203", max_request_duration: "1m30s", purpose: "ops")
                         Listener 4: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")
                          Log Level: info
                              Mlock: supported: false, enabled: false
                            Version: Boundary v0.10.3
                        Version Sha: d9eba38993eb70820a396894f2f1e28601d13c3d
         Worker Auth Current Key Id: folic-obliged-dude-stroller-skinless-eloquence-legible-dispense
   Worker Auth Registration Request: GzusqckarbczHoLGQ4UA25uSRm41paoR5HikgcBsCT4PMDFT7StpsFy5xjiWJwxszReKwcfGniKLcdpQto5HjhH3PqmdLU8fdT9kM7RMLiyzLKWdLqVWBhhdUiEy7Re2ConJcGWdHsGK7Th6zVQ3SXjqND3dQ3ytcVtAhdEznJQ58ib6HoMvpMTs66TS5ULCBXxpQ1u2syC6ChNPEPbaSpQd9pKWjPcPRVDjKpMzp6cjw9LZSPxBdadM81f7yS3voWoM5yMciXdUW6rqSMaP1NxRvQUAdhVQsM1ZqGLHNV
           Worker Auth Storage Path: /var/folders/8g/4dnhwwzx2d771tkklxwrd0380000gp/T/nodeenrollment1533264699
           Worker Public Proxy Addr: 127.0.0.1:9202

==> Boundary server started! Log data will stream in below:

{
  "id": "GypYTtKfJI",
  "source": "https://hashicorp.com/boundary/localmachine/controller+worker",
  "specversion": "1.0",
  "type": "system",
  "data": {
    "version": "v0.1",
    "op": "github.com/hashicorp/boundary/internal/observability/event.(*HclogLoggerAdapter).writeEvent",
    "data": {
      "@original-log-level": "none",
      "@original-log-name": "aws",
      "msg": "configuring client automatic mTLS"
    }
  },
  "datacontentype": "text/plain",
  "time": "2022-09-06T14:14:37.939433-06:00"
}
...
... More log output ...
...

Leave dev mode running in the current session, and open a new terminal window or tab.

Authenticate to the local Boundary dev server. Enter the password password when prompted.

$ boundary authenticate password -auth-method-id ampw_1234567890 -login-name admin
Please enter the password (it will be hidden): <password>

Authentication information:
  Account ID:      acctpw_1234567890
  Auth Method ID:  ampw_1234567890
  Expiration Time: Wed, 14 Jul 2021 11:38:18 MDT
  User ID:         u_1234567890

The token was successfully stored in the chosen keyring and is not displayed here.

Providers

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.

Create a user

First, create an Auth0 user that will be permitted to log into the application that authorizes Boundary.

  1. Once signed up, the Auth0 Dashboard is displayed. Navigate to the User Management view using the sidebar on the left side of the page.

    Auth0 Dashboard

  2. Click + Create User.

    Auth0 Dashboard

  3. Enter the user Email and Password, then Click Create.

    Auth0 Dashboard

  4. The new user's details should be displayed in the User Management Dashboard.

    Auth0 Dashboard

  5. If using Terraform to provision Boundary, copy the user_id value under the Identity Provider Attributes section. Save this value for defining the oidc_user subject later on.

    Auth0 Dashboard

Create an application

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.

  1. Navigate to the Applications view using the sidebar on the left side of the page.

  2. From the Applications view, click the + Create Application button.

    Auth0 Create Application

  3. Select Regular Web Application and give your application a name. This tutorial calls the application Boundary OIDC Test. Click Create.

    Auth0 Name Web Application

  4. 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:callback under the Allowed Callback URLs field. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback.

    https://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
    

    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 :3000 (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud:3000)

    https://BOUNDARY_ADDR:3000
    

    Make sure your config matches the image shown below.

    Auth0 Application Settings

    Paste the following callback URL under the Allowed Callback URLs field.

    http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    

    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 http://localhost:3000 because Boundary is running in dev mode.

    Make sure your config matches the image shown below.

    Auth0 Application Settings

  5. Three important values are listed at the top of the Settings view for use when configuring OIDC with Boundary.

    • Domain
    • Client ID
    • Client Secret

    Keep this page open to refer to these values in the next steps.

    Auth0 Application Settings

A customer identity account and sample application are required to setup Okta as an OIDC provider for Boundary. If you don't have a account, sign up for Okta. It is recommended to use a personal account for testing, and to avoid integrating an email address that might already be associated with Okta. A free account is suitable for testing OIDC integration with Boundary.

Create a user

You have the option of creating a dedicated user for testing the OIDC authentication with.

If you want to use the default user, skip user creation and head to the next section on creating an application.

Note: If you choose to create a new Okta user outside of the default account, note that you may need to log out of the administrative account and log in as the new user when authenticating via Boundary later on.

Create an Okta user that will be permitted to log into the application that authorizes Boundary. This is managed using the "Directory" dashboard.

  1. Once signed up, the Okta Admin Dashboard is displayed, or can be visited at the /admin endpoint for your Okta domain.

    Open the Directory menu using the sidebar on the left side of the page and click on People.

    Okta Dashboard

  2. Click Add person.

    Okta Add Person

  3. Enter the user details, Email and change the Password field to "Set by admin". Then enter the user's password, and Click Save.

    Okta Create User

  4. The new user's details should be displayed in the People Dashboard.

  5. If using Terraform to provision Boundary, select the newly created user, then copy the URL endpoint (excluding any trailing # symbol). This is the user ID. Save this value for defining the oidc_user subject later on.

    Auth0 Dashboard

Create an application

An application is what authorizes Okta 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.

  1. Navigate to the Applications view using the sidebar on the left side of the page.

  2. From the Applications view, click the Add Application button.

    Okta Create Application

  3. In the Add Application Dashboard, click the Create New App button.

    Okta Create New App

  4. In the "Create a New Application Integration" popup, select OpenID Connect for the "Web" platform and click Create.

    Okta Create New App

  5. From the "Create OpenID Connect App Integration" page, give your application a name. This tutorial calls the application Boundary OIDC Test.

    You will also need to provide a Login redirect URIs. Set this value to the HCP Boundary Cluster address you copied from the HCP portal. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud.

    https://BOUNDARY_ADDR
    

    You will also need to construct a Logout redirect URI by appending :3000 at the end of the HCP Boundary Cluster address. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud:3000.

    https://BOUNDARY_ADDR:3000
    

    Make sure the fields shown in the screenshot below match your config, and then click Save.

    Okta Name Application

    You will also need to provide a Login redirect URIs of http://localhost:9200.

    http://localhost:9200
    

    and a a Logout redirect URIs of http://localhost:3000.

    http://localhost:3000
    

    Make sure the fields shown in the screenshot below match your config, and then click Save.

    Okta Name Application

  6. Once saved 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 Assignments setting view.

    Click Assign and select Assign to People.

    Okta Name Application

    In the "Assign Boundary OIDC Test to People" pop-up, click the Assign button next to the user name you want to associate with the application. If you did not create a new user in the previous step, this will be the default Okta login account.

    Okta Name Application

    Scroll down to the bottom of the "Assign Boundary OIDC Test to People" form, click Save and Go Back and then Done. The user should now be listed under the Boundary OIDC Test application's "Assignments" tab.

  7. Navigate to the Boundary OIDC Test application's General setting view. Click Edit under the "General Settings" section.

    Scroll down to the Login section.

    Construct a callback URL and paste it under the Sign-in redirect URIs field. The callback URL is created by appending /v1/auth-methods/oidc:authenticate:callback after your HCP Boundary Cluster URL. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback.

    http://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
    

    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 Okta provider settings ahead of time.

    Set the Initiate login URI to the same callback URL value.

    Lastly, construct the Logout redirect URIs by appending :3000 to the end of your HCP Boundary Cluster URl. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud:3000

    https://BOUNDARY_ADDR:3000
    

    Click Save. Make sure your config matches the image shown below.

    Okta Application Settings

    Paste the following callback URL under the Sign-in redirect URIs field.

    http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    

    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 Okta provider settings ahead of time.

    Set the Initiate login URI to the same callback URL value.

    Lastly, ensure that the Logout redirect URIs is set to http://localhost:3000 for this tutorial, because Boundary is running in dev mode.

    http://localhost:3000
    

    Click Save. Make sure your config matches the image shown below.

    Okta Application Settings

  8. Scroll to the top of the Boundary OIDC Test application's General setting view.

    Okta Application Settings

    Three important values are listed here for use when configuring OIDC with Boundary.

    • Okta Domain
    • Client ID
    • Client secret

    Keep this page open to refer to these values in the next steps.

An Azure account and sample application are required to setup Azure AD as an OIDC provider for Boundary. If you don't have an account, sign up for Azure. It is recommended to use a personal Microsoft account for testing, and to avoid integrating an account that might already be associated with Azure. A free account is suitable for testing OIDC integration with Boundary. Please note that you are responsible for any charges incurred by following the steps in this tutorial.

Create a user

First, create an Azure AD user that will be permitted to log into the application that authorizes Boundary.

  1. Once signed up, it may take some time for a new tenant to become available. Once available, sign in to the Azure Portal. Navigate to the Azure Active Directory view using the sidebar on the left side of the page.

    Azure Portal

  2. You will need an Azure AD tenant that is permitted to log into the application that authorizes Boundary. If no tenants are listed in the Azure AD view, create a new tenant by following these instructions in the Azure docs. You can also use a pre-existing tenant if one is already set up. This tutorial uses the Boundary organization and the boundaryoidc domain name.

  3. Next, create a new user. In the tenant sidebar menu, select Users from the Manage section. Click the + New User button.

    Azure Users Portal

  4. Enter the User name, and under Password enable the Let me create the password option. Define a password, then click Create.

    Azure Create User

  5. The new user should then be displayed under the Azure AD Users portal. This tutorial created a user named admin with the User Principle Name admin@boundaryoidc.onmicrosoft.com.

    Azure Create User

  6. If using Terraform to provision Boundary, select the newly created user to view its details. Copy the Object ID value under the Identity section. Save this value for defining the oidc_user subject later on.

    Azure Create User

Create an application

An application is what authorizes Azure AD 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. This content borrows heavily from the Azure register an application documentation.

  1. From the Azure AD view, select App Registrations using the sidebar on the left side of the page.

  2. From the Applications view, click the + New Registration button.

    Azure Create Application

  3. Select New Registration, give your application a name and select its tenancy model. For this proof-of-concept tutorial, select single-tenant. This tutorial calls the application Boundary OIDC Test.

    Construct a callback URI and paste it under the Sign-in redirect URIs field. The callback URI is created by appending /v1/auth-methods/oidc:authenticate:callback after your HCP Boundary Cluster URL. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback.

    Paste the callback URI in the Web field.

    http://BOUNDARY_ADDR/v1/auth-methods/oidc:authenticate:callback
    

    Click Register.

    Azure New App Registration

    Once registered, you will be taken to the properties page for your new app registration.

    Provide the redirect URI, which is http://localhost:9200/v1/auth-methods/oidc:authenticate:callback when Boundary is running in dev mode.

    Paste the following redirect URI in the Web field.

    http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    

    Click Register.

    Azure New App Registration

    Once registered, you will be taken to the properties page for your new app registration.

  4. Select Certificates & Secrets from the Azure AD menu on the left. Click New client secret and fill out the secret details. This tutorial describes the secret as Boundary OIDC test secret.

    Click Add.

    Azure New Secret

    Azure New Secret

    Copy the client Secret value and store it for use later. Ensure you grab the Value, not the Secret ID.

    Azure New Secret

  5. Select Authentication from the Azure AD menu on the left.

    Scroll down and locate the Front-channel logout URL. The logout URL ensures session logouts are handled correctly.

    Construct the logout URL by appending :3000 to the end of your HCP Boundary Cluster URl. For example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud:3000

    https://BOUNDARY_ADDR:3000
    

    Double-check that the Redirect URI entered when the app was registered is correct. Make sure your config matches the image shown below.

    Click Save.

    Azure Redirect URIs

    Scroll down and locate the Front-channel logout URL and enter https://localhost:3000. This ensures session logouts are handled correctly with Boundary running in dev mode.

    Double-check that the Redirect URI entered when the app was registered is correct. Make sure your config matches the image shown below.

    Click Save.

    Azure Redirect URIs

  6. Lastly, navigate back to the App overview view using the menu on the left.

    From this view, copy the Directory (Tenant) ID and the Application (client) ID.

    Azure App Settings

    You will also need to construct the application Issuer URL.

    An Azure AD OIDC identity provider issuer will typically have format of https://sts.windows.net/Tenant_ID/, but it may vary depending on your account.

    Note: You may need to refer to Azure OIDC documentation for latest OIDC endpoint schemas.

    Three important values are needed when configuring OIDC with Boundary.

    • Issuer
    • Client ID
    • Client Secret

    The following format is used for these values:

    • issuer -> https://sts.windows.net/Tenant_ID/ Be sure to include a trailing / at the end
    • client-id -> Application (client) ID)
    • client-secret -> Client Secret value

    For example, this tutorial uses the following values:

    • Issuer: https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/
    • Client ID: a4d21a76-e08c-4d8d-8c47-e1c423ee4d11
    • Client Secret: X9u~u58--~rWLR4Q9i1-PtdZOi_s04~9O-

    Keep these values in a safe place for use in the next steps.

Auth method creation

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.

Create auth method for the provider

To set up a new auth method for your provider you will need the following from your provider's application settings:

  • issuer
  • client-id
  • client-secret

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:

  • issuer -> Domain
  • client-id -> Client ID
  • client-secret -> Client Secret

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>

Example:

$ 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.

Note: The 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 BOUNDARY_ADDR environment variable set when logging in to the CLI (for example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud). The following example passes this shell variable to the boundary auth-methods 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"
  • The signing-algorithm is commonly set to RS256.

  • The api-url-prefix is used by the OIDC provider in the authentication flow, and should match the HCP Boundary cluster's address. The BOUNDARY_ADDR variable is passed in this example.

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

For Dev mode the api-url-prefix is set to the local controller's address of http://localhost:9200.

$ boundary auth-methods create oidc \
  -issuer "https://ISSUER_URL" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "http://localhost:9200" \
  -name "auth0"
  • The signing-algorithm is commonly set to RS256.

  • The api-url-prefix is used by the OIDC provider in the authentication flow, and should match the Boundary controller's address, set to http://localhost:9200 in this example.

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 "http://localhost:9200" \
   -name "auth0"

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:39:33 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

  Attributes:
    api_url_prefix:     http://localhost:9200
    callback_url:       http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    client_id:          zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx
    client_secret_hmac: ayJRYSCphzxcHiKJvBrnDVtz1yiR958ejQuRGdQJMeM
    issuer:             https://dev-1vdl8c0q.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.

For Okta, these settings map to the following:

  • issuer -> Okta Domain
  • client-id -> Client ID
  • client-secret -> Client secret

With these values you gathered from Okta's 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>

Example:

$ export CLIENT_ID=0oal6fr0tPGZ0DSbr6d5; \
export CLIENT_SECRET=4BStQlbuTTrh5P-JhGAKW2FVPh48idEbFLKGGKJJ

These values will be passed to Boundary when creating the new OIDC auth method.

Note: The 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 BOUNDARY_ADDR environment variable set when logging in to the CLI (for example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud). The following example passes this shell variable to the boundary auth-methods 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 "okta"
  • The signing-algorithm is commonly set to RS256.

  • The api-url-prefix is used by the OIDC provider in the authentication flow, and should match the HCP Boundary cluster's address. The BOUNDARY_ADDR variable is passed in this example.

Example:

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

Auth Method information:
  Created Time:         Fri, 09 Sep 2022 11:54:33 MDT
  ID:                   amoidc_qlt29w7c8h
  Name:                 okta
  Type:                 oidc
  Updated Time:         Fri, 09 Sep 2022 11:54:33 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://e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3.boundary.hashicorp.cloud
    callback_url:       https://e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback
    client_id:          0oal6fr0tPGZ0DSbr5d6
    client_secret_hmac: c5op-CkYUuEb7d-ubOjc5UBT_YqVP-CCu2pRL7EH8ls
    issuer:             https://dev-1944432.okta.com
    signing_algorithms: [RS256]
    state:              inactive

For Dev mode the api-url-prefix is set to the local controller's address of http://localhost:9200.

$ boundary auth-methods create oidc \
  -issuer "https://ISSUER_URL" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "http://localhost:9200" \
  -name "okta"
  • The signing-algorithm is commonly set to RS256.

  • The api-url-prefix is used by the OIDC provider in the authentication flow, and should match the Boundary controller's address, set to http://localhost:9200 in this example.

Example:

$ boundary auth-methods create oidc \
  -issuer "https://dev-1944432.okta.com" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "http://localhost:9200" \
  -name "okta"


Auth Method information:
  Created Time:         Mon, 10 May 2021 15:12:15 MDT
  ID:                   amoidc_tublWgOrr6
  Name:                 okta
  Type:                 oidc
  Updated Time:         Mon, 10 May 2021 15:12:15 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

  Attributes:
    api_url_prefix:     http://localhost:9200
    callback_url:       http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    client_id:          0oal6fr0tPGZ0DSbr5d6
    client_secret_hmac: D5RCKhf9AMulUFM3NcAwxz-K4jqnheJnEgqREVWFc0Q
    issuer:             https://dev-1944432.okta.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.

For Azure AD, these settings map to the following:

  • issuer -> https://sts.windows.net/Tenant_ID/ Be sure to include a trailing / at the end
  • client-id -> Application (client) ID)
  • client-secret -> Client Secret value

With these values you gathered from setting up an Azure AD application, 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>

Example:

$ export CLIENT_ID=a4d21a76-e08c-4d8d-8c47-e1c423ee4d11; \
export CLIENT_SECRET=X9u~u58--~rWLR4Q9i1-PtdZOi_s04~91-

These values will be passed to Boundary when creating the new OIDC auth method.

Note: The 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 BOUNDARY_ADDR environment variable set when logging in to the CLI (for example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud). The following example passes this shell variable to the boundary auth-methods create oidc command, but the cluster address can also be passed directly.

$ boundary auth-methods create oidc \
  -issuer "https://sts.windows.net/TENANT_ID/" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "$BOUNDARY_ADDR" \
  -name "azure"
  • The signing-algorithm is commonly set to RS256.

  • The api-url-prefix is used by the OIDC provider in the authentication flow, and should match the HCP Boundary cluster's address. The BOUNDARY_ADDR variable is passed in this example.

Example:

$ boundary auth-methods create oidc \
  -issuer "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "$BOUNDARY_ADDR" \
  -name "azure"

Auth Method information:
  Created Time:         Mon, 12 Sep 2022 13:40:38 MDT
  ID:                   amoidc_rFqhKQlrvn
  Name:                 azure
  Type:                 oidc
  Updated Time:         Mon, 12 Sep 2022 13:40:38 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://e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3.boundary.hashicorp.cloud
    callback_url:       https://e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback
    client_id:          09443893-b713-4dbf-a417-8882bff4168d
    client_secret_hmac: SEOTy9cZgs7BTYRknG44rFxQQ64xY3qp2i1iEDpkvX0
    issuer:             https://sts.windows.net/0e3e2e88-8caf-41ca-b4da-e3b33b6c52ec/
    signing_algorithms: [RS256]
    state:              inactive

For Dev mode the api-url-prefix is set to the local controller's address of http://localhost:9200.

$ boundary auth-methods create oidc \
  -issuer "https://sts.windows.net/TENANT_ID/" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "http://localhost:9200" \
  -name "azure"
  • The signing-algorithm is commonly set to RS256.

  • The api-url-prefix is used by the OIDC provider in the authentication flow, and should match the Boundary controller's address, set to http://localhost:9200 in this example.

Example:

$ boundary auth-methods create oidc \
  -issuer "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/" \
  -client-id "$CLIENT_ID" \
  -client-secret "$CLIENT_SECRET" \
  -signing-algorithm RS256 \
  -api-url-prefix "https://localhost:9200" \
  -name "azure"

Auth Method information:
  Created Time:         Mon, 07 Jun 2021 14:28:45 MDT
  ID:                   amoidc_rFqhKQlrvn
  Name:                 azure
  Type:                 oidc
  Updated Time:         Mon, 07 Jun 2021 14:28:45 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

  Attributes:
    api_url_prefix:     https://localhost:9200
    callback_url:       https://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    client_id:          a4d21a76-e08c-4d8d-8c47-e1c423ee4d11
    client_secret_hmac: SOhcIKhF0rBbe_Xc-2eHY0BNfIc3AO8GkQ0iohgLT_4
    issuer:             https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/
    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.

Next we will review the available authentication states and activate the new OIDC auth method.

The Boundary Admin Console provides a UI for creating and managing OIDC resources, including auth methods.

Open the Admin Console UI by entering your HCP Boundary Cluster URL into a browser (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud).

Enter the admin username and password you created when you deployed the new instance and click Authenticate.

Open the Admin Console UI by entering the Dev Controller URL of http://localhost:9200 into a browser.

Enter the admin username admin and password password and click Authenticate.

Admin Console Login

For Auth0, these settings map to the following:

  • issuer -> Domain
  • client-id -> Client ID
  • client-secret -> Client Secret

With these values you gathered from the Auth0 application settings above a new OIDC auth method can be created.

Start by navigating to the Auth Methods settings view using the menu on the left side of the Admin Console. Select New and click OIDC.

Admin Console Auth0

Fill out the form details using the settings gathered from the Auth0 application settings.

These include:

  • Name (Example: Auth0)
  • Description (Example: Auth0 OIDC test auth method)
  • Issuer (Example: https://dev-1vdl8c0q.us.auth0.com/) Ensure the Issuer has a trailing / at the end
  • Client ID (Example: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzz)
  • Client Secret (Example: t35c9NNw1aZ8haQKYJjCL0lauNOSp5UNPovUJXo8Ea2sPZAR1DszEowX-5-lg-Xr)

Admin Console Auth0

Additionally, set the Max Age and API URL Prefix. The Max Age is set to 0, while the API URL Prefix is set to the HCP Boundary Cluster URL (for example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud)

  • Max Age: 0
  • API URL Prefix: https://BOUNDARY_ADDR

The Max Age property defines the amount of time since the user's last authentication that must pass before the user must log in again. For this demonstration, it will prevent any existing Auth0 accounts currently authenticated in the browser from being used when the authentication is performed.

The API URL Prefix is used for actions like token retrieval and redirection.

Admin Console Auth0

Once the form is completed, click Save.

Additionally, set the Max Age and API URL Prefix as follows:

  • Max Age: 0
  • API URL Prefix: http://localhost:9200

The Max Age property defines the amount of time since the user's last authentication that must pass before the user must log in again. For this demonstration, it will prevent any existing Auth0 accounts currently authenticated in the browser from being used when the authentication is performed.

The API URL Prefix is set to http://localhost:9200 because Boundary is running in dev mode. This URL is used for actions like token retrieval and redirection.

Admin Console Auth0

Once the form is completed, click Save.

With the new auth method created, an allowed signing algorithm can be added.

Click Edit Form for the new auth method and scroll down to the Signing Algorithms section. Ensure that RS256 is selected and click Add.

Once added, Save the form.

Admin Console Auth0

The new authentication method has now been created. To the right of the new auth method, notice the state is set to Inactive. Before it can be used the new auth method must be switched to an active state.

Next we will review the available authentication states and activate the new OIDC auth method.

Troubleshooting: If unable to save the auth method, ensure that the Issuer has a trailing / at the end of the URL.

For Okta, these settings map to the following:

  • issuer -> Okta Domain
  • client-id -> Client ID
  • client-secret -> Client secret

With these values you gathered from Okta's application settings above a new OIDC auth method can be created.

Start by navigating to the Auth Methods settings view using the menu on the left side of the Admin Console. Select New and click OIDC.

Admin Console Okta

Fill out the form details using the settings gathered from the Okta application settings.

These include:

  • Name (Example: Okta)
  • Description (Example: Okta OIDC test auth method)
  • Issuer (Example: https://dev-1944432.okta.com)
  • Client ID (Example: 0oal6fr0tPGZ0DSbr5d9)
  • Client Secret (Example: 4BStQlbuTTrh5P-JhGAKW2FVPh48idEbCAOWWVXK)

Admin Console Okta

Additionally, set the API URL Prefix. The API URL Prefix is set to the HCP Boundary Cluster URL (for example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud)

  • API URL Prefix: https://BOUNDARY_ADDR

The API URL Prefix is used for actions like token retrieval and redirection.

Admin Console Okta

Once the form is completed, click Save.

Additionally, set the API URL Prefix as follows:

  • API URL Prefix: http://localhost:9200

The API URL Prefix is set to http://localhost:9200 because Boundary is running in dev mode. This URL is used for actions like token retrieval and redirection.

Admin Console Okta

Once the form is completed, click Save.

With the new auth method created, an allowed signing algorithm can be added.

Click Edit Form for the new auth method and scroll down to the Signing Algorithms section. Ensure that RS256 is selected and click Add.

Once added, Save the form.

Admin Console Okta

The new authentication method has now been created. To the right of the new auth method, notice the state is set to Inactive. Before it can be used the new auth method must be switched to an active state.

Next we will review the available authentication states and activate the new OIDC auth method.

Troubleshooting: If unable to save the auth method, ensure that the Issuer is prefixed by https:// and does NOT have a trailing / at the end of the URL.

For Azure AD, these settings map to the following:

  • issuer -> https://sts.windows.net/Tenant_ID/
  • client-id -> Application (client) ID)
  • client-secret -> Client Secret value

With these values you gathered from setting up an Azure AD application, a new OIDC auth method can be created.

Start by navigating to the Auth Methods settings view using the menu on the left side of the Admin Console. Select New and click OIDC.

Admin Console Azure

Fill out the form details using the settings gathered from the Azure AD application settings.

These include:

  • Name (Example: Azure)
  • Description (Example: Azure OIDC test auth method)
  • Issuer (Example: https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/) Ensure the Issuer has a trailing / at the end
  • Client ID (Example: a4d21a76-e08c-4d8d-8c47-e1c423ee4d11)
  • Client Secret (Example: X9u~u58--~rWLR4Q9i1-PtdZOi_s04~91-)

Admin Console Azure

Additionally, set the API URL Prefix. The API URL Prefix is set to the HCP Boundary Cluster URL (for example, https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud)

  • API URL Prefix: https://BOUNDARY_ADDR

The API URL Prefix is used for actions like token retrieval and redirection.

Admin Console Azure

Once the form is completed, click Save.

Additionally, set the API URL Prefix as follows:

  • API URL Prefix: http://localhost:9200

The API URL Prefix is set to http://localhost:9200 because Boundary is running in dev mode. This URL is used for actions like token retrieval and redirection.

Admin Console Azure

Once the form is completed, click Save.

With the new auth method created, an allowed signing algorithm can be added.

Click Edit Form for the new auth method and scroll down to the Signing Algorithms section. Ensure that RS256 is selected and click Add.

Once added, Save the form.

Admin Console Azure

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.

Next we will review the available authentication states and activate the new OIDC auth method.

Troubleshooting: If unable to save the auth method, ensure that the Issuer is prefixed by https:// and has a trailing / at the end of the URL.

Begin by creating a working directory to store the Terraform configuration file and changing into that directory. This tutorial will work out of the user's HOME directory.

$ mkdir learn-boundary-oidc && cd learn-boundary-oidc/

Next, create a Terraform configuration file called main.tf.

$ touch main.tf

Open the main.tf file in your code editor and add the base Boundary provider configuration below. The 1.0.2 version or above is required to support OIDC. An output value is included to print the oidc auth method id when Terraform applies the configuration.

The initial setup should set the boundary provider to match Boundary's authentication configuration so that Terraform can authenticate to Boundary. These settings are discussed in the Get Setup section.

Copy the following configuration, but update the addr, auth_method_id, password_auth_method_login_name, and password_auth_method_password with the correct values for your Boundary org.

  • addr is the BOUNDARY_ADDR copied from the HCP portal.
  • auth_method_id is for the password auth method and can be gathered from the Boundary Admin Console UI.
  • password_auth_method_login_name and password_auth_method_password were created upon initial setup of the HCP Boundary cluster.
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

provider "boundary" {
  addr                            = "BOUNDARY_ADDR" # updateme
  auth_method_id                  = "ampw_1234567890"    # updateme
  password_auth_method_login_name = "myuser"             # updateme
  password_auth_method_password   = "passpass"           # updateme
}

Copy the following configuration, but replace the recovery_kms_hcl key with the value printed in the boundary dev terminal window.

learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

output "auth-method-id" {
  value = boundary_auth_method_oidc.provider.id
}

provider "boundary" {
  addr             = "http://127.0.0.1:9200"
  recovery_kms_hcl = <<EOT
kms "aead" {
  purpose = "recovery"
  aead_type = "aes-gcm"
  key = "1/niAcbdYlJGqwOJfRtx3AyewF+Ty2EnioOR/q7tWRo="
  key_id = "global_recovery"
}
EOT
}

Next, Boundary Terraform resources will be used to set up the provider of choice.

For Auth0, these settings map to the following:

  • issuer -> Domain
  • client-id -> Client ID
  • client-secret -> Client Secret
  • subject -> user_id

With these values you gathered from the Auth0 application settings a new OIDC auth method can be created.

The Terraform Boundary provider enables OIDC using the boundary_auth_method_oidc and boundary_account_oidc resources.

The boundary_auth_method_oidc resource uses the following attributes to configure a new auth method:

resource "boundary_auth_method_oidc" "name" {
  name                = (String)
  description         = (String)
  scope_id            = (String)
  issuer              = (String)
  client_id           = (String)
  client_secret       = (String)
  signing_algorithms  = (List of String)
  api_url_prefix      = (String)
}
  • The scope_id is the global scope ID. For HCP this is gathered from the Boundary Admin Console UI, or is o_1234567890 if using Boundary's Dev mode.
  • The issuer was gathered from the provider, and should be prefixed by https://
  • The client_id was gathered from the provider
  • The client_secret was gathered from the provider
  • The signing_algorithms are defined by the provider's issued tokens, and will usually include RS256
  • The api_url_prefix is used when generating callback urls and corresponds to an address where the controller is reachable by the provider. For HCP Boundary this is the Boundary Cluster URL found in the HCP portal (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud). For dev mode this is http://localhost:9200

The boundary_account_oidc resource uses the following attributes to configure a new auth method:

resource "boundary_account_oidc" "name" {
  name           = (String)
  description    = (String)
  auth_method_id = (String)
  issuer         = (String)
  subject        = (String)
}
  • The auth_method_id is defined by the boundary_auth_method_oidc resource, and can be accessed using the named scope id, like boundary_auth_meethod_oidc.name.id
  • The issuer was gathered from the provider, and should be prefixed by https://
  • The subject maps to the user ID, and was gathered from the provider when creating a user

Add these two resources into your main.tf file. The entire file contents are shown below.

Make sure the following values are updated:

  • addr (from HCP portal)
  • auth_method_id (from Boundary Admin Console UI)
  • password_auth_method_login_name (from initial Boundary Cluster creation)
  • password_auth_method_password (from initial Boundary Cluster creation)
  • scope_id (global scope from Boundary Admin Console UI)
  • issuer (from provider)
  • client_id (from provider)
  • client_secret (from provider)
  • subject (from provider)
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

provider "boundary" {
  addr                            = "BOUNDARY_ADDR" # updateme
  auth_method_id                  = "ampw_1234567890"    # updateme
  password_auth_method_login_name = "myuser"             # updateme
  password_auth_method_password   = "passpass"           # updateme
}

resource "boundary_auth_method_oidc" "provider" {
  name               = "Auth0"
  description        = "OIDC auth method for Auth0"
  scope_id           = "o_1234567890"                    # updateme
  issuer             = "https://dev-1vdl8c0q.us.auth0.com/"   # updateme
  client_id          = "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx"     # updateme
  client_secret      = "t35c9NNw1aZ8haQKYJjCL0lauNOSp5UNPovUJXo8Ea2sPZAR1DszEowX-5-lg-Xr"   # updateme
  signing_algorithms = ["RS256"]
  api_url_prefix     = "BOUNDARY_ADDR"                   # updateme
}

resource "boundary_account_oidc" "oidc_user" {
  name           = "user1"
  description    = "OIDC account for user1"
  auth_method_id = boundary_auth_method_oidc.provider.id
  issuer  = "https://dev-1vdl8c0q.us.auth0.com/"              # updateme
  subject = "auth0|6077581e2ce19d006dfaf211"
}

Make sure the following values are updated:

  • kms key (from boundary dev)
  • issuer (from provider)
  • client_id (from provider)
  • client_secret (from provider)
  • subject (from provider)
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

output "auth-method-id" {
  value = boundary_auth_method_oidc.provider.id
}

provider "boundary" {
  addr             = "http://127.0.0.1:9200"
  recovery_kms_hcl = <<EOT
kms "aead" {
  purpose = "recovery"
  aead_type = "aes-gcm"
  key = "gm0aHvU1ENpc9mrB5Kt2bqCyh9PODOqnDznryFksyI0="
  key_id = "global_recovery"
}
EOT
}

resource "boundary_auth_method_oidc" "provider" {
  name               = "Auth0"
  description        = "OIDC auth method for Auth0"
  scope_id           = "o_1234567890"
  issuer             = "https://dev-1vdl8c0q.us.auth0.com/"
  client_id          = "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx"
  client_secret      = "t35c9NNw1aZ8haQKYJjCL0lauNOSp5UNPovUJXo8Ea2sPZAR1DszEowX-5-lg-Xr"
  signing_algorithms = ["RS256"]
  api_url_prefix     = "http://localhost:9200"
}

resource "boundary_account_oidc" "oidc_user" {
  name           = "user1"
  description    = "OIDC account for user1"
  auth_method_id = boundary_auth_method_oidc.provider.id
  issuer  = "https://dev-1vdl8c0q.us.auth0.com/"
  subject = "auth0|6077581e2ce19d006dfaf211"
}

With these resources in place, first initialize Terraform.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/boundary versions matching "1.0.12"...
- Installing hashicorp/boundary v1.0.12...
- Installed hashicorp/boundary v1.0.12 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Next, apply the configuration. Enter yes when prompted for confirmation.

$ terraform apply

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # boundary_account_oidc.oidc_user will be created
  + resource "boundary_account_oidc" "oidc_user" {
      + auth_method_id = (known after apply)
      + description    = "OIDC account for user1"
      + id             = (known after apply)
      + issuer         = "https://dev-1vdl8c0q.us.auth0.com/"
      + name           = "user1"
      + subject        = "auth0|6077581e2ce19d006dfaf211"
    }

  # boundary_auth_method_oidc.provider will be created
  + resource "boundary_auth_method_oidc" "provider" {
      + api_url_prefix     = "https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud"
      + callback_url       = (known after apply)
      + client_id          = "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx"
      + client_secret      = "t35c9NNw1aZ8haQKYJjCL0lauNOSp5UNPovUJXo8Ea2sPZAR1DszEowX-5-lg-Xr"
      + client_secret_hmac = (known after apply)
      + description        = "OIDC auth method for Auth0"
      + id                 = (known after apply)
      + issuer             = "https://dev-1vdl8c0q.us.auth0.com/"
      + name               = "Auth0"
      + scope_id           = "o_1234567890"
      + signing_algorithms = [
          + "RS256",
        ]
      + state              = (known after apply)
      + type               = "oidc"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_auth_method_oidc.provider: Creating...
boundary_auth_method_oidc.provider: Creation complete after 1s [id=amoidc_AliCbVihqv]
boundary_account_oidc.oidc_user: Creating...
boundary_account_oidc.oidc_user: Creation complete after 0s [id=acctoidc_Hrbbcmxuny]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

auth-method-id = amoidc_AliCbVihqv

The new authentication method has been created! If Terraform encounters an error, ensure the issuer, client_id and client_secret have been copied correctly from the provider, and that the issuer is prefixed with https://.

Copy the auth-method-id from the output.

For Okta, these settings map to the following:

  • issuer -> Okta Domain
  • client-id -> Client ID
  • client-secret -> Client secret
  • subject -> user_id

With these values you gathered from the Okta application settings a new OIDC auth method can be created.

The Terraform Boundary provider enables OIDC using the boundary_auth_method_oidc and boundary_account_oidc resources.

The boundary_auth_method_oidc resource uses the following attributes to configure a new auth method:

resource "boundary_auth_method_oidc" "name" {
  name               = (String)
  description        = (String)
  scope_id           = (String)
  issuer             = (String)
  client_id          = (String)
  client_secret      = (String)
  signing_algorithms = (List of String)
  api_url_prefix     = (String)
}
  • The scope_id is the global scope ID. For HCP this is gathered from the Boundary Admin Console UI, or is o_1234567890 if using Boundary's Dev mode.
  • The issuer was gathered from the provider, and should be prefixed by https://
  • The client_id was gathered from the provider
  • The client_secret was gathered from the provider
  • The signing_algorithms are defined by the provider's issued tokens, and will usually include RS256
  • The api_url_prefix is used when generating callback urls and corresponds to an address where the controller is reachable by the provider. For HCP Boundary this is the Boundary Cluster URL found in the HCP portal (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud). For dev mode this is http://localhost:9200

The boundary_account_oidc resource uses the following attributes to configure a new auth method:

resource "boundary_account_oidc" "name" {
  name           = (String)
  description    = (String)
  auth_method_id = (String)
  issuer         = (String)
  subject        = (String)
}
  • The auth_method_id is defined by the boundary_auth_method_oidc resource, and can be accessed using the named scope id, like boundary_auth_meethod_oidc.name.id
  • The issuer was gathered from the provider, and should be prefixed by https://
  • The subject maps to the user ID, and was gathered from the provider when creating a user

Add these two resources into your main.tf file. The entire file contents are shown below.

Make sure the following values are updated:

  • addr (from HCP portal)
  • auth_method_id (from Boundary Admin Console UI)
  • password_auth_method_login_name (from initial Boundary Cluster creation)
  • password_auth_method_password (from initial Boundary Cluster creation)
  • scope_id (global scope from Boundary Admin Console UI)
  • issuer (from provider)
  • client_id (from provider)
  • client_secret (from provider)
  • subject (from provider)
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

provider "boundary" {
  addr                            = "BOUNDARY_ADDR" # updateme
  auth_method_id                  = "ampw_1234567890"    # updateme
  password_auth_method_login_name = "myuser"             # updateme
  password_auth_method_password   = "passpass"           # updateme
}

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Okta"
  description          = "OIDC auth method for Okta"
  scope_id             = "o_1234567890"                  # updateme
  issuer             = "https://dev-1944432.okta.com"    # updateme
  client_id          = "0oal6fr0tPGZ0DSbr5d6"            # updateme
  client_secret      = "4BStQlbuTTrh5P-JhGAKW2FVPh48idEbCAOWWVXM"   # updateme
  signing_algorithms = ["RS256"]
  api_url_prefix     = "https://BOUNDARY_ADDR"                 # updateme
}

resource "boundary_account_oidc" "oidc_user" {
  name           = "user1"
  description    = "OIDC account for user1"
  auth_method_id = boundary_auth_method_oidc.provider.id
  issuer  = "https://dev-1944432.okta.com"                          # updateme
  subject = "00ul68uytv7ROjOHd5d6"
}

Make sure the following values are updated:

  • kms key (from boundary dev)
  • issuer (from provider)
  • client_id (from provider)
  • client_secret (from provider)
  • subject (from provider)
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

output "auth-method-id" {
  value = boundary_auth_method_oidc.provider.id
}

provider "boundary" {
  addr             = "http://127.0.0.1:9200"
  recovery_kms_hcl = <<EOT
kms "aead" {
  purpose = "recovery"
  aead_type = "aes-gcm"
  key = "uZr3hmWkEkq+9mMgW/wnm6QTXhkAftKKgKnoIcaUzEY="
  key_id = "global_recovery"
}
EOT
}

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Okta"
  description          = "OIDC auth method for Okta"
  scope_id             = "o_1234567890"
  issuer             = "https://dev-1944432.okta.com"
  client_id          = "0oal6fr0tPGZ0DSbr5d6"
  client_secret      = "4BStQlbuTTrh5P-JhGAKW2FVPh48idEbCAOWWVXM"
  signing_algorithms = ["RS256"]
  api_url_prefix     = "http://localhost:9200"
}

resource "boundary_account_oidc" "oidc_user" {
  name           = "user1"
  description    = "OIDC account for user1"
  auth_method_id = boundary_auth_method_oidc.provider.id
  issuer  = "https://dev-1944432.okta.com"
  subject = "00ul68uytv7ROjOHd5d6"
}

With these resources in place, first initialize Terraform.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/boundary versions matching "1.0.12"...
- Installing hashicorp/boundary v1.0.12...
- Installed hashicorp/boundary v1.0.12 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Next, apply the configuration. Enter yes when prompted for confirmation.

$ terraform apply

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # boundary_account_oidc.oidc_user will be created
  + resource "boundary_account_oidc" "oidc_user" {
      + auth_method_id = (known after apply)
      + description    = "OIDC account for user1"
      + id             = (known after apply)
      + issuer         = "https://dev-1944432.okta.com"
      + name           = "user1"
      + subject        = "00ul68uytv7ROjOHd5d6"
    }

  # boundary_auth_method_oidc.provider will be created
  + resource "boundary_auth_method_oidc" "provider" {
      + api_url_prefix     = "https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud"
      + callback_url       = (known after apply)
      + client_id          = "0oal6fr0tPGZ0DSbr5d6"
      + client_secret      = "4BStQlbuTTrh5P-JhGAKW2FVPh48idEbCAOWWVXM"
      + client_secret_hmac = (known after apply)
      + description        = "OIDC auth method for Okta"
      + id                 = (known after apply)
      + issuer             = "https://dev-1944432.okta.com"
      + name               = "Okta"
      + scope_id           = "o_1234567890"
      + signing_algorithms = [
          + "RS256",
        ]
      + state              = (known after apply)
      + type               = "oidc"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_auth_method_oidc.provider: Creating...
boundary_auth_method_oidc.provider: Creation complete after 1s [id=amoidc_cjCWZnr79C]
boundary_account_oidc.oidc_user: Creating...
boundary_account_oidc.oidc_user: Creation complete after 0s [id=acctoidc_JZ3AViFu2z]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

auth-method-id = amoidc_cjCWZnr79C

The new authentication method has been created! If Terraform encounters an error, ensure the issuer, client_id and client_secret have been copied correctly from the provider, and that the issuer is prefixed with https://.

Copy the auth-method-id from the output.

For Azure AD, these settings map to the following:

  • issuer -> https://sts.windows.net/Tenant_ID/ Be sure to include a trailing / at the end
  • client-id -> Application (client) ID)
  • client-secret -> Client Secret value
  • subject -> User object_id

With these values you gathered from the Azure AD application settings a new OIDC auth method can be created.

The Terraform Boundary provider enables OIDC using the boundary_auth_method_oidc and boundary_account_oidc resources.

The boundary_auth_method_oidc resource uses the following attributes to configure a new auth method:

resource "boundary_auth_method_oidc" "name" {
  name                = (String)
  description         = (String)
  scope_id            = (String)
  issuer              = (String)
  client_id           = (String)
  client_secret       = (String)
  signing_algorithms  = (List of String)
  api_url_prefix      = (String)
}
  • The scope_id is the global scope ID. For HCP this is gathered from the Boundary Admin Console UI, or is o_1234567890 if using Boundary's Dev mode.
  • The issuer was gathered from the provider, and should be prefixed by https://
  • The client_id was gathered from the provider
  • The client_secret was gathered from the provider
  • The signing_algorithms are defined by the provider's issued tokens, and will usually include RS256
  • The api_url_prefix is used when generating callback urls and corresponds to an address where the controller is reachable by the provider. For HCP Boundary this is the Boundary Cluster URL found in the HCP portal (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud). For dev mode this is http://localhost:9200

The boundary_account_oidc resource uses the following attributes to configure a new auth method:

resource "boundary_account_oidc" "name" {
  name           = (String)
  description    = (String)
  auth_method_id = (String)
  issuer         = (String)
  subject        = (String)
}
  • The auth_method_id is defined by the boundary_auth_method_oidc resource, and can be accessed using the named scope id, like boundary_auth_meethod_oidc.name.id
  • The issuer was gathered from the provider, and should be prefixed by https://
  • The subject maps to the user Object ID, and was gathered from the provider when creating a user

Add these two resources into your main.tf file. The entire file contents are shown below.

Make sure the following values are updated:

  • addr (from HCP portal)
  • auth_method_id (from Boundary Admin Console UI)
  • password_auth_method_login_name (from initial Boundary Cluster creation)
  • password_auth_method_password (from initial Boundary Cluster creation)
  • scope_id (global scope from Boundary Admin Console UI)
  • issuer (from provider)
  • client_id (from provider)
  • client_secret (from provider)
  • subject (from provider)
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

provider "boundary" {
  addr                            = "BOUNDARY_ADDR" # updateme
  auth_method_id                  = "ampw_1234567890"    # updateme
  password_auth_method_login_name = "myuser"             # updateme
  password_auth_method_password   = "passpass"           # updateme
}

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Azure"
  description          = "OIDC auth method for Azure"
  scope_id             = "o_1234567890"                  # updateme
  issuer               = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"   # updateme
  client_id            = "a4d21a76-e08c-4d8d-8c47-e1c423ee4d11"   # updateme
  client_secret        = "X9u~u58--~rWLR4Q9i1-PtdZOi_s04~9O-"     # updateme
  signing_algorithms   = ["RS256"]
  api_url_prefix       = "https://BOUNDARY_ADDR"             # updateme
}

resource "boundary_account_oidc" "oidc_user" {
  name           = "user1"
  description    = "OIDC account for user1"
  auth_method_id = boundary_auth_method_oidc.provider.id
  issuer  = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"  # updateme
  subject = "c3dc63d0-90e6-4855-b9c0-e87da14a9c5f"
}

Make sure the following values are updated:

  • kms key (from boundary dev)
  • issuer (from provider)
  • client_id (from provider)
  • client_secret (from provider)
  • subject (from provider)
learn-boundary-oidc/main.tf
terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.12"
    }
  }
}

output "auth-method-id" {
  value = boundary_auth_method_oidc.provider.id
}

provider "boundary" {
  addr             = "http://127.0.0.1:9200"
  recovery_kms_hcl = <<EOT
kms "aead" {
  purpose = "recovery"
  aead_type = "aes-gcm"
  key = "m4+NMLonZAcAbr0VhFRThgnt+QM/P6BelMCEdYCBAa0="
  key_id = "global_recovery"
}
EOT
}

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Azure"
  description          = "OIDC auth method for Azure"
  scope_id             = "o_1234567890"
  issuer               = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"
  client_id            = "a4d21a76-e08c-4d8d-8c47-e1c423ee4d11"
  client_secret        = "X9u~u58--~rWLR4Q9i1-PtdZOi_s04~9O-"
  signing_algorithms   = ["RS256"]
  api_url_prefix       = "http://localhost:9200"
}

resource "boundary_account_oidc" "oidc_user" {
  name           = "user1"
  description    = "OIDC account for user1"
  auth_method_id = boundary_auth_method_oidc.provider.id
  issuer  = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"
  subject = "c3dc63d0-90e6-4855-b9c0-e87da14a9c5f"
}

With these resources in place, first initialize Terraform.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/boundary versions matching "1.0.12"...
- Installing hashicorp/boundary v1.0.12...
- Installed hashicorp/boundary v1.0.12 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Next, apply the configuration. Enter yes when prompted for confirmation.

$ terraform apply

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # boundary_account_oidc.oidc_user will be created
  + resource "boundary_account_oidc" "oidc_user" {
      + auth_method_id = (known after apply)
      + description    = "OIDC account for user1"
      + id             = (known after apply)
      + issuer         = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"
      + name           = "user1"
      + subject        = "c3dc63d0-90e6-4855-b9c0-e87da14a9c5f"
    }

  # boundary_auth_method_oidc.provider will be created
  + resource "boundary_auth_method_oidc" "provider" {
      + api_url_prefix     = "http://localhost:9200"
      + callback_url       = (known after apply)
      + client_id          = "a4d21a76-e08c-4d8d-8c47-e1c423ee4d11"
      + client_secret      = "X9u~u58--~rWLR4Q9i1-PtdZOi_s04~9O-"
      + client_secret_hmac = (known after apply)
      + description        = "OIDC auth method for Azure"
      + id                 = (known after apply)
      + issuer             = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"
      + name               = "Azure"
      + scope_id           = "o_1234567890"
      + signing_algorithms = [
          + "RS256",
        ]
      + state              = (known after apply)
      + type               = "oidc"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_auth_method_oidc.provider: Creating...
boundary_auth_method_oidc.provider: Creation complete after 1s [id=amoidc_ZMettTQoi7]
boundary_account_oidc.oidc_user: Creating...
boundary_account_oidc.oidc_user: Creation complete after 0s [id=acctoidc_RioLnuyZMw]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

auth-method-id = amoidc_ZMettTQoi7

The new authentication method has been created! If Terraform encounters an error, ensure the issuer, client_id and client_secret have been copied correctly from the provider, and that the issuer is prefixed with https://.

Copy the auth-method-id from the output.

Authentication states

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.

State change operations

  • 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:

  • inactive users can not authenticate with inactive auth methods and are not be listed for unauthenticated users.
  • active-private users can authenticate with active-private auth methods and are not be listed for unauthenticated users.
  • active-public users 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 the -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.

Activate the OIDC auth method

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

Example:

$ 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.

Set OIDC as primary login

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.

Enable the the auth method by updating its state to active-public.

$ boundary auth-methods change-state oidc -id amoidc_tublWgOrr6 -state active-public

Auth Method information:
  Created Time:         Fri, 09 Sep 2022 11:54:33 MDT
  ID:                   amoidc_tublWgOrr6
  Name:                 okta
  Type:                 oidc
  Updated Time:         Mon, 12 Sep 2022 14:05:59 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
    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:          0oal6fr0tPGZ0DSbr5d6
    client_secret_hmac: c5op-CkYUuEb7d-ubOjc5UBT_YqVP-CCu2pRL7EH8ls
    issuer:             https://dev-1944432.okta.com
    signing_algorithms: [RS256]
    state:              active-public

With the state set to active the login type will now be allowed.

Set OIDC as primary login

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 have more than one auth method 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_tublWgOrr6 -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_tublWgOrr6
  Updated Time:             Mon, 12 Sep 2022 14:06:40 MDT
  Version:                  4

  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

Enable the the auth method by updating its state to active-public.

$ boundary auth-methods change-state oidc -id amoidc_rFqhKQlrvn -state active-public

Auth Method information:
  Created Time:         Mon, 12 Sep 2022 13:40:38 MDT
  ID:                   amoidc_rFqhKQlrvn
  Name:                 azure
  Type:                 oidc
  Updated Time:         Mon, 12 Sep 2022 13:56:43 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
    managed-groups:
      create
      list

  Attributes:
    api_url_prefix:     https://e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3.boundary.hashicorp.cloud
    callback_url:       https://e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback
    client_id:          09443893-b713-4dbf-a417-8882bff4168d
    client_secret_hmac: SEOTy9cZgs7BTYRknG44rFxQQ64xY3qp2i1iEDpkvX0
    issuer:             https://sts.windows.net/0e3e2e88-8caf-41ca-b4da-e3b33b6c52ec/
    signing_algorithms: [RS256]
    state:              active-public

With the state set to active the login type will now be allowed.

Set OIDC as primary login

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_rFqhKQlrvn -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_rFqhKQlrvn
  Updated Time:             Mon, 12 Sep 2022 13:58:47 MDT
  Version:                  3

  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_rFqhKQlrvn
Opening returned authentication URL in your browser...

A browser tab should automatically open and prompt you to log in with the user credentials created when setting up Azure AD.

After successful authentication, return to your terminal and notice the Authentication information that is printed.

$ boundary authenticate oidc -auth-method-id amoidc_rFqhKQlrvn
Opening returned authentication URL in your browser...

Authentication information:
  Account ID:      acctoidc_oztPFBFesH
  Auth Method ID:  amoidc_rFqhKQlrvn
  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.

Before the new auth method will be allowed it must be set to an active state.

Under the settings for the new auth method, select Inactive from the menu in the upper-right side of the page and change its state by clicking Public.

Admin Console Auth0

The login type is now allowed.

Set OIDC as primary login

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.

Under the settings for the new auth method, select Manage from the menu in the upper-right side of the page.

Admin Console Auth0

A confirmation window will be displayed to inform you that new users that sign in via OIDC will automatically be added to the new auth method. Select OK to continue.

Admin Console Auth0

Now try authenticating using the newly created OIDC auth method.

Select the admin user menu in the top-right corner of the page and select Deauthenticate.

Next, select the new auth method called Auth0, and click Authenticate.

Admin Console Auth0

A browser tab should automatically open and prompt you to log in with your Auth0 user account credentials.

Auth0 Application Login

After successful authentication you are automatically redirected to the Admin Console. Notice the restricted permissions for this new user, which can be updated and assigned using Roles and Groups.

If you were to log back into the Admin Console as the admin user, you would notice the new OIDC user has automatically been added under the Users view.

Admin Console Auth0

Next you will review the various methods that can be used to authenticate to Boundary using the new OIDC auth method.

Before the new auth method will be allowed it must be set to an active state.

Under the settings for the new auth method, select Inactive from the menu in the upper-right side of the page and change its state by clicking Public.

Admin Console Okta

The login type will now allow be allowed.

Set OIDC as primary login

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.

Under the settings for the new auth method, select Manage from the menu in the upper-right side of the page.

Admin Console Okta

A confirmation window will be displayed to inform you that new users that sign in via OIDC will automatically be added to the new auth method. Select OK to continue.

Admin Console Okta

Now try authenticating using the newly created OIDC auth method.

Select the admin user menu in the top-right corner of the page and select Deauthenticate.

Next, select the new auth method called Okta, and click Authenticate.

Admin Console Okta

A browser tab should automatically open and prompt you to log in with your Okta user account credentials.

Okta Application Login

Login Issues: If you experience any issues logging into Okta, such as a 400 Bad Request error, you may be logged into the wrong Okta account. Visit the Okta Dashboard, select your username in the upper-right corner of the window and click Sign Out. Then, revisit the previously opened Authenticate Boundary browser tab and click Retry to log back into Okta with the new user account credentials.

After successful authentication you are automatically redirected to the Admin Console. Notice the restricted permissions for this new user, which can be updated and assigned using Roles and Groups.

If you were to log back into the Admin Console as the admin user, you would notice the new OIDC user has automatically been added under the Users view.

Admin Console Okta

Next you will review the various methods that can be used to authenticate to Boundary using the new OIDC auth method.

Before the new auth method will be allowed it must be set to an active state.

Under the settings for the new auth method, select Inactive from the menu in the upper-right side of the page and change its state by clicking Public.

Admin Console Azure

The login type will now allow be allowed.

Set OIDC as primary login

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.

Under the settings for the new auth method, select Manage from the menu in the upper-right side of the page.

Admin Console Azure

A confirmation window will be displayed to inform you that new users that sign in via OIDC will automatically be added to the new auth method. Select OK to continue.

Admin Console Azure

Now try authenticating using the newly created OIDC auth method.

Select the admin user menu in the top-right corner of the page and select Deauthenticate.

Next, select the new auth method called Azure, and click Authenticate.

Admin Console Azure

A browser tab should automatically open and prompt you to log in with your Azure user account credentials. Ensure you log in with the test user credentials created in the Azure AD application setup, not your primary Azure account.

Azure Application Login

Login Issues: If you experience any issues logging in, you may be logged into the wrong Azure account. Visit the Azure Portal, select your username in the upper-right corner of the window and click Sign Out. Then, revisit the previously opened Authenticate Boundary browser tab and click Retry to log back into Azure with the test user account credentials.

After successful authentication you are automatically redirected to the Admin Console. Notice the restricted permissions for this new user, which can be updated and assigned using Roles and Groups.

If you were to log back into the Admin Console as the admin user, you would notice the new OIDC user has automatically been added under the Users view.

Admin Console Azure

Next you will review the various methods that can be used to authenticate to Boundary using the new OIDC auth method.

Auth methods must be updated to an active state before they can be used.

The state of the new auth method can be checked using the read operation. First, ensure you are logged in as the admin user.

$ boundary authenticate password -auth-method-id ampw_1234567890 -login-name admin
Please enter the password (it will be hidden): <password>

Authentication information:
  Account ID:      apw_DZRvFzmb0Y
  Auth Method ID:  ampw_1234567890
  Expiration Time: Thu, 20 May 2021 16:32:06 MDT
  User ID:         u_1234567890

The token was successfully stored in the chosen keyring and is not displayed here.

Next read the auth method details. Use the auth-method-id you copied from the terraform apply output.

$ boundary auth-methods read -id amoidc_AliCbVihqv

Auth Method information:
  Created Time:         Thu, 13 May 2021 17:01:02 MDT
  Description:          OIDC auth method for Auth0
  ID:                   amoidc_AliCbVihqv
  Name:                 Auth0
  Type:                 oidc
  Updated Time:         Thu, 13 May 2021 17:01:02 MDT
  Version:              2

  Scope:
    ID:                 o_1234567890
    Name:               Generated org scope
    Parent Scope ID:    global
    Type:               org

  Authorized Actions:
    no-op
    read
    update
    delete
    change-state
    authenticate

  Authorized Actions on Auth Method's Collections:
    accounts:
      create
      list

  Attributes:
    api_url_prefix:     http://localhost:9200
    callback_url:       http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    client_id:          zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx
    client_secret_hmac: AhyxTBqlZpnny78iA9M7QHKAKocI17bjwvS70B1ccg0
    issuer:             https://dev-1vdl8c0q.us.auth0.com/
    signing_algorithms: [RS256]
    state:              active-public

Notice at the bottom of the output that the login state is already set to active-public.

It's important to be aware that using Terraform to provision an auth method will set the state to active by default, unless otherwise defined. The state attribute can be used on the boundary_auth_method_oidc resource to set an auth method to active-private or inactive.

Now that the auth method state has been verified, the primary login type can be defined for the global scope.

Set OIDC as primary login

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 have more than one auth method which resulted in no primary auth method being set for the Scope.

Make three updates to the boundary_auth_method_oidc resource in the main.tf file:

  • Set the auth method's state to active-public for clarity
  • Set the new OIDC auth method as the primary auth method for the global scope by setting the is_primary_for_scope attribute
  • 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.

Below is an example. Update your main.tf file accordingly.

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Auth0"
  description          = "OIDC auth method for Auth0"
  scope_id             = "o_1234567890"
  issuer             = "https://dev-1vdl8c0q.us.auth0.com/"
  client_id          = "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx"
  client_secret      = "t35c9NNw1aZ8haQKYJjCL0lauNOSp5UNPovUJXo8Ea2sPZAR1DszEowX-5-lg-Xr"
  signing_algorithms = ["RS256"]
  api_url_prefix     = "http://localhost:9200"
  is_primary_for_scope = true
  state = "active-public"
  max_age = 0
}

Apply the updated configuration. Enter yes when prompted.

$ terraform apply
boundary_auth_method_oidc.provider: Refreshing state... [id=amoidc_AliCbVihqv]
boundary_account_oidc.oidc_user: Refreshing state... [id=acctoidc_Hrbbcmxuny]

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  ~ update in-place
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # boundary_account_oidc.oidc_user must be replaced
-/+ resource "boundary_account_oidc" "oidc_user" {
        auth_method_id = "amoidc_AliCbVihqv"
        description    = "OIDC account for user1"
      ~ id             = "acctoidc_Hrbbcmxuny" -> (known after apply)
      + issuer         = "https://dev-1vdl8c0q.us.auth0.com/" # forces replacement
        name           = "user1"
      + subject        = "auth0|6077581e2ce19d006dfaf211"
    }

  # boundary_auth_method_oidc.provider will be updated in-place
  ~ resource "boundary_auth_method_oidc" "provider" {
        api_url_prefix       = "http://localhost:9200"
        callback_url         = "http://localhost:9200/v1/auth-methods/oidc:authenticate:callback"
        client_id            = "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx"
        client_secret        = "t35c9NNw1aZ8haQKYJjCL0lauNOSp5UNPovUJXo8Ea2sPZAR1DszEowX-5-lg-Xr"
        client_secret_hmac   = "AhyxTBqlZpnny78iA9M7QHKAKocI17bjwvS70B1ccg0"
        description          = "OIDC auth method for Auth0"
        id                   = "amoidc_AliCbVihqv"
      + is_primary_for_scope = true
        issuer               = "https://dev-1vdl8c0q.us.auth0.com/"
      + max_age              = 0
        name                 = "Auth0"
        scope_id             = "o_1234567890"
        signing_algorithms   = [
            "RS256",
        ]
        state                = "active-public"
        type                 = "oidc"
    }

Plan: 1 to add, 1 to change, 1 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_account_oidc.oidc_user: Destroying... [id=acctoidc_Hrbbcmxuny]
boundary_auth_method_oidc.provider: Modifying... [id=amoidc_AliCbVihqv]
boundary_auth_method_oidc.provider: Modifications complete after 0s [id=amoidc_AliCbVihqv]
boundary_account_oidc.oidc_user: Destruction complete after 0s
boundary_account_oidc.oidc_user: Creating...
boundary_account_oidc.oidc_user: Creation complete after 0s [id=acctoidc_VUKa3gJkPp]

Apply complete! Resources: 1 added, 1 changed, 1 destroyed.

Outputs:

auth-method-id = amoidc_AliCbVihqv

With the auth method set to active and defined as the primary login method, users can now authenticate using their preferred method of choice.

Next read the auth method details. Use the auth-method-id you copied from the terraform apply output.

$ boundary auth-methods read -id amoidc_cjCWZnr79C

Auth Method information:
  Created Time:         Thu, 13 May 2021 17:25:56 MDT
  Description:          OIDC auth method for Okta
  ID:                   amoidc_cjCWZnr79C
  Name:                 Okta
  Type:                 oidc
  Updated Time:         Thu, 13 May 2021 17:25:57 MDT
  Version:              2

  Scope:
    ID:                 o_1234567890
    Name:               Generated org scope
    Parent Scope ID:    global
    Type:               org

  Authorized Actions:
    no-op
    read
    update
    delete
    change-state
    authenticate

  Authorized Actions on Auth Method's Collections:
    accounts:
      create
      list

  Attributes:
    api_url_prefix:     http://localhost:9200
    callback_url:       http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    client_id:          0oal6fr0tPGZ0DSbr5d6
    client_secret_hmac: rrnZgSer00fGL0qiGsO_DryD-wNX3CCBMXJiFVRIWWk
    issuer:             https://dev-1944432.okta.com
    signing_algorithms: [RS256]
    state:              active-public

Notice at the bottom of the output that the login state is already set to active-public.

It's important to be aware that using Terraform to provision an auth method will set the state to active by default, unless otherwise defined. The state attribute can be used on the boundary_auth_method_oidc resource to set an auth method to active-private or inactive.

Now that the auth method state has been verified, the primary login type can be defined for the global scope.

Set OIDC as primary login

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 have more than one auth method which resulted in no primary auth method being set for the Scope.

Make three updates to the boundary_auth_method_oidc resource in the main.tf file:

  • Set the auth method's state to active-public for clarity
  • Set the new OIDC auth method as the primary auth method for the global scope by setting the is_primary_for_scope attribute
  • 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.

Below is an example. Update your main.tf file accordingly.

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Okta"
  description          = "OIDC auth method for Okta"
  scope_id             = "o_1234567890"
  issuer             = "https://dev-1944432.okta.com"
  client_id          = "0oal6fr0tPGZ0DSbr5d6"
  client_secret      = "4BStQlbuTTrh5P-JhGAKW2FVPh48idEbCAOWWVXM"
  signing_algorithms = ["RS256"]
  api_url_prefix     = "http://localhost:9200"
  is_primary_for_scope = true
  state = "active-public"
  max_age = 0
}

Apply the updated configuration. Enter yes when prompted.

$ terraform apply
boundary_auth_method_oidc.provider: Refreshing state... [id=amoidc_cjCWZnr79C]
boundary_account_oidc.oidc_user: Refreshing state... [id=acctoidc_JZ3AViFu2z]

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  ~ update in-place
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # boundary_account_oidc.oidc_user must be replaced
-/+ resource "boundary_account_oidc" "oidc_user" {
        auth_method_id = "amoidc_cjCWZnr79C"
        description    = "OIDC account for user1"
      ~ id             = "acctoidc_JZ3AViFu2z" -> (known after apply)
      + issuer         = "https://dev-1944432.okta.com" # forces replacement
        name           = "user1"
      + subject        = "00ul68uytv7ROjOHd5d6"
    }

  # boundary_auth_method_oidc.provider will be updated in-place
  ~ resource "boundary_auth_method_oidc" "provider" {
        api_url_prefix       = "http://localhost:9200"
        callback_url         = "http://localhost:9200/v1/auth-methods/oidc:authenticate:callback"
        client_id            = "0oal6fr0tPGZ0DSbr5d6"
        client_secret        = "4BStQlbuTTrh5P-JhGAKW2FVPh48idEbCAOWWVXM"
        client_secret_hmac   = "rrnZgSer00fGL0qiGsO_DryD-wNX3CCBMXJiFVRIWWk"
        description          = "OIDC auth method for Okta"
        id                   = "amoidc_cjCWZnr79C"
      + is_primary_for_scope = true
        issuer               = "https://dev-1944432.okta.com"
      + max_age              = 0
        name                 = "Okta"
        scope_id             = "o_1234567890"
        signing_algorithms   = [
            "RS256",
        ]
        state                = "active-public"
        type                 = "oidc"
    }

Plan: 1 to add, 1 to change, 1 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_account_oidc.oidc_user: Destroying... [id=acctoidc_JZ3AViFu2z]
boundary_auth_method_oidc.provider: Modifying... [id=amoidc_cjCWZnr79C]
boundary_auth_method_oidc.provider: Modifications complete after 0s [id=amoidc_cjCWZnr79C]
boundary_account_oidc.oidc_user: Destruction complete after 0s
boundary_account_oidc.oidc_user: Creating...
boundary_account_oidc.oidc_user: Creation complete after 0s [id=acctoidc_JZ3AViFu2z]

Apply complete! Resources: 1 added, 1 changed, 1 destroyed.

Outputs:

auth-method-id = amoidc_cjCWZnr79C

With the auth method set to active and defined as the primary login method, users can now authenticate using their preferred method of choice.

Next read the auth method details. Use the auth-method-id you copied from the terraform apply output.

$ boundary auth-methods read -id amoidc_ZMettTQoi7

Auth Method information:
  Created Time:         Wed, 09 Jun 2021 12:59:44 MDT
  Description:          OIDC auth method for Azure
  ID:                   amoidc_ZMettTQoi7
  Name:                 Azure
  Type:                 oidc
  Updated Time:         Wed, 09 Jun 2021 12:59:45 MDT
  Version:              2

  Scope:
    ID:                 o_1234567890
    Name:               Generated org scope
    Parent Scope ID:    global
    Type:               org

  Authorized Actions:
    no-op
    read
    update
    delete
    change-state
    authenticate

  Authorized Actions on Auth Method's Collections:
    accounts:
      create
      list

  Attributes:
    api_url_prefix:     http://localhost:9200
    callback_url:       http://localhost:9200/v1/auth-methods/oidc:authenticate:callback
    client_id:          a4d21a76-e08c-4d8d-8c47-e1c423ee4d11
    client_secret_hmac: qbLhGSr0XZpZhdEjChZwjJMqG-dZzsX9gSRG4f44jWQ
    issuer:             https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/
    signing_algorithms: [RS256]
    state:              active-public

Notice at the bottom of the output that the login state is already set to active-public.

It's important to be aware that using Terraform to provision an auth method will set the state to active by default, unless otherwise defined. The state attribute can be used on the boundary_auth_method_oidc resource to set an auth method to active-private or inactive.

Now that the auth method state has been verified, the primary login type can be defined for the global scope.

Set OIDC as primary login

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 have more than one auth method which resulted in no primary auth method being set for the Scope.

Make three updates to the boundary_auth_method_oidc resource in the main.tf file:

  • Set the auth method's state to active-public for clarity
  • Set the new OIDC auth method as the primary auth method for the global scope by setting the is_primary_for_scope attribute

Below is an example. Update your main.tf file accordingly.

resource "boundary_auth_method_oidc" "provider" {
  name                 = "Azure"
  description          = "OIDC auth method for Azure"
  scope_id             = "o_1234567890"
  issuer               = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"
  client_id            = "a4d21a76-e08c-4d8d-8c47-e1c423ee4d11"
  client_secret        = "X9u~u58--~rWLR4Q9i1-PtdZOi_s04~9O-"
  signing_algorithms   = ["RS256"]
  api_url_prefix       = "http://localhost:9200"
  is_primary_for_scope = true
  state                = "active-public"
}

Apply the updated configuration. Enter yes when prompted.

$ terraform apply
boundary_auth_method_oidc.provider: Refreshing state... [id=amoidc_ZMettTQoi7]
boundary_account_oidc.oidc_user: Refreshing state... [id=acctoidc_RioLnuyZMw]

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  ~ update in-place
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # boundary_account_oidc.oidc_user must be replaced
-/+ resource "boundary_account_oidc" "oidc_user" {
        auth_method_id = "amoidc_ZMettTQoi7"
        description    = "OIDC account for user1"
      ~ id             = "acctoidc_RioLnuyZMw" -> (known after apply)
      + issuer         = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/" # forces replacement
        name           = "user1"
      + subject        = "c3dc63d0-90e6-4855-b9c0-e87da14a9c5f"
    }

  # boundary_auth_method_oidc.provider will be updated in-place
  ~ resource "boundary_auth_method_oidc" "provider" {
        api_url_prefix       = "http://localhost:9200"
        callback_url         = "http://localhost:9200/v1/auth-methods/oidc:authenticate:callback"
        client_id            = "a4d21a76-e08c-4d8d-8c47-e1c423ee4d11"
        client_secret        = "X9u~u58--~rWLR4Q9i1-PtdZOi_s04~9O-"
        client_secret_hmac   = "qbLhGSr0XZpZhdEjChZwjJMqG-dZzsX9gSRG4f44jWQ"
        description          = "OIDC auth method for Azure"
        id                   = "amoidc_ZMettTQoi7"
      + is_primary_for_scope = true
        issuer               = "https://sts.windows.net/e29eae0c-29d7-4851-5e1fb68bfb3-5f8e3/"
        name                 = "Azure"
        scope_id             = "o_1234567890"
        signing_algorithms   = [
            "RS256",
        ]
        state                = "active-public"
        type                 = "oidc"
    }

Plan: 1 to add, 1 to change, 1 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_account_oidc.oidc_user: Destroying... [id=acctoidc_RioLnuyZMw]
boundary_auth_method_oidc.provider: Modifying... [id=amoidc_ZMettTQoi7]
boundary_auth_method_oidc.provider: Modifications complete after 0s [id=amoidc_ZMettTQoi7]
boundary_account_oidc.oidc_user: Destruction complete after 0s
boundary_account_oidc.oidc_user: Creating...
boundary_account_oidc.oidc_user: Creation complete after 0s [id=acctoidc_RioLnuyZMw]

Apply complete! Resources: 1 added, 1 changed, 1 destroyed.

Outputs:

auth-method-id = amoidc_ZMettTQoi7

With the auth method set to active and defined as the primary login method, users can now authenticate using their preferred method of choice.

Authenticate via OIDC

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.

The 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.

Auth0 Application Login

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!

  1. Navigate to the Boundary Cluster URL in your web browser. This is your HCP Cluster URL, such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud, or http://localhost:9200 if using Dev mode.

    Select OIDC or the name of the new auth method (such as Auth0) and click Authenticate.

    Auth0 Application Login

  2. If your browser doesn't allow pop-ups, you may be presented with an "Authentication Pending" message, which you can bypass by clicking Retry. If you do not encounter this message proceed to the next step. Consider enabling pop-ups from your localhost for the rest of this tutorial.

    Auth0 Application Login

  3. Next, enter your Auth0 user credentials and click Continue.

    Auth0 Application Login

  4. You should receive a "Successful Authentication" message and automatically be redirected to the Admin Console. If you are not redirected, check to make sure your browser is not blocking pop-ups from http://localhost:9200, or allow pop-ups temporarily.

    Auth0 Application Login

  5. Once authenticated, navigate to the Auth Methods view on the left, and notice the OIDC Type and ID used when setting up the auth method. Explore the other views and notice what this user has access to view and not view. The OIDC user could be updated to include new privileges if an admin user assigns it to a role.

    Auth0 Application Login

    You have now completed OIDC integration with the Admin Console!

The Boundary Desktop app is currently available for MacOS and Windows users.

Ensure that the latest version of the Boundary Desktop app is installed from the releases page before attempting to login with OIDC. The minimum version of the app allowing OIDC login is 1.0.0.

  1. Launch the Boundary Desktop app and enter the Boundary Cluster URL.

    The Cluster URL was copied from the HCP portal, such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud. Click Submit.

    Desktop Origin

    Launch the Boundary Desktop app and enter http://localhost:9200 as the Cluster URL, then click Submit.

    Desktop Cluster URL

  2. Select OIDC and click Authenticate.

    Desktop OIDC Login

  3. A browser window should launch and prompt for your provider's user credentials. You may see an "Authentication Pending" message, and can click the "Retry" button to force a new authentication tab to open.

    Desktop Application Login

    Submit your OIDC provider user credentials. Below is an example of authenticating via Auth0.

    Desktop Application Login

  4. You should receive a "Successful Authentication" message.

    Desktop Successful Auth

    Once authenticated, open the Boundary Desktop app again and verify the authenticated user in the upper-right corner of the application window.

    It is expected for this user to be unprivileged, and to be denied access to view targets and sessions. The OIDC user could be updated to include new privileges if an admin user assigns it to a role.

    Desktop Application Login

    You have now completed OIDC integration with the Boundary Desktop app!

Cleanup and teardown

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

1. Stop Boundary dev mode

Locate the shell where boundary dev was run and enter ctrl+c to stop dev mode.

^C==> Boundary dev environment shutdown triggered
[INFO]  worker: status ticking shutting down
[INFO]  controller: terminating completed sessions ticking shutting down
[INFO]  controller: closing expired pending tokens ticking shutting down
[INFO]  controller: status ticking shutting down
[INFO]  controller: recovery nonce ticking shutting down

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.

Next steps

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.

To learn more about the basics of managing user accounts, check out the Manage Users and Groups and Manage Roles tutorials.

 Previous
 Next

This tutorial also appears in:

  •  
    9 tutorials
    Interact with Security tools
    Use Terraform to interact with security tooling like HashiCorp Vault and Boundary. Manage Vault and Vault Enterprise. Configure Vault to use AppRole with Chef. Deploy Consul-backed Vault on Kubernetes.
    • Terraform
  •  
    16 tutorials
    HashiCorp Products - Better Together
    Use Terraform with other Hashicorp products including Vault, Boundary, Consul, Packer, and Hashicorp Cloud Platform.
    • Terraform

On this page

  1. OIDC Authentication
  2. Prerequisites
  3. Get setup
  4. Providers
  5. Auth method creation
  6. Authentication states
  7. Authenticate via OIDC
  8. Cleanup and teardown
  9. Next steps
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)