HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Boundary
Identity management

Manage OIDC IdP groups

  • 13min
  • |
  • Boundary

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.

OIDC group membership can be automatically maintained using managed groups.

This tutorial provides an example of managing identity provider (IdP) groups with Auth0, Okta, or Azure Active Directory providers and managing those authentication methods from HCP Boundary or Boundary's dev mode. Examples are provided for management via the CLI, Admin Console, or Terraform. The managed group is then used as a principal within a role to assign an example grant.

Manage IdP groups overview

  1. Get setup
  2. Managed groups background
  3. Create a managed group
  4. Create a role
  5. Verify permissions

Prerequisites

  • This tutorial assumes the user has completed setting up an identity provider according to the instructions in the Auth0, Okta, or Azure AD OIDC tutorials. This tutorial assumes the user has left the instance of HCP Boundary or Boundary's dev mode running, with an OIDC auth method fully configured.

  • A Boundary binary greater than 0.5.0 in your PATH

  • This tutorial assumes that you are able to 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 Terraform 0.13.0 or greater provides an optional workflow for this tutorial. The binary must be available in your PATH.

Get setup

This tutorial assumes the reader has successfully completed setting up an OIDC provider test account according to the instructions in the Auth0, Okta, or Azure AD OIDC tutorials. The reader should have left an instance of HCP Boundary or Boundary's dev mode running, with the sample OIDC provider configured.

Tip

If you want an environment that's easy to deploy for testing OIDC, consider following the Terraform deployment instructions in the OIDC Authentication tutorial. The dev environment can then easily be re-deployed in the future by launching Boundary and running Terraform.

To check that everything is set up properly, ensure that you can authenticate via OIDC using the CLI or Admin Console.

