This documentation is for WSO2 Identity Server 5.5.0 . View documentation for the latest release.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Purpose of Request Object in OpenID Connect

This enables sending authentication request parameters in a self-contained JWT instead of plain request parameters. Request Object can be specified to the authorization server either by value or by reference.

...

The Identity Server will respond to the above sample request as follows:
  1. Here the requested scope is considered as 'openid email' as the scope value of the request object is declared. So the server will ignore the scope value which is associated with the authorization request and considers the requested scope as 'openid email'
  2. It considers the claims "given_name" and "email" which are marked as 'essential:true' for 'userinfo' member. Even if they are not mapped with the openid or address scope in the registry, if these claims are requested claims, then 'given_name' and 'email' will be returned from the Userinfo endpoint. In a nutshell, the claims which are marked as 'essential: true' only get controlled by the requested claims and ignore the requested scopes. If the server cannot provide those essential claims, there will not be any failure or error message returning from the server.
  3. The claims like "nickname" it will act as a default claim and will be controlled by both requested scopes and the requested claims.
  4. If the server cannot provide the requested essential claims, the server will return null for the specific claim and the flow will not break.
Note

This behavior is common to the id token as well

You can try out the sample listed in Passing OIDC Authentication Request Parameters in a Request Object page to see how request objects work in IS. 

Signature Validation
Request Object may be signed or unsigned (plaintext). When it is plaintext, this is indicated by use of the non-algorithm [JWA]. If the Request Object is signed, the server will extract the certificate by the client_id. When registering the Auth application in the Identity Server, we need to provide the corresponding public certificate of the Request Object signing party. As of now, the Identity Server only supports RSA signature algorithms only. If the header does not contain valid signature algorithm, the server will reject the signature validation. Based on the certificate value, it will generate the public key and validate the signature using the nimbus library. 
Decryption
The request parameter value can be even a JWE. If it is a JWE, it will consist of five parts which are separated by four '.'  characters which are JOSE header, JWE encrypted key, Initialization vector, Ciphertext, and Authentication tag. The values of these five sections can be seen by doing a base64 encoding. JOSE header consists of 'alg' and 'enc' values. An algorithm defined in 'enc' is used to do the content encryption while the algorithm defined in the 'alg' is used to do the key wrapping. Here, the nimbus library is used for the decryption by providing the Identity Server's private key. 

If the Request Object is a nested JWT, which is signed and encrypted, then the payload (Cipher Text) of the Request Object is a signed JWT. So the server will decrypt the JWE first and then check the payload for signature validation.

Extension Points
All the validations and the request object builder are extensible so that a third party user can build the request object and do any validations in their own way. At the moment, Identity Server does not have a default implementation for request_uri parameter and instead, it extracts the request_uri parameter from the request object and pass it.
So externally, a user can implement a CustomRequestObjectBuilder (by implementing org.wso2.carbon.identity.openidconnect.RequestObjectBuilder) to obtain the Request Object from request_uri parameter and do the necessary customizations.

The following configuration changes should be done in $IS_HOME/repository/conf/identity/identity.xml when writing extension points for this feature.


Code Block
 <OpenIDConnect>
  <RequestObjectBuilders>
     <RequestObjectBuilder>
        <Type>request_param_value_builder</Type>
  		<ClassName>org.wso2.carbon.identity.openidconnect.RequestParamRequestObjectBuilder</ClassName>
     </RequestObjectBuilder>
  </RequestObjectBuilders>
  <RequestObjectValidator>org.wso2.carbon.identity.openidconnect.RequestObjectValidatorImpl</RequestObjectValidator>
  </OpenIDConnect>

If the configuration is not present, the default classes will be executed. 


Note

Please note that Identity Server 5.5.0 does not have a default implementation for request_uri parameter.

If you implement a CustomRequestObjectBuilder to obtain Request Object from request_uri, you need to register it as a new RequestObjectBuilder, in $IS_HOME/repository/conf/identity/identity.xml.

Code Block
 <OpenIDConnect>
  <RequestObjectBuilders>
   ....
  <RequestObjectBuilder>
     <Type>request_uri_param_value_builder</Type>
     <ClassName>xxx.CustomRequestObjectBuilder</ClassName>
  </RequestObjectBuilder>
  ...
  </OpenIDConnect>