Skip to content

Commit

Permalink
auth/oidc: Documentation updates for Azure AD applications
Browse files Browse the repository at this point in the history
  • Loading branch information
@austingebauer
austingebauer committed Jan 27, 2022
1 parent d14ee7d commit 4105255
Show file tree
Hide file tree
Showing 2 changed files with 95 additions and 93 deletions.
181 changes: 91 additions & 90 deletions website/content/docs/auth/jwt/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,95 +23,6 @@ Both methods allow additional processing of the claims data in the JWT. Some of
the concepts common to both methods will be covered first, followed by specific
examples of OIDC and JWT usage.

### JWT Verification

JWT signatures will be verified against public keys from the issuer. This process can be done in
three different ways, though only one method may be configured for a single backend:

- **Static Keys**. A set of public keys is stored directly in the backend 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 instance of the backend can be mounted and configured
at a different path.

### Bound Claims

Once a JWT has been validated as being properly signed and not expired, the
authorization flow will validate that any configured "bound" parameters match.
In some cases there are dedicated parameters, for example `bound_subject`,
which must match the JWT's `sub` parameter. A role may also be configured to
check arbitrary claims through the `bound_claims` map. The map contains a set
of claims and their required values. For example, assume `bound_claims` is set
to:

```json
{
"division": "Europe",
"department": "Engineering"
}
```

Only JWTs containing both the "division" and "department" claims, and
respective matching values of "Europe" and "Engineering", would be authorized.
If the expected value is a list, the claim must match one of the items in the list.
To limit authorization to a set of email addresses:

```json
{
"email": ["fred@example.com", "julie@example.com"]
}
```

Bound claims can optionally be configured with globs. See the [API documentation](/api-docs/auth/jwt#bound_claims_type) for more details.

### Claims as Metadata

Data from claims can be copied into the resulting auth token and alias metadata by configuring `claim_mappings`. This role
parameter is a map of items to copy. The map elements are of the form: `"<JWT claim>":"<metadata key>"`. Assume
`claim_mappings` is set to:

```json
{
"division": "organization",
"department": "department"
}
```

This specifies that the value in the JWT claim "division" should be copied to the metadata key "organization". The JWT
"department" claim value will also be copied into metadata but will retain the key name. If a claim is configured in `claim_mappings`,
it must existing in the JWT or else the authentication will fail.

Note: the metadata key name "role" is reserved and may not be used for claim mappings.

### Claim specifications and JSON Pointer

Some parameters (e.g. `bound_claims`, `groups_claim`, `claim_mappings`) 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 JSON data to be referenced:

```json
{
"division": "North America",
"groups": {
"primary": "Engineering",
"secondary": "Software"
}
}
```

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.

## OIDC Authentication

This section covers the setup and use of OIDC roles. If a JWT is to be provided directly,
Expand Down Expand Up @@ -257,6 +168,23 @@ EOF
The authentication flow for roles of type "jwt" is simpler than OIDC since Vault
only needs to validate the provided JWT.

### JWT Verification

JWT signatures will be verified against public keys from the issuer. This process can be done in
three different ways, though only one method may be configured for a single backend:

- **Static Keys**. A set of public keys is stored directly in the backend 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 instance of the backend can be mounted and configured
at a different path.

### Via the CLI

The default path is `/jwt`. If this auth method was enabled at a
Expand Down Expand Up @@ -310,7 +238,7 @@ management tool.
$ vault auth enable oidc
```

1. Use the `/config` endpoint to configure Vault. To support JWT roles, either local keys or an OIDC
1. Use the `/config` endpoint to configure Vault. To support JWT roles, either local keys, a JWKS URL, or an OIDC
Discovery URL must be present. For OIDC roles, OIDC Discovery URL, OIDC Client ID and OIDC Client Secret are required. For the
list of available configuration options, please see the [API documentation](/api/auth/jwt).

Expand All @@ -326,6 +254,7 @@ management tool.

```text
vault write auth/jwt/role/demo \
allowed_redirect_uris="http://localhost:8250/oidc/callback" \
bound_subject="r3qX9DljwFIWhsiqwFiu38209F10atW6@clients" \
bound_audiences="https://vault.plugin.auth.jwt.test" \
user_claim="https://vault/user" \
Expand All @@ -341,6 +270,78 @@ management tool.
For the complete list of configuration options, please see the API
documentation.

### Bound Claims

Once a JWT has been validated as being properly signed and not expired, the
authorization flow will validate that any configured "bound" parameters match.
In some cases there are dedicated parameters, for example `bound_subject`,
which must match the JWT's `sub` parameter. A role may also be configured to
check arbitrary claims through the `bound_claims` map. The map contains a set
of claims and their required values. For example, assume `bound_claims` is set
to:

```json
{
"division": "Europe",
"department": "Engineering"
}
```

Only JWTs containing both the "division" and "department" claims, and
respective matching values of "Europe" and "Engineering", would be authorized.
If the expected value is a list, the claim must match one of the items in the list.
To limit authorization to a set of email addresses:

```json
{
"email": ["fred@example.com", "julie@example.com"]
}
```

Bound claims can optionally be configured with globs. See the [API documentation](/api-docs/auth/jwt#bound_claims_type) for more details.

### Claims as Metadata

Data from claims can be copied into the resulting auth token and alias metadata by configuring `claim_mappings`. This role
parameter is a map of items to copy. The map elements are of the form: `"<JWT claim>":"<metadata key>"`. Assume
`claim_mappings` is set to:

```json
{
"division": "organization",
"department": "department"
}
```

This specifies that the value in the JWT claim "division" should be copied to the metadata key "organization". The JWT
"department" claim value will also be copied into metadata but will retain the key name. If a claim is configured in `claim_mappings`,
it must existing in the JWT or else the authentication will fail.

Note: the metadata key name "role" is reserved and may not be used for claim mappings.

### Claim Specifications and JSON Pointer

Some parameters (e.g. `bound_claims`, `groups_claim`, `claim_mappings`) 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 JSON data to be referenced:

```json
{
"division": "North America",
"groups": {
"primary": "Engineering",
"secondary": "Software"
}
}
```

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.

## API

The JWT Auth Plugin has a full HTTP API. Please see the
Expand Down
7 changes: 4 additions & 3 deletions website/content/docs/auth/jwt/oidc_providers.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ and additions may be submitted via the [Vault Github repository](https://github.

## Azure Active Directory (AAD)

~> **Note:** Azure Active Directory Applications that have custom signing keys as a result of using
the [claims-mapping](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-claims-mapping)
feature are currently not supported for OIDC authentication.

Reference: [Azure Active Directory v2.0 and the OpenID Connect protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc)

1. Choose your Azure tenant.
Expand All @@ -32,9 +36,6 @@ Reference: [Azure Active Directory v2.0 and the OpenID Connect protocol](https:/

1. Record the "Application (client) ID" as you will need it as the `oidc_client_id`.

1. Under **API Permissions** grant the following permission:
- Microsoft Graph API permission [GroupMember.Read.All](https://docs.microsoft.com/en-us/graph/permissions-reference#application-permissions-23)

1. Under **Endpoints**, copy the OpenID Connect metadata document URL, omitting the `/well-known...` portion.
- The endpoint URL (`oidc_discovery_url`) will look like: https://login.microsoftonline.com/tenant-guid-dead-beef-aaaa-aaaa/v2.0

Expand Down

0 comments on commit 4105255

Please sign in to comment.