The following steps demonstrate authentication to Boundary using the Auth0 provider. The steps are essentially the same for any OIDC provider. If you encounter issues logging in, refer back to the OIDC Authentication tutorial for detailed steps on configuring an OIDC provider.

  1. Navigate to the Boundary admin UI.

    Navigate to the HCP Boundary cluster address in your browser (such as https://a2c4e6-867-53o9-994d-b6670e90b03J.boundary.hashicorp.cloud), click on "Choose a different scope" and select the Global scope. Select provider's name (such as Auth0) or "OIDC" and click Authenticate.

    Admin Console Org Scope Admin Console Org Scope

  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 provider's test account 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 or allow pop-ups temporarily.

    Auth0 Application Login 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. Select the auth method's name (such as Auth0) to view the account details. Click on the Roles tab and notice that the user associated with the account does not have permission to view the account details. The new user associated with the account has very limited permissions by default, and is unable to read the role details.

Managed groups background

In Boundary, the managed group resource represents a collection of accounts. A collection is automatically maintained by evaluating a filter defined in the managed group's configuration against the information returned by auth method's identity provider (IdP).

Accounts can be associated with zero or more managed groups within the same auth method, and grants can be associated with a managed group when used as a principle within a role.

Membership in a managed group is defined when an OIDC auth method is used for authentication. The collection is built based on filter criteria that match against the OIDC ID token and User Info endpoints, and every authentication updates the group membership comparison against the filter.

Gather OIDC account attributes

Managed Groups require filter criteria that describe which accounts belong to the group, and in turn should inherit any scoped permissions granted by an associate user and role. These filter attributes are returned from the OIDC provider when a user authenticates to Boundary using an OIDC account.

Filters can be built on two types of data returned from the OIDC provider: the claims from the JSON Web Token (JWT), or the claims from the UserInfo endpoint.

The claims can be obtained directly from an OIDC provider in a few ways. For example, claims info from Azure AD could be obtained from the Azure Portal, the Azure CLI, The Azure AD PowerShell Module, or by querying endpoint metadata.

Boundary gathers claims info from the JWT and userinfo endpoint and stores them as account attributes. These attributes are updated upon authentication to an OIDC provider, and are used as the basis for resolving a managed groups filter.

Start by displaying the gathered claims info for your IdP provider. Examples are shown below for Auth0, Okta, and Azure AD.

Ensure you are logged into the CLI as the admin user.

$ boundary authenticate password -auth-method-id $BOUNDARY_AUTH_METHOD_ID -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: Tue, 17 Aug 2021 13:56:57 MDT
  User ID:         u_1234567890

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

List the accounts associated with the OIDC auth method.

$ boundary accounts list -auth-method-id $OIDC_AUTH_ID

Account information:
  ID:                    acctoidc_xyYYFpjk34
    Version:             1
    Type:                oidc
    Authorized Actions:
      no-op
      read
      update
      delete

Copy the oidc account ID and read its details.

$ boundary accounts read -id acctoidc_xyYYFpjk34

Account information:
  Auth Method ID:      amoidc_9zoOFfKMmJ
  Created Time:        Wed, 18 Aug 2021 11:10:20 MDT
  ID:                  acctoidc_xyYYFpjk34
  Type:                oidc
  Updated Time:        Wed, 18 Aug 2021 11:10:20 MDT
  Version:             1

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

  Authorized Actions:
    no-op
    read
    update
    delete

  Attributes:
    issuer:            https://dev-1vdl8c0q.us.auth0.com/
    subject:           auth0|6077581e2ce19d006dfaf211
    token_claims:
    {
    "aud": "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx",
    "exp": 1629342620,
    "iat": 1629306620,
    "iss": "https://dev-1vdl8c0q.us.auth0.com/",
    "nonce": "nI9FKzQuTUSELZdVxxPR",
    "sub": "auth0|6077581e2ce19d006dfaf211"
    }
    userinfo_claims:
    {
    "sub": "auth0|6077581e2ce19d006dfaf211"
    }

Notice the Attributes section of the output. This information is populated by the IdP provider claims returned from the JWT and userinfo endpoint.

Custom claims can be utilized in Boundary by updating the info returned by the provider. This is non-trivial, and requires additional configuration of the provider. More information on account claims can be found in the Auth0 documentation. Claims attributes are updated when the user authenticates via Boundary using an associated account from the provider.

Copy the userinfo_claims: {"sub":} value (auth0|6077581e2ce19d006dfaf211 in this example).

Managed groups filters

Creating a managed group requires the oidc auth method ID and a filter that selects users for membership based on account claims.

In Boundary, filter expressions are used to extend functionality. The filter syntax includes creating expressions that match operators with a selector and a value. These plaintext expressions support Boolean logic and parenthesization, enabling compound expressions by connecting logical and, or and not statements.

Managed groups filtering enables automatic group management by selecting attributes from account claims returned by the OIDC provider. Claims associated with the JWT and userinfo endpoints are currently available for these filters.

As an example, consider the following hypothetical attributes for a Boundary OIDC user account.

  Attributes:
    issuer:            https://dev-1vdl8c0q.us.auth0.com/
    subject:           auth0|6077581e2ce19d006dfaf211
    token_claims:
    {
    "aud": "zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx",
    "exp": 1628738383,
    "iat": 1628702383,
    "iss": "https://dev-1vdl8c0q.us.auth0.com/",
    "nonce": "01BtOSuAunf0XeQXt3hR",
    "sub": "auth0|6077581e2ce19d006dfaf211",
    "custom":
      {
      "department": "infosec"
      }
    }
    userinfo_claims:
    {
    "roles": ["user", "operator"],
    "sub": "auth0|6077581e2ce19d006dfaf211",
    "email": "operator@boundary.com",
    "name": "operator"
    }

Examples of filters that could be used with a managed group include:

Expressions can be connected together to obtain the needed level of complexity for defining group membership. In this example, a user could receive the correct sets of permissions automatically by assigning them a role of "operator", or using another set of claims.

Note

Not all of these claims are returned from an identity provider by default, and would require additional configuration of the provider before they would be available to Boundary.

In order to create a managed group, filter criteria must first be selected from a set of account claims. Filters can be modified or updated later on after the creation of a managed group.

Create a managed group

Create a managed group with the following filter criteria:

"auth0" in "/userinfo/sub"

Log back in to the Admin Console UI global scope as the admin user.

Under the global scope, navigate to the Auth Methods view using the sidebar. Select the Auth0 Auth Method. Click the Managed Groups tab, and then click Create Managed Group.

Fill out the following type oidc managed group form fields:

  • Name: auth0 userinfo
  • Filter: `"auth0" in "/userinfo/sub

Click Save.

New managed group form New managed group form

Note

When creating a custom claim, it may be necessary to use JSON Pointer syntax to render the namespace properly. If you receive an Error evaluating submitted filter expression, attempt to reformat your filter using JSON Pointer syntax. For example, in JSON Pointer syntax http:// is written as http:~1~1. If your claim response contained http://my-domain, you might create the above filter like this: "auth0" in "/userinfo/http:~1~1my-domain/sub"

This filter selects all accounts whose /userinfo/sub claim contains auth0. Any of the other filter criteria available under the acctoidc attributes can be used for building an appropriate filter.

Verify group membership

Next, verify that oidc account is correctly assigned to the managed group.

Select the auth0 userinfo managed group, and then the Members tab. The OIDC account ID associated with the auth0 account should be displayed (acctoidc_2g9lcC4fIL in this example.)

Troubleshooting

If the Member IDs section is missing, first log out of the admin account, then log in as the OIDC user. This will refresh the userinfo claims for the OIDC user account. Next, re-authenticate as the admin user and attempt to verify the group membership again. If the member ID is still missing, check that the filter defined under the account details is correct. If the filter is incorrect, edit the managed group filter, then save the filter and attempt to verify the group membership again.

Create a role

With the managed group created and automatically managing group membership, the next step is to apply permissions to the group by creating a role.

After creating a role, the managed group is added as a role principle and grants are assigned to the role. To learn more about group principles, check out the Manage Users and Groups tutorial. To understand how permissions are granted, check out the Manage Roles tutorial.

Note

While basic CRUD operations can be performed on managed groups, admins cannot currently add managed groups as role principals using the Admin Console UI. Complete the next section using the CLI or Terraform workflows.

First, create a new role under the org scope.

$ boundary roles create -scope-id=$ORG_ID

Role information:
  Created Time:        Wed, 18 Aug 2021 11:58:34 MDT
  Grant Scope ID:      o_1234567890
  ID:                  r_0Uz8McGUEs
  Updated Time:        Wed, 18 Aug 2021 11:58:34 MDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete
    add-principals
    set-principals
    remove-principals
    add-grants
    set-grants
    remove-grants

Copy the role ID from the output, such as r_0Uz8McGUEs and create an environment variable.

$ export ROLE_ID=<actual-copied-value>

Add Managed Group as a role principle

Next, add the new managed group as a role principle so the group will inherit any grants associated with the role.

$ boundary roles add-principals -id=$ROLE_ID -principal $MG_OIDC_ID

Role information:
  Created Time:        Wed, 18 Aug 2021 11:58:34 MDT
  Grant Scope ID:      o_1234567890
  ID:                  r_0Uz8McGUEs
  Updated Time:        Wed, 18 Aug 2021 12:09:50 MDT
  Version:             3

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

  Authorized Actions:
    no-op
    read
    update
    delete
    add-principals
    set-principals
    remove-principals
    add-grants
    set-grants
    remove-grants

  Principals:
    ID:             mgoidc_VUsKIPJHS5
      Type:         managed group
      Scope ID:     o_1234567890

Assign grants to roles

Use the grant ids=*;type=role;actions=list,read, which selects any role ID and allows list and read actions to be performed. To learn more about setting permission grants, check out the Permission Grant Formats documentation.

$ boundary roles add-grants -id=$ROLE_ID -grant "ids=*;type=role;actions=list,read"

Role information:
  Created Time:        Wed, 18 Aug 2021 11:58:34 MDT
  Grant Scope ID:      o_1234567890
  ID:                  r_0Uz8McGUEs
  Updated Time:        Wed, 18 Aug 2021 12:07:36 MDT
  Version:             2

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

  Authorized Actions:
    no-op
    read
    update
    delete
    add-principals
    set-principals
    remove-principals
    add-grants
    set-grants
    remove-grants

  Principals:
    ID:             mgoidc_VUsKIPJHS5
      Type:         managed group
      Scope ID:     o_1234567890

  Canonical Grants:
    ids=*;type=role;actions=list,read

With the grants in place the oidc user should automatically be allowed to list and read roles upon authentication.

Verify permissions

Validate that the OIDC user has been granted permission to view roles.

Log in using the OIDC authentication method.

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

Authentication information:
  Account ID:      acctoidc_xyYYFpjk34
  Auth Method ID:  amoidc_9zoOFfKMmJ
  Expiration Time: Wed, 25 Aug 2021 12:14:23 MDT
  User ID:         u_Kt2AI1hPmC

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

In your browser, enter the username and password associated with your provider's test account.

OIDC Login

You should receive a "Successful authentication" message. Close the browser tab and return to your terminal.

Check that OIDC user has permissions to read the role associated with the managed group by the admin user account.

$ boundary roles read -id $ROLE_ID

Role information:
  Created Time:        Wed, 18 Aug 2021 11:58:34 MDT
  Grant Scope ID:      o_1234567890
  ID:                  r_0Uz8McGUEs
  Updated Time:        Wed, 18 Aug 2021 12:09:50 MDT
  Version:             3

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

  Authorized Actions:
    read

  Principals:
    ID:             mgoidc_VUsKIPJHS5
      Type:         managed group
      Scope ID:     o_1234567890

  Canonical Grants:
    ids=*;type=role;actions=list,read

The OIDC user now has permission to read the role created with the admin account.

While the user can now list and read roles, other actions like reading account details are still restricted. Additional permissions can be granted by updating the filters associated with the managed group.

Cleanup and teardown

  1. Clean up Terraform resources (optional)

    If you followed the Terraform workflow and want to clean up, destroy the managed resources, and enter yes when prompted for confirmation.

    $ terraform apply -destroy

    Note

    Terraform 0.15.2 and above uses terraform destroy -apply to clean up resources. If using an older version, execute terraform destroy instead.

  2. Stop Boundary

    Log in to the HCP portal and delete the HCP Boundary instance.

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

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

  5. 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 create an OIDC managed group and assign it grants. You set up a managed group with a filter to automatically manage group membership, created a role, added the managed group as a role principle, and assigned grants to the role that were inherited by the managed group's members.

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

Previous

OIDC authentication with Azure

 Next Collection

Self-managed deployment