Working with Request Object in WSO2 Identity Server

Request object is a jwt token which requests for some claims from Identity provider during authorization process. Request object is a JWT (JSON Web Token) that contains a set of request parameters as its Claims.

Request Object can be of 2 types

1. request parameter (Passed by value)
2. request_uri parameter (Passed by reference)

WSO2 Identity Server supports request parameter (Passed by value)

How to Test a Request Object Passed by value Flow

Step 01

Configure Claims

• Add two new external claims(customClaim1 & customClaim2). Here we create two claims under oidc dialect and map those claims to local claims.
• Navigate to Main -> claims -> Add -> Add External Claims

Dialect URI : http://wso2.org/oidc/claim 
External Claim URI : customClaim1
Mapped Local Claim:http://wso2.org/claims/challengeQuestion1
Dialect URI : http://wso2.org/oidc/claim 
External Claim URI : customClaim2
Mapped Local Claim:http://wso2.org/claims/challengeQuestion2

Here, customClaim1 and customClaim2 are selected as claim URIs because those are not configured as requested claims in the OIDC scope. For the purpose of testing, these claims are mapped to existing http://wso2.org/claims/challengeQuestion1 and http://wso2.org/claims/challengeQuestion2 local claims.

Step 02

Configure Challenge Question1 & Challenge Question2 as supported by Default

• Navigate to Main ->Claims -> List > http://wso2.org/claims
• Select https://wso2.org/claims. Select Challenge Question1 & Challenge Question2 and configure them as supported by default.

Step 03

Create a self signed certificate for the service provider

1. Navigate to IS-Home>repository>resources>security
2. Execute the below command

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

3. After the successful execution of the above command 2 files will be generated as key.pem (private key) certificate.pem (public certificate) inside repository/resources/security. You can view these certificates using any text editors. (vim or visual studio code)

Step 04

Configuring a Service Provider

• Navigate to Main -> Service Provider -> Add and create a service provider.
• In the Basic Information section, select the Application Certificate as Upload SP certificate.
• Inside the text box, upload the public certificate you obtained for the service provider.

