WSO2 Identity Server: Configure using REST APIs for OIDC Conformance Testing

5 min readFeb 28, 2021

WSO2 Identity Server is an open-source identity and access management solution. It is built upon open-source principles and open standards so it enables freedom from platform and vendor lock-in situations and enables easy customization and extension capabilities. WSO2 Identity server offers a wide range of enterprise-grade capabilities such as;

Single Sign-on (SSO)
Identity federation
Adaptive authentication
Account management and identity provisioning
Access control
APIs and API security
Identity bridging
Identity analytics
Privacy compliance

OpenID Connect

OpenID Connect(OIDC) is a protocol for user authentication which allows client applications to verify the identity of the end-user when the user is trying to access a protected HTTPS endpoint.

WSO2 Identity Server conforms to the following OIDC specifications

OpenID Connect core 1.0
Basic client implementation
Implicit client implementation

But what if you want to customize WSO2 Identity server and make sure it still conforms to OIDC specification after your modifications? How do you easily check for OIDC conformance ?

The answer is simple, OpenID Foundation developed a test suite that can be used to test any OIDC providers or relying parties to see if they conform to OIDC specification.

My previous article Running OIDC Conformance Suite Locally with WSO2 Identity Server describes how to run this test suite locally with WSO2 identity server to test it. This involves a lot of manual configurations and can be a bit tedious.

But WSO2 Identity Server provides REST APIs that can be used to easily perform these configurations. To run OIDC conformance tests, following configurations are required in the Identity Server

Register Service providers
Set values for user claims
Service provider claim configuration
Advanced authentication configuration

Before using these REST endpoints we need to obtain an access token to consume the API. Authorization for APIs is enforced using permissions so each endpoint has a minimum level of permission required to consume that endpoint.

So when you obtain an access token you need to define the scope corresponding to permissions required to perform all the configurations. Following scopes are required to perform configurations for OIDC testing

internal_user_mgt_update
internal_application_mgt_create
internal_application_mgt_update
internal_application_mgt_view
internal_claim_meta_update

You can send a POST request to oauth2/token the endpoint with the above scope to obtain an access token. Following is the request format

curl -v -X POST -H “Authorization: Basic <base64encoded clientId:clientSecrect>” -k -d “grant_type=password&username=admin&password=admin&scope=YOUR_SCOPE” -H “Content-Type:application/x-www-form-urlencoded” https://localhost:9443/oauth2/token

A successful response looks like this

{“access_token”:”bf01d540-fa67–314f-9ff3–3ed5ef9fa5bd”, “Refresh_token”:”dc3906cc-34f9–376c-a6f4–1c2e6b9626c7", “Scope”:”internal_user_mgt_update”, “token_type”:”Bearer”, “expires_in”:3600}

After obtaining an access token you can use the REST APIs to perform the configurations. Let’s look at how to perform these configurations in detail

Registering Service Providers

For a single test plan in the OIDC conformance suite, we need to register two service providers in the WSO2 Identity Server. To register a service provider you need to send a POST request to application REST endpoint.

https://localhost:9443/api/server/v1/applications

And you need to provide service provider configuration details in the request body. following is a sample request

curl --location --request POST 'https://localhost:9443/api/server/v1/applications' \
--header 'Authorization: Bearer bf01d540-fa67–314f-9ff3–3ed5ef9fa5bd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "{SERVICE_PROVIDER_NAME}",
    "inboundProtocolConfiguration": {
        "oidc": {
            "state": "ACTIVE",
            "grantTypes": [
                "authorization_code"
            ],
            "publicClient": false,
            "validateRequestObjectSignature": false,
            "callbackURLs": [
                {CALLBACK_URL}
            ],
            "allowedOrigins": []
        }
    },
    "authenticationSequence": {
        "type": "DEFAULT",
        "steps": [
            {
                "id": 1,
                "options": [
                    {
                        "idp": "LOCAL",
                        "authenticator": "basic"
                    }
                ]
            }
        ],
        "subjectStepId": 1,
        "attributeStepId": 1
    },
    "advancedConfigurations": {
        "discoverableByEndUsers": false
    },
    "description": "Service provider for OIDC conformance suite",
    "templateId": "b9c5e11e-fc78-484b-9bec-015d247561b8"
}'

