Configure SSO with Auth0

OIDC authentication is useful when you want to deploy SSO widely in your organization and do not want to manage access solely with Nomad access control list (ACL) tokens.

Once implemented, SSO enables an interactive login procedure that users may initiate from either the Nomad UI or CLI.

In this guide, you configure Auth0 as an identity provider. Your configuration uses the user metadata in Auth0 to automatically grant permissions in Nomad ACL.

This is a multi-step process that includes the following:

Configuring an application in Auth0 for Nomad integration
Creating a role and user in Auth0
Setting up Nomad ACL policies and roles to provide permissions to users
Using Nomad binding rules to automatically assign permissions to users based on their metadata values

You should be familiar with Auth0 and the following Auth0 documentation:

Prerequisites

In order to complete this guide, you need:

A Nomad cluster with ACLs enabled and bootstrapped. Refer to Bootstrap the ACL system for instructions.
The Nomad ACL management token for your cluster. Assign the value to an environment variable named NOMAD_TOKEN in your local terminal session.
A valid Auth0 account.

Refer to the Nomad Quick Start tutorial if you need to set up a cluster.

Set up Auth0

Create a native application. Refer to the Auth0 Create Applications guide for instructions.
- Note the Domain, Client ID, and Client Secret values. You use these to configure an auth method in Nomad.
- Set the callback URLs that Auth0 uses to redirect the user after the authentication process is complete. In the Allowed Callback URLs field, enter the following:
  - <NOMAD_ADDRESS>/ui/settings/tokens: This is the callback address when you perform OIDC login with the Nomad web UI. If you are running Nomad with a modified HTTP port, ensure that the UI address uses this value.
  - http://localhost:4649/oidc/callback: This is the callback address that the Nomad CLI uses when you perform OIDC login using the CLI.
  In this example, the Nomad address is http://3.145.29.13:4646.
```
http://3.145.29.13:4646/ui/settings/tokens,
http://localhost:4649/oidc/callback
```
Create a role called engineering. Refer to the the Auth0 Create Roles guide for instructions.
Create a user with a connection type of Username-Password-Authentication. Assign the engineering role to that user. Refer to these Auth0 guides for instructions:
- Create Users
- Assign Roles to Users
Create a login trigger that adds user roles to the token that Auth0 sends back to Nomad.
1. Create a custom action to add custom claims to the token. Refer to the Auth0 Create an Action section for instructions.
  Give your action these values:
  - Name: Nomad OIDC
  - Trigger: Login/Post Login
  After you create the action, replace the exports.onExecutePostLogin method with the method that sets a custom claim to add user roles to the tokens.
```
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'http://nomad.internal';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}
```
  You use the http://nomad.internal namespace to separate the claims that are not part of the JWT RFC. The namespace is arbitrary but must be unique. Auth0 enforces the presence of a unique namespace by discarding claims that are not namespaced and not in the RFC.
  Click Deploy to deploy your Nomad OIDC action.
2. Create a post-login trigger.
  1. From the Auth0 dashboard for your Nomad application, click on Actions and then Triggers.
  2. Select post-login.
  3. In the Add Action pane's Custom tab, select Nomad OIDC and drag it to the Post Login canvas so that the flow is Start -> Nomad OIDC -> Complete.
  4. Apply your changes.

Create Nomad ACL policies and roles

After the login procedure confirms the user's identity, it has to then give that user privileges when creating their ACL token. Auth methods in Nomad use binding rules, which enable Nomad's ACL system to assign privilege to a new token through ACL policies and roles.

In order to assign a privilege to a token with an auth method, 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.

Define policy for Auth0 users

Create a policy named engineering-read to allow read-only access to the “default” namespace and node objects.

Create a policy file named default-read.hcl, add the following configuration to it, and save the file.

// Grants read access to the namespace “default”.
namespace "default" {
  policy = "read"
}

// Grants read access to Nomad nodes.
node {
  policy = "read"
}

Submit the policy to Nomad.

Note: Ensure that the NOMAD_TOKEN environment variable is set to your Nomad management token.

$ nomad acl policy apply engineering-read default-read.hcl
Successfully wrote "engineering-read" ACL policy!

Assign the policy to a role

Next, create a role named engineering-read and link it to the policy.

