diff --git a/website/content/docs/concepts/acl.mdx b/website/content/docs/concepts/acl.mdx new file mode 100644 index 000000000..10f313729 --- /dev/null +++ b/website/content/docs/concepts/acl.mdx @@ -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/ diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 049561e3d..24959a882 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -81,6 +81,10 @@ "title": "Overview", "path": "concepts" }, + { + "title": "ACL", + "path": "concepts/acl" + }, { "title": "Architecture", "path": "concepts/architecture"