From 49e6680892a820fa7697765d5d15eada58db2462 Mon Sep 17 00:00:00 2001 From: "R.B. Boyer" Date: Wed, 13 May 2020 14:14:03 -0500 Subject: [PATCH] docs: docs for jwt and oidc auth methods (#7847) --- website/data/docs-navigation.js | 2 +- website/pages/api-docs/acl/auth-methods.mdx | 12 +- website/pages/api-docs/acl/index.mdx | 179 ++++++++++++++- website/pages/docs/acl/acl-system.mdx | 2 +- website/pages/docs/acl/auth-methods/index.mdx | 13 +- website/pages/docs/acl/auth-methods/jwt.mdx | 175 ++++++++++++++ .../docs/acl/auth-methods/kubernetes.mdx | 33 +-- website/pages/docs/acl/auth-methods/oidc.mdx | 214 ++++++++++++++++++ website/pages/docs/acl/index.mdx | 2 +- website/pages/docs/agent/options.mdx | 2 +- .../docs/commands/acl/auth-method/create.mdx | 18 ++ .../docs/commands/acl/auth-method/update.mdx | 18 ++ website/pages/docs/commands/login.mdx | 11 + website/pages/docs/enterprise/index.mdx | 1 + .../docs/guides/managing-acl-policies.mdx | 2 +- website/pages/docs/k8s/helm.mdx | 2 +- .../partials/jwt_claim_mapping_details.mdx | 77 +++++++ website/pages/partials/jwt_or_oidc.mdx | 18 ++ 18 files changed, 751 insertions(+), 30 deletions(-) create mode 100644 website/pages/docs/acl/auth-methods/jwt.mdx create mode 100644 website/pages/docs/acl/auth-methods/oidc.mdx create mode 100644 website/pages/partials/jwt_claim_mapping_details.mdx create mode 100644 website/pages/partials/jwt_or_oidc.mdx diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index a94dec0a8..51fe093bc 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -139,7 +139,7 @@ export default [ 'acl-rules', 'acl-legacy', 'acl-migrate-tokens', - { category: 'auth-methods', content: ['kubernetes'] }, + { category: 'auth-methods', content: ['kubernetes', 'jwt', 'oidc']}, ], }, { diff --git a/website/pages/api-docs/acl/auth-methods.mdx b/website/pages/api-docs/acl/auth-methods.mdx index adcba3fb7..eb4cc3e4a 100644 --- a/website/pages/api-docs/acl/auth-methods.mdx +++ b/website/pages/api-docs/acl/auth-methods.mdx @@ -42,8 +42,8 @@ The table below shows this endpoint's support for This field is immutable and must be unique. - `Type` `(string: )` - The type of auth method being configured. - The only allowed value in Consul 1.5.0 is `"kubernetes"`. This field is - immutable. + This field is immutable. For allowed values see the [auth method + documentation](/docs/acl/auth-methods). - `Description` `(string: "")` - Free form human readable description of the auth method. @@ -59,10 +59,12 @@ The table below shows this endpoint's support for `"5m"` (i.e., 60 seconds or 5 minutes, respectively). This value must be no smaller than 1 minute and no longer than 24 hours. Added in Consul 1.8.0. + This must be set to a nonzero value for `type=oidc`. + - `Config` `(map[string]string: )` - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the [auth - method documentation](/docs/acl/acl-auth-methods). + method documentation](/docs/acl/auth-methods). - `Namespace` `(string: "")` - Specifies the namespace to create the auth method within. If not provided in the JSON body, the value of @@ -232,10 +234,12 @@ The table below shows this endpoint's support for `"5m"` (i.e., 60 seconds or 5 minutes, respectively). This value must be no smaller than 1 minute and no longer than 24 hours. Added in Consul 1.8.0. + This must be set to a nonzero value for `type=oidc`. + - `Config` `(map[string]string: )` - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the [auth - method documentation](/docs/acl/acl-auth-methods). + method documentation](/docs/acl/auth-methods). - `Namespace` `(string: "")` - Specifies the namespace of the auth method to update. If not provided in the JSON body, the value of diff --git a/website/pages/api-docs/acl/index.mdx b/website/pages/api-docs/acl/index.mdx index 4472bf2f8..3e32facea 100644 --- a/website/pages/api-docs/acl/index.mdx +++ b/website/pages/api-docs/acl/index.mdx @@ -267,7 +267,7 @@ agent_prefix "" { ## Login to Auth Method This endpoint was added in Consul 1.5.0 and is used to exchange an [auth -method](/docs/acl/acl-auth-methods) bearer token for a newly-created +method](/docs/acl/auth-methods) bearer token for a newly-created Consul ACL token. | Method | Path | Produces | @@ -385,3 +385,180 @@ $ curl \ --request POST \ http://127.0.0.1:8500/v1/acl/logout ``` + +## OIDC Authorization URL Request + + This is an enterprise only endpoint. This feature is currently in beta. + +This endpoint was added in Consul 1.8.0 and is used to obtain an authorization +URL from Consul to start an [OIDC login flow](/docs/acl/auth-methods/oidc). + +| Method | Path | Produces | +| ------ | -------------------- | ------------------ | +| `POST` | `/acl/oidc/auth-url` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/features/blocking), +[consistency modes](/api/features/consistency), +[agent caching](/api/features/caching), and +[required ACLs](/api#authentication). + +| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | +| ---------------- | ----------------- | ------------- | ------------ | +| `NO` | `none` | `none` | `none` | + +-> **Note** - To use the login process to create tokens in any connected +secondary datacenter, [ACL +replication](/docs/agent/options#acl_enable_token_replication) must be +enabled. Login requires the ability to create local tokens which is restricted +to the primary datacenter and any secondary datacenters with ACL token +replication enabled. + +### Parameters + +- `AuthMethod` `(string: )` - The name of the auth method to use for + login. This must be of type [`oidc`](/docs/acl/auth-methods/oidc). + +- `RedirectURI` `(string: )` - See [Redirect + URIs](/docs/acl/auth-methods/oidc#redirect-uris) for more information. + +- `ClientNonce` `(string: "")` - Optional client-provided nonce that must match + during callback, if present. + +- `Meta` `(map: nil)` - Specifies arbitrary KV metadata + linked to the token. Can be useful to track origins. + +- `Namespace` `(string: "")` - Specifies the namespace of + the Auth Method to use for Login. If not provided in the JSON body, the value of + the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. + If not provided at all, the namespace will be inherited from the request's ACL + token, or will default to the `default` namespace. + + This must match the namespace provided on the [OIDC Callback](#oidc-callback). + +### Sample Payload + +```json +{ + "AuthMethod": "auth0", + "RedirectURI": "http://localhost:8550/oidc/callback" +} +``` + +### Sample Request + +```shell +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8500/v1/acl/oidc/auth-url +``` + +### Sample Response + +```json +{ + "AuthURL": "https://myprovider.com/authorize?client_id=..." +} +``` + +## OIDC Callback + + This is an enterprise only endpoint. This feature is currently in beta. + +This endpoint was added in Consul 1.8.0 and is used to exchange an OIDC +authorization code for an OIDC ID Token. The ID token will in turn be exchanged +for a newly-created Consul ACL token. + +| Method | Path | Produces | +| ------ | -------------------- | ------------------ | +| `POST` | `/acl/oidc/callback` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/features/blocking), +[consistency modes](/api/features/consistency), +[agent caching](/api/features/caching), and +[required ACLs](/api#authentication). + +| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | +| ---------------- | ----------------- | ------------- | ------------ | +| `NO` | `none` | `none` | `none` | + +-> **Note** - To use the login process to create tokens in any connected +secondary datacenter, [ACL +replication](/docs/agent/options#acl_enable_token_replication) must be +enabled. Login requires the ability to create local tokens which is restricted +to the primary datacenter and any secondary datacenters with ACL token +replication enabled. + +### Parameters + +- `AuthMethod` `(string: )` - The name of the auth method to use for + login. This must be of type [`oidc`](/docs/acl/auth-methods/oidc). + +- `State` `(string: )` - Opaque state ID that is part of the + Authorization URL and will be included in the the redirect following + successful authentication on the provider. + +- `Code` `(string: )` - Provider-generated authorization code that + Consul will exchange for an ID token. + +- `ClientNonce` `(string: "")` - Optional client-provided nonce that must match + the one provided in the auth url request, if present. + +- `Meta` `(map: nil)` - Specifies arbitrary KV metadata + linked to the token. Can be useful to track origins. + +- `Namespace` `(string: "")` - Specifies the namespace of + the Auth Method to use for Login. If not provided in the JSON body, the value of + the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. + If not provided at all, the namespace will be inherited from the request's ACL + token, or will default to the `default` namespace. + + This must match the namespace provided on the [OIDC Callback](#oidc-callback). + +### Sample Payload + +```json +{ + "AuthMethod": "auth0", + "State": "aa3f1903c2f5eac666e6f92e804cf7fc0ff1d15b", + "Code": "dn0u9oM9WegYBEnp" +} +``` + +### Sample Request + +```shell +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8500/v1/acl/oidc/callback +``` + +### Sample Response + +```json +{ + "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b", + "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586", + "Description": "token created via OIDC login", + "Roles": [ + { + "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7", + "Name": "demo" + } + ], + "ServiceIdentities": [ + { + "ServiceName": "example" + } + ], + "Local": true, + "AuthMethod": "auth0", + "CreateTime": "2019-04-29T10:08:08.404370762-05:00", + "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=", + "CreateIndex": 36, + "ModifyIndex": 36 +} +``` diff --git a/website/pages/docs/acl/acl-system.mdx b/website/pages/docs/acl/acl-system.mdx index 3c316628f..0d3998b9c 100644 --- a/website/pages/docs/acl/acl-system.mdx +++ b/website/pages/docs/acl/acl-system.mdx @@ -47,7 +47,7 @@ may benefit from additional components in the ACL system: independently configured. (Added in Consul 1.5.0) - **ACL Auth Methods and Binding Rules** - To learn more about these topics, - see the [dedicated auth methods documentation page](/docs/acl/acl-auth-methods). + see the [auth methods documentation page](/docs/acl/auth-methods). ACL tokens, policies, roles, auth methods, and binding rules are managed by Consul operators via Consul's [ACL API](/api/acl/acl), diff --git a/website/pages/docs/acl/auth-methods/index.mdx b/website/pages/docs/acl/auth-methods/index.mdx index 3641b66cc..fe6ada50d 100644 --- a/website/pages/docs/acl/auth-methods/index.mdx +++ b/website/pages/docs/acl/auth-methods/index.mdx @@ -10,15 +10,12 @@ description: >- # ACL Auth Methods --> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer. +-> **1.5.0+:** Auth methods only exist in Consul versions 1.5.0 and newer. An auth method is a component in Consul that performs authentication against a trusted external party to authorize the creation of an ACL tokens usable within the local datacenter. -The only supported type of auth method in Consul 1.5.0 is -[`kubernetes`](/docs/acl/auth-methods/kubernetes). - ## Overview Without an auth method a trusted operator is critically involved in the @@ -36,6 +33,14 @@ In Consul 1.5.0 the focus is around simplifying the creation of tokens with the privileges necessary to participate in a [Connect](/docs/connect) service mesh with minimal operator intervention. +## Supported Types + +| Types | Consul Version | +| ----- | -------------- | +| [`kubernetes`](/docs/acl/auth-methods/kubernetes) | 1.5.0+ | +| [`jwt`](/docs/acl/auth-methods/jwt) | 1.8.0+ | +| [`oidc`](/docs/acl/auth-methods/oidc) | 1.8.0+ | + ## Operator Configuration An operator needs to configure each auth method that is to be trusted by diff --git a/website/pages/docs/acl/auth-methods/jwt.mdx b/website/pages/docs/acl/auth-methods/jwt.mdx new file mode 100644 index 000000000..88fbe3a75 --- /dev/null +++ b/website/pages/docs/acl/auth-methods/jwt.mdx @@ -0,0 +1,175 @@ +--- +layout: docs +page_title: JWT Auth Method +sidebar_title: JWT Beta +description: >- + The JWT auth method can be used to authenticate with Consul by providing a + JWT directly. The JWT is cryptographically verified using locally-provided + keys, or, if configured, an OIDC Discovery service can be used to fetch the + appropriate keys. +--- + +# JWT Auth Method Beta + +-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. + +The `jwt` auth method can be used to authenticate with Consul 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, an +OIDC Discovery service can be used to fetch the appropriate keys. + +This page assumes general knowledge of JWTs and the concepts described in the +main [auth method documentation](/docs/acl/auth-methods). + +Both the [`jwt`](/docs/acl/auth-methods/jwt) and the +[`oidc`](/docs/acl/auth-methods/oidc) auth method types allow additional +processing of the claims data in the JWT. + +@include 'jwt_or_oidc.mdx' + +## Config Parameters + +The following auth method [`Config`](/api/acl/auth-methods#config) +parameters are required to properly configure an auth method of type +`jwt`: + +- `JWTValidationPubKeys` `(array)` - A list of PEM-encoded public keys + to use to authenticate signatures locally. + + Exactly one of `JWKSURL` `JWTValidationPubKeys`, or `OIDCDiscoveryURL` is required. + +- `OIDCDiscoveryURL` `(string: "")` - The OIDC Discovery URL, without any + .well-known component (base path). + + Exactly one of `JWKSURL` `JWTValidationPubKeys`, or `OIDCDiscoveryURL` is required. + +- `OIDCDiscoveryCACert` `(string: "")` - PEM encoded CA cert for use by the TLS + client used to talk with the OIDC Discovery URL. NOTE: Every line must end + with a newline (`\n`). If not set, system certificates are used. + +- `JWKSURL` `(string: "")` - The JWKS URL to use to authenticate signatures. + + Exactly one of `JWKSURL` `JWTValidationPubKeys`, or `OIDCDiscoveryURL` is required. + +- `JWKSCACert` `(string: "")` - PEM encoded CA cert for use by the TLS client + used to talk with the JWKS URL. NOTE: Every line must end with a newline + (`\n`). If not set, system certificates are used. + +- `ClaimMappings` `(map[string]string)` - Mappings of claims (key) that + [will be copied to a metadata field](#trusted-identity-attributes-via-claim-mappings) + (value). Use this if the claim you are capturing is singular (such as an attribute). + + When mapped, the values 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](#trusted-identity-attributes-via-claim-mappings) + (value). Use this if the claim you are capturing is list-like (such as groups). + + When mapped, the values in each list can be any of a number, string, or + boolean and will all be stringified when returned. + +- `JWTSupportedAlgs` `(array)` - JWTSupportedAlgs is a list of + supported signing algorithms. Defaults to `RS256`. + +- `BoundAudiences` `(array)` - List of `aud` claims that are valid for + login; any match is sufficient. + +- `BoundIssuer` `(string: "")` - The value against which to match the `iss` + claim in a JWT. + +- `ExpirationLeeway` `(duration: 0s)` - Duration in seconds of leeway when + validating expiration of a token to account for clock skew. Defaults to 150 + (2.5 minutes) if set to 0 and can be disabled if set to -1. + +- `NotBeforeLeeway` `(duration: 0s)` - Duration in seconds of leeway when + validating not before values of a token to account for clock skew. Defaults + to 150 (2.5 minutes) if set to 0 and can be disabled if set to -1. + +- `ClockSkewLeeway` `(duration: 0s)` - Duration in seconds of leeway when + validating all claims to account for clock skew. Defaults to 60 (1 minute) + if set to 0 and can be disabled if set to -1. + +### Sample Configs + +#### Static Keys + +```json +{ + ...other fields... + "Config": { + "BoundIssuer": "corp-issuer", + "JWTValidationPubKeys": [ + "" + ], + "ClaimMappings": { + "http://example.com/first_name": "first_name", + "http://example.com/last_name": "last_name" + }, + "ListClaimMappings": { + "http://example.com/groups": "groups" + } + } +} +``` + +#### JWKS + +```json +{ + ...other fields... + "Config": { + "JWKSURL": "https://my-corp-jwks-url.example.com/", + "ClaimMappings": { + "http://example.com/first_name": "first_name", + "http://example.com/last_name": "last_name" + }, + "ListClaimMappings": { + "http://example.com/groups": "groups" + } + } +} +``` + +#### OIDC Discovery + +```json +{ + ...other fields... + "Config": { + "BoundAudiences": [ + "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt" + ], + "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/", + "ClaimMappings": { + "http://example.com/first_name": "first_name", + "http://example.com/last_name": "last_name" + }, + "ListClaimMappings": { + "http://example.com/groups": "groups" + } + } +} +``` + +## JWT Verification + +JWT signatures will be verified against public keys from the issuer. This +process can be done one of three ways: + +- **Static Keys** - A set of public keys is stored directly in the + configuration. + +- **JWKS** - A JSON Web Key Set ([JWKS](https://tools.ietf.org/html/rfc7517)) + URL (and optional certificate chain) is configured. Keys will be fetched from + this endpoint during authentication. + +- **OIDC Discovery** - An OIDC Discovery URL (and optional certificate chain) + is configured. Keys will be fetched from this URL during authentication. When + OIDC Discovery is used, OIDC validation criteria (e.g. `iss`, `aud`, etc.) + will be applied. + +If multiple methods are needed, another auth method of this type may be created +with a different name. + +@include 'jwt_claim_mapping_details.mdx' diff --git a/website/pages/docs/acl/auth-methods/kubernetes.mdx b/website/pages/docs/acl/auth-methods/kubernetes.mdx index 43a226b9c..7f0a6478f 100644 --- a/website/pages/docs/acl/auth-methods/kubernetes.mdx +++ b/website/pages/docs/acl/auth-methods/kubernetes.mdx @@ -8,17 +8,17 @@ description: >- easy to introduce a Consul token into a Kubernetes pod. --- --> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer. - # Kubernetes Auth Method +-> **1.5.0+:** This feature is available in Consul versions 1.5.0 and newer. + The `kubernetes` auth method type allows for a Kubernetes service account token to be used to authenticate to Consul. This method of authentication makes it easy to introduce a Consul token into a Kubernetes pod. This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and the concepts described in the main [auth method -documentation](/docs/acl/acl-auth-methods). +documentation](/docs/acl/auth-methods). ## Config Parameters @@ -31,7 +31,7 @@ parameters are required to properly configure an auth method of type - `CACert` `(string: )` - PEM encoded CA cert for use by the TLS client used to talk with the Kubernetes API. NOTE: Every line must end with a - newline (`\n`). + newline (`\n`). If not set, system certificates are used. - `ServiceAccountJWT` `(string: )` - A Service Account Token ([JWT](https://jwt.io/ 'JSON Web Token')) used by the Consul leader to @@ -43,11 +43,13 @@ parameters are required to properly configure an auth method of type namespace instead of creating tokens in the auth methods own namespace. Note that mapping namespaces requires the auth method to reside within the `default` namespace. + Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules). - `ConsulNamespacePrefix` `(string: )` - **Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).** When `MapNamespaces` is enabled, this value will be prefixed to the Kubernetes namespace to determine the Consul namespace to create the new token within. + Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules). - `ConsulNamespaceOverrides` `(map: )` - **Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).** @@ -56,6 +58,7 @@ parameters are required to properly configure an auth method of type be used without adding the `ConsulNamespacePrefix`. If the value in the map is `""` then the auth methods namespace will be used instead of attempting to determine an alternate namespace. + Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules). ### Sample Config @@ -131,17 +134,6 @@ roleRef: apiGroup: rbac.authorization.k8s.io ``` -## Trusted Identity Attributes - -The authentication step returns the following trusted identity attributes for -use in binding rule selectors and bind name interpolation. - -| Attributes | Supported Selector Operations | Can be Interpolated | -| -------------------------- | -------------------------------------------------- | ------------------- | -| `serviceaccount.namespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | -| `serviceaccount.name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | -| `serviceaccount.uid` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | - ## Kubernetes Authentication Details Initially the @@ -156,3 +148,14 @@ API to check for the existence of an annotation of `consul.hashicorp.com/service-name` on the ServiceAccount object. If one is found its value will override the trusted attribute of `serviceaccount.name` for the purposes of evaluating any binding rules. + +## Trusted Identity Attributes + +The authentication step returns the following trusted identity attributes for +use in binding rule selectors and bind name interpolation. + +| Attributes | Supported Selector Operations | Can be Interpolated | +| -------------------------- | -------------------------------------------------- | ------------------- | +| `serviceaccount.namespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | +| `serviceaccount.name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | +| `serviceaccount.uid` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | diff --git a/website/pages/docs/acl/auth-methods/oidc.mdx b/website/pages/docs/acl/auth-methods/oidc.mdx new file mode 100644 index 000000000..ccbdd7696 --- /dev/null +++ b/website/pages/docs/acl/auth-methods/oidc.mdx @@ -0,0 +1,214 @@ +--- +layout: docs +page_title: OIDC Auth Method +sidebar_title: OIDC Beta +description: >- + The OIDC auth method can be used to authenticate with Consul using OpenID + Connect (OIDC). This method allows authentication via a configured OIDC + provider using the user's web browser. This method may be initiated from the + Consul UI or the command line. +--- + +# OIDC Auth Method Beta + + + +This feature is available in [Consul +Enterprise](https://www.hashicorp.com/products/consul/) version 1.8.0 and +newer. + +The `oidc` auth method can be used to authenticate with Consul using +[OIDC](https://en.wikipedia.org/wiki/OpenID_Connect). This method allows +authentication via a configured OIDC provider using the user's web browser. +This method may be initiated from the Consul UI or the command line. + +This page assumes general knowledge of [OIDC +concepts](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1) and +the concepts described in the main [auth method +documentation](/docs/acl/auth-methods). + +Both the [`jwt`](/docs/acl/auth-methods/jwt) and the +[`oidc`](/docs/acl/auth-methods/oidc) auth method types allow additional +processing of the claims data in the JWT. + +@include 'jwt_or_oidc.mdx' + +## Config Parameters + +The following auth method [`Config`](/api/acl/auth-methods#config) +parameters are required to properly configure an auth method of type +`oidc`: + +- `OIDCDiscoveryURL` `(string: )` - The OIDC Discovery URL, without any + .well-known component (base path). + +- `OIDCDiscoveryCACert` `(string: "")` - PEM encoded CA cert for use by the TLS + client used to talk with the OIDC Discovery URL. NOTE: Every line must end + with a newline (`\n`). If not set, system certificates are used. + +- `OIDCClientID` `(string: )` - The OAuth Client ID configured with + your OIDC provider. + +- `OIDCClientSecret` `(string: )` - The OAuth Client Secret configured with + your OIDC provider. + +- `AllowedRedirectURIs` `(array)` - Comma-separated list of allowed + values for `redirect_uri`. Must be non-empty. + +- `ClaimMappings` `(map[string]string)` - Mappings of claims (key) that + [will be copied to a metadata field](#trusted-identity-attributes-via-claim-mappings) + (value). Use this if the claim you are capturing is singular (such as an attribute). + + When mapped, the values 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](#trusted-identity-attributes-via-claim-mappings) + (value). Use this if the claim you are capturing is list-like (such as groups). + + When mapped, the values in each list can be any of a number, string, or + boolean and will all be stringified when returned. + +- `OIDCScopes` `(array)` - Comma-separated list of OIDC scopes. + +- `JWTSupportedAlgs` `(array)` - JWTSupportedAlgs is a list of + supported signing algorithms. Defaults to `RS256`. ([Available + algorithms](https://github.com/hashicorp/consul/blob/master/vendor/github.com/coreos/go-oidc/jose.go#L7)) + +- `BoundAudiences` `(array)` - List of `aud` claims that are valid for + login; any match is sufficient. + +- `VerboseOIDCLogging` `(bool: false)` - Log received OIDC tokens and claims when + debug-level logging is active. Not recommended in production since sensitive + information may be present in OIDC responses. + +### Sample Config + +```json +{ + ...other fields... + "Config": { + "AllowedRedirectURIs": [ + "http://localhost:8550/oidc/callback", + "http://localhost:8500/ui/oidc/callback" + ], + "BoundAudiences": [ + "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt" + ], + "ClaimMappings": { + "http://example.com/first_name": "first_name", + "http://example.com/last_name": "last_name" + }, + "ListClaimMappings": { + "http://consul.com/groups": "groups" + }, + "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt", + "OIDCClientSecret": "...(omitted)...", + "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/" + } +} +``` + +## JWT Verification + +JWT signatures will be verified against public keys from the issuer via OIDC +discovery. Keys will be fetched from the OIDC Discovery URL during +authentication and OIDC validation criteria (e.g. `iss`, `aud`, etc.) will be +applied. + +## OIDC Authentication + +Consul includes two built-in OIDC login flows: the Consul UI, and the CLI using +[`consul login`](/docs/commands/login). + +### Redirect URIs + +An important part of OIDC auth method configuration is properly setting +redirect URIs. This must be done both in Consul and with the OIDC provider, and +these configurations must align. The redirect URIs are specified for an auth +method with the [`AllowedRedirectURIs`](#allowedredirecturis) parameter. There +are different redirect URIs to configure the Consul UI and CLI flows, so one or +both will need to be set up depending on the installation. + +#### Consul UI + +Logging in via the Consul UI requires a redirect URI of the form: +`http://localhost:8500/ui/oidc/callback` or +`https://{host:port}/ui/oidc/callback` + +The "host:port" must be correct for the Consul agent serving the Consul UI. + +#### CLI + +If you plan to support authentication via `consul login -type=oidc +-method=`, a localhost redirect URI must be set (usually this is +`http://localhost:8550/oidc/callback`). Logins via the CLI may specify a +different host and/or listening port if needed, and a URI with this host/port +must match one of the configured redirected URIs. These same "localhost" URIs +must be added to the provider as well. + +### OIDC Login + +#### Consul UI + +1. Click the "Log in" link at the top right of the menu bar. +2. Click one of the "Continue with..." buttons for your OIDC auth method of choice. +3. Complete the authentication with the configured provider. + +#### CLI + +``` +$ consul login -method=oidc -type=oidc -token-sink-file=consul.token + +Complete the login via your OIDC provider. Launching browser to: + + https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8550%2Foidc%2Fcallback&client_id=r3qXc2bix9eF... +``` + +The browser will open to the generated URL to complete the provider's login. +The URL may be entered manually if the browser cannot be automatically opened. + +The callback listener may be customized with the following optional parameters. +These are typically not required to be set: + +The callback listener defaults to listen on `localhost:8550`. If you want to +customize that use the optional flag +[`-oidc-callback-listen-addr=`](/docs/commands/login#oidc-callback-listen-addr). + +## 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. Some tips for setting up OIDC: + +- Monitor the log output for the Consul servers. Important information about + OIDC validation failures will be emitted. + +- Ensure Redirect URIs are correct in Consul and on the provider. They need to + match exactly. Check: http/https, 127.0.0.1/localhost, port numbers, whether + trailing slashes are present. + +- [`BoundAudiences`](#boundaudiences) is optional and typically + not required. OIDC providers will use the `client_id` as the audience and + OIDC validation expects this. + +- Check your provider for what scopes are required in order to receive all of + the information you need. The scopes "profile" and "groups" often need to be + requested, and can be added by setting + `[OIDCScopes](#oidcscopes)="profile,groups"` on the auth method. + +- 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. An example of how to decode the + JWT (in this case located in the `access_token` field of a JSON response): + + cat jwt.json | jq -r .access_token | cut -d. -f2 | base64 -D + +- The [`VerboseOIDCLogging`](#verboseoidclogging) option is available which + will log the received OIDC token if debug level logging is enabled. This can + be helpful when debugging provider setup and verifying that the received + claims are what you expect. Since claims data is logged verbatim and may + contain sensitive information, this option should not be used in production. + +@include 'jwt_claim_mapping_details.mdx' diff --git a/website/pages/docs/acl/index.mdx b/website/pages/docs/acl/index.mdx index cdbda3ef0..3fc84070f 100644 --- a/website/pages/docs/acl/index.mdx +++ b/website/pages/docs/acl/index.mdx @@ -38,7 +38,7 @@ the policy that must be enforced. Read the ACL rules An auth method is a component in Consul that performs authentication against a trusted external party to authorize the creation of an ACL tokens usable within the local datacenter. Read the ACL auth method -[documentation](/docs/acl/acl-auth-methods) to learn more about how they +[documentation](/docs/acl/auth-methods) to learn more about how they work and why you may want to use them. ### ACL Legacy System diff --git a/website/pages/docs/agent/options.mdx b/website/pages/docs/agent/options.mdx index 7055cc351..9accc54d7 100644 --- a/website/pages/docs/agent/options.mdx +++ b/website/pages/docs/agent/options.mdx @@ -627,7 +627,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." secondary Consul datacenters will perform replication of only ACL policies and roles. Setting this configuration will will enable ACL token replication and allow for the creation of both [local tokens](/api/acl/tokens#local) and - [auth methods](/docs/acl/acl-auth-methods) in connected secondary datacenters. + [auth methods](/docs/acl/auth-methods) in connected secondary datacenters. - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either `true` or `false`. When `true` tokens set using the API will be persisted to diff --git a/website/pages/docs/commands/acl/auth-method/create.mdx b/website/pages/docs/commands/acl/auth-method/create.mdx index 07934928e..afe6620cf 100644 --- a/website/pages/docs/commands/acl/auth-method/create.mdx +++ b/website/pages/docs/commands/acl/auth-method/create.mdx @@ -31,6 +31,17 @@ Usage: `consul acl auth-method create [options] [args]` - `-type=` - The new auth method's type. This flag is required. +- `-display-name=` - An optional name to use instead of the name when + displaying this auth method in a UI. Added in Consul 1.8.0. + +- `-max-token-ttl=` - Duration of time all tokens created by this + auth method should be valid for. Added in Consul 1.8.0. + +- `-config=` - The configuration for the auth method. Must be JSON. 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. Added in Consul 1.8.0. + - `-kubernetes-ca-cert=` - PEM encoded CA cert for use by the TLS client used to talk with the Kubernetes API. May be prefixed with '@' to indicate that the value is a file path to load the cert from. This flag is @@ -49,6 +60,13 @@ Usage: `consul acl auth-method create [options] [args]` @include 'http_api_namespace_options.mdx' +- `-namespace-rule-bind-namespace=` - Namespace to bind on match. Can + use `${var}` interpolation. Added in Consul 1.8.0. + +- `-namespace-rule-selector=` - An expression that matches against + verified identity attributes returned from the auth method during login to + determine if the namespace rule applies. Added in Consul 1.8.0. + ## Examples Create a new Kubernetes auth method: diff --git a/website/pages/docs/commands/acl/auth-method/update.mdx b/website/pages/docs/commands/acl/auth-method/update.mdx index c0ee46a2f..147bea76c 100644 --- a/website/pages/docs/commands/acl/auth-method/update.mdx +++ b/website/pages/docs/commands/acl/auth-method/update.mdx @@ -27,6 +27,17 @@ Usage: `consul acl auth-method update [options] [args]` - `-description=` - A description of the auth method. +- `-display-name=` - An optional name to use instead of the name when + displaying this auth method in a UI. Added in Consul 1.8.0. + +- `-max-token-ttl=` - Duration of time all tokens created by this + auth method should be valid for. Added in Consul 1.8.0. + +- `-config=` - The configuration for the auth method. Must be JSON. 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. Added in Consul 1.8.0. + - `-kubernetes-ca-cert=` - PEM encoded CA cert for use by the TLS client used to talk with the Kubernetes API. May be prefixed with '@' to indicate that the value is a file path to load the cert from. This flag is @@ -54,6 +65,13 @@ Usage: `consul acl auth-method update [options] [args]` @include 'http_api_namespace_options.mdx' +- `-namespace-rule-bind-namespace=` - Namespace to bind on match. Can + use `${var}` interpolation. Added in Consul 1.8.0. + +- `-namespace-rule-selector=` - An expression that matches against + verified identity attributes returned from the auth method during login to + determine if the namespace rule applies. Added in Consul 1.8.0. + ## Examples Update an auth method: diff --git a/website/pages/docs/commands/login.mdx b/website/pages/docs/commands/login.mdx index 212e819a6..de001441e 100644 --- a/website/pages/docs/commands/login.mdx +++ b/website/pages/docs/commands/login.mdx @@ -37,6 +37,17 @@ Usage: `consul login [options]` - `-token-sink-file=` - The most recent token's SecretID is kept up to date in this file. +- `-type=` - Type of the auth method to login to. This field is + optional and defaults to no type. Required for `type=oidc` auth method login. + Added in Consul 1.8.0. + +#### Enterprise Options + +@include 'http_api_namespace_options.mdx' + +- `-oidc-callback-listen-addr=` - The address to bind a webserver on to + handle the browser callback from the OIDC workflow. Added in Consul 1.8.0. + ### Examples Login to an auth method. diff --git a/website/pages/docs/enterprise/index.mdx b/website/pages/docs/enterprise/index.mdx index 4591a0984..5dc50cbd7 100644 --- a/website/pages/docs/enterprise/index.mdx +++ b/website/pages/docs/enterprise/index.mdx @@ -25,6 +25,7 @@ Features include: - [Network Segments](/docs/enterprise/network-segments) - [Namespaces](/docs/enterprise/namespaces) - [Sentinel](/docs/enterprise/sentinel) +- [OIDC Auth Method](/docs/acl/auth-methods/oidc) These features are part of [Consul Enterprise](https://www.hashicorp.com/consul). diff --git a/website/pages/docs/guides/managing-acl-policies.mdx b/website/pages/docs/guides/managing-acl-policies.mdx index f1699dbd2..3615f9edc 100644 --- a/website/pages/docs/guides/managing-acl-policies.mdx +++ b/website/pages/docs/guides/managing-acl-policies.mdx @@ -13,7 +13,7 @@ level: Implementation This guide is for Operators with the responsibility of creating and managing ACL tokens for a Consul datacenter. It includes several recommendations on how to discover the minimum privileges required to complete operations. Throughout the guide we'll provide examples and use cases that you can adapt to your environment, however, it does not include environment specific recommendations. After completing this guide, you will have a better understanding of how to effectively manage ACL policies and tokens. -We expect operators to automate the policy and token generation process in production environments. Additionally, if you are using a container orchestrator, the process will vary even though the concepts in this guide will still be applicable. If you are using the official Consul-Kubernetes Helm chart to deploy Consul, use the [authentication method documentation](https://www.consul.io/docs/acl/acl-auth-methods.html) instead of generating policies manually or automating the methods here. +We expect operators to automate the policy and token generation process in production environments. Additionally, if you are using a container orchestrator, the process will vary even though the concepts in this guide will still be applicable. If you are using the official Consul-Kubernetes Helm chart to deploy Consul, use the [authentication method documentation](/docs/acl/auth-methods) instead of generating policies manually or automating the methods here. ## Prerequisites diff --git a/website/pages/docs/k8s/helm.mdx b/website/pages/docs/k8s/helm.mdx index 98b62bc2b..be18cda5e 100644 --- a/website/pages/docs/k8s/helm.mdx +++ b/website/pages/docs/k8s/helm.mdx @@ -694,7 +694,7 @@ and consider if they're appropriate for your deployment. beta.kubernetes.io/arch: amd64 ``` - - `aclBindingRuleSelector` ((#v-connectinject-acl-bindingrule-selector)) (`string: "serviceaccount.name!=default"`) - A [selector](/docs/acl/acl-auth-methods#binding-rules) + - `aclBindingRuleSelector` ((#v-connectinject-acl-bindingrule-selector)) (`string: "serviceaccount.name!=default"`) - A [selector](/docs/acl/auth-methods#binding-rules) for restricting automatic injection to only matching services based on their associated service account. By default, services using the `default` Kubernetes service account will be prevented from logging in. This only has effect if ACLs diff --git a/website/pages/partials/jwt_claim_mapping_details.mdx b/website/pages/partials/jwt_claim_mapping_details.mdx new file mode 100644 index 000000000..d5f9415b1 --- /dev/null +++ b/website/pages/partials/jwt_claim_mapping_details.mdx @@ -0,0 +1,77 @@ +## Trusted Identity Attributes via Claim Mappings + +Data from JWT claims can be returned from the authentication step as trusted +identity attributes for use in binding rule selectors and bind name +interpolation. + +Control of which claims are mapped to which identity attributes is governed by +the [`ClaimMappings`](#claimmappings) and +[`ListClaimMappings`](#listclaimmappings). These are both maps of items to copy +with elements of the form: `"":""`. + +The only difference between these two types of mappings is that `ClaimMappings` +is used to map singular values (such as a name, department, or team) while +`ListClaimMappings` is used to map lists of values. + +The singular values mapped by `ClaimMappings` can be interpolated in a binding +rule, and the lists of values mapped by `ListClaimMappings` cannot. + +Assume this is your config snippet: + +```json +{ ...other fields... + "ClaimMappings": { + "givenName": "first_name", + "surname": "last_name" + }, + "ListClaimMappings": { + "groups": "groups" + } +} +``` + +This specifies that the values in the JWT claims `"givenName"` and `"surname"` +should be copied to attributes named `"value.first_name"` and +`"value.last_name"` respectively. Additionally the list of values in the JWT +claim `"groups"` should be copied to an attribute named `"list.groups"`. + +The following table shows the resulting attributes that will be extracted, 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 + +The [`ClaimMappings`](#claimmappings) and +[`ListClaimMappings`](#listclaimmappings) fields are used to point to data +within the JWT. If the desired key is at the top of level of the JWT, the name +can be provided directly. If it is nested at a lower level, a JSON Pointer may +be used. + +Assume the following JWT claims are decoded: + +```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" +} +``` + +A parameter of `"division"` will reference `"North America"`, as this is a top +level key. A parameter `"/groups/primary"` uses JSON Pointer syntax to +reference `"Engineering"` at a lower level. Any valid JSON Pointer can be used +as a selector. Refer to the [JSON Pointer +RFC](https://tools.ietf.org/html/rfc6901) for a full description of the syntax diff --git a/website/pages/partials/jwt_or_oidc.mdx b/website/pages/partials/jwt_or_oidc.mdx new file mode 100644 index 000000000..4bb3c4308 --- /dev/null +++ b/website/pages/partials/jwt_or_oidc.mdx @@ -0,0 +1,18 @@ +## JWT vs OIDC Auth Methods + +Since both the `oidc` and `jwt` auth methods ultimately operate on JWTs as +bearer tokens, it may be confusing to know which is right for a given use case. + +- **JWT**: The user or application performing the Consul login must already be + in possession of a valid JWT to begin. There is no browser interaction + required. This is ideal for machine-oriented headless login where an operator + may have already arranged for a valid JWT to be dropped on a VM or provided + to a container. + +- **OIDC**: The user performing the Consul login does not have a JWT nor do + they even need to know what that means. This is ideal for human-oriented + interactive login where an operator or administrator may have deployed SSO + widely and doesn't want to have the burden of tracking and distributing + Consul ACL tokens to any authorized coworker who may need to have access to a + Consul instance. Browser interaction is required. **This is only available in + [Consul Enterprise](https://www.hashicorp.com/products/consul/)**.