$ nomad acl role create -name=engineering-read -policy=engineering-read
ID           = fc6d21c9-31cf-fd12-fe9a-7636c07f2d97
Name         = engineering-read
Description  = <none>
Policies     = engineering-read
Create Index = 18
Modify Index = 18

Create the OIDC auth method for Nomad

Create a configuration file named auth-method-config.json for the new auth method and add the following contents to it.

{
  "OIDCDiscoveryURL": "https://<AUTH0_DOMAIN>/",
  "OIDCClientID": "<AUTH0_CLIENT_ID>",
  "OIDCClientSecret": "<AUTH0_CLIENT_SECRET>",
  "BoundAudiences": ["<AUTH0_CLIENT_ID>"],
  "AllowedRedirectURIs": [
     "<NOMAD_ADDRESS>/ui/settings/tokens",
     "http://localhost:4649/oidc/callback",
  ],
  "ListClaimMappings": {
    "http://nomad.internal/roles": "roles"
  }
}

Replace AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET with the values for Domain, Client ID, and Client Secret that you noted in the Set up your Auth0 application, role, and user section.

Make sure the AllowedRedirectURIs entries match the callback URLs you configured in Auth0.

Create the auth method with the Nomad CLI or API.

Use the nomad acl auth-method create command to create the auth method. Note that the token time-to-live is set to five minutes. Refer to the nomad acl auth-method create command reference for a complete explanation of the options.

$ nomad acl auth-method create -type=OIDC \
    -name=auth0 \
    -default=true \
    -max-token-ttl=5m \
    -token-locality=global \
    -config=@auth-method-config.json

Use the ACL auth methods API to create the auth method. The payload is the auth-method-config.json file.

$ curl -sL --header 'x-nomad-token: <MANAGEMENT_TOKEN>' --request POST \
    <NOMAD_ADDRESS>/v1/acl/auth-method \
    --data @auth-method-config.json

Replace the following placeholders:

<MANAGEMENT_TOKEN> with the value of your Nomad management token
<NOMAD_ADDRESS> with the address of your Nomad cluster, such as http://3.145.29.13:4646

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, you can configure Nomad to bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. Configure this with Nomad binding rules.

Grant ACL role permissions with Auth0 app metadata

Grant users in the engineering Auth0 role the Nomad ACL role named engineering-read.

$ nomad acl binding-rule create \
    -auth-method=auth0 \
    -bind-type=role \
    -bind-name=engineering-read \
    -selector='engineering in list.roles'

ID           = afb29209-9a87-e042-1983-d4d0f70bf271
Description  = <none>
Auth Method  = auth0
Selector     = "engineering in list.roles"
Bind Type    = role
Bind Name    = engineering-read
Create Time  = 2023-01-17 11:34:50.588734 +0000 UTC
Modify Time  = 2023-01-17 11:34:50.588734 +0000 UTC
Create Index = 22
Modify Index = 22

This automatically associates every user with an engineering role in their Auth0 tokens to the Nomad engineering-read ACL Role associated with an ACL policy.

Log in with OIDC

Now that the configuration is complete, log in to Nomad using Auth0.

Use the nomad login -method=auth0 CLI command to log into Nomad. The -oidc-callback-addr parameter is optional and defaults to locahost:4649.

$ nomad login -method=auth0 -oidc-callback-addr=localhost:4649

The command redirects you to a browser page. When prompted, accept and authorize the Nomad access to your Auth0 App. Then log into Auth0 with the username and password that you created in the Set up Auth0 section.

Nomad UI post login page showing Signed in via OIDC

The CLI writes your ACL token to the console.

Successfully logged in via OIDC and auth0

Accessor ID  = f2e78673-cbe5-8a69-1ad1-d16c2b63e9bf
Secret ID    = e3d937a3-fe2b-f144-8384-e4fcbe7e9a65
Name         = OIDC-auth0
Type         = client
Global       = true
Create Time  = 2023-01-17 11:40:36.48495 +0000 UTC
Expiry Time  = 2023-01-17 11:50:36.48495 +0000 UTC
Create Index = 17
Modify Index = 17
Policies     = []

Roles
ID                                    Name
db1b4129-3b7b-f2f5-5118-b885a1ff226e  engineering-read