mirror of
https://github.com/kemko/nomad.git
synced 2026-01-05 18:05:42 +03:00
9bcfe7bd36
* initial * Update for Auth0 changes. * updated to end * fix URL with double forward slashes
358 lines
12 KiB
Plaintext
358 lines
12 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Configure SSO with Auth0
|
|
description: |-
|
|
Create and configure an Auth0 application for SSO in Nomad, set up Nomad
|
|
ACL policies and roles, and configure binding rules to assign user permissions
|
|
automatically.
|
|
---
|
|
|
|
# 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](https://auth0.com/) 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:
|
|
|
|
- [Understand How Metadata Works in User
|
|
Profiles](https://auth0.com/docs/manage-users/user-accounts/metadata)
|
|
- [Manage User Metadata with the post-login Action
|
|
Trigger](https://auth0.com/docs/manage-users/user-accounts/metadata/manage-user-metadata)
|
|
- [Login Trigger - Add user roles to ID and Access
|
|
tokens](https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#add-user-roles-to-id-and-access-tokens)
|
|
|
|
## Prerequisites
|
|
|
|
In order to complete this guide, you need:
|
|
|
|
- A Nomad cluster with ACLs enabled and bootstrapped. Refer to [Bootstrap the
|
|
ACL system](/nomad/docs/secure/acl/bootstrap) for instructions.
|
|
- The [Nomad ACL management token](/nomad/docs/secure/acl/tokens#token-types)
|
|
for your cluster. Assign the value to an environment variable named
|
|
`NOMAD_TOKEN` in your local terminal session.
|
|
- A valid [Auth0](https://auth0.com/) account.
|
|
|
|
Refer to the [Nomad Quick Start tutorial](/nomad/tutorials/get-started) if you
|
|
need to set up a cluster.
|
|
|
|
## Set up Auth0
|
|
|
|
1. Create a native application. Refer to the Auth0 [Create Applications
|
|
guide](https://auth0.com/docs/get-started/auth0-overview/create-applications)
|
|
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](/nomad/docs/configuration#http-2), 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](https://developer.hashicorp.com/nomad/commands/login#examples).
|
|
|
|
In this example, the Nomad address is `http://3.145.29.13:4646`.
|
|
|
|
```plaintext
|
|
http://3.145.29.13:4646/ui/settings/tokens,
|
|
http://localhost:4649/oidc/callback
|
|
```
|
|
|
|
1. Create a role called `engineering`. Refer to the the Auth0 [Create Roles
|
|
guide](https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/create-roles)
|
|
for instructions.
|
|
1. 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](https://auth0.com/docs/manage-users/user-accounts/create-users)
|
|
- [Assign Roles to Users](https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
|
|
|
|
1. Create a [login
|
|
trigger](https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/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](https://auth0.com/docs/customize/actions/write-your-first-action#create-an-action)
|
|
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](https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#add-user-roles-to-id-and-access-tokens).
|
|
|
|
```javascript
|
|
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](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 not namespaced and not in
|
|
the RFC.
|
|
|
|
Click **Deploy** to deploy your Nomad OIDC action.
|
|
|
|
1. Create a [post-login
|
|
trigger](https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#login-post-login).
|
|
|
|
1. From the Auth0 dashboard for your Nomad application, click on
|
|
**Actions** and then **Triggers**.
|
|
1. Select **post-login**.
|
|
1. 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**.
|
|
1. 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.
|
|
|
|
```hcl
|
|
// 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.
|
|
|
|
```shell-session
|
|
$ 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.
|
|
|
|
```shell-session
|
|
$ 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.
|
|
|
|
<CodeBlockConfig filename="auth-method-config.json">
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
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](#set-up-auth0).
|
|
|
|
Make sure the `AllowedRedirectURIs` entries match the callback URLs you
|
|
configured in Auth0.
|
|
|
|
Create the auth method with the Nomad CLI or API.
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
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](/nomad/commands/acl/auth-method/create)
|
|
for a complete explanation of the options.
|
|
|
|
```shell-session
|
|
$ nomad acl auth-method create -type=OIDC \
|
|
-name=auth0 \
|
|
-default=true \
|
|
-max-token-ttl=5m \
|
|
-token-locality=global \
|
|
-config=@auth-method-config.json
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="API">
|
|
|
|
Use the [ACL auth methods
|
|
API](http://localhost:3000/nomad/api-docs/acl/auth-methods#create-auth-method)
|
|
to create the auth method. The payload is the `auth-method-config.json` file.
|
|
|
|
```shell-session
|
|
$ 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`
|
|
|
|
</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, 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`.
|
|
|
|
```shell-session
|
|
$ nomad acl binding-rule create \
|
|
-auth-method=auth0 \
|
|
-bind-type=role \
|
|
-bind-name=engineering-read \
|
|
-selector='engineering in list.roles'
|
|
```
|
|
|
|
```plaintext hideClipboard
|
|
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.
|
|
|
|
<Tabs>
|
|
<Tab heading="CLI">
|
|
|
|
Use the [`nomad login -method=auth0` CLI command](/nomad/commands/login) to log
|
|
into Nomad. The `-oidc-callback-addr` parameter is optional and defaults to `locahost:4649`.
|
|
|
|
```shell-session
|
|
$ 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](#set-up-auth0).
|
|
|
|
|
|
|
|
The CLI writes your ACL token to the console.
|
|
|
|
```plaintext hideClipboard
|
|
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
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="Nomad UI">
|
|
|
|
Navigate to your Nomad web UI and click on the **Sign In** button. Then click
|
|
the **Sign in with auth0** button to start the flow.
|
|
|
|
|
|
|
|
|
|
|
|
</Tab>
|
|
</Tabs>
|