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 request or request_uri to send a request object in an authorization request to the Identify OAuth 2.0/OIDC authorization server.

Discovery endpoint

You can check the discovery endpoint of your Identify instance to verify support for request object features:

"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 used by your OIDC client.

UI to register 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 using either the request or request_uri parameter. The request object content can be signed (for example, with RS256) or unsigned.

Example request where some parameters are in the request object and others are in URL parameters:

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 and also sends the same parameters in URL parameters, values in the request object take precedence:

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 is:

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

Request object validation notes

When a user signs in to an OIDC client, Identify shows an error page (instead of redirecting the user back to the client) if one of the following validations fails:

  • Invalid request object: request and request_uri cannot be used in the same authorization request.
  • The Request URI must use an HTTPS scheme.
  • The Request URI cannot be found in pre-registered request_uris.
  • Invalid client ID: client_id in the request object must be the same as the one in the OAuth request.
  • Invalid response type: response_type in the request object must be the same as the one in the OAuth request.
  • The request and request_uri parameters MUST NOT be included in request objects.
  • 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: Specifies the allowed redirect URI scheme(s). This can be a single scheme (for example, https) or multiple comma-separated schemes (for example, https,myapp) for native OIDC clients that use custom URI schemes. Native clients can use custom URI schemes in addition to standard http and https.
  • codeChallengeMethod: Forces a specific code challenge method.

During parsing, authorization request parameters in the request object are validated against AdditionalValidationRules. If any validation fails, the OAuth server returns an invalid_request_object error code along with an error message describing the specific failure.