docs: add ACL concepts page to introduce objects. (#15895)
This commit is contained in:
James Rasell
GitHub
parent
52a86b9d32
commit
06664baeb1
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
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/
|
||||
|
|
@ -81,6 +81,10 @@
|
|||
"title": "Overview",
|
||||
"path": "concepts"
|
||||
},
|
||||
{
|
||||
"title": "ACL",
|
||||
"path": "concepts/acl"
|
||||
},
|
||||
{
|
||||
"title": "Architecture",
|
||||
"path": "concepts/architecture"
|
||||
|
|
|
|||
Loading…
Reference in New Issue