auth/oidc: Documentation updates for Azure AD applications

hashicorp · Jan 27, 2022 · 4105255 · 4105255
1 parent d14ee7d
commit 4105255
Show file tree

Hide file tree

Showing 2 changed files with 95 additions and 93 deletions.
diff --git a/website/content/docs/auth/jwt/index.mdx b/website/content/docs/auth/jwt/index.mdx
@@ -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,
@@ -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
@@ -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).
 
@@ -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" \
@@ -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

diff --git a/website/content/docs/auth/jwt/oidc_providers.mdx b/website/content/docs/auth/jwt/oidc_providers.mdx
@@ -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.
@@ -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