97 lines
4.3 KiB
Plaintext
97 lines
4.3 KiB
Plaintext
---
|
|
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/
|