luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

docs: docs for jwt and oidc auth methods (#7847)

This commit is contained in:
R.B. Boyer 2020-05-13 14:14:03 -05:00 committed by GitHub
parent 9b95af60b8
commit 49e6680892
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 751 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/data/docs-navigation.js
View File

@ -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']},
],
},
{

12
website/pages/api-docs/acl/auth-methods.mdx
View File

@ -42,8 +42,8 @@ The table below shows this endpoint's support for
This field is immutable and must be unique.
- `Type` `(string: <required>)` - 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: <required>)` - 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: "")` <EnterpriseAlert inline /> - 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: <required>)` - 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: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the auth method to update. If not provided in the JSON body, the value of

179
website/pages/api-docs/acl/index.mdx
View File

@ -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
<EnterpriseAlert> This is an enterprise only endpoint. This feature is currently in beta. </EnterpriseAlert>
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: <required>)` - The name of the auth method to use for
login. This must be of type [`oidc`](/docs/acl/auth-methods/oidc).
- `RedirectURI` `(string: <required>)` - 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<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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
<EnterpriseAlert> This is an enterprise only endpoint. This feature is currently in beta. </EnterpriseAlert>
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: <required>)` - The name of the auth method to use for
login. This must be of type [`oidc`](/docs/acl/auth-methods/oidc).
- `State` `(string: <required>)` - 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: <required>)` - 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<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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
}
```

2
website/pages/docs/acl/acl-system.mdx
View File

@ -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),

13
website/pages/docs/acl/auth-methods/index.mdx
View File

@ -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+ <EnterpriseAlert inline /> |
## Operator Configuration
An operator needs to configure each auth method that is to be trusted by

175
website/pages/docs/acl/auth-methods/jwt.mdx Normal file
View File

@ -0,0 +1,175 @@
---
layout: docs
page_title: JWT Auth Method
sidebar_title: JWT <sup>Beta</sup>
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 <sup>Beta</sup>
-> **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<string>)` - 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<string>)` - JWTSupportedAlgs is a list of
supported signing algorithms. Defaults to `RS256`.
- `BoundAudiences` `(array<string>)` - 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": [
"<public key PEM>"
],
"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'

33
website/pages/docs/acl/auth-methods/kubernetes.mdx
View File

@ -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: <required>)` - 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: <required>)` - 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: <optional>)` <EnterpriseAlert inline /> -
**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: <string:string>)` <EnterpriseAlert inline /> -
**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 |

214
website/pages/docs/acl/auth-methods/oidc.mdx Normal file
View File

@ -0,0 +1,214 @@
---
layout: docs
page_title: OIDC Auth Method
sidebar_title: OIDC <sup>Beta</sup>
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 <sup>Beta</sup>
<EnterpriseAlert />
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: <required>)` - 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: <required>)` - The OAuth Client ID configured with
your OIDC provider.
- `OIDCClientSecret` `(string: <required>)` - The OAuth Client Secret configured with
your OIDC provider.
- `AllowedRedirectURIs` `(array<string>)` - 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<string>)` - Comma-separated list of OIDC scopes.
- `JWTSupportedAlgs` `(array<string>)` - 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<string>)` - 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=<name>`, 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=<host:port>`](/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'

2
website/pages/docs/acl/index.mdx
View File

@ -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

2
website/pages/docs/agent/options.mdx
View File

@ -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

18
website/pages/docs/commands/acl/auth-method/create.mdx
View File

@ -31,6 +31,17 @@ Usage: `consul acl auth-method create [options] [args]`
- `-type=<string>` - The new auth method's type. This flag is required.
- `-display-name=<string>` - 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>` - Duration of time all tokens created by this
auth method should be valid for. Added in Consul 1.8.0.
- `-config=<string>` - 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=<string>` - 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=<value>` - Namespace to bind on match. Can
use `${var}` interpolation. Added in Consul 1.8.0.
- `-namespace-rule-selector=<value>` - 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:

18
website/pages/docs/commands/acl/auth-method/update.mdx
View File

@ -27,6 +27,17 @@ Usage: `consul acl auth-method update [options] [args]`
- `-description=<string>` - A description of the auth method.
- `-display-name=<string>` - 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>` - Duration of time all tokens created by this
auth method should be valid for. Added in Consul 1.8.0.
- `-config=<string>` - 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=<string>` - 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=<value>` - Namespace to bind on match. Can
use `${var}` interpolation. Added in Consul 1.8.0.
- `-namespace-rule-selector=<value>` - 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:

11
website/pages/docs/commands/login.mdx
View File

@ -37,6 +37,17 @@ Usage: `consul login [options]`
- `-token-sink-file=<string>` - The most recent token's SecretID is kept up to
date in this file.
- `-type=<string>` - 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=<string>` - 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.

1
website/pages/docs/enterprise/index.mdx
View File

@ -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).

2
website/pages/docs/guides/managing-acl-policies.mdx
View File

@ -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

2
website/pages/docs/k8s/helm.mdx
View File

@ -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

77
website/pages/partials/jwt_claim_mapping_details.mdx Normal file
View File

@ -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: `"<JWT claim>":"<attribute suffix>"`.
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

18
website/pages/partials/jwt_or_oidc.mdx Normal file
View File

@ -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/)**.