Passing Request parameters as JWTs

The request Authorization Request parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be optionally signed and/or encrypted. It represents the request as a JWT whose Claims are the request parameters specified in Section 3.1.2. This JWT is called a Request Object. You can use either the request or the request_uri send a request object in an authorization request to Identify OAuth 2.0/OIDC authorization server.

Discovery endpoint

You can check the discovery endpoint of your Identify instance to see if it has support for the Request parameter feature:

"request_parameter_supported": true,
"request_uri_parameter_supported": true,
"require_request_uri_registration": false,
"request_object_signing_alg_values_supported": ["RS256"]

Dynamic registration endpoint

The dynamic registration endpoint supports the request_uris parameter. You can use it to pre-register request_uri values which your OIDC application uses.

UI to register the list of request_uris

In addition to the dynamic registration endpoint, you can register or update the request_uris through the Safewhere Admin interface.

setting

Request object

You can pass a request object either by the "request" or the "request_uri" parameter. The request object content can be signed (with the RS256) or not.

An example of a request parameter which has some parameters put in the request object and some others in the request url paremeters:

https://identify.safewhere.com/runtime/oauth2/authorize.idp?redirect_uri=http%3a%2f%2flocalhost%3a62640%2fHome%2fCodeFlowCallback&max_age=100&request=eyJhbGciOiJSU...n9azVytmYf6Q

The request object is:

{
  "response_type": "code",
  "client_id": "clientId_5BC0M3L3FVN7JB8",
  "scope": "openid",
  "redirect_uri": "https://op.certification.openid.net:61586/authz_cb",
  "state": "jD6jn3ANqZCDtN0x",
  "nonce": "99A7Y5mjZmJRX0uA",
  "whr": "urn:https://test.safewhere.local/adfs/services/trust",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256"
}

The code_challenge and code_challenge_method parameters enhance security by enabling the Proof Key for Code Exchange (PKCE) mechanism, which helps to mitigate authorization code interception attacks.

When an authorization request uses a valid request object but also put all the same parameters in the request url paremeters, the parameters in the request object takes precedence over the ones in url parameters:

https://identify.safewhere.com/runtime/oauth2/authorize.idp?client_id=webmvc_codeflow_id&scope=openid&redirect_uri=http%3a%2f%2flocalhost%3a62640%2fHome%2fCodeFlowCallback&response_type=code&max_age=100&nonce=cab83c5f5baf4a82a420ad6c7eed2283&request=eyJhbGciOiJSUzI1NiIs...9n9azVytmYf6Q

The full list of those parameters are:

  • scope
  • max_age
  • response_mode
  • state
  • prompt
  • id_token_hint
  • nonce
  • redirect_uri
  • whr
  • code_challenge
  • code_challenge_method

Request object validation notes

When the user does a login to an OIDC application, Identify will stop at an error page (instead of redirecting the user to the application) if one of the following validation fails:

  • Invalid request object: [request] and [request_uri] can not be used in the same authorization request.
  • The Request URI must be an HTTPS schema URI.
  • The Request uri cannot be found in the pre-register request_uris.
  • Client id is not valid; client_id in request object must be the SAME as the one in OAuth request syntax.
  • Response type is not valid; response_type in request object must be the SAME as the one in OAuth request syntax.
  • The request and request_uri parameters MUST NOT be included in Request Objects.
  • It is unable to load jwt from request_uri.
  • Request Object Jwt cannot be read.
  • Missing 'alg' header value in the JWT.
  • The code_challenge_method parameter value must be either plain or S256. If the code_challenge_method parameter is included in a request object, the code_challenge parameter must also be included, and vice versa.

If the JWT is signed, the following errors with corresponding error messages may occur:

  • Invalid setting: The jwks_uri and jwks parameters MUST NOT be used together.
  • It is unable to load jwks from "ClientJwksUri".
  • Invalid setting: Client jwks is not configured yet, please check the appropriate settings again.
  • Invalid setting: Signing credential which is used for signing the Request Object could not be found on client's jwks, please check the appropriate settings again.
  • The Request Object is not in JWS Compact serialized format.
  • The request object is invalid due to the following error: [Signing token validation failed message].

Validate the Request object against AdditionalValidationRules

AdditionalValidationRules is an additional setting for the OIDC connection that lets you customize validation rules. This includes defining required parameters, excluding prohibited parameters, setting required response claims, code challenge method, and specifying the redirect URI scheme.

The value for AdditionalValidationRules is provided in JSON format:

 {
    "authorize": {
       "requiredParameters" : "state, code_challenge, code_challenge_method, nonce",
       "prohibitedParameters" : "display, response_mode,id_token_hint",
       "redirectUriScheme": "https",
       "codeChallengeMethod": "S256"
    },
    ...
  }
  • requiredParameters: defines a comma-separated list of required parameters for an authorization request.
  • prohibitedParameters: defines a list of prohibited parameters for an authorization request.
  • redirectUriScheme: forces the redirect URI scheme into a specific one.
  • codeChallengeMethod: forces the code challenge method into a specific one.

During parsing, the Authorize request's parameters in the Request object are validated against the AdditionalValidationRules. If any validation fails, the OAuth server returns an invalid_request_object error code along with a corresponding error message based on the specific failure.