docs: add auth-methods section in acl concepts #24917
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: JSON Web Token (JWT) Auth Method | ||
| description: >- | ||
| Use the JWT auth method to authenticate to Nomad with a JSON web token and receive an ACL token with privileges based on JWT identity attributes. Learn how to configure the auth method parameters using this reference page and example configuration. | ||
| --- | ||
|
|
||
| # JSON Web Token (JWT) Auth Method | ||
|
|
||
| Use the `jwt` auth method to authenticate with Nomad by providing a | ||
| [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) directly. The JWT is | ||
| cryptographically verified using locally-provided keys, or, if configured, you may use an | ||
| OIDC Discovery service to fetch the appropriate keys. | ||
|
|
||
| Refer to [auth-method create] for the parameters required to create a JWT auth-method with a given verification method. | ||
|
|
||
| ## JWT Verification | ||
|
|
||
| Nomad verifies JWT signatures against public keys from the issuer. This | ||
| process uses one of these methods: | ||
|
|
||
| - **Static Keys** - A set of public keys is stored directly in the | ||
| configuration. | ||
|
|
||
| - **JWKS** - Configure a JSON Web Key Set ([JWKS](https://tools.ietf.org/html/rfc7517)) | ||
| URL and optional certificate chain. Nomad fetches keys from | ||
| this endpoint during authentication. | ||
|
|
||
| - **OIDC Discovery** - Configure an OIDC Discovery URL and optional certificate chain. Nomad fetches keys from this URL during authentication. When you use OIDC Discovery, Nomad applies OIDC validation criteria such as `iss` and `aud`. | ||
|
|
||
| If you need multiple methods, create another auth method of this type | ||
| with a different name. | ||
|
|
||
| @include 'jwt_claim_mapping_details.mdx' | ||
|
|
||
| [auth-method create]: /nomad/docs/commands/acl/auth-method/create |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,135 @@ | ||||||
| --- | ||||||
| layout: docs | ||||||
| page_title: OpenID Connect (OIDC) Auth Method | ||||||
| description: >- | ||||||
| Use the OIDC auth method type to authenticate to Nomad through a web browser with an OpenID Connect provider. Learn how to configure the auth method parameters using this reference page and example configuration. | ||||||
| --- | ||||||
|
|
||||||
| # OpenID Connect (OIDC) Auth Method | ||||||
|
|
||||||
| Use the `oidc` auth method to authenticate to Nomad with | ||||||
| [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). This method allows | ||||||
| authentication via a configured OIDC provider using the user's web browser. | ||||||
| Initiate this method from the Nomad UI or the command line. | ||||||
|
|
||||||
| ## Prerequisites | ||||||
|
|
||||||
| - General knowledge of [OIDC concepts](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1) | ||||||
| - [Nomad Access Control List fundamentals][ACL Overview]. | ||||||
|
|
||||||
| Refer to [auth-method create] for the parameters required to create an OIDC auth-method. | ||||||
|
|
||||||
| ## JWT Verification | ||||||
|
|
||||||
| Nomad uses OIDC discovery to verify JWT signatures against public | ||||||
| keys from the issuer. Nomad first fetches keys from the OIDC | ||||||
| Discovery URL during authentication and then applies OIDC | ||||||
| validation criteria such as `iss` and `aud`. | ||||||
|
|
||||||
| ## OIDC Authentication | ||||||
|
|
||||||
| Nomad includes two built-in OIDC login flows: the Nomad UI, and the CLI using | ||||||
| [`nomad login`](/nomad/docs/commands/login). | ||||||
|
|
||||||
| ### Redirect URIs | ||||||
|
|
||||||
| Properly setting redirect URIs is an important part of OIDC auth method | ||||||
| configuration. You must configure this in both Nomad and the OIDC | ||||||
| provider, and these configurations must align. | ||||||
|
|
||||||
| Specify the redirect URIs for an auth method with the | ||||||
| `AllowedRedirectURIs` parameter. The Nomad UI and CLI use different | ||||||
| redirect URIs, so you need to configure one or both, depending on your | ||||||
| installation. | ||||||
|
|
||||||
| #### Nomad UI | ||||||
|
|
||||||
| Logging in with the Nomad UI requires a redirect URI in one of the following forms: | ||||||
|
|
||||||
| - `http://localhost:4649/ui/oidc/callback` | ||||||
| - `https://{host:port}/ui/oidc/callback` | ||||||
|
|
||||||
| The "host:port" must be correct for the Nomad agent serving the Nomad UI. | ||||||
|
|
||||||
| #### CLI | ||||||
|
|
||||||
| If you plan to support authentication that uses the | ||||||
| `nomad login -method=<name>` command, you must configure a | ||||||
| localhost redirect URI, which is usually | ||||||
| `http://localhost:4649/oidc/callback`. Logins that use the CLI may | ||||||
| specify a different host and listening port if needed. A URI with | ||||||
| this host and port must match one of the configured redirected | ||||||
| URIs. You must add these same "localhost" URIs to the provider | ||||||
| as well. | ||||||
|
|
||||||
| ### OIDC Login | ||||||
|
|
||||||
| #### Nomad UI | ||||||
|
|
||||||
| 1. Select one of the provider links in the Nomad homepage or navigate directly to `/ui/settings/tokens`. | ||||||
| 1. Click one of the buttons for your OIDC auth method of choice. | ||||||
| 1. Complete the authentication with the configured provider. | ||||||
|
|
||||||
| #### CLI | ||||||
|
|
||||||
mismithhisler marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| Execute the `nomad login -method=oidc` command to log in. | ||||||
|
|
||||||
| ```shell-session | ||||||
| $ nomad login -method=oidc | ||||||
|
|
||||||
| Complete the login via your OIDC provider. Launching browser to: | ||||||
|
|
||||||
| https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A4649%2Foidc%2Fcallback&client_id=r3qXc2bix9eF... | ||||||
| ``` | ||||||
|
|
||||||
| Your browser opens to the generated URL to complete the provider's login. | ||||||
| Enter the URL manually if the browser does not automatically open. | ||||||
|
|
||||||
| The callback listener defaults to `localhost:4649`. You may optionally | ||||||
| pass a host and port to the callback listener with the | ||||||
| `-oidc-callback-addr=<host:port>` flag. In this example, you specify custom host and port. | ||||||
|
There was a problem hiding this comment. I think a little more could be done to associate this callback addr to the CLI redirect URL |
||||||
|
|
||||||
| ```shell-session | ||||||
| $ nomad login -method=oidc -oidc-callback-addr=https://custom.host:9080 | ||||||
| ``` | ||||||
|
|
||||||
| ## OIDC Configuration Troubleshooting | ||||||
|
|
||||||
| The amount of configuration required for OIDC is relatively small, but it can | ||||||
| be tricky to debug why things aren't working. The following are tips for setting up OIDC: | ||||||
|
|
||||||
| - Monitor the log output for the Nomad servers for important | ||||||
| information about OIDC validation failures. | ||||||
|
|
||||||
| - Ensure correct redirect URIs in Nmad and on the provider. URIs | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| need to match exactly. Check http/https, 127.0.0.1/localhost, | ||||||
| port numbers, and whether trailing slashes are present. | ||||||
|
|
||||||
| - The `BoundAudiences` option is typically | ||||||
| not required. OIDC providers use the `client_id` as the audience and | ||||||
| OIDC validation expects this. | ||||||
|
|
||||||
| - Check your provider for scopes that are required to receive all of | ||||||
| the information you need. You often need to request the scopes | ||||||
| `profile` and `groups`, which you may set with | ||||||
| `OIDCScopes=["profile", "groups"]` in the auth method configuration. | ||||||
|
|
||||||
| - If you're seeing claim-related errors in logs, review the provider's docs | ||||||
| very carefully to see how they're naming and structuring their claims. | ||||||
| Depending on the provider, you may be able to construct a simple `curl` | ||||||
| [implicit grant](https://developer.okta.com/blog/2018/05/24/what-is-the-oauth2-implicit-grant-type) | ||||||
| request to obtain a JWT that you can inspect. This example decodes the | ||||||
| JWT located in the `access_token` field of a JSON response. | ||||||
|
|
||||||
| jq --raw-output '.access_token / "." | .[1] | @base64d' jwt.json | ||||||
|
|
||||||
| - With debug level logging, use the `VerboseLogging` option to log the | ||||||
| received OIDC token. This can be helpful when debugging provider setup | ||||||
|
There was a problem hiding this comment. this is such a handy feature. for a second I didn't think it was documented anywhere, but it's over in https://nomad-eij8m5abq-hashicorp.vercel.app/nomad/api-docs/acl/auth-methods#verboselogging I think this page should link there too, not only to the I almost want a but also, in the OIDCScopes bullet, you specify that it's in the auth method config, but here it just says "option". maybe it's clear enough, but I was briefly unsure. |
||||||
| and verifying that the received claims are what you expect. Since claims | ||||||
| data is logged verbatim and may contain sensitive information, | ||||||
| do not use this option in production. | ||||||
|
|
||||||
| @include 'jwt_claim_mapping_details.mdx' | ||||||
|
|
||||||
| [ACL Overview]: /nomad/docs/concepts/acl | ||||||
| [auth-method create]: /nomad/docs/commands/acl/auth-method/create | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| ## Trusted Identity Attributes via Claim Mappings | ||
|
|
||
| The authentication step can return data from JWT claims as trusted | ||
| identity attributes for use in binding rule selectors and bind name | ||
| interpolation. | ||
|
|
||
| The `ClaimMappings` and `ListClaimMappings` attributes control how Nomad maps claims | ||
| to identity attributes. Both are maps of items to copy, | ||
| with elements of the form `"<JWT claim>":"<attribute suffix>"`. | ||
|
|
||
| Use `ClaimMappings` to map singular values and `ListClaimMappings` to map lists of values. | ||
|
|
||
| Nomad can interpolate the singular values mapped by `ClaimMappings` in a binding | ||
| rule, but Nomad cannot interpolate the lists of values mapped by `ListClaimMappings`. | ||
|
There was a problem hiding this comment. could include an interpolation in your example -- I don't quite follow where exactly I could put which kind of interpolation, and I don't see anything about this on the maybe add link(s) to |
||
|
|
||
| This examples contains `ClaimMappings` and `ListClaimMappings`. The configuration | ||
| instructs Nomad to copy the values in the JWT claims `"givenName"` and `"surname"` | ||
| to attributes named `"value.first_name"` and `"value.last_name"` respectively. | ||
| Additionally, Nomad should copy the list of values in the JWT | ||
| claim `"groups"` to an attribute named `"list.roles"`. | ||
|
|
||
| ```json | ||
| { | ||
| "Name": "example-auth-method", | ||
| "Type": "<jwt|oidc>", | ||
| "Description": "Example auth method", | ||
| "Config": { | ||
| "ClaimMappings": { | ||
| "givenName": "first_name", | ||
| "surname": "last_name" | ||
| }, | ||
| "ListClaimMappings": { | ||
| "groups": "roles" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The following table shows the resulting attributes and | ||
| the ways they may be used in rule bindings: | ||
|
|
||
| | Attributes | Supported selector operations | Can be interpolated | | ||
| | ------------------ | -------------------------------------------------- | ------------------- | | ||
| | `value.first_name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | | ||
| | `value.last_name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | | ||
| | `list.groups` | In, Not In, Is Empty, Is Not Empty | no | | ||
|
|
||
| ### Claim Specifications and JSON Pointer | ||
|
|
||
| Use the `ClaimMappings` and `ListClaimMappings` fields to point to data | ||
| within the JWT. If the desired key is at the top of level of the JWT, you may | ||
| provide the name directly. If it is nested at a lower level, you may use a JSON | ||
| Pointer. | ||
|
|
||
| This example shows decoded JWT claims. | ||
|
|
||
| ```json | ||
| { | ||
| "division": "North America", | ||
| "groups": { | ||
| "primary": "Engineering", | ||
| "secondary": "Software" | ||
| }, | ||
| "iss": "https://my-corp-app-name.auth0.com/", | ||
| "sub": "auth0|eiw7OWoh5ieSh7ieyahC3ief0uyuraphaengae9d", | ||
| "aud": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt", | ||
| "iat": 1589224148, | ||
| "exp": 1589260148, | ||
| "nonce": "eKiihooH3Fah8Ieshah4leeti6ien3" | ||
| } | ||
| ``` | ||
|
|
||
| Use the following syntax to reference data: | ||
|
|
||
| - Top-level key: Use direct reference. For example, `"division"` refers to `"North America"`. | ||
| - Nested key: Use JSON Pointer syntax. For example, `"/groups/primary"` refers to `"Engineering"`. | ||
|
|
||
| You may use any valid JSON Pointer as a selector. Refer to the [JSON Pointer | ||
| RFC](https://tools.ietf.org/html/rfc6901) for a full description of the syntax. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
oddly, these get link-ified in the preview