From 9e5ce1f06b7bce371223ab0800fdc6ddc64f1fcf Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Tue, 2 Dec 2025 11:14:30 +0100 Subject: [PATCH 1/9] update auth0 sso for 1.22.x --- .../v1.22.x/content/docs/secure/sso/auth0.mdx | 200 +++--------------- 1 file changed, 28 insertions(+), 172 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx index a5f926e70f..79896dde4d 100644 --- a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx @@ -7,7 +7,11 @@ description: >- # Enable Auth0 single sign-on (SSO) -This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI. +This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). + +OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with individual Consul ACL tokens. Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. + +In this example you will configure [Auth0](https://auth0.com/) as an identity provider, and use the user metadata in Auth0 to automatically grant permissions in Consul ACL. This approach unifies the user permissions grant without the need to create individual user tokens or to define permissions individually for the different users. @@ -15,78 +19,16 @@ This page describes the process to configure Consul to use Auth0 for single sign -## Overview - -Consul Enterprise 1.8.0 introduced the ability to configure single sign-on (SSO) and to authenticate with Consul using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). - -OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with Consul ACL tokens. - -Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. - -In this tutorial you will configure [Auth0](https://auth0.com/) as an identity provider. Your configuration will use the user metadata in Auth0 to automatically grant permissions in Consul ACL. - -This is a multi-step process that includes: - -- configure an application in Auth0 for Consul integration; -- set up Consul ACL policies and roles to provide permissions to users -- configure user metadata and use binding rules to automatically assign permissions to users based on their metadata values. - -This approach unifies the user permissions grant without the need to create individual user tokens or to define permissions individually for the different users. The tutorial also shows one example of how to define service permissions grants for a user based on unique metadata values of the individual user, making this approach also suitable for finer grained permissions. - -## Prerequisites - -In order to complete this tutorial the following prerequisites need to be satisfied: - -- A Consul Enterprise datacenter or local dev agent. The datacenter will need ACLs enabled to use the OIDC authentication method. You can use the following ACL configuration as a minimal example to follow the steps in this tutorial: - - - -```hcl -acl { - enabled = true - default_policy = "deny" - - tokens { - initial_management = "root" - agent = "root" - } -} -``` - -```json -{ - "acl": { - "enabled": true, - "default_policy": "deny", - "tokens": { - "initial_management": "root", - "agent": "root" - } - } -} -``` +## Workflow - - - -- A valid [Auth0](https://auth0.com/) account. If you do not have one, create -one now, before continuing with the tutorial. The tutorial will show you the -configuration steps necessary to configure your Auth0 account to interact with -Consul. +1. [Configure an Auth0 application for Consul integration](#configure-auth0-application) +1. [Create Auth0 users and metadata](#create-auth0-users-and-metadata) +1. [Enable the OIDC auth method for Consul](#enable-the-oidc-auth-method-for-consul) +1. [Login with OIDC](#login-with-oidc) ## Configure Auth0 application -In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**. - -Once you have created a new account, Auth0 should already have a default -application called _Default App_ in the main Dashboard. - -In this tutorial we will be using the default application. - -Select **Default App** and open the **Settings** tab. - -In the Application configuration, you can set the callback URLs that the user -will be redirected to after the authentication process is completed. +Open the **Settings** tab in the [Auth0 App dashboard](https://manage.auth0.com/#/). ![Auth0 UI configure application to set callback URLs](/img/sso/auth0-configure-callback-urls.png) @@ -97,11 +39,9 @@ http://:8550/oidc/callback, http://:8500/ui/oidc/callback ``` -The `http://:8550/oidc/callback` address will be used by the -CLI when you login via `consul login -type=oidc -method=oidc` command. +The `http://:8550/oidc/callback` address will be used by the CLI when you login via `consul login -type=oidc -method=oidc` command. -The `http://:8500/ui/oidc/callback` address will -be used by the Consul UI when you login with OIDC auth method. +The `http://:8500/ui/oidc/callback` address will be used by the Consul UI when you login with OIDC auth method. @@ -109,22 +49,13 @@ be used by the Consul UI when you login with OIDC auth method. -For example, if you are running your Consul agent _locally_ you would use: - -```uri -http://localhost:8550/oidc/callback, -http://localhost:8500/ui/oidc/callback -``` - ## Create Auth0 users and metadata In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_ ![Auth0 UI create user form](/img/sso/auth0-create-user.png) -Create at least one demo user with username/password authentication. - -Edit the user's record and assign some `user_metadata` and `app_metadata` such as: +Create the user with username/password authentication. Then edit the user's record and assign `user_metadata` and `app_metadata` such as: ```json { @@ -143,11 +74,7 @@ Edit the user's record and assign some `user_metadata` and `app_metadata` such a ![Auth0 UI configure user metadata](/img/sso/auth0-configure-user-metadata.png) -## Configure claims in the ID tokens using Auth0 rules - -In the Auth0 dashboard for your application, on the sidebar, select **Rules**. - -Create a new rule with the following content: +Then, in the Auth0 dashboard for your application, on the sidebar, select **Rules** and create a new rule with the following content: ```javascript function (user, context, callback) { @@ -165,74 +92,25 @@ function (user, context, callback) { -> In this tutorial, we used `http://consul.internal` to namespace the claims that are not part of the [JWT RFC](https://tools.ietf.org/html/rfc7519). The namespace is arbitrary but must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are unnamespaced and not in the RFC. -## Create Consul policies and roles - -After the login procedure confirms the user identity, it has to then give them privileges when creating their ACL token. Auth methods in Consul use _binding rules_ to control that. - -Binding rules allow for two ways to assign privileges to a new token: - -- [Service identities](/consul/docs/security/acl#acl-service-identities): this approach is better suited for application login and is not suggested for user login. -- [Roles](/consul/docs/security/acl#acl-roles): this approach is preferred when enabling user login. - -Roles are a named collection of privileges, such as lists of policies and service identities, that can be linked to a token. - -In order to assign some privilege to a token via an auth method, you will first define the privilege in a policy and then assign that policy to a role. In this way, the binding rule can reference the role by name. - -### Step 1: Define policy for Auth0 users - -Create a policy named `eng-ro` to allow full read-only access of any service for service discovery. - -```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl policy create -name eng-ro \ - -rules='service_prefix "" { policy="read" } node_prefix "" { policy="read" }' -``` - -If the command completes successfully, you will receive an output similar to this: - -```plaintext hideClipboard -ID: 56c478f2-21a3-dc84-9116-4827e32125ff -Name: eng-ro -Namespace: default -Description: -Datacenters: -Rules: -service_prefix "" { policy="read" } node_prefix "" { policy="read" } -``` - -### Assign a policy to a role - -Next create a role named `eng-ro` linked to the policy created earlier. - -```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl role create -name eng-ro -policy-name eng-ro -``` - -If the command completes successfully, you will receive an output similar to this: - -```plaintext hideClipboard -Name: eng-ro -Namespace: default -Description: -Policies: - 56c478f2-21a3-dc84-9116-4827e32125ff - eng-ro -``` - ## Enable the OIDC auth method for Consul -In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**. - -Select **Default App**, and open the **Settings** tab. +In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**, then select your application (for example, **Default App**), and open the **Settings** tab. ![Auth0 UI get application parameters](/img/sso/auth0-get-application-params.png) You will use the values from **Domain**, **Client ID**, and **Client Secret** to create a configuration file for the OIDC auth method for Consul. +Make sure you replace: + +- `` +- `` +- `` + +with the values you retrieved from the Auth0 dashboard. + - Create a configuration file named `auth-method-config.json` for the new auth method. @@ -259,14 +137,6 @@ Create a configuration file named `auth-method-config.json` for the new auth met -You can use the following snippet as an example. Make sure you replace: - -- `` -- `` -- `` - -with the values you retrieved from the Auth0 dashboard. - Apply the configuration using the `consul acl auth-method` CLI command. ```shell-session @@ -280,7 +150,6 @@ $ CONSUL_HTTP_TOKEN=root \ - Create a configuration file named`auth-method-config.json` for the new auth method. @@ -312,14 +181,6 @@ Create a configuration file named`auth-method-config.json` for the new auth meth -You can use the following snippet as an example. Make sure you replace: - -- `` -- `` -- `` - -with the values you retrieved from the Auth0 dashboard. - Apply the configuration using the `acl/auth-method` API endpoint. ```shell-session @@ -331,12 +192,11 @@ $ curl -sL --header 'x-consul-token: root' --request PUT \ - Once you have configured the auth method, you can automate permissions grants to users using the metadata you defined earlier. This means that once auth method trust is established, Consul can be configured to bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. This can be configured using Consul binding rules. ### Grant role permissions with app metadata -Grant users in the `engineering` group the role `eng-ro`. +Assign the Consul role `eng-ro` to users in the Auth0 `engineering` group. ```shell-session $ CONSUL_HTTP_TOKEN=root \ @@ -357,11 +217,11 @@ BindName: eng-ro Selector: engineering in list.groups ``` -This will automatically associate every user with `engineering` in their `app_metadata` to Consul `eng-ro` role that you already associated with an ACL policy. +This will automatically associate every user with `engineering` in their `app_metadata` in Auth0 to the Consul `eng-ro` role. Check the following documentation for further information on Consul [roles](consul/docs/secure/acl/role) and Consul [policies](/consul/docs/secure/acl/policy). ### Grant service permissions with user metadata -If you want to grant users permissions to register services, you can use a service type binding. In this tutorial, you will grant users in the `engineering` group the ability to register a service in the service mesh with their own name. +If you want to grant users permissions to register services, you can use a service type binding. Here's how to grant users in the `engineering` group the ability to register a service in the service mesh with their own name. ```shell-session $ CONSUL_HTTP_TOKEN=root \ @@ -396,7 +256,7 @@ $ consul login -method=auth0 -type=oidc -token-sink-file=dev.token The command will redirect you to a browser page from which you can use the user credentials to login in Consul with SSO. -When prompted, accept and authorize the Consul access to your Default App. +When prompted, accept and authorize the Consul access to your Auth0 App. ![Consul UI post login page showing Signed in via OIDC](/img/sso/consul-ui-oidc-signed-in.png) @@ -447,8 +307,4 @@ Once login is successful, you can navigate to the Consul UI. In this tutorial you learned how to enable SSO for Consul Enterprise, and how to use Auth0 as the OIDC provider. -You configured Auth0 and created a user to test the SSO feature. - -Finally, you tested the SSO login using both the CLI and the UI. - Complete [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) to learn how to configure production ready ACLs for your Consul datacenter. From cc114969781e7fe9e875b7603aa6310b6cff00cf Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Tue, 2 Dec 2025 11:15:55 +0100 Subject: [PATCH 2/9] update auth0 sso for 1.21.x --- .../v1.21.x/content/docs/secure/sso/auth0.mdx | 200 +++--------------- 1 file changed, 28 insertions(+), 172 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx index a5f926e70f..79896dde4d 100644 --- a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx @@ -7,7 +7,11 @@ description: >- # Enable Auth0 single sign-on (SSO) -This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI. +This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). + +OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with individual Consul ACL tokens. Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. + +In this example you will configure [Auth0](https://auth0.com/) as an identity provider, and use the user metadata in Auth0 to automatically grant permissions in Consul ACL. This approach unifies the user permissions grant without the need to create individual user tokens or to define permissions individually for the different users. @@ -15,78 +19,16 @@ This page describes the process to configure Consul to use Auth0 for single sign -## Overview - -Consul Enterprise 1.8.0 introduced the ability to configure single sign-on (SSO) and to authenticate with Consul using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). - -OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with Consul ACL tokens. - -Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. - -In this tutorial you will configure [Auth0](https://auth0.com/) as an identity provider. Your configuration will use the user metadata in Auth0 to automatically grant permissions in Consul ACL. - -This is a multi-step process that includes: - -- configure an application in Auth0 for Consul integration; -- set up Consul ACL policies and roles to provide permissions to users -- configure user metadata and use binding rules to automatically assign permissions to users based on their metadata values. - -This approach unifies the user permissions grant without the need to create individual user tokens or to define permissions individually for the different users. The tutorial also shows one example of how to define service permissions grants for a user based on unique metadata values of the individual user, making this approach also suitable for finer grained permissions. - -## Prerequisites - -In order to complete this tutorial the following prerequisites need to be satisfied: - -- A Consul Enterprise datacenter or local dev agent. The datacenter will need ACLs enabled to use the OIDC authentication method. You can use the following ACL configuration as a minimal example to follow the steps in this tutorial: - - - -```hcl -acl { - enabled = true - default_policy = "deny" - - tokens { - initial_management = "root" - agent = "root" - } -} -``` - -```json -{ - "acl": { - "enabled": true, - "default_policy": "deny", - "tokens": { - "initial_management": "root", - "agent": "root" - } - } -} -``` +## Workflow - - - -- A valid [Auth0](https://auth0.com/) account. If you do not have one, create -one now, before continuing with the tutorial. The tutorial will show you the -configuration steps necessary to configure your Auth0 account to interact with -Consul. +1. [Configure an Auth0 application for Consul integration](#configure-auth0-application) +1. [Create Auth0 users and metadata](#create-auth0-users-and-metadata) +1. [Enable the OIDC auth method for Consul](#enable-the-oidc-auth-method-for-consul) +1. [Login with OIDC](#login-with-oidc) ## Configure Auth0 application -In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**. - -Once you have created a new account, Auth0 should already have a default -application called _Default App_ in the main Dashboard. - -In this tutorial we will be using the default application. - -Select **Default App** and open the **Settings** tab. - -In the Application configuration, you can set the callback URLs that the user -will be redirected to after the authentication process is completed. +Open the **Settings** tab in the [Auth0 App dashboard](https://manage.auth0.com/#/). ![Auth0 UI configure application to set callback URLs](/img/sso/auth0-configure-callback-urls.png) @@ -97,11 +39,9 @@ http://:8550/oidc/callback, http://:8500/ui/oidc/callback ``` -The `http://:8550/oidc/callback` address will be used by the -CLI when you login via `consul login -type=oidc -method=oidc` command. +The `http://:8550/oidc/callback` address will be used by the CLI when you login via `consul login -type=oidc -method=oidc` command. -The `http://:8500/ui/oidc/callback` address will -be used by the Consul UI when you login with OIDC auth method. +The `http://:8500/ui/oidc/callback` address will be used by the Consul UI when you login with OIDC auth method. @@ -109,22 +49,13 @@ be used by the Consul UI when you login with OIDC auth method. -For example, if you are running your Consul agent _locally_ you would use: - -```uri -http://localhost:8550/oidc/callback, -http://localhost:8500/ui/oidc/callback -``` - ## Create Auth0 users and metadata In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_ ![Auth0 UI create user form](/img/sso/auth0-create-user.png) -Create at least one demo user with username/password authentication. - -Edit the user's record and assign some `user_metadata` and `app_metadata` such as: +Create the user with username/password authentication. Then edit the user's record and assign `user_metadata` and `app_metadata` such as: ```json { @@ -143,11 +74,7 @@ Edit the user's record and assign some `user_metadata` and `app_metadata` such a ![Auth0 UI configure user metadata](/img/sso/auth0-configure-user-metadata.png) -## Configure claims in the ID tokens using Auth0 rules - -In the Auth0 dashboard for your application, on the sidebar, select **Rules**. - -Create a new rule with the following content: +Then, in the Auth0 dashboard for your application, on the sidebar, select **Rules** and create a new rule with the following content: ```javascript function (user, context, callback) { @@ -165,74 +92,25 @@ function (user, context, callback) { -> In this tutorial, we used `http://consul.internal` to namespace the claims that are not part of the [JWT RFC](https://tools.ietf.org/html/rfc7519). The namespace is arbitrary but must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are unnamespaced and not in the RFC. -## Create Consul policies and roles - -After the login procedure confirms the user identity, it has to then give them privileges when creating their ACL token. Auth methods in Consul use _binding rules_ to control that. - -Binding rules allow for two ways to assign privileges to a new token: - -- [Service identities](/consul/docs/security/acl#acl-service-identities): this approach is better suited for application login and is not suggested for user login. -- [Roles](/consul/docs/security/acl#acl-roles): this approach is preferred when enabling user login. - -Roles are a named collection of privileges, such as lists of policies and service identities, that can be linked to a token. - -In order to assign some privilege to a token via an auth method, you will first define the privilege in a policy and then assign that policy to a role. In this way, the binding rule can reference the role by name. - -### Step 1: Define policy for Auth0 users - -Create a policy named `eng-ro` to allow full read-only access of any service for service discovery. - -```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl policy create -name eng-ro \ - -rules='service_prefix "" { policy="read" } node_prefix "" { policy="read" }' -``` - -If the command completes successfully, you will receive an output similar to this: - -```plaintext hideClipboard -ID: 56c478f2-21a3-dc84-9116-4827e32125ff -Name: eng-ro -Namespace: default -Description: -Datacenters: -Rules: -service_prefix "" { policy="read" } node_prefix "" { policy="read" } -``` - -### Assign a policy to a role - -Next create a role named `eng-ro` linked to the policy created earlier. - -```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl role create -name eng-ro -policy-name eng-ro -``` - -If the command completes successfully, you will receive an output similar to this: - -```plaintext hideClipboard -Name: eng-ro -Namespace: default -Description: -Policies: - 56c478f2-21a3-dc84-9116-4827e32125ff - eng-ro -``` - ## Enable the OIDC auth method for Consul -In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**. - -Select **Default App**, and open the **Settings** tab. +In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**, then select your application (for example, **Default App**), and open the **Settings** tab. ![Auth0 UI get application parameters](/img/sso/auth0-get-application-params.png) You will use the values from **Domain**, **Client ID**, and **Client Secret** to create a configuration file for the OIDC auth method for Consul. +Make sure you replace: + +- `` +- `` +- `` + +with the values you retrieved from the Auth0 dashboard. + - Create a configuration file named `auth-method-config.json` for the new auth method. @@ -259,14 +137,6 @@ Create a configuration file named `auth-method-config.json` for the new auth met -You can use the following snippet as an example. Make sure you replace: - -- `` -- `` -- `` - -with the values you retrieved from the Auth0 dashboard. - Apply the configuration using the `consul acl auth-method` CLI command. ```shell-session @@ -280,7 +150,6 @@ $ CONSUL_HTTP_TOKEN=root \ - Create a configuration file named`auth-method-config.json` for the new auth method. @@ -312,14 +181,6 @@ Create a configuration file named`auth-method-config.json` for the new auth meth -You can use the following snippet as an example. Make sure you replace: - -- `` -- `` -- `` - -with the values you retrieved from the Auth0 dashboard. - Apply the configuration using the `acl/auth-method` API endpoint. ```shell-session @@ -331,12 +192,11 @@ $ curl -sL --header 'x-consul-token: root' --request PUT \ - Once you have configured the auth method, you can automate permissions grants to users using the metadata you defined earlier. This means that once auth method trust is established, Consul can be configured to bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. This can be configured using Consul binding rules. ### Grant role permissions with app metadata -Grant users in the `engineering` group the role `eng-ro`. +Assign the Consul role `eng-ro` to users in the Auth0 `engineering` group. ```shell-session $ CONSUL_HTTP_TOKEN=root \ @@ -357,11 +217,11 @@ BindName: eng-ro Selector: engineering in list.groups ``` -This will automatically associate every user with `engineering` in their `app_metadata` to Consul `eng-ro` role that you already associated with an ACL policy. +This will automatically associate every user with `engineering` in their `app_metadata` in Auth0 to the Consul `eng-ro` role. Check the following documentation for further information on Consul [roles](consul/docs/secure/acl/role) and Consul [policies](/consul/docs/secure/acl/policy). ### Grant service permissions with user metadata -If you want to grant users permissions to register services, you can use a service type binding. In this tutorial, you will grant users in the `engineering` group the ability to register a service in the service mesh with their own name. +If you want to grant users permissions to register services, you can use a service type binding. Here's how to grant users in the `engineering` group the ability to register a service in the service mesh with their own name. ```shell-session $ CONSUL_HTTP_TOKEN=root \ @@ -396,7 +256,7 @@ $ consul login -method=auth0 -type=oidc -token-sink-file=dev.token The command will redirect you to a browser page from which you can use the user credentials to login in Consul with SSO. -When prompted, accept and authorize the Consul access to your Default App. +When prompted, accept and authorize the Consul access to your Auth0 App. ![Consul UI post login page showing Signed in via OIDC](/img/sso/consul-ui-oidc-signed-in.png) @@ -447,8 +307,4 @@ Once login is successful, you can navigate to the Consul UI. In this tutorial you learned how to enable SSO for Consul Enterprise, and how to use Auth0 as the OIDC provider. -You configured Auth0 and created a user to test the SSO feature. - -Finally, you tested the SSO login using both the CLI and the UI. - Complete [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) to learn how to configure production ready ACLs for your Consul datacenter. From 3f940027c3d2aeb2baa77df277adee2a3a78aa61 Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Fri, 5 Dec 2025 14:42:42 +0100 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../v1.21.x/content/docs/secure/sso/auth0.mdx | 51 +++++++++---------- 1 file changed, 23 insertions(+), 28 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx index 79896dde4d..8948fd681e 100644 --- a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx @@ -7,22 +7,23 @@ description: >- # Enable Auth0 single sign-on (SSO) -This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). +This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using OpenID Connect (OIDC). OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with individual Consul ACL tokens. Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. +## Introduction -In this example you will configure [Auth0](https://auth0.com/) as an identity provider, and use the user metadata in Auth0 to automatically grant permissions in Consul ACL. This approach unifies the user permissions grant without the need to create individual user tokens or to define permissions individually for the different users. +These instructions configure Auth0 as an identity provider, so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. - The single sign-on (SSO) functionality demonstrated here requires self-managed [Consul Enterprise](https://www.hashicorp.com/products/consul/pricing/). If you've purchased or wish to try out Consul Enterprise, refer to [how to access Consul Enterprise](/consul/docs/enterprise#access-consul-enterprise). + The single sign-on (SSO) functionality demonstrated here requires [Consul Enterprise](/consul/docs/enterprise#access-consul-enterprise). ## Workflow 1. [Configure an Auth0 application for Consul integration](#configure-auth0-application) -1. [Create Auth0 users and metadata](#create-auth0-users-and-metadata) +1. [Create a rule to associate Auth0 users and Consul metadata](#create-auth0-users-and-metadata) 1. [Enable the OIDC auth method for Consul](#enable-the-oidc-auth-method-for-consul) 1. [Login with OIDC](#login-with-oidc) @@ -39,9 +40,9 @@ http://:8550/oidc/callback, http://:8500/ui/oidc/callback ``` -The `http://:8550/oidc/callback` address will be used by the CLI when you login via `consul login -type=oidc -method=oidc` command. +The `http://:8550/oidc/callback` address is for logins with the CLI `consul login -type=oidc -method=oidc` command. -The `http://:8500/ui/oidc/callback` address will be used by the Consul UI when you login with OIDC auth method. +The `http://:8500/ui/oidc/callback` is for logins with the Consul UI. @@ -59,22 +60,16 @@ Create the user with username/password authentication. Then edit the user's reco ```json { - // user_metadata (end-user editable) - "first_name": "Kara", - "last_name": "Danvers" -} -``` +The data you associate with Auth0 may change depending on your existing configurations. This example uses `user_metadata` and `app_metadata` to configure Auth0. ```json { - // app_metadata (end-user not editable) - "roles": ["engineering"] +// user_metadata (end-user editable) +"first_name": "Kara", +"last_name": "Danvers" } -``` -![Auth0 UI configure user metadata](/img/sso/auth0-configure-user-metadata.png) - -Then, in the Auth0 dashboard for your application, on the sidebar, select **Rules** and create a new rule with the following content: +In Auth0, create a new rule with the following javascript function: ```javascript function (user, context, callback) { @@ -88,17 +83,17 @@ function (user, context, callback) { } ``` -![Auth0 UI configure callback rule](/img/sso/auth0-configure-callback-rule.png) +This functions associates your user and app metadata in Auth0 with Consul's data. --> In this tutorial, we used `http://consul.internal` to namespace the claims that are not part of the [JWT RFC](https://tools.ietf.org/html/rfc7519). The namespace is arbitrary but must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are unnamespaced and not in the RFC. +This example uses `http://consul.internal` to namespace the claims that are not part of the [JWT RFC](https://tools.ietf.org/html/rfc7519). The namespace is arbitrary, but it must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are unnamespaced and not in the RFC. ## Enable the OIDC auth method for Consul -In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**, then select your application (for example, **Default App**), and open the **Settings** tab. - -![Auth0 UI get application parameters](/img/sso/auth0-get-application-params.png) +Retrieve the following application parameters from Auth0: -You will use the values from **Domain**, **Client ID**, and **Client Secret** to create a configuration file for the OIDC auth method for Consul. +- **Domain** +- **Client ID** +- **Client Secret** Make sure you replace: @@ -192,11 +187,11 @@ $ curl -sL --header 'x-consul-token: root' --request PUT \ -Once you have configured the auth method, you can automate permissions grants to users using the metadata you defined earlier. This means that once auth method trust is established, Consul can be configured to bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. This can be configured using Consul binding rules. +After you configure the auth method, you can automate permissions grants to users. That way, Consul can bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. You can configure this behavior with Consul binding rules. ### Grant role permissions with app metadata -Assign the Consul role `eng-ro` to users in the Auth0 `engineering` group. +Next, create a Consul ACL role and token to associate with the Auth0 method. The following command creates an ACL role named `eng-ro` and assigns it to users in the Auth0 `engineering` group. ```shell-session $ CONSUL_HTTP_TOKEN=root \ @@ -217,11 +212,11 @@ BindName: eng-ro Selector: engineering in list.groups ``` -This will automatically associate every user with `engineering` in their `app_metadata` in Auth0 to the Consul `eng-ro` role. Check the following documentation for further information on Consul [roles](consul/docs/secure/acl/role) and Consul [policies](/consul/docs/secure/acl/policy). +Every user with `engineering` in their `app_metadata` in Auth0 will be assigned the Consul `eng-ro` role. Check the following documentation for further information on [Consul ACL roles](consul/docs/secure/acl/role) and [Consul ACL policies](/consul/docs/secure/acl/policy). ### Grant service permissions with user metadata -If you want to grant users permissions to register services, you can use a service type binding. Here's how to grant users in the `engineering` group the ability to register a service in the service mesh with their own name. +If you want to grant users permissions to register services, use a service type binding. The following example grants users in the `engineering` group the ability to register a service using a token that is dynamically generated from their own name. ```shell-session $ CONSUL_HTTP_TOKEN=root \ @@ -305,6 +300,6 @@ Once login is successful, you can navigate to the Consul UI. ## Next steps -In this tutorial you learned how to enable SSO for Consul Enterprise, and how to use Auth0 as the OIDC provider. +## Next steps Complete [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) to learn how to configure production ready ACLs for your Consul datacenter. From 8d8efaad21867f765fe7692d39d5243d888ec340 Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Fri, 5 Dec 2025 16:14:23 +0100 Subject: [PATCH 4/9] fixing codereview points --- .../v1.21.x/content/docs/secure/sso/auth0.mdx | 102 ++++++++++-------- 1 file changed, 55 insertions(+), 47 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx index 8948fd681e..577d67d17b 100644 --- a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx @@ -10,6 +10,7 @@ description: >- This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using OpenID Connect (OIDC). OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with individual Consul ACL tokens. Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. + ## Introduction These instructions configure Auth0 as an identity provider, so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. @@ -29,20 +30,26 @@ These instructions configure Auth0 as an identity provider, so that Consul can u ## Configure Auth0 application -Open the **Settings** tab in the [Auth0 App dashboard](https://manage.auth0.com/#/). +In order to configure an Auth0 application for Consul, you will first need to take note of your Consul agent address. This is the address that you use to access Consul, either via the UI or the CLI. To fetch it, run the following command: + +```shell-session +$ echo $CONSUL_HTTP_ADDR +http://localhost:8500 +``` + +In this case, the Consul agent address is `localhost`, running on the default port `8500`. Next, open the **Settings** tab in the [Auth0 App dashboard](https://manage.auth0.com/#/). ![Auth0 UI configure application to set callback URLs](/img/sso/auth0-configure-callback-urls.png) In the **Allowed Callback URLs** field, enter the following: ```uri -http://:8550/oidc/callback, -http://:8500/ui/oidc/callback +http://localhost:8550/oidc/callback, +http://localhost:8500/ui/oidc/callback ``` -The `http://:8550/oidc/callback` address is for logins with the CLI `consul login -type=oidc -method=oidc` command. - -The `http://:8500/ui/oidc/callback` is for logins with the Consul UI. +The `http://localhost:8550/oidc/callback` address is for logins with the CLI `consul login -type=oidc -method=oidc` command. +The `http://localhost:8500/ui/oidc/callback` is for logins with the Consul UI. @@ -52,22 +59,26 @@ The `http://:8500/ui/oidc/callback` is for logins with the ## Create Auth0 users and metadata -In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_ +In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_. ![Auth0 UI create user form](/img/sso/auth0-create-user.png) -Create the user with username/password authentication. Then edit the user's record and assign `user_metadata` and `app_metadata` such as: +The data you associate with Auth0 may change depending on your existing configurations. This example uses `user_metadata` and `app_metadata` to configure Auth0. ```json { -The data you associate with Auth0 may change depending on your existing configurations. This example uses `user_metadata` and `app_metadata` to configure Auth0. + // user_metadata (end-user editable) + "first_name": "Kara", + "last_name": "Danvers" +} +``` ```json { -// user_metadata (end-user editable) -"first_name": "Kara", -"last_name": "Danvers" + // app_metadata (end-user not editable) + "roles": ["engineering"] } +``` In Auth0, create a new rule with the following javascript function: @@ -89,24 +100,10 @@ This example uses `http://consul.internal` to namespace the claims that are not ## Enable the OIDC auth method for Consul -Retrieve the following application parameters from Auth0: - -- **Domain** -- **Client ID** -- **Client Secret** - -Make sure you replace: - -- `` -- `` -- `` - -with the values you retrieved from the Auth0 dashboard. +In order to enable the OIDC auth method for Consul, you need to create a new auth method configuration that points to your Auth0 application. The contents of this configuration file depend on which way you supply it to Consul. You can either use the Consul CLI or the HTTP API. - - -Create a configuration file named `auth-method-config.json` for the new auth method. + @@ -132,20 +129,8 @@ Create a configuration file named `auth-method-config.json` for the new auth met -Apply the configuration using the `consul acl auth-method` CLI command. - -```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl auth-method create -type oidc \ - -name auth0 \ - -max-token-ttl=5m \ - -config=@auth-method-config.json -``` - - - -Create a configuration file named`auth-method-config.json` for the new auth method. + @@ -176,11 +161,36 @@ Create a configuration file named`auth-method-config.json` for the new auth meth + + + +The configuration file above contains variables that you need to replace with the values from your Auth0 application. Make sure you replace: + +- `` +- `` +- `` + +After you create the configuration file, apply it to Consul for the new auth method to take effect. Note that the configuration file contents differ slightly depending on whether you use the CLI or the HTTP API. + + + + +Apply the configuration using the `consul acl auth-method` CLI command. + +```shell-session +$ consul acl auth-method create -type oidc \ + -name auth0 -max-token-ttl=5m \ + -config=@auth-method-config.json +``` + + + + Apply the configuration using the `acl/auth-method` API endpoint. ```shell-session -$ curl -sL --header 'x-consul-token: root' --request PUT \ - http://localhost:8500/v1/acl/auth-method \ +$ curl -sL --header "x-consul-token: $CONSUL_HTTP_TOKEN" \ + --request PUT http://localhost:8500/v1/acl/auth-method \ --data @auth-method-config.json ``` @@ -194,8 +204,7 @@ After you configure the auth method, you can automate permissions grants to user Next, create a Consul ACL role and token to associate with the Auth0 method. The following command creates an ACL role named `eng-ro` and assigns it to users in the Auth0 `engineering` group. ```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl binding-rule create \ +$ consul acl binding-rule create \ -method=auth0 \ -bind-type=role \ -bind-name=eng-ro \ @@ -219,8 +228,7 @@ Every user with `engineering` in their `app_metadata` in Auth0 will be assigned If you want to grant users permissions to register services, use a service type binding. The following example grants users in the `engineering` group the ability to register a service using a token that is dynamically generated from their own name. ```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl binding-rule create \ +$ consul acl binding-rule create \ -method=auth0 \ -bind-type=service \ -bind-name='dev-${value.first_name}-${value.last_name}' \ From 999957f20a861475047f1c62f9915d2f8a7cc155 Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Fri, 5 Dec 2025 16:16:42 +0100 Subject: [PATCH 5/9] fixing codereview points for v1.22.x --- .../v1.22.x/content/docs/secure/sso/auth0.mdx | 117 +++++++++--------- 1 file changed, 60 insertions(+), 57 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx index 79896dde4d..577d67d17b 100644 --- a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx @@ -7,41 +7,49 @@ description: >- # Enable Auth0 single sign-on (SSO) -This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). +This page describes the process to configure Consul to use Auth0 for single sign-on (SSO) in the Consul UI and CLI using OpenID Connect (OIDC). OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access with individual Consul ACL tokens. Once implemented, SSO will enable an interactive login procedure that can be initiated from either the Consul UI or the command line. -In this example you will configure [Auth0](https://auth0.com/) as an identity provider, and use the user metadata in Auth0 to automatically grant permissions in Consul ACL. This approach unifies the user permissions grant without the need to create individual user tokens or to define permissions individually for the different users. +## Introduction + +These instructions configure Auth0 as an identity provider, so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. - The single sign-on (SSO) functionality demonstrated here requires self-managed [Consul Enterprise](https://www.hashicorp.com/products/consul/pricing/). If you've purchased or wish to try out Consul Enterprise, refer to [how to access Consul Enterprise](/consul/docs/enterprise#access-consul-enterprise). + The single sign-on (SSO) functionality demonstrated here requires [Consul Enterprise](/consul/docs/enterprise#access-consul-enterprise). ## Workflow 1. [Configure an Auth0 application for Consul integration](#configure-auth0-application) -1. [Create Auth0 users and metadata](#create-auth0-users-and-metadata) +1. [Create a rule to associate Auth0 users and Consul metadata](#create-auth0-users-and-metadata) 1. [Enable the OIDC auth method for Consul](#enable-the-oidc-auth-method-for-consul) 1. [Login with OIDC](#login-with-oidc) ## Configure Auth0 application -Open the **Settings** tab in the [Auth0 App dashboard](https://manage.auth0.com/#/). +In order to configure an Auth0 application for Consul, you will first need to take note of your Consul agent address. This is the address that you use to access Consul, either via the UI or the CLI. To fetch it, run the following command: + +```shell-session +$ echo $CONSUL_HTTP_ADDR +http://localhost:8500 +``` + +In this case, the Consul agent address is `localhost`, running on the default port `8500`. Next, open the **Settings** tab in the [Auth0 App dashboard](https://manage.auth0.com/#/). ![Auth0 UI configure application to set callback URLs](/img/sso/auth0-configure-callback-urls.png) In the **Allowed Callback URLs** field, enter the following: ```uri -http://:8550/oidc/callback, -http://:8500/ui/oidc/callback +http://localhost:8550/oidc/callback, +http://localhost:8500/ui/oidc/callback ``` -The `http://:8550/oidc/callback` address will be used by the CLI when you login via `consul login -type=oidc -method=oidc` command. - -The `http://:8500/ui/oidc/callback` address will be used by the Consul UI when you login with OIDC auth method. +The `http://localhost:8550/oidc/callback` address is for logins with the CLI `consul login -type=oidc -method=oidc` command. +The `http://localhost:8500/ui/oidc/callback` is for logins with the Consul UI. @@ -51,11 +59,11 @@ The `http://:8500/ui/oidc/callback` address will be used b ## Create Auth0 users and metadata -In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_ +In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_. ![Auth0 UI create user form](/img/sso/auth0-create-user.png) -Create the user with username/password authentication. Then edit the user's record and assign `user_metadata` and `app_metadata` such as: +The data you associate with Auth0 may change depending on your existing configurations. This example uses `user_metadata` and `app_metadata` to configure Auth0. ```json { @@ -72,9 +80,7 @@ Create the user with username/password authentication. Then edit the user's reco } ``` -![Auth0 UI configure user metadata](/img/sso/auth0-configure-user-metadata.png) - -Then, in the Auth0 dashboard for your application, on the sidebar, select **Rules** and create a new rule with the following content: +In Auth0, create a new rule with the following javascript function: ```javascript function (user, context, callback) { @@ -88,30 +94,16 @@ function (user, context, callback) { } ``` -![Auth0 UI configure callback rule](/img/sso/auth0-configure-callback-rule.png) +This functions associates your user and app metadata in Auth0 with Consul's data. --> In this tutorial, we used `http://consul.internal` to namespace the claims that are not part of the [JWT RFC](https://tools.ietf.org/html/rfc7519). The namespace is arbitrary but must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are unnamespaced and not in the RFC. +This example uses `http://consul.internal` to namespace the claims that are not part of the [JWT RFC](https://tools.ietf.org/html/rfc7519). The namespace is arbitrary, but it must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are unnamespaced and not in the RFC. ## Enable the OIDC auth method for Consul -In the [Auth0 dashboard](https://manage.auth0.com/#/), select **Applications**, then select your application (for example, **Default App**), and open the **Settings** tab. - -![Auth0 UI get application parameters](/img/sso/auth0-get-application-params.png) - -You will use the values from **Domain**, **Client ID**, and **Client Secret** to create a configuration file for the OIDC auth method for Consul. - -Make sure you replace: - -- `` -- `` -- `` - -with the values you retrieved from the Auth0 dashboard. +In order to enable the OIDC auth method for Consul, you need to create a new auth method configuration that points to your Auth0 application. The contents of this configuration file depend on which way you supply it to Consul. You can either use the Consul CLI or the HTTP API. - - -Create a configuration file named `auth-method-config.json` for the new auth method. + @@ -137,20 +129,8 @@ Create a configuration file named `auth-method-config.json` for the new auth met -Apply the configuration using the `consul acl auth-method` CLI command. - -```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl auth-method create -type oidc \ - -name auth0 \ - -max-token-ttl=5m \ - -config=@auth-method-config.json -``` - - - -Create a configuration file named`auth-method-config.json` for the new auth method. + @@ -181,26 +161,50 @@ Create a configuration file named`auth-method-config.json` for the new auth meth + + + +The configuration file above contains variables that you need to replace with the values from your Auth0 application. Make sure you replace: + +- `` +- `` +- `` + +After you create the configuration file, apply it to Consul for the new auth method to take effect. Note that the configuration file contents differ slightly depending on whether you use the CLI or the HTTP API. + + + + +Apply the configuration using the `consul acl auth-method` CLI command. + +```shell-session +$ consul acl auth-method create -type oidc \ + -name auth0 -max-token-ttl=5m \ + -config=@auth-method-config.json +``` + + + + Apply the configuration using the `acl/auth-method` API endpoint. ```shell-session -$ curl -sL --header 'x-consul-token: root' --request PUT \ - http://localhost:8500/v1/acl/auth-method \ +$ curl -sL --header "x-consul-token: $CONSUL_HTTP_TOKEN" \ + --request PUT http://localhost:8500/v1/acl/auth-method \ --data @auth-method-config.json ``` -Once you have configured the auth method, you can automate permissions grants to users using the metadata you defined earlier. This means that once auth method trust is established, Consul can be configured to bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. This can be configured using Consul binding rules. +After you configure the auth method, you can automate permissions grants to users. That way, Consul can bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. You can configure this behavior with Consul binding rules. ### Grant role permissions with app metadata -Assign the Consul role `eng-ro` to users in the Auth0 `engineering` group. +Next, create a Consul ACL role and token to associate with the Auth0 method. The following command creates an ACL role named `eng-ro` and assigns it to users in the Auth0 `engineering` group. ```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl binding-rule create \ +$ consul acl binding-rule create \ -method=auth0 \ -bind-type=role \ -bind-name=eng-ro \ @@ -217,15 +221,14 @@ BindName: eng-ro Selector: engineering in list.groups ``` -This will automatically associate every user with `engineering` in their `app_metadata` in Auth0 to the Consul `eng-ro` role. Check the following documentation for further information on Consul [roles](consul/docs/secure/acl/role) and Consul [policies](/consul/docs/secure/acl/policy). +Every user with `engineering` in their `app_metadata` in Auth0 will be assigned the Consul `eng-ro` role. Check the following documentation for further information on [Consul ACL roles](consul/docs/secure/acl/role) and [Consul ACL policies](/consul/docs/secure/acl/policy). ### Grant service permissions with user metadata -If you want to grant users permissions to register services, you can use a service type binding. Here's how to grant users in the `engineering` group the ability to register a service in the service mesh with their own name. +If you want to grant users permissions to register services, use a service type binding. The following example grants users in the `engineering` group the ability to register a service using a token that is dynamically generated from their own name. ```shell-session -$ CONSUL_HTTP_TOKEN=root \ - consul acl binding-rule create \ +$ consul acl binding-rule create \ -method=auth0 \ -bind-type=service \ -bind-name='dev-${value.first_name}-${value.last_name}' \ @@ -305,6 +308,6 @@ Once login is successful, you can navigate to the Consul UI. ## Next steps -In this tutorial you learned how to enable SSO for Consul Enterprise, and how to use Auth0 as the OIDC provider. +## Next steps Complete [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) to learn how to configure production ready ACLs for your Consul datacenter. From 910bacff7666110ed994c417e47cb919cca688cb Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Fri, 5 Dec 2025 17:25:30 +0100 Subject: [PATCH 6/9] add consul token explanation to curl command --- content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx | 2 +- content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx index 577d67d17b..ecb4ffa0e9 100644 --- a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx @@ -186,7 +186,7 @@ $ consul acl auth-method create -type oidc \ -Apply the configuration using the `acl/auth-method` API endpoint. +Apply the configuration using the `acl/auth-method` API endpoint. Note the use of the `CONSUL_HTTP_TOKEN` environment variable to authenticate the request. ```shell-session $ curl -sL --header "x-consul-token: $CONSUL_HTTP_TOKEN" \ diff --git a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx index 577d67d17b..ecb4ffa0e9 100644 --- a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx @@ -186,7 +186,7 @@ $ consul acl auth-method create -type oidc \ -Apply the configuration using the `acl/auth-method` API endpoint. +Apply the configuration using the `acl/auth-method` API endpoint. Note the use of the `CONSUL_HTTP_TOKEN` environment variable to authenticate the request. ```shell-session $ curl -sL --header "x-consul-token: $CONSUL_HTTP_TOKEN" \ From c1a2965ebc1267b95dc8c9fb62f273747f081c16 Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Thu, 11 Dec 2025 17:03:28 +0100 Subject: [PATCH 7/9] removing duplicate next-steps section --- content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx | 2 -- content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx | 2 -- 2 files changed, 4 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx index ecb4ffa0e9..e00f6010e4 100644 --- a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx @@ -308,6 +308,4 @@ Once login is successful, you can navigate to the Consul UI. ## Next steps -## Next steps - Complete [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) to learn how to configure production ready ACLs for your Consul datacenter. diff --git a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx index ecb4ffa0e9..e00f6010e4 100644 --- a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx @@ -308,6 +308,4 @@ Once login is successful, you can navigate to the Consul UI. ## Next steps -## Next steps - Complete [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) to learn how to configure production ready ACLs for your Consul datacenter. From bd5c93c60204ff90818001adc495b621abd564a4 Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Fri, 12 Dec 2025 18:54:36 +0100 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../v1.21.x/content/docs/secure/sso/auth0.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx index e00f6010e4..1a0da2f7ee 100644 --- a/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx @@ -13,7 +13,7 @@ OIDC authentication is useful when you want to deploy SSO widely in your organiz ## Introduction -These instructions configure Auth0 as an identity provider, so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. +These instructions configure Auth0 as an identity provider so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. @@ -30,7 +30,7 @@ These instructions configure Auth0 as an identity provider, so that Consul can u ## Configure Auth0 application -In order to configure an Auth0 application for Consul, you will first need to take note of your Consul agent address. This is the address that you use to access Consul, either via the UI or the CLI. To fetch it, run the following command: +To configure an Auth0 application for Consul, you need your Consul agent address. This is the address that you use to access Consul, either in your web browser with the Consul UI or with your terminal through the CLI. To fetch the address, run the following command: ```shell-session $ echo $CONSUL_HTTP_ADDR @@ -59,7 +59,7 @@ The `http://localhost:8500/ui/oidc/callback` is for logins with the Consul UI. ## Create Auth0 users and metadata -In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_. +In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on **Create User**. ![Auth0 UI create user form](/img/sso/auth0-create-user.png) @@ -100,7 +100,9 @@ This example uses `http://consul.internal` to namespace the claims that are not ## Enable the OIDC auth method for Consul -In order to enable the OIDC auth method for Consul, you need to create a new auth method configuration that points to your Auth0 application. The contents of this configuration file depend on which way you supply it to Consul. You can either use the Consul CLI or the HTTP API. +In order to enable the OIDC auth method for Consul, you need to create a new auth method configuration that points to your Auth0 application. The contents of this configuration file depend on which way you supply it to Consul. + +You can either use the Consul CLI or the HTTP API. Note that the configuration file contents differ slightly depending on whether you use the CLI or the HTTP API. @@ -170,7 +172,7 @@ The configuration file above contains variables that you need to replace with th - `` - `` -After you create the configuration file, apply it to Consul for the new auth method to take effect. Note that the configuration file contents differ slightly depending on whether you use the CLI or the HTTP API. +After you create the configuration file, apply it to Consul for the new auth method to take effect. @@ -197,7 +199,7 @@ $ curl -sL --header "x-consul-token: $CONSUL_HTTP_TOKEN" \ -After you configure the auth method, you can automate permissions grants to users. That way, Consul can bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. You can configure this behavior with Consul binding rules. +After you configure the auth method, you can automate permissions grants to users. That way, Consul can bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. You can configure this behavior with Consul binding rules. ### Grant role permissions with app metadata From 467a1d0a8affd82ffd37f0640746f2eb970b2942 Mon Sep 17 00:00:00 2001 From: Krastin Krastev Date: Fri, 12 Dec 2025 18:56:15 +0100 Subject: [PATCH 9/9] propagate changes from 1.21.x file to 1.22.x --- .../v1.22.x/content/docs/secure/sso/auth0.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx index e00f6010e4..1a0da2f7ee 100644 --- a/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx +++ b/content/consul/v1.22.x/content/docs/secure/sso/auth0.mdx @@ -13,7 +13,7 @@ OIDC authentication is useful when you want to deploy SSO widely in your organiz ## Introduction -These instructions configure Auth0 as an identity provider, so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. +These instructions configure Auth0 as an identity provider so that Consul can use data in Auth0 to automatically grant permissions for Consul ACL. This approach unifies the user permissions grants without creating individual user tokens or manually defining individual permissions for different users. @@ -30,7 +30,7 @@ These instructions configure Auth0 as an identity provider, so that Consul can u ## Configure Auth0 application -In order to configure an Auth0 application for Consul, you will first need to take note of your Consul agent address. This is the address that you use to access Consul, either via the UI or the CLI. To fetch it, run the following command: +To configure an Auth0 application for Consul, you need your Consul agent address. This is the address that you use to access Consul, either in your web browser with the Consul UI or with your terminal through the CLI. To fetch the address, run the following command: ```shell-session $ echo $CONSUL_HTTP_ADDR @@ -59,7 +59,7 @@ The `http://localhost:8500/ui/oidc/callback` is for logins with the Consul UI. ## Create Auth0 users and metadata -In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on _Create User_. +In the Auth0 dashboard for your app, on the sidebar, select **Users & Roles > Users** and click on **Create User**. ![Auth0 UI create user form](/img/sso/auth0-create-user.png) @@ -100,7 +100,9 @@ This example uses `http://consul.internal` to namespace the claims that are not ## Enable the OIDC auth method for Consul -In order to enable the OIDC auth method for Consul, you need to create a new auth method configuration that points to your Auth0 application. The contents of this configuration file depend on which way you supply it to Consul. You can either use the Consul CLI or the HTTP API. +In order to enable the OIDC auth method for Consul, you need to create a new auth method configuration that points to your Auth0 application. The contents of this configuration file depend on which way you supply it to Consul. + +You can either use the Consul CLI or the HTTP API. Note that the configuration file contents differ slightly depending on whether you use the CLI or the HTTP API. @@ -170,7 +172,7 @@ The configuration file above contains variables that you need to replace with th - `` - `` -After you create the configuration file, apply it to Consul for the new auth method to take effect. Note that the configuration file contents differ slightly depending on whether you use the CLI or the HTTP API. +After you create the configuration file, apply it to Consul for the new auth method to take effect. @@ -197,7 +199,7 @@ $ curl -sL --header "x-consul-token: $CONSUL_HTTP_TOKEN" \ -After you configure the auth method, you can automate permissions grants to users. That way, Consul can bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. You can configure this behavior with Consul binding rules. +After you configure the auth method, you can automate permissions grants to users. That way, Consul can bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. You can configure this behavior with Consul binding rules. ### Grant role permissions with app metadata