• Navigate to Inbound Authentication Configuration.
• Select OAuth/OpenID Connet Configuration.
• Select Configure button, add callback URL and update the SP(http://localhost:8080/playground2/oauth2client)

Step 05

Configure Claims for the registered Service Provider

• Edit the service provider that you created above, expand Claim Configuration > Use local Claim Dialect.

Step 06

Creating a User and Updating user profile with claim values

• Navigate to Main -> Users and Roles and Add new user
• Create a new user as Alex.
• Then update his profile.
• Now in his user profile, you will be asked to enter email address, challenge question1, challenge question2, and country.

Step 07

Create a JWT Object to pass by value

{
 “client_id”: “<client-id>”,
 “sub”: “<client-id>”,
 “aud”: [
 “https://localhost:9443/oauth2/token"
 ],
 “claims”: {
 “userinfo”: {
 “given_name”: {
 “essential”: true
 },
 “nickname”: null,
 “email”: {
 “essential”: true
 },
 “customClaim2”: {
 “essential”: true
 }
 },
 “id_token”: {
 “gender”: null,
 “birthdate”: {
 “essential”: true
 },
 “customClaim1”: {
 “essential”: true
 }
 }
 },
 “iss”: “<client-id>”,
 “exp”: 1633415557,
 “iat”: 1633411957,
 “jti”: “1003”
}

Note

When you are copying the payload from the medium to jwt.io “ “ will be copied as a different element. Therefore make sure that you will replace all the “ “ in the payload from your keyboard. Other wise you will get a error from the jwt.io when you try to generate the JWT saying Invalid Signature as follows.

Also in the jwt.io check the “ “ whether its replaced correctly with keyboard value. If you copy the payload to a text doc and replace the “ “. Still “ “ this might get changed when you copy for jwt.io. So check in the jwt .io whether its replaced correctly.

Once you replace “” correctly in jwt.io encoded request object will get generated in jwt.io. You can copy that value as the request object and proceed. Still sometimes you may notice the Invalid Signature Error in the jwt.io. But if you get the encoded value generated successfully you can get that value and proceed with the flow.

• Modify client_id and update it with your service providers client id.
• Open https://jwt.io and select the algorithm as RS256
• Paste the payload into payload section.
• In the VERIFY SIGNATURE section , delete every thing inside those text boxes and paste the public certificate and private key of the Service provider.

Now generate the jwt which will be a encoded value.

Step 08

Configure Playground App in Tomcat

• Do a authorize request using a browser and obtain a authorization code, response_type=code.

Get the latest palyground.war and deploy it in tomcat and Run the tomcat server

or else you can send a browser request as follows

https://localhost:9443/oauth2/authorize?scope=openid&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fplayground2%2Foauth2client&client_id=e_govr0VxJqqiNLAY4LQijXbkOQa &request=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJjbGllbnRfaWQiOiJlX2dvdnIwVnhKcXFpTkxBWTRMUWlqWGJrT1FhICIsInN1YiI6ImVfZ292cjBWeEpxcWlOTEFZNExRaWpYYmtPUWEgIiwiYXVkIjpbImh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIl0sImNsYWltcyI6eyJ1c2VyaW5mbyI6eyJnaXZlbl9uYW1lIjp7ImVzc2VudGlhbCI6dHJ1ZX0sIm5pY2tuYW1lIjpudWxsLCJlbWFpbCI6eyJlc3NlbnRpYWwiOnRydWV9LCJjdXN0b21jbGFpbTIiOnsiZXNzZW50aWFsIjp0cnVlfX0sImlkX3Rva2VuIjp7ImdlbmRlciI6bnVsbCwiYmlydGhkYXRlIjp7ImVzc2VudGlhbCI6dHJ1ZX0sImN1c3RvbWNsYWltMSI6eyJlc3NlbnRpYWwiOnRydWV9fX0sImlzcyI6ImVfZ292cjBWeEpxcWlOTEFZNExRaWpYYmtPUWEgIiwiZXhwIjoxNTUzNDIyNTM3LCJpYXQiOjE1MTY3ODMyNzgsImp0aSI6IjEwMDMifQ.YputORL4oMi6Va8moERGUXL4VedC1ttr8RHZLeKR6eea61T2sqlnziPF6zBJQON9o6j6t1nDNYzrxkNbzbv6oGbz3KT8opbwuQBcMwTIzBv92uaR97c6Gdzwkd9odRsqadHfPV_RrN5dLNR8NMoQiJ-nMfQ_eZtfWqJva8IPO0j93wSce6-JFpe9cQA_k2izZ-BBMN7Ju52QfobvR_npqb-UjWj3r3yKOtnZXJvsn2xNAWiZ5LpsT19aWXmB8iHnEOELYKbAXSJUZGJY-tNMdhw2JzTPtnkxVuFoCjnqZCDArgv11a4_eOVv6FBL0qjD5V3imS_TjN8sWRv6_hvAYA

Step 09

Talk to token EP and request for access token and id token

• Using the code we obtained, we can get a access token and id token.

curl -k -v — user <client_id>:<client_secret> -d “grant_type=authorization_code&code=<code>&redirect_uri=http://localhost:8080/playground2/oauth2client&scope= “ https://localhost:9443/oauth2/token

• We can use the playground app as well to obtain the access token in place of curl command

Copy the id_token obtained and use jwt.to and paste it in the encoded section and check the decoded payload. You should be able to see that customClaim1 value which we marked as essential:true under id_token in step 7 payload has been retrieved with the id_token.

• As we have requested customclaim1 in the id_token, it will be sent in the id_token.

Step 10

Talk to the userinfo EP

• Using curl command below, obtain user information from user info endpoint. You can use the playground app and talk to user info EP as well in place of using curl command

Request
curl -k -H "Authorization: Bearer <access_token>" https://localhost:9443/oauth2/userinfo
Response
{“country”:”Sri Lanka”, “sub”:”alex”, “email”:”alex@gmail.com”, “customclaim2”:”What is your father’s name?”}

customclaim2 claim can be obtained from the userInfo endpoint as we have requested it during step 07 in the payload under user info section.

Troubleshooting Request Object Expired Error.

In any case if you get a error as follows

This could be due to expiry time mismatch when you create the payload.

During such a occasion you can use Authorization Grant type using playground app and obtain the ID Token. Then get the values received for parameters exp and iat and replace the payload in step 7 exp and iat values with new ID Tokens expiry values and generate the jwt using jwt.io.

How To Test Enable Request Object Signature Validation

There is a config in the registered service provider as Enable Request Object Signature Validation.

Tick the check box as below to enable it

Once this is enabled you can upload a incorrect public certificate for the service provider upload certificate section and try out a request object flow. During this flow you wont be able to complete the flow as you have enabled signature validation and therefore IS will check for this validation and as we have uploaded a wrong certificate for SP signature validation will fail. This way we can check whether enabling this config works as expected.

If you are working with Request Object Feature on IS version 5.12.0 or above

When we use openid as the scope, it won't return any claims in the id token which we marked as essential:true under id_token in the request object payload.
To return the claims in the id token, we need to add those claims in a separate custom oidc scope and give that custom scope in the scope parameter in the API call. Please Refer https://github.com/wso2/product-is/issues/13301