kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-02 08:25:43 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
2bfe81772119f431fc75271d20aa7ca4fa3c1921
nomad/website/content/api-docs/acl/auth-methods.mdx

511 lines
17 KiB
Plaintext
Raw Blame History

---
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](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `Name` `(string: <required>)` - Name is the identifier of the ACL auth method.
The name can contain alphanumeric characters and dashes. This name must be
unique and must not exceed 128 characters.
- `Type` `(string: <required>)` - ACL auth method type, supports `OIDC` and `JWT`.
- `TokenLocality` `(string: <required>)` - 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`.
- `TokenNameFormat` `(string <optional>)` - Defines the token name format for the
generated tokens This can be lightly templated using HIL `${foo}` syntax.
Defaults to `${auth_method_type}-${auth_method_name}`.
- `MaxTokenTTL` `(duration: <required>)` - 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: <required>)` - The raw configuration to use for
the auth method. This parameter is part of the auth method configuration, not
specific to Nomad.
- `OIDCDiscoveryURL` `(string: <required>)` - The OIDC discovery URL, without
any `.well-known` component (base path). Required for `OIDC` method type.
Either this, the `JWKSURL` or the `JWTValidationPubKeys` is required for
`JWT` method type.
- `OIDCClientID` `(string: <required>)` - The OAuth client ID configured with
your OIDC provider. Required for `OIDC` method type.
- `OIDCClientSecret` `(string: <required>)` - The OAuth client secret
configured with your OIDC provider. Required for `OIDC` method type.
- `OIDCDisableUserInfo` `(bool: false)` - When set to `true`, Nomad will not make
a request to the identity provider to get OIDC UserInfo. You may wish to set this
if your identity provider doesn't send any additional claims from the UserInfo
endpoint.
- `OIDCScopes` `(array<string>)` - List of OIDC scopes.
- `JWTValidationPubKeys` `(array<string>)` - A list of PEM-encoded public keys
to use to validate JWT signatures locally. Either this, the `JWKSURL` or the
`OIDCDiscoveryURL` is required for `JWT` method type.
- `JWKSURL` `(string)` - JSON Web Key Sets url for authenticating JWT
signatures. Either this, the `JWTValidationPubKeys` or the
`OIDCDiscoverURL` is required for `JWT` method type.
- `BoundAudiences` `(array<string>)` - List of aud claims that are valid for
login; any match is sufficient.
- `AllowedRedirectURIs` `(array<string>)` - A list of allowed values for
redirect_uri. Must be non-empty.
- `DiscoveryCaPem` `(array<string>)` - 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.
- `JWKSCACert` `(string)` - PEM encoded CA cert for use by the TLS client used
to talk with the JWKS server.
- `SigningAlgs` `(array<string>)` - A list of supported signing algorithms.
Defaults to `RS256`.
- `ExpirationLeeway` `(duration)` - Duration in seconds of leeway when
validating expiration of a JWT to account for clock skew.
- `NotBeforeLeeway` `(duration)` - Duration in seconds of leeway when
validating not before values of a JWT to account for clock skew.
- `ClockSkewLeeway` `(duration)` - Duration in seconds of leeway when
validating all JWT claims to account for clock skew.
- `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",
"TokenNameFormat": "${auth_method_type}-${value.user}",
"MaxTokenTTL": "1h0m0s",
"Default": false,
"Config": {
"OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
"OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
"OIDCClientSecret": "example-client-secret",
"OIDCScopes": [
"groups"
],
"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: <NOMAD_TOKEN_SECRET_ID>" \
--data @payload.json \
https://localhost:4646/v1/acl/auth-method
```
### Sample response
```json
{
"MaxTokenTTL": "1h0m0s",
"Name": "example-acl-auth-method",
"Type": "OIDC",
"TokenLocality": "local",
"TokenNameFormat": "${auth_method_type}-${value.user}",
"Default": false,
"Config": {
"OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
"OIDCClientID": "v1rpi2myptmv1rpi2myptmv1rpi2mypt",
"OIDCClientSecret": "example-client-secret",
"OIDCScopes": [
"groups"
],
"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](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `Name` `(string: <required>)` - Names is the identifier of the ACL auth
method. The name can contain alphanumeric characters and dashes.
This name must be unique and must not exceed 128 characters.
- `Type` `(string: <required>)` - 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"
- `TokenNameFormat` `(string <optional>)` - Defines the token name format for the
generated tokens This can be lightly templated using HIL '${foo}' syntax.
Defaults to '${auth_method_type}-${auth_method_name}'
- `MaxTokenTTL` `(duration: <required>)` - 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.
- `OIDCDisableUserInfo` `(bool: false)` - When set to `true`, Nomad will not make
a request to the identity provider to get OIDC UserInfo. You may wish to set this
if your identity provider doesn't send any additional claims from the UserInfo
endpoint.
- `OIDCScopes` `(array<string>)` - List of OIDC scopes.
- `BoundAudiences` `(array<string>)` - List of aud claims that are valid for
login; any match is sufficient.
- `AllowedRedirectURIs` `(array<string>)` - A list of allowed values for
redirect_uri. Must be non-empty.
- `DiscoveryCaPem` `(array<string>)` - 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<string>)` - 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",
"TokenNameFormat": "${auth_method_type}-${value.user}",
"Maxtokenttl": "1h0m0s",
"Default": true,
"Config": {
"OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
"OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
"OIDCClientSecret": "example-client-secret",
"OIDCScopes": [
"groups"
],
"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: <NOMAD_TOKEN_SECRET_ID>" \
--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",
"TokenNameFormat": "${auth_method_type}-${value.user}",
"Default": true,
"Config": {
"OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
"OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
"OIDCClientSecret": "example-client-secret",
"OIDCScopes": [
"groups"
],
"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](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---- |
| `YES` | `all` | None |
### Sample request
```shell-session
$ curl \
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
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](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------ |
| `YES` | `all` | `management` token |
### Parameters
- `:method_name` `(string: <required>)` - 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: <NOMAD_TOKEN_SECRET_ID>" \
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",
"TokenNameFormat": "${auth_method_type}-${value.user}",
"Default": true,
"Config": {
"OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
"OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
"OIDCClientSecret": "example-client-secret",
"OIDCScopes": [
"groups"
],
"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](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `method_name` `(string: <required>)` - 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: <NOMAD_TOKEN_SECRET_ID>" \
https://localhost:4646/v1/acl/auth-method/example-acl-auth-method
```
Reference in New Issue View Git Blame Copy Permalink