---
layout: docs
page_title: Access Control List (ACL)
description: Learn about Nomad's ACL subsystem
---

# Access Control List (ACL)

The Nomad ACL system is designed to be intuitive, high-performance, and to
provide administrative insight. At the highest level, there are four major
components to the ACL system: tokens, policies, roles, and capabilities. The
two components named auth methods and binding rules are specific to Nomad's
Single Sign-On (SSO) ACL capabilities.

The Nomad [access control tutorials][] provide detailed information and
guidance on Nomad ACL system.

### Policy

Policies consist of a set of rules defining the capabilities or actions to be
granted. For example, a `readonly` policy might only grant the ability to list
and inspect running jobs, but not to submit new ones. No permissions are
granted by default, making Nomad a default-deny system.

Each policy comprises one or more rules. The rules define the capabilities of a
Nomad ACL token for accessing the objects in a Nomad cluster, objects like
namespaces, node, agent, operator, quota, etc. For more information on writing
policies, see the [ACL policy reference doc][].

### Role

Roles group one or more ACL policies into a container which can then be used to
generate ACL tokens for authorisation. This abstraction allows easier control
and updating of ACL permissions, particularly in larger, more diverse clusters.

### Token

Requests to Nomad are authenticated using a bearer token. Each ACL token has a
public Accessor ID which is used to name a token and a Secret ID which is used
to make requests to Nomad. The Secret ID is provided using a request header
(`X-Nomad-Token`) and is used to authenticate the caller. Tokens are either
management or client types. The `management` tokens are effectively "root" in
the system and can perform any operation. The `client` tokens are associated
with one or more ACL policies or roles which grant specific capabilities.

When ACL tokens are created, they can be optionally marked as `Global`. This
causes them to be created in the authoritative region and replicated to all
other regions. Otherwise, tokens are created locally in the region the request
was made and not replicated. `Local` tokens cannot be used for cross-region
requests since they are not replicated between regions.

### Workload Identity

Nomad allocations can receive workload identities in the form of a
[JSON Web Token (JWT)][]. The
[Workload Identity concept page][workload identity] has more information on
this topic.

### Auth Method

Authentication methods dictate how Nomad should talk to SSO providers when a
user requests to authenticate using one. Currently, Nomad only supports the
[OpenID Connect (OIDC)][oidc] SSO workflow which allows users to log in to Nomad
via applications such as [Auth0][auth0], [Okta][okta], and [Vault][vault].

### Binding Rule

Binding rules provide a mapping between a Nomad user's SSO authorisation claims
and internal Nomad objects such as ACL Roles and ACL Policies. A binding rule
is directly related to a single auth method, and therefore only evaluated by
login attempts using that method. All binding rules mapped to an auth method
are evaluated during each login attempt.

A successful selector match between an SSO provider claim and a binding rule
will result in the generated ACL token having the identified ACL role or policy
assigned to it. If the `BindType` parameter is `management`, the ACL token
generated will be a `management` token, rather than a client token. This
matcher supersedes role or policy assignments, and therefore should be used
with caution.

## Replication

Multi-region federated clusters run replication process to replicate ACL
objects from the [authoritative region][]. The replication processes run on
each federated leader and replicate ACL policies, roles, auth methods, binding
rules, and token marked as `Global`.

[access control tutorials]: /nomad/tutorials/access-control
[ACL policy reference doc]: /nomad/docs/other-specifications/acl-policy
[authoritative region]: /nomad/docs/configuration/server#authoritative_region
[JSON Web Token (JWT)]: https://datatracker.ietf.org/doc/html/rfc7519
[workload identity]: /nomad/docs/concepts/workload-identity
[oidc]: https://openid.net/connect/
[auth0]: https://auth0.com/
[okta]: https://www.okta.com/
[vault]: https://www.vaultproject.io/