acl: SSO auth methods CLI documentation (#15538)

This PR provides documentation for the ACL Auth Methods CLI commands. Co-authored-by: James Rasell <jrasell@users.noreply.github.com>
2026-01-05 01:45:44 +03:00 · 2022-12-14 13:35:26 +01:00
parent 627debc14b
commit 758bc68925
7 changed files with 336 additions and 0 deletions
--- a/website/content/docs/commands/acl/auth-method/create.mdx
+++ b/website/content/docs/commands/acl/auth-method/create.mdx
@@ -0,0 +1,100 @@
+---
+layout: docs
+page_title: 'Commands: acl auth-method create'
+description: The auth-method create command is used to create new ACL Auth Methods.
+---
+
+# Command: acl auth-method create
+
+The `acl auth-method create` command is used to create new ACL Auth Methods.
+
+## Usage
+
+```plaintext
+nomad acl auth-method create [options]
+```
+
+The `acl auth-method create` command requires the correct setting of the create options
+via flags detailed below.
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Create Options
+
+- `-name`: Sets the human readable name for the ACL auth method. The name must
+  be between 1-128 characters and is a required parameter.
+
+- `-description`: A free form text description of the auth-method that must not exceed
+  256 characters.
+
+- `-type`: Sets the type of the auth method. Currently the only supported type
+  is `OIDC`.
+
+- `-max-token-ttl`: Sets the duration of time all tokens created by this auth
+  method should be valid for.
+
+- `-token-locality`: Defines the kind of token that this auth method should
+  produce. This can be either `local` or `global`.
+
+- `-default`: Specifies whether this auth method should be treated as a default
+  one in case no auth method is explicitly specified for a login command.
+
+- `-config`: Auth method [configuration] in JSON format. May be prefixed with '@'
+  to indicate that the value is a file path to load the config from. '-' may also
+  be given to indicate that the config is available on stdin.
+
+- `-json`: Output the ACL auth-method in a JSON format.
+
+- `-t`: Format and display the ACL auth-method using a Go template.
+
+## Examples
+
+Create a new ACL Role:
+
+```shell-session
+$ nomad acl auth-method create -name "example-acl-auth-method" -type "OIDC" -max-token-ttl "1h" -token-locality "local" -config "@config.json"
+Created ACL auth method:
+Name                   = example-acl-auth-method
+Type                   = OIDC
+Locality               = local
+MaxTokenTTL            = 1h0m0s
+Default                = false
+OIDC Discovery URL     = https://my-corp-app-name.auth0.com/
+OIDC Client ID         = V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt
+OIDC Client Secret     = example-client-secret
+Bound audiences        = V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt
+Allowed redirects URIs = http://localhost:4646/oidc/callback
+Discovery CA pem       = <none>
+Signing algorithms     = <none>
+Claim mappings         = {http://example.com/first_name: first_name}; {http://example.com/last_name: last_name}
+List claim mappings    = {http://nomad.com/groups: groups}
+Create Index           = 14
+Modify Index           = 14
+```
+
+Example config file:
+
+```json
+{
+  "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
+  "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
+  "OIDCClientSecret": "example-client-secret",
+  "BoundAudiences": [
+    "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
+  ],
+  "AllowedRedirectURIs": [
+    "http://localhost:4646/oidc/callback"
+  ],
+  "ClaimMappings": {
+    "http://example.com/first_name": "first_name",
+    "http://example.com/last_name": "last_name"
+  },
+  "ListClaimMappings": {
+    "http://nomad.com/groups": "groups"
+  }
+}
+```
+
+[configuration]: /api-docs/acl/auth-methods#config
--- a/website/content/docs/commands/acl/auth-method/delete.mdx
+++ b/website/content/docs/commands/acl/auth-method/delete.mdx
@@ -0,0 +1,30 @@
+---
+layout: docs
+page_title: 'Commands: acl auth-method delete'
+description: The auth-method delete command is used to delete existing ACL Auth Methods.
+---
+
+# Command: acl auth-method delete
+
+The `acl auth-method delete` command is used to delete existing ACL Auth Methods.
+
+## Usage
+
+```plaintext
+nomad acl auth-method delete [options] <auth-method_name>
+```
+
+The `acl auth-method delete` command requires an existing method's name.
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Examples
+
+Delete an existing ACL Auth Method:
+
+```shell-session
+$ nomad acl auth-method delete example-auth-method
+ACL auth method example-auth-method successfully deleted
+```
--- a/website/content/docs/commands/acl/auth-method/info.mdx
+++ b/website/content/docs/commands/acl/auth-method/info.mdx
@@ -0,0 +1,53 @@
+---
+layout: docs
+page_title: 'Commands: acl auth-method info'
+description: |
+  The auth-method info command is used to fetch information about an existing
+  ACL Auth Method.
+---
+
+# Command: acl auth-method info
+
+The `acl auth-method info` command is used to fetch information about an existing ACL Auth Method.
+
+## Usage
+
+```plaintext
+nomad acl auth-method info [options] <auth-method_name>
+```
+
+The `acl auth-method info` command requires an existing method's name.
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Info Options
+
+- `-json`: Output the ACL auth method in a JSON format.
+
+- `-t`: Format and display the ACL auth method using a Go template.
+
+## Examples
+
+Fetch information about an existing ACL Auth Method:
+
+```shell-session
+$ nomad acl auth-method info example-acl-auth-method
+Name                   = example-acl-auth-method
+Type                   = OIDC
+Locality               = local
+MaxTokenTTL            = 1h0m0s
+Default                = false
+OIDC Discovery URL     = https://my-corp-app-name.auth0.com/
+OIDC Client ID         = V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt
+OIDC Client Secret     = example-client-secret
+Bound audiences        = V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt
+Allowed redirects URIs = http://localhost:4646/oidc/callback
+Discovery CA pem       = <none>
+Signing algorithms     = <none>
+Claim mappings         = {http://example.com/first_name: first_name}; {http://example.com/last_name: last_name}
+List claim mappings    = {http://nomad.com/groups: groups}
+Create Index           = 14
+Modify Index           = 33
+```
--- a/website/content/docs/commands/acl/auth-method/list.mdx
+++ b/website/content/docs/commands/acl/auth-method/list.mdx
@@ -0,0 +1,35 @@
+---
+layout: docs
+page_title: 'Commands: acl auth-method list'
+description: The auth-method list command is used to list existing ACL Roles.
+---
+
+# Command: acl auth-method list
+
+The `acl auth-method list` command is used to list existing ACL Auth Methods.
+
+## Usage
+
+```plaintext
+nomad acl auth-method list [options]
+```
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## List Options
+
+- `-json` : Output the ACL auth-methods in a JSON format.
+
+- `-t` : Format and display the ACL auth-methods using a Go template.
+
+## Examples
+
+List all ACL Auth Methods:
+
+```shell-session
+$ nomad acl auth-method list
+Name                     Type  Default
+example-acl-auth-method  OIDC  false
+```
--- a/website/content/docs/commands/acl/auth-method/update.mdx
+++ b/website/content/docs/commands/acl/auth-method/update.mdx
@@ -0,0 +1,83 @@
+---
+layout: docs
+page_title: 'Commands: acl auth-method update'
+description: The auth-method update command is used to update existing ACL Auth Methods.
+---
+
+# Command: acl auth-method update
+
+The `acl auth-method update` command is used to update existing ACL Auth Methods.
+
+## Usage
+
+```plaintext
+nomad acl auth-method update [options] <auth-method_name>
+```
+
+The `acl auth-method update` command requires an existing method's name.
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Update Options
+
+- `-name`: Sets the human-readable name for the ACL Role. It is required and
+  can contain alphanumeric characters, dashes, and underscores. This name must
+  be unique and must not exceed 128 characters.
+
+- `-description`: A free form text description of the role that must not exceed
+  256 characters.
+
+- `-policy`: Specifies a policy to associate with the role identified by their
+  name. This flag can be specified multiple times and must be specified at
+  least once.
+
+- `-no-merge`: Do not merge the current role information with what is provided
+  to the command. Instead, overwrite all fields with the exception of the role
+  ID which is immutable.
+
+- `-type`: Updates the type of the auth method. Currently the only supported
+  type is `OIDC`.
+
+- `-max-token-ttl`: Updates the duration of time all tokens created by this auth
+  method should be valid for.
+
+- `-token-locality`: Updates the kind of token that this auth method should
+  produce. This can be either `local` or `global`.
+
+- `-default`: Specifies whether this auth method should be treated as a default
+  one in case no auth method is explicitly specified for a login command.
+
+- `-config`: Auth method [configuration] in JSON format. May be prefixed with '@'
+  to indicate that the value is a file path to load the config from. '-' may also
+  be given to indicate that the config is available on stdin.
+
+- `-json`: Output the ACL auth method in a JSON format.
+
+- `-t`: Format and display the ACL auth method using a Go template.
+
+## Examples
+
+Update an existing ACL auth method:
+
+```shell-session
+$ nomad acl auth-method update -token-locality "global" -config @config.json example-acl-auth-method
+Updated ACL auth method:
+Name                   = example-acl-auth-method
+Type                   = OIDC
+Locality               = global
+MaxTokenTTL            = 1h0m0s
+Default                = false
+OIDC Discovery URL     = https://my-new-corp-app-name.auth0.com/
+OIDC Client ID         = V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt
+OIDC Client Secret     = example-client-secret
+Bound audiences        = V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt
+Allowed redirects URIs = http://localhost:4646/oidc/callback
+Discovery CA pem       = <none>
+Signing algorithms     = <none>
+Claim mappings         = {http://example.com/first_name: first_name}; {http://example.com/last_name: last_name}
+List claim mappings    = {http://nomad.com/groups: groups}
+Create Index           = 14
+Modify Index           = 33
+```
--- a/website/content/docs/commands/acl/index.mdx
+++ b/website/content/docs/commands/acl/index.mdx
@@ -19,6 +19,11 @@ Run `nomad acl <subcommand> -h` for help on that subcommand. The following
 subcommands are available:

 - [`acl bootstrap`][bootstrap] - Bootstrap the initial ACL token
+- [`acl auth-method create`][authmethodcreate] - Create a new ACL auth method
+- [`acl auth-method delete`][authmethoddelete] - Delete an existing ACL auth method
+- [`acl auth-method info`][authmethodinfo] - Fetch information on an existing ACL auth method
+- [`acl auth-method list`][authmethodlist] - List available ACL auth methods
+- [`acl auth-method update`][authmethodupdate] - Update existing ACL auth method
 - [`acl policy apply`][policyapply] - Create or update ACL policies
 - [`acl policy delete`][policydelete] - Delete an existing ACL policies
 - [`acl policy info`][policyinfo] - Fetch information on an existing ACL policy
@@ -36,6 +41,11 @@ subcommands are available:
 - [`acl token update`][tokenupdate] - Update existing ACL token

 [bootstrap]: /docs/commands/acl/bootstrap
+[authmethodcreate]: /docs/commands/acl/auth-method/create
+[authmethoddelete]: /docs/commands/acl/auth-method/delete
+[authmethodinfo]: /docs/commands/acl/auth-method/info
+[authmethodlist]: /docs/commands/acl/auth-method/list
+[authmethodupdate]: /docs/commands/acl/auth-method/update
 [policyapply]: /docs/commands/acl/policy/apply
 [policydelete]: /docs/commands/acl/policy/delete
 [policyinfo]: /docs/commands/acl/policy/info
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -236,6 +236,31 @@
            "title": "bootstrap",
            "path": "commands/acl/bootstrap"
          },
+          {
+            "title": "auth-method",
+            "routes": [
+              {
+                "title": "create",
+                "path": "commands/acl/auth-method/create"
+              },
+              {
+                "title": "delete",
+                "path": "commands/acl/auth-method/delete"
+              },
+              {
+                "title": "info",
+                "path": "commands/acl/auth-method/info"
+              },
+              {
+                "title": "list",
+                "path": "commands/acl/auth-method/list"
+              },
+              {
+                "title": "update",
+                "path": "commands/acl/auth-method/update"
+              }
+            ]
+          },
          {
            "title": "policy",
            "routes": [