mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 18:35:44 +03:00
123 lines
5.5 KiB
Plaintext
123 lines
5.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Access Control List (ACL)
|
|
description: Learn how Nomad's Access Control List (ACL) security system uses tokens, policies, roles, and capabilities to control access to data and resources.
|
|
---
|
|
|
|
# Access Control List (ACL)
|
|
|
|
This page provides conceptual information about Nomad's Access Control List
|
|
(ACL) security system. At the highest level, Nomad's ACL system has tokens,
|
|
policies, roles, and capabilities. Additionally, Nomad's Single Sign-On (SSO)
|
|
ACL capabilities use auth methods and binding rules to restrict access.
|
|
|
|
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)][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 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], and
|
|
non-interactive login via externally-issued [JSON Web Tokens (JWT)][jwt].
|
|
|
|
Since both the `oidc` and `jwt` auth methods ultimately operate on JWTs as
|
|
bearer tokens, use the following to determine which method fits your use case:
|
|
|
|
- **JWT**
|
|
|
|
- Ideal for machine-oriented, headless login where an operator may have already
|
|
arranged for a valid JWT to be dropped on a VM or provided to a container.
|
|
- User or application performing the Nomad login must have a valid JWT
|
|
to begin login.
|
|
- Does not require browser interaction.
|
|
|
|
- **OIDC**
|
|
|
|
- Ideal for human-oriented, interactive login where an operator or administrator
|
|
may have deployed SSO widely and doesn't want to distribute Nomad ACL tokens
|
|
to every authorized user.
|
|
- User performing the Nomad login does not need a JWT.
|
|
- Requires browser interaction.
|
|
|
|
## 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.
|
|
|
|
<Note>
|
|
Binding rules are evaluated in no specific order, and should there be an
|
|
overlap in their selectors or scope, a "sum" of all the binding rules will be
|
|
applied, thus the least granular binding rules will always override the more
|
|
granular ones, as long as they apply to the same auth method and identity.
|
|
</Note>
|
|
|
|
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
|
|
[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/
|