Manage OIDC IdP groups
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
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
PATHThis 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.
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.
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.
Next, enter your provider's test account credentials and click Continue.
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.
Once authenticated, navigate to the Auth Methods view on the left, and notice the
OIDCType 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.
List the accounts associated with the OIDC auth method.
Copy the oidc account ID and read its details.
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.
Examples of filters that could be used with a managed group include:
"operator" in "/userinfo/roles"matches accounts that include "operator" in the roles returned in the userinfo reply"/token/custom/department" == "infosec"matches accounts that have "infosec" in the "/token/custom/department" JWT claim"boundary.com" in "/userinfo/email" and "auth0" in "/userinfo/sub"matches accounts that have "boundary.com" in the email claim and auth0 in the sub claim
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.
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.
Copy the role ID from the output, such as r_0Uz8McGUEs and create
an environment variable.
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.
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.
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.
In your browser, enter the username and password associated with your provider's test account.
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.
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
Clean up Terraform resources (optional)
If you followed the Terraform workflow and want to clean up, destroy the managed resources, and enter
yeswhen prompted for confirmation.Note
Terraform 0.15.2 and above uses
terraform destroy -applyto clean up resources. If using an older version, executeterraform destroyinstead.Stop Boundary
Log in to the HCP portal and delete the HCP Boundary instance.
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.
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.
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.