OIDC authentication with Okta

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

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.

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.

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)
• Signing Algorthm (Set to RS256) - Click Add

Additionally, set the API URL Prefix as follows:

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

Once the form is completed, click Save.

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.

Start by ensuring you are logged in to Boundary as the admin user.

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, Client Secret, and Issuer URL as environment variables.

$ export CLIENT_ID="<COPIED-CLIENT-ID>"; \export CLIENT_SECRET="<COPIED-CLIENT-SECRET>"; \export ISSUER_URL="<COPIED-OKTA-DOMAIN>"

Example:

$ export CLIENT_ID="0oal6fr0tPGZ0DSbr6d5"; \export CLIENT_SECRET="4BStQlbuTTrh5P-JhGAKW2FVPh48idEbFLKGGKJJ"; \export ISSUER_URL="dev-1944432.okta.com"

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

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://$ISSUER_URL" \  -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.

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 replace the recovery_kms_hcl key with the value printed in the boundary dev terminal window.

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 = <<EOTkms "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 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:

• kms key (from boundary dev)
• issuer (from provider)
• client_id (from provider)
• client_secret (from provider)
• subject (from provider)

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 = <<EOTkms "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 providerselections it made above. Include this file in your version control repositoryso that Terraform can guarantee to make the same selections by default whenyou run "terraform init" in the future. Terraform has been successfully initialized! You may now begin working with Terraform. Try running "terraform plan" to seeany changes that are required for your infrastructure. All Terraform commandsshould 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, othercommands 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.

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.

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

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

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.

A browser tab should automatically open and prompt you to log in with your Okta 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.

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

Enable 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 using 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

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 adminPlease 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_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 using 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 applyboundary_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 0sboundary_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.

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

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

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

   

2. Select Okta and click Authenticate.

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.

   

   Submit your OIDC provider user credentials.

   

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

   

   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.

   

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

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 the name of the new auth method (such as Okta) and click Authenticate.

   

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.

   

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

   

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.

   

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.

   You have now completed OIDC integration with the Admin Console.

The boundary authenticate oidc command will launch a browser session to enable authentication using the configured provider.

$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgAOpening 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 an Okta login prompt.

After logging in your terminal should confirm the Account and User IDs.

$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgAOpening 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 using 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 using the CLI.