From be8f04e89fea1257a88091a30517fdf69fedcbda Mon Sep 17 00:00:00 2001
From: Piotr Kazmierczak <470696+pkazmierczak@users.noreply.github.com>
Date: Fri, 9 Jun 2023 16:50:22 +0200
Subject: [PATCH] docs: corrections and additional information for OIDC-related
 concepts (#17470)

---
 .../content/api-docs/acl/binding-rules.mdx    |  4 +++
 .../docs/commands/acl/binding-rule/create.mdx | 26 +++++++++++++++++++
 website/content/docs/concepts/acl.mdx         | 11 ++++----
 3 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/website/content/api-docs/acl/binding-rules.mdx b/website/content/api-docs/acl/binding-rules.mdx
index 1d4653ed1..93451a870 100644
--- a/website/content/api-docs/acl/binding-rules.mdx
+++ b/website/content/api-docs/acl/binding-rules.mdx
@@ -132,6 +132,10 @@ The table below shows this endpoint's support for
   require it to be encased in quotes and escaped such as
   `"\"project-developer\" in list.roles"`.
 
+  ~> **Caveat:** Selectors that operate on `ClaimMappings` (as opposed to
+  `ListClaimMappings`), the key that we match against has to be prefixed with
+  `value.` (e.g. `value.owner == username` for a claim mapping that has `owner`
+  as its key).
 
 - `BindType` `(string: <required>)` - Adjusts how this binding rule is applied
   at login time. Valid values are `role`, `policy`, and `management`.
diff --git a/website/content/docs/commands/acl/binding-rule/create.mdx b/website/content/docs/commands/acl/binding-rule/create.mdx
index 65ebd989d..e15d87075 100644
--- a/website/content/docs/commands/acl/binding-rule/create.mdx
+++ b/website/content/docs/commands/acl/binding-rule/create.mdx
@@ -32,6 +32,10 @@ via flags detailed below.
 - `-selector`: Selector is an expression that matches against verified identity
   attributes returned from the auth method during login.
 
+  ~> **Caveat:** Selectors that operate on `ClaimMappings` (as opposed to
+  `ListClaimMappings`), the key that we match against has to be prefixed with
+  `value.`
+
 - `-bind-type`: Specifies adjusts how this binding rule is applied at login time
   to internal Nomad objects. Valid options are `role`, `policy`, and `management`.
 
@@ -109,3 +113,25 @@ Modify Time  = 2022-12-20 11:15:22.582568 +0000 UTC
 Create Index = 14
 Modify Index = 14
 ```
+
+Create a new ACL Binding Rule where the selector uses a mathing against a
+single `ClaimMapping` which uses `owner` as its value:
+
+```shell-session
+$ nomad acl binding-rule create \
+    -description "example binding rule" \
+    -auth-method "github" \
+    -bind-type "role" \
+    -bind-name "eng-ro" \
+    -selector="value.owner == user"
+ID           = 698fdad6-dcb3-79dd-dc72-b43374057dea
+Description  = example binding rule
+Auth Method  = github
+Selector     = "value.owner == user"
+Bind Type    = role
+Bind Name    = eng-ro
+Create Time  = 2022-12-20 11:15:22.582568 +0000 UTC
+Modify Time  = 2022-12-20 11:15:22.582568 +0000 UTC
+Create Index = 14
+Modify Index = 14
+```
diff --git a/website/content/docs/concepts/acl.mdx b/website/content/docs/concepts/acl.mdx
index 10f313729..aee744db8 100644
--- a/website/content/docs/concepts/acl.mdx
+++ b/website/content/docs/concepts/acl.mdx
@@ -52,16 +52,17 @@ 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
+[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 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].
+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].
 
 ### Binding Rule
 
@@ -88,7 +89,7 @@ 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
+[jwt]: https://datatracker.ietf.org/doc/html/rfc7519
 [workload identity]: /nomad/docs/concepts/workload-identity
 [oidc]: https://openid.net/connect/
 [auth0]: https://auth0.com/