Authenticate users with single sign-on (SSO) and Auth0

Nomad 1.5.0 introduces the ability to configure single sign-on (SSO) and to authenticate with Nomad using OIDC.

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 can be initiated from either the Nomad UI or a command line interface.

In this tutorial you will configure Auth0 as an identity provider. Your configuration will use the user metadata in Auth0 to automatically grant permissions in Nomad ACL.

This is a multi-step process that includes:

• configuring an application in Auth0 for Nomad integration;
• setting up Nomad ACL policies and roles to provide permissions to users
• configuring 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.

Prerequisites

In order to complete this tutorial, you will need:

• A Nomad local dev agent or cluster with ACLs enabled and bootstrapped and the management token saved in an environment variable named NOMAD_TOKEN. For instructions on creating a cluster, check the getting started tutorial for a local development cluster or the cluster setup tutorials for a cluster on one of the major cloud providers.

• A valid Auth0 account.

Configure Auth0 application

In the Auth0 dashboard, select Applications and click + Create Application using the type Native. Once complete, click on the Settings tab of the new page.

In the Application configuration, set the callback URLs that the user will be redirected to after the authentication process is completed. The first address will be used by the CLI when you login via the nomad login -type=oidc command and the second one by the Nomad UI when you login with an OIDC auth method.

In this example with a local development cluster, enter the following In the Allowed Callback URLs field.

http://localhost:4649/oidc/callback,
http://localhost:4646/ui/settings/tokens

For non-local clusters, replace localhost with your Nomad cluster's address.

Create Auth0 users and metadata

In the Auth0 dashboard for your app, on the sidebar, select Users & Roles > Users and click on Create User.

Create a user with username/password authentication, edit the user's record, and add the following to the app_metadata section.

{
  "roles": ["engineering"]
}

Configure claims in the ID tokens using Auth0 Actions

In the Auth0 dashboard for your application, on the sidebar, select Actions > Library.

Create a new action with the following content.

exports.onExecutePostLogin = async (event, api) => {
    const namespace = "http://nomad.internal/roles"
    api.idToken.setCustomClaim(
        `${namespace}`, event.user.app_metadata.roles
    );         
    api.accessToken.setCustomClaim(
        `${namespace}`, event.user.app_metadata.roles
    );
    return;
};

Now that action library configuration is complete, you can create a flow.

In the Auth0 dashboard for your application, click on Actions and then Flows from the sidebar.

Click on the Login section and choose the custom build library for your flow.

Create Nomad ACL 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 Nomad use binding rules to control that.

Binding rules allow for privilege to be assigned to a new token via ACL policies and/or ACL roles.

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.

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.

$ 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

Enable the OIDC auth method for Nomad

In the Auth0 dashboard, select Applications, the application you created earlier, and open the Settings tab. Note the Domain, Client ID, and Client Secret values. You will use these to create a configuration file for the OIDC auth method config for Nomad.

Create a configuration file named auth-method-config.json for the new auth method, add the following contents to it, replace AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET with the values for Domain, Client ID, and Client Secret from the Auth0 dashboard, and save the file.

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

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

$ curl -sL --header 'x-nomad-token: <ROOT_TOKEN>' --request PUT \
    http://localhost:4646/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, Nomad 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 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 will automatically associate every user with engineering in their app_metadata to the Nomad engineering-read ACL Role associated with an ACL policy.

Login with OIDC

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

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

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

Once login is successful, you can browse the Nomad UI.

Next steps

In this tutorial you learned how to enable SSO for Nomad, 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.