From 605597ffd09435a0f19678316b43183e2147678b Mon Sep 17 00:00:00 2001 From: Piotr Kazmierczak <470696+pkazmierczak@users.noreply.github.com> Date: Fri, 9 Dec 2022 09:47:31 +0100 Subject: [PATCH] acl: SSO auth methods API documentation (#15475) This PR provides documentation for the ACL Auth Methods API endpoints. Co-authored-by: James Rasell --- website/content/api-docs/acl/auth-methods.mdx | 447 ++++++++++++++++++ website/content/api-docs/acl/index.mdx | 8 +- website/data/api-docs-nav-data.json | 4 + 3 files changed, 455 insertions(+), 4 deletions(-) create mode 100644 website/content/api-docs/acl/auth-methods.mdx diff --git a/website/content/api-docs/acl/auth-methods.mdx b/website/content/api-docs/acl/auth-methods.mdx new file mode 100644 index 000000000..e462d9218 --- /dev/null +++ b/website/content/api-docs/acl/auth-methods.mdx @@ -0,0 +1,447 @@ +--- +layout: api +page_title: ACL Auth Methods - HTTP API +description: The /acl/auth-methods endpoints are used to configure and manage ACL auth methods. +--- + +# ACL Auth Methods HTTP API + +The `/acl/auth-methods` and `/acl/auth-method` endpoints are used to manage ACL Auth Methods. + +## Create Auth Method + +This endpoint creates an ACL Auth Method. The request is always forwarded to the +authoritative region. + +| Method | Path | Produces | +| ------ | ------------------ | ------------------ | +| `POST` | `/acl/auth-method` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `management` | + +### Parameters + +- `Name` `(string: )` - Names is the identifier of the ACL Auth + Method. The name can contain alphanumeric characters, dashes, and underscores. + This name must be unique and must not exceed 128 characters. + +- `Type` `(string: )` - ACL Auth Role SSO identifier. Currently, the + only supported Type is "OIDC." + +- `TokenLocality` `(string: )` - Defines whether the ACL Auth Method + creates a local or global token when performing SSO login. This field must be + set to either "local" or "global" + +- `MaxTokenTTL` `(duration: )` - Defines the maximum life of a token created + by this method. When set, it will initialize the `ExpirationTime` field on all + tokens to a value of `Token.CreateTime + AuthMethod.MaxTokenTTL`. This field is + not persisted beyond its initial use. Can be specified in the form of `"60s"` or + `"5m"` (i.e., 60 seconds or 5 minutes, respectively). + +- `Default` `(bool: false)` - Defines whether this ACL Auth Method is to be + set as default when running `nomad login` command. + +- `Config` `(ACLAuthMethodConfig: )` - The raw configuration to use for + the auth method. This parameter is part of the auth method configuration, not + specific to Nomad. + + - `OIDCDiscoveryURL` `(string: )` - The OIDC Discovery URL, without + any .well-known component (base path). + + - `OIDCClientID` `(string: )` - The OAuth Client ID configured with + your OIDC provider. + + - `OIDCClientSecret` `(string: )` - The OAuth Client Secret + configured with your OIDC provider. + + - `BoundAudiences` `(array)` - List of aud claims that are valid for + login; any match is sufficient. + + - `AllowedRedirectURIs` `(array)` - A list of allowed values for + redirect_uri. Must be non-empty. + + - `DiscoveryCaPem` `(array)` - PEM encoded CA certs for use by the TLS + client used to talk with the OIDC Discovery URL. If not set, system + certificates are used. + + - `SigningAlgs` `(array)` - A list of supported signing algorithms. + Defaults to `RS256`. + + - `ClaimMappings` `(map[string]string)` - Mappings of claims (key) that will + be copied to a metadata field (value). Use this if the claim you are capturing + is singular (such as an attribute). + + When mapped, the values in each list can be any of a number, string, or + boolean and will all be stringified when returned. + + - `ListClaimMappings` `(map[string]string)` - Mappings of claims (key) will be + copied to a metadata field (value). Use this if the claim you are capturing is + list-like (such as groups). + +### Sample Payload + +```json +{ + "Name": "example-acl-auth-method", + "Type": "OIDC", + "TokenLocality": "local", + "MaxTokenTTL": "1h0m0s", + "Default": false, + "Config": { + "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" + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --request POST \ + --header "X-Nomad-Token: " \ + --data @payload.json \ + https://localhost:4646/v1/acl/auth-method +``` + +### Sample Response + +```json +{ + "MaxTokenTTL": "1h0m0s", + "Name": "example-acl-auth-method", + "Type": "OIDC", + "TokenLocality": "local", + "Default": false, + "Config": { + "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/", + "OIDCClientID": "v1rpi2myptmv1rpi2myptmv1rpi2mypt", + "OIDCClientSecret": "example-client-secret", + "BoundAudiences": [ + "v1rpi2myptmv1rpi2myptmv1rpi2mypt" + ], + "AllowedRedirectURIs": [ + "http://localhost:4646/oidc/callback" + ], + "DiscoveryCaPem": null, + "SigningAlgs": null, + "ClaimMappings": { + "http://example.com/first_name": "first_name", + "http://example.com/last_name": "last_name" + }, + "ListClaimMappings": { + "http://nomad.com/groups": "groups" + } + }, + "CreateTime": "2022-12-08T11:04:43.46206Z", + "ModifyTime": "2022-12-08T11:04:43.46206Z", + "CreateIndex": 12, + "ModifyIndex": 12 +} +``` + +## Update Auth Method + +This endpoint updates an existing ACL Auth Method. The request is always +forwarded to the authoritative region. + +| Method | Path | Produces | +| ------ | ------------------------------- | ------------------ | +| `POST` | `/acl/auth-method/:method_name` | `application/json` | + +The table below shows this endpoint's support for [blocking +queries](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `management` | + +### Parameters + +- `Name` `(string: )` - Names is the identifier of the ACL Auth + Method. The name can contain alphanumeric characters, dashes, and underscores. + This name must be unique and must not exceed 128 characters. + +- `Type` `(string: )` - ACL Auth Role SSO identifier. Currently, the + only supported Type is "OIDC." + +- `TokenLocality` `(string: "")` - Defines whether the ACL Auth Method + creates a local or global token when performing SSO login. This field must be + set to either "local" or "global" + +- `MaxTokenTTL` `(duration: )` - Defines the maximum life of a token created + by this method. When set it will initialize the `ExpirationTime` field on all + tokens to a value of `Token.CreateTime + AuthMethod.MaxTokenTTL`. This field is + not persisted beyond its initial use. Can be specified in the form of `"60s"` or + `"5m"` (i.e., 60 seconds or 5 minutes, respectively). + +- `Default` `(bool: false)` - Defines whether this ACL Auth Method is to be + set as default when running `nomad login` command. + +- `Config` `(ACLAuthMethodConfig: nil)` - The raw configuration to use for + the auth method. This parameter is part of the auth method configuration, not + specific to Nomad. + + - `OIDCDiscoveryURL` `(string: "")` - The OIDC Discovery URL, without + any .well-known component (base path). + + - `OIDCClientID` `(string: "")` - The OAuth Client ID configured with + your OIDC provider. + + - `OIDCClientSecret` `(string: "")` - The OAuth Client Secret + configured with your OIDC provider. + + - `BoundAudiences` `(array)` - List of aud claims that are valid for + login; any match is sufficient. + + - `AllowedRedirectURIs` `(array)` - A list of allowed values for + redirect_uri. Must be non-empty. + + - `DiscoveryCaPem` `(array)` - PEM encoded CA certs for use by the TLS + client used to talk with the OIDC Discovery URL. If not set, system + certificates are used. + + - `SigningAlgs` `(array)` - A list of supported signing algorithms. + Defaults to `RS256`. + + - `ClaimMappings` `(map[string]string)` - Mappings of claims (key) that will + be copied to a metadata field (value). Use this if the claim you are capturing + is singular (such as an attribute). + + When mapped, the values in each list can be any of a number, string, or + boolean and will all be stringified when returned. + + - `ListClaimMappings` `(map[string]string)` - Mappings of claims (key) will be + copied to a metadata field (value). Use this if the claim you are capturing is + list-like (such as groups). + +### Sample Payload + +```json +{ + "Name": "example-acl-auth-method", + "Type": "OIDC", + "Tokenlocality": "global", + "Maxtokenttl": "1h0m0s", + "Default": true, + "Config": { + "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" + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --request POST \ + --header "X-Nomad-Token: " \ + --data @payload.json \ + https://localhost:4646/v1/acl/auth-method/example-acl-auth-method +``` + +### Sample Response + +```json +{ + "MaxTokenTTL": "1h0m0s", + "Name": "example-acl-auth-method", + "Type": "OIDC", + "TokenLocality": "global", + "Default": true, + "Config": { + "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" + } + } + "CreateTime": "2022-12-08T11:04:43.46206Z", + "ModifyTime": "2022-12-08T11:04:43.46206Z", + "CreateIndex": 12, + "ModifyIndex": 32 +} +``` + +## List Auth Methods + +This endpoint lists all ACL Auth Methods. This lists the auth methods that have +been replicated to the region, and may lag behind the authoritative region. + +| Method | Path | Produces | +| ------ | ------------------- | ------------------ | +| `GET` | `/acl/auth-methods` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries), +[consistency modes](/api-docs#consistency-modes) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ---- | +| `YES` | `all` | None | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Nomad-Token: " \ + https://localhost:4646/v1/acl/auth-methods +``` + +### Sample Response + +```json +[ + { + "CreateIndex": 12, + "Default": true, + "ModifyIndex": 32, + "Name": "example-acl-auth-method", + "Type": "OIDC" + } +] +``` + +## Read Auth Method by Name + +This endpoint reads an ACL Auth Method with the given name. This queries the +auth method that has been replicated to the region, and may lag behind the +authoritative region. + +| Method | Path | Produces | +| ------ | ------------------------------- | ------------------ | +| `GET` | `/acl/auth-method/:method_name` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries), +[consistency modes](/api-docs#consistency-modes) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------------ | +| `YES` | `all` | `management` token | + +### Parameters + +- `:method_name` `(string: )` - Specifies the name of the ACL Auth + Method. This is specified as part of the path. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Nomad-Token: " \ + https://localhost:4646/v1/acl/auth-method/example-acl-auth-method +``` + +### Sample Response + +```json +{ + "MaxTokenTTL": "1h0m0s", + "Name": "example-acl-auth-method", + "Type": "OIDC", + "TokenLocality": "global", + "Default": true, + "Config": { + "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" + } + }, + "CreateTime": "2022-12-08T11:04:43.46206Z", + "ModifyTime": "2022-12-08T11:04:43.46206Z", + "CreateIndex": 12, + "ModifyIndex": 32 +} +``` + +## Delete Auth Method + +This endpoint deletes the ACL Auth Method as identified by its name. This +request is always forwarded to the authoritative region. + +| Method | Path | Produces | +| -------- | ------------------------------- | -------------- | +| `DELETE` | `/acl/auth-method/:method_name` | `(empty body)` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `management` | + +### Parameters + +- `method_name` `(string: )` - Specifies the name of auth method to + delete and is specified as part of the path. + +### Sample Request + +```shell-session +$ curl \ + --request DELETE \ + --header "X-Nomad-Token: " \ + https://localhost:4646/v1/acl/auth-method/example-acl-auth-method +``` diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx index b9b8af4b6..823782867 100644 --- a/website/content/api-docs/acl/index.mdx +++ b/website/content/api-docs/acl/index.mdx @@ -7,9 +7,9 @@ description: |- # ACL HTTP API -The `/acl` endpoints provide access to the ACL subsystem which includes -ACL bootstrapping, ACL Policies, ACL Roles, and ACL Tokens. For more details -about ACLs, please see the -[ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control). +The `/acl` endpoints provide access to the ACL subsystem which includes ACL +bootstrapping, ACL Policies, ACL Roles, ACL Tokens, and ACL Auth Methods. For +more details about ACLs, please see the [ACL +Guide](https://learn.hashicorp.com/collections/nomad/access-control). Please choose a subsection in the navigation for more information. diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 58e3ca94f..9a81aa5f6 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -24,6 +24,10 @@ "title": "Overview", "path": "acl" }, + { + "title": "Auth Methods", + "path": "acl/auth-methods" + }, { "title": "Policies", "path": "acl/policies"