Skip to content

CE-919 - Update "Enable Auth0 single sign-on (SSO)" #1421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
krastin merged 13 commits into from
Dec 15, 2025
+120 −402
Merged

CE-919 - Update "Enable Auth0 single sign-on (SSO)" #1421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
9e5ce1f
update auth0 sso for 1.22.x
krastin Dec 2, 2025
cc11496
update auth0 sso for 1.21.x
krastin Dec 2, 2025
0fc9beb
Merge branch 'main' into krastin/ce-919
krastin Dec 2, 2025
3f94002
Apply suggestions from code review
krastin Dec 5, 2025
8d8efaa
fixing codereview points
krastin Dec 5, 2025
999957f
fixing codereview points for v1.22.x
krastin Dec 5, 2025
910bacf
add consul token explanation to curl command
krastin Dec 5, 2025
15a4ec7
Merge branch 'main' into krastin/ce-919
krastin Dec 11, 2025
c1a2965
removing duplicate next-steps section
krastin Dec 11, 2025
bd5c93c
Apply suggestions from code review
krastin Dec 12, 2025
467a1d0
propagate changes from 1.21.x file to 1.22.x
krastin Dec 12, 2025
b8272f7
Merge branch 'main' into krastin/ce-919
krastin Dec 12, 2025
88b5bab
Merge branch 'main' into krastin/ce-919
krastin Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
261 changes: 60 additions & 201 deletions content/consul/v1.21.x/content/docs/secure/sso/auth0.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,124 +7,63 @@ 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 OpenID Connect (OIDC).

<Note title="Enterprise Only">

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

</Note>

## 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:
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.

- 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:
## Introduction

<CodeTabs heading="Consul agent configuration">
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.

```hcl
acl {
enabled = true
default_policy = "deny"
<Note title="Enterprise Only">

tokens {
initial_management = "root"
agent = "root"
}
}
```
The single sign-on (SSO) functionality demonstrated here requires [Consul Enterprise](/consul/docs/enterprise#access-consul-enterprise).

```json
{
"acl": {
"enabled": true,
"default_policy": "deny",
"tokens": {
"initial_management": "root",
"agent": "root"
}
}
}
```

</CodeTabs>
</Note>

## 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 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

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

Select **Default App** and open the **Settings** tab.
```shell-session
$ echo $CONSUL_HTTP_ADDR
http://localhost:8500
```

In the Application configuration, you can set the callback URLs that the user
will be redirected to after the authentication process is completed.
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://<consul_agent_address>:8550/oidc/callback,
http://<consul_agent_address>:8500/ui/oidc/callback
http://localhost:8550/oidc/callback,
http://localhost:8500/ui/oidc/callback
```

The `http://<consul_agent_address>:8550/oidc/callback` address will be used by the
CLI when you login via `consul login -type=oidc -method=oidc` command.

The `http://<consul_agent_address>: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.

<Note>

The callback URLs must be comma-separated.

</Note>

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_
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:
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
{
Expand All @@ -141,13 +80,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:
In Auth0, create a new rule with the following javascript function:

```javascript
function (user, context, callback) {
Expand All @@ -161,79 +94,18 @@ function (user, context, callback) {
}
```

![Auth0 UI configure callback rule](/img/sso/auth0-configure-callback-rule.png)

-> 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.
This functions associates your user and app metadata in Auth0 with Consul's data.

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
```
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**.
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.

Select **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.
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.

<Tabs>
<Tab heading="CLI command">


Create a configuration file named `auth-method-config.json` for the new auth method.
<Tab group="cli" heading="CLI command">

<CodeBlockConfig filename="auth-method-config.json">

Expand All @@ -259,29 +131,8 @@ Create a configuration file named `auth-method-config.json` for the new auth met

</CodeBlockConfig>

You can use the following snippet as an example. Make sure you replace:

- `<AUTH0_DOMAIN>`
- `<AUTH0_CLIENT_ID>`
- `<AUTH0_CLIENT_SECRET>`

with the values you retrieved from the Auth0 dashboard.

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
```

</Tab>
<Tab heading="API call using cURL">


Create a configuration file named`auth-method-config.json` for the new auth method.
<Tab group="api" heading="API call using cURL">

<CodeBlockConfig filename="auth-method-config.json">

Expand Down Expand Up @@ -312,35 +163,50 @@ Create a configuration file named`auth-method-config.json` for the new auth meth

</CodeBlockConfig>

You can use the following snippet as an example. Make sure you replace:
</Tab>
</Tabs>

The configuration file above contains variables that you need to replace with the values from your Auth0 application. Make sure you replace:

- `<AUTH0_DOMAIN>`
- `<AUTH0_CLIENT_ID>`
- `<AUTH0_CLIENT_SECRET>`

with the values you retrieved from the Auth0 dashboard.
After you create the configuration file, apply it to Consul for the new auth method to take effect.

<Tabs>
<Tab group="cli" heading="CLI command">

Apply the configuration using the `acl/auth-method` API endpoint.
Apply the configuration using the `consul acl auth-method` CLI command.

```shell-session
$ curl -sL --header 'x-consul-token: root' --request PUT \
http://localhost:8500/v1/acl/auth-method \
$ consul acl auth-method create -type oidc \
-name auth0 -max-token-ttl=5m \
-config=@auth-method-config.json
```

</Tab>
<Tab group="api" heading="API call using cURL">

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" \
--request PUT http://localhost:8500/v1/acl/auth-method \
--data @auth-method-config.json
```

</Tab>
</Tabs>


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

Grant users in the `engineering` group the role `eng-ro`.
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 \
Expand All @@ -357,15 +223,14 @@ 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.
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. 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, 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}' \
Expand Down Expand Up @@ -396,7 +261,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)

Expand Down Expand Up @@ -445,10 +310,4 @@ 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.

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