feat(oidc): jwt secured authorization response mode (#5914)

This implements the Financial-grade API JWT Secured Authorization Response Mode for OAuth 2.0 also known as JARM per https://openid.net/specs/openid-financial-api-jarm.html and related specifications. This implements part of the FAPI 2.0 security profile. Signed-off-by: James Elliott <james-d-elliott@users.noreply.github.com>
authelia · Aug 30, 2023 · 0196e0b · 0196e0b
1 parent 0da4abf
commit 0196e0b
Show file tree

Hide file tree

Showing 62 changed files with 2,368 additions and 414 deletions.
diff --git a/api/openapi.yml b/api/openapi.yml
@@ -1754,8 +1754,8 @@ components:
               description: If special characters are required when using the standard mode.
     handlers.DuoDeviceBody:
       required:
-        - device
-        - method
+        - 'device'
+        - 'method'
       type: object
       properties:
         device:
@@ -1794,8 +1794,8 @@ components:
                       example: push
     handlers.bodyFirstFactorRequest:
       required:
-        - username
-        - password
+        - 'username'
+        - 'password'
       type: object
       properties:
         username:
@@ -1854,15 +1854,15 @@ components:
     {{- if .PasswordReset }}
     handlers.PasswordResetStep1RequestBody:
       required:
-        - username
+        - 'username'
       type: object
       properties:
         username:
           type: string
           example: john
     handlers.PasswordResetStep2RequestBody:
       required:
-        - password
+        - 'password'
       type: object
       properties:
         password:
@@ -1916,7 +1916,7 @@ components:
           example: Authentication failed, please retry later.
     middlewares.IdentityVerificationFinishBody:
       required:
-        - token
+        - 'token'
       type: object
       properties:
         token:
@@ -1960,7 +1960,7 @@ components:
               example: true
     handlers.UserInfo.MethodBody:
       required:
-        - method
+        - 'method'
       type: object
       properties:
         method:
@@ -2067,7 +2067,10 @@ components:
               allOf:
                 - $ref: '#/components/schemas/webauthn.AuthenticatorResponse'
                 - type: object
-                  required: [authenticatorData, clientDataJSON, signature]
+                  required:
+                    - 'authenticatorData'
+                    - 'clientDataJSON'
+                    - 'signature'
                   properties:
                     authenticatorData:
                       type: string
@@ -2391,11 +2394,11 @@ components:
     openid.spec.Metadata.OAuth2AuthorizationServer:
       type: object
       required:
-        - issuer
-        - authorization_endpoint
-        - subject_types_supported
-        - response_types_supported
-        - require_pushed_authorization_requests
+        - 'issuer'
+        - 'authorization_endpoint'
+        - 'subject_types_supported'
+        - 'response_types_supported'
+        - 'require_pushed_authorization_requests'
       properties:
         authorization_endpoint:
           description: >
@@ -2480,7 +2483,7 @@ components:
           type: array
           example: ["RS256"]
           items:
-            $ref: '#/components/schemas/jose.spec.jws'
+            $ref: '#/components/schemas/jose.spec.JWS'
         issuer:
           description:
             URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier.
@@ -2575,7 +2578,7 @@ components:
           type: array
           example: ["RS256"]
           items:
-            $ref: '#/components/schemas/jose.spec.jws'
+            $ref: '#/components/schemas/jose.spec.JWS'
         scopes_supported:
           description: >
             JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports. The server
@@ -2633,7 +2636,7 @@ components:
           type: array
           example: ["RS256"]
           items:
-            $ref: '#/components/schemas/jose.spec.jws'
+            $ref: '#/components/schemas/jose.spec.JWS'
         ui_locales_supported:
           type: array
           description: >
@@ -2642,6 +2645,12 @@ components:
           example: ["en-US"]
           items:
             type: string
+        authorization_response_iss_parameter_supported:
+          description: >
+            Boolean parameter indicating whether the authorization server provides the iss parameter in the
+            authorization response as defined in Section 2. If omitted, the default value is false.
+          type: boolean
+          example: true
     openid.spec.Metadata.OpenIDConfiguration:
       type: object
       required:
@@ -2837,7 +2846,7 @@ components:
           type: array
           example: ["RS256"]
           items:
-            $ref: '#/components/schemas/jose.spec.jws'
+            $ref: '#/components/schemas/jose.spec.JWS'
         issuer:
           description: >
             URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier.
@@ -2974,7 +2983,7 @@ components:
           type: array
           example: ["RS256"]
           items:
-            $ref: '#/components/schemas/jose.spec.jws'
+            $ref: '#/components/schemas/jose.spec.JWS'
         scopes_supported:
           description: >
             JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports.
@@ -3033,7 +3042,7 @@ components:
           type: array
           example: ["RS256"]
           items:
-            $ref: '#/components/schemas/jose.spec.jws'
+            $ref: '#/components/schemas/jose.spec.JWS'
         ui_locales_supported:
           description: >
             Languages and scripts supported for the user interface, represented as a JSON array of BCP47
@@ -3078,6 +3087,20 @@ components:
           example: ["none", "RS256"]
           items:
             $ref: '#/components/schemas/jose.spec.JWS.None'
+        authorization_signing_alg_values_supported:
+          description: >
+            OPTIONAL. A JSON array containing a list of the JWS [RFC7515] signing algorithms (alg values) supported by
+            the authorization endpoint to sign the response.
+          type: array
+          example: ["RS256"]
+          items:
+            $ref: '#/components/schemas/jose.spec.JWS'
+        authorization_response_iss_parameter_supported:
+          description: >
+            Boolean parameter indicating whether the authorization server provides the iss parameter in the
+            authorization response as defined in Section 2. If omitted, the default value is false.
+          type: boolean
+          example: true
     openid.spec.IntrospectionResponse:
       type: object
       required:
@@ -3687,9 +3710,13 @@ components:
         Endpoint. This use of this parameter is NOT RECOMMENDED when the Response Mode that would be requested is
         the default mode specified for the Response Type.
       enum:
+        - 'form_post'
         - 'query'
         - 'fragment'
-        - 'form_post'
+        - 'jwt'
+        - 'form_post.jwt'
+        - 'query.jwt'
+        -  'fragment.jwt'
       example: 'query'
       type: string
     openid.spec.GrantType:
@@ -3727,9 +3754,9 @@ components:
       description: The JSON Web Signature Algorithm
       oneOf:
         - $ref: '#/components/schemas/jose.spec.None'
-        - $ref: '#/components/schemas/jose.spec.jws'
+        - $ref: '#/components/schemas/jose.spec.JWS'
       type: string
-    jose.spec.jws:
+    jose.spec.JWS:
       description: The JSON Web Signature Algorithm
       enum:
         - 'HS256'

diff --git a/config.template.yml b/config.template.yml
@@ -1415,24 +1415,37 @@ notifier:
         ## available if configured.
         # request_object_signing_alg: 'RS256'
 
-        ## The signing algorithm used for ID Tokens. An issuer JWK with a matching algorithm must be available.
-        ## Has no effect if id_token_signing_key_id is configured.
-        # id_token_signing_alg: 'RS256'
+        ## The signing algorithm used for signing the authorization response. An issuer JWK with a matching algorithm
+        ## must be available when configured. Configuring this value enables the  JWT Secured Authorization Response
+        ## Mode (JARM) for this client. JARM is not understood by a majority of clients so you should only configure
+        ## this when you know it's supported.
+        ## Has no effect if authorization_signed_response_key_id is configured.
+        # authorization_signed_response_alg: 'none'
+
+        ## The signing key id used for signing the authorization response. An issuer JWK with a matching key id must be
+        ## available when configured. Configuring this value enables the JWT Secured Authorization Response Mode (JARM)
+        ## for this client. JARM is not understood by a majority of clients so you should only configure this when you
+        ## know it's supported.
+        # authorization_signed_response_key_id: ''
+
+        ## The signing algorithm used for ID Tokens. An issuer JWK with a matching algorithm must be available when
+        ## configured. Has no effect if id_token_signed_response_key_id is configured.
+        # id_token_signed_response_alg: 'RS256'
 
         ## The signing key id used for ID Tokens. An issuer JWK with a matching key id must be available when
         ## configured.
-        # id_token_signing_key_id: ''
+        # id_token_signed_response_key_id: ''
 
         ## The signing algorithm used for User Info responses. An issuer JWK with a matching algorithm must be
         ## available. Has no effect if userinfo_signing_key_id is configured.
-        # userinfo_signing_alg: 'none'
+        # userinfo_signed_response_alg: 'none'
 
         ## The signing key id used for User Info responses. An issuer JWK with a matching key id must be available when
         ## configured.
-        # userinfo_signing_key_id: ''
+        # userinfo_signed_response_key_id: ''
 
         ## The signing algorithm used for Introspection responses. An issuer JWK with a matching algorithm must be
-        ## available. Has no effect if introspection_signed_response_key_id is configured.
+        ## available when configured. Has no effect if introspection_signed_response_key_id is configured.
         # introspection_signed_response_alg: 'none'
 
         ## The signing key id used for Introspection responses. An issuer JWK with a matching key id must be available

diff --git a/docs/content/en/configuration/identity-providers/openid-connect/clients.md b/docs/content/en/configuration/identity-providers/openid-connect/clients.md
@@ -57,10 +57,12 @@ identity_providers:
         enforce_par: false
         enforce_pkce: false
         pkce_challenge_method: 'S256'
-        id_token_signing_alg: 'RS256'
-        id_token_signing_key_id: ''
-        userinfo_signing_alg: 'none'
-        userinfo_signing_key_id: ''
+        authorization_signed_response_alg: 'RS256'
+        authorization_signed_response_key_id: ''
+        id_token_signed_response_alg: 'RS256'
+        id_token_signed_response_key_id: ''
+        userinfo_signed_response_alg: 'none'
+        userinfo_signed_response_key_id: ''
         request_object_signing_alg: 'RS256'
         token_endpoint_auth_signing_alg: 'RS256'
         token_endpoint_auth_method: ''
@@ -286,11 +288,40 @@ effectively enables the [enforce_pkce](#enforcepkce) option for this client.
 Valid values are an empty string, `plain`, or `S256`. It should be noted that `S256` is strongly recommended if the
 relying party supports it.
 
-### id_token_signing_alg
+### authorization_signed_response_alg
 
 {{< confkey type="string" default="RS256" required="no" >}}
 
-_**Note:** This value is completely ignored if the [id_token_signing_key_id](#idtokensigningkeyid) is defined._
+_**Note:** This value is completely ignored if the [authorization_signed_response_key_id](#authorizationsignedresponsekeyid) is
+defined._
+
+The algorithm used to sign the authorization responses.
+
+See the response object section of the
+[integration guide](../../../integration/openid-connect/introduction.md#response-object) for more information including
+the algorithm column for supported values. This value can not be set to `none`.
+
+The algorithm chosen must have a key configured in the [issuer_private_keys](provider.md#issuerprivatekeys) section to
+be considered valid.
+
+See the response object section of the [integration guide](../../../integration/openid-connect/introduction.md#response-object)
+for more information including the algorithm column for supported values.
+
+### authorization_signed_response_key_id
+
+{{< confkey type="string" required="no" >}}
+
+_**Note:** This value automatically configures the [authorization_signed_response_alg](#authorizationsignedresponsealg) value with the algorithm
+of the specified key._
+
+The key id of the JWK used to sign the ID Tokens in the token responses. The value of this must one of those provided or
+calculated in the [issuer_private_keys](provider.md#issuerprivatekeys).
+
+### id_token_signed_response_alg
+
+{{< confkey type="string" default="RS256" required="no" >}}
+
+_**Note:** This value is completely ignored if the [id_token_signed_response_key_id](#idtokensignedresponsekeyid) is defined._
 
 The algorithm used to sign the ID Tokens in the token responses.
 
@@ -304,21 +335,21 @@ be considered valid.
 See the response object section of the [integration guide](../../../integration/openid-connect/introduction.md#response-object)
 for more information including the algorithm column for supported values.
 
-### id_token_signing_key_id
+### id_token_signed_response_key_id
 
 {{< confkey type="string" required="no" >}}
 
-_**Note:** This value automatically configures the [id_token_signing_alg](#idtokensigningalg) value with the algorithm
+_**Note:** This value automatically configures the [id_token_signed_response_alg](#idtokensignedresponsealg) value with the algorithm
 of the specified key._
 
 The key id of the JWK used to sign the ID Tokens in the token responses. The value of this must one of those provided or
 calculated in the [issuer_private_keys](provider.md#issuerprivatekeys).
 
-### userinfo_signing_alg
+### userinfo_signed_response_alg
 
 {{< confkey type="string" default="none" required="no" >}}
 
-_**Note:** This value is completely ignored if the [userinfo_signing_key_id](#userinfosigningkeyid) is defined._
+_**Note:** This value is completely ignored if the [userinfo_signed_response_key_id](#userinfosignedresponsealg) is defined._
 
 The algorithm used to sign the userinfo endpoint responses.
 
@@ -329,12 +360,12 @@ support `none` as a value for this endpoint.
 The algorithm chosen must have a key configured in the [issuer_private_keys](provider.md#issuerprivatekeys) section to
 be considered valid.
 
-### userinfo_signing_key_id
+### userinfo_signed_response_key_id
 
 {{< confkey type="string" required="no" >}}
 
-_**Note:** This value automatically configures the [userinfo_signing_alg](#userinfosigningalg) value with the algorithm
-of the specified key._
+_**Note:** This value automatically configures the [userinfo_signed_response_alg](#userinfosignedresponsealg) value
+with the algorithm of the specified key._
 
 The key id of the JWK used to sign the userinfo endpoint responses in the token responses. The value of this must one of
 those provided or calculated in the

diff --git a/docs/content/en/configuration/identity-providers/openid-connect/provider.md b/docs/content/en/configuration/identity-providers/openid-connect/provider.md
@@ -149,7 +149,7 @@ The list of JWKS instead of or in addition to the [issuer_private_key](#issuerpr
 
 The default key for each algorithm is is decided based on the order of this list. The first key for each algorithm is
 considered the default if a client is not configured to use a specific key id. For example if a client has
-[id_token_signing_alg](clients.md#idtokensigningalg) `ES256` and [id_token_signing_key_id](clients.md#idtokensigningkid) is
+[id_token_signed_response_alg](clients.md#idtokensignedresponsealg) `ES256` and [id_token_signed_response_key_id](clients.md#idtokensignedresponsekeyid) is
 not specified then the first `ES256` key in this list is used.
 
 #### key_id

diff --git a/docs/content/en/integration/openid-connect/apache-guacamole/index.md b/docs/content/en/integration/openid-connect/apache-guacamole/index.md
@@ -78,7 +78,7 @@ identity_providers:
         - 'id_token'
       grant_types:
         - 'implicit'
-      userinfo_signing_alg: 'none'
+      userinfo_signed_response_alg: 'none'
 ```
 
 ## See Also

diff --git a/docs/content/en/integration/openid-connect/argocd/index.md b/docs/content/en/integration/openid-connect/argocd/index.md
@@ -77,7 +77,7 @@ identity_providers:
         - 'groups'
         - 'email'
         - 'profile'
-      userinfo_signing_alg: 'none'
+      userinfo_signed_response_alg: 'none'
     - id: 'argocd-cli'
       description: 'Argo CD (CLI)'
       public: true
@@ -90,7 +90,7 @@ identity_providers:
         - 'email'
         - 'profile'
         - 'offline_access'
-      userinfo_signing_alg: 'none'
+      userinfo_signed_response_alg: 'none'
 ```
 
 ## See Also

diff --git a/docs/content/en/integration/openid-connect/bookstack/index.md b/docs/content/en/integration/openid-connect/bookstack/index.md
@@ -78,7 +78,7 @@ identity_providers:
         - 'openid'
         - 'profile'
         - 'email'
-      userinfo_signing_alg: 'none'
+      userinfo_signed_response_alg: 'none'
 ```
 
 ## See Also