Add the access token you obtained to Authorization header and for callbackURLs you need to provide the callback URL provided by the OIDC conformance suite when you create a test plan. Identity server will return a 201 created success response upon successfully creating a service provider.

Set Values for User Claims

To set user claim values you can use SCIM 2.0 API in WSO2 Identity Server. You can send a PATCH request to the following endpoint.

https://localhost:9443/scim2/Me

You need to provide claim values in the request body. Following is a sample request

curl --location --request PATCH 'https://localhost:9443/scim2/Me' \
--header 'Authorization: Bearer bf01d540-fa67–314f-9ff3–3ed5ef9fa5bd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Operations": [
        {
          "op": "add",
          "value": {
            "nickName": "yasas"
          }
        }    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}'

You need to set values for the following claims

street_address, address, phone_number, phone_number_verified, website, zoneinfo, birthdate, gender, profile, preferred_username, given_name, middle_name, locale, picture, updated_at, name, nickname, family_name, email, email_verified

Identity Server will return a response with status 200 after successfully updating claim values. following information will be included in the response

{
  "meta": {
    "created": "2021-02-01T10:34:29Z",
    "location": "https://localhost:9443/scim2/Users/008bba85-451d-414b-87de-c03b5a1f4217",
    "lastModified": "2021-02-01T10:34:29Z",
    "resourceType": "User"
  },
  "schemas": [
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
     
    ]
  ],
  "nickName": "yasas"
}

Service Provider Claim Configuration

After creating service providers and adding claim values, we can move onto claim configuration for these service providers. We need to add each of the claim URIs to requested claims for each service provider. To do this we can use the applications REST endpoint we used to create service providers. Following is a sample HTTP request to add email claim to service provider with application id b9d173ea-27f8–46f4–9545–2ccf5b0227cc.

curl --location --request PATCH 'https://localhost:9443/api/server/v1/applications/b9d173ea-27f8-46f4-9545-2ccf5b0227cc' \
--header 'Authorization: Bearer bf01d540-fa67–314f-9ff3–3ed5ef9fa5bd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "claimConfiguration": {
        "dialect": "LOCAL",
        "requestedClaims": [
            {
                "claim": {
                    "uri": "http://wso2.org/claims/emailaddress"
                },
                "mandatory": false
            },
        ]
    }
}'

Upon successfully updating identity server will return a response with code 200

Advanced authentication configuration

There is a test case in OIDC conformance suite that sends acr_values parameter to authorization endpoint and checks if it’s available in the ID token. For this to work we need to configure script based adaptive authentication for registered service providers in the identity server. For the purpose of testing we will add only a single authentication step of basicauth.

To set this up we can use the same applications endpoint we used earlier. Following is a sample request to configure service provider with application id b9d173ea-27f8–46f4–9545–2ccf5b0227cc.

curl --location --request PATCH 'https://localhost:9443/api/server/v1/applications/b9d173ea-27f8-46f4-9545-2ccf5b0227cc' \
--header 'Authorization: Bearer bf01d540-fa67–314f-9ff3–3ed5ef9fa5bd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "authenticationSequence": {
        "attributeStepId": 1,
        "steps": [
            {
                "id": 1,
                "options": [
                    {
                        "authenticator": "BasicAuthenticator",
                        "idp": "LOCAL"
                    }
                ]
            }
        ],
        "subjectStepId": 1,
        "type": "USER_DEFINED",
        "script": "\"
var supportedAcrValues = ['\''acr1'\''];
\\n\\nvar onLoginRequest = function(context) {\\n 
var selectedAcr = selectAcrFrom(context,supportedAcrValues);\\n      Log.info('\''--------------- ACR selected: '\'' + selectedAcr);\\n    context.selectedAcr = selectedAcr;\\n    
switch (selectedAcr) {\\n        
case supportedAcrValues[0] :\\n            
executeStep(1);\\n            
break;\\n
default :\\n            
executeStep(1);    
}\\n};\""
}
}'

After successful completion identity server will return a response with code 200.

And you are done, that’s all the configurations you need to make !

As you can see its very easy to configure WSO2 Identity Server using REST APIs. You can easily write a script to call these REST APIs and automate the process of configuring the WSO2 identity server.