Invoking APIs in Asgardeo

Asgardeo is the new IDaaS platform by WSO2.
If you are interested to try out Asgardeo, you can register to Asgardeo for free from here.

APIs should be always secured. Also, there are some standard ways to invoke these protected APIs.
In this article, I will show how to invoke endpoints of SCIM, DCR, Session Management APIs in Asgardeo.

There are two ways to invoke APIs in Asgardeo.

1. With an access token retrieved via Client Credential grant.
2. With an access token retrieved via Authorization Code grant.

Invoke APIs with an access token retrieved using Client Credential grant

We can invoke the below Asgardeo endpoints with an access_token retrieved using the client_credential grant type via https://api.asgardeo.io/t/<org_name>/oauth2/token endpoint.

• SCIM /Users => REST API to manage Users
• SCIM /Groups => REST API to manage Groups ( Group is a set of users who have the same permissions/privileges to access resources in an organization)
• DCR => This REST API implements the OAuth 2.0 Dynamic Client Registration Protocol and the OAuth 2.0 Dynamic Client Registration Management Protocol according to the OAuth 2.0 specification.

You will be able to retrieve an access_token by following the below steps.

1. Create a Standard-Based application with OpenID Connect protocol

• Go to the Asgardeo console and click on New Application.

• Create a new Standard-Based Application.

• Enter a name and select OAuth2.0/OpenID Connect as the protocol.
• Click Register.

• You will be redirected to the Application page.

• You can find the Client ID and Client Secret values from the Protocol tab. These values are required to retrieve an access token.
• As we are trying to retrieve tokens using the client_credential grant type, we need to enable the Client Credential grant as an allowed grant type. (This grant is enabled by default).
  If you have already disabled it, you need to enable it and update the configuration by clicking the Update button at the bottom of the page.

2. Retrieve the Access Token

You can use the below curl command to retrieve the access token.
Here, use the clientID, clientSecret values of our new standard-based application as the client_id, client_secret.
Update <organization> value in the request with your organization name.

curl --request POST 'https://api.asgardeo.io/t/<organization>/oauth2/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'grant_type=client_credentials' \ 
--data-urlencode 'client_id=<client_id>' \ 
--data-urlencode 'client_secret=<client_secret>' \ 
--data-urlencode 'scope=<seperate scopes_with_a_space>'

You can also find a sample token request from this postman collection. You can test this after replacing the clientID, clientSecret, scope values in the token request with the correct values.

How we can find the Scopes for a particular API?

If you are looking for the scopes required for a specific Asgardeo API, the best place to find that is the Asgardeo Documentation.

Note: If you couldn’t find the scope for any specific API from the Asgardeo documentation, you can get help from the Asgardeo community by posting your question on the IAM4DEVS Community Platform.

API Samples

• SCIM2 /Users Endpoints

Scopes :

GET /Users=> internal_user_mgt_list
POST /Users => internal_user_mgt_create
GET /Users/{id} => internal_user_mgt_view
PUT /Users/{id} => internal_user_mgt_update
DELETE /Users/{id} => internal_user_mgt_delete
PATCH /Users/{id} => internal_user_mgt_update

PATCH -> Supported Operations :

* add
* replace
* remove

Token Request :

curl --request POST 'https://api.asgardeo.io/t/<org_name>/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'scope=internal_user_mgt_list internal_user_mgt_create internal_user_mgt_update internal_user_mgt_delete internal_user_mgt_view'

Ex:

• GET /Users

curl --request GET 'https://api.asgardeo.io/t/<org_name>/scim2/Users' \
--header 'Authorization: Bearer <access_token>'

SCIM /Users Postman Collection : https://www.getpostman.com/collections/c78a9d18b3fc8eee7180

• DCR(Dynamic Client Registration) API

Scopes :

GET api/identity/oauth2/dcr/v1.1/register/<client_Id> : internal_application_mgt_view
GET api/identity/oauth2/dcr/v1.1/register?client_name : internal_application_mgt_view
PUT api/identity/oauth2/dcr/v1.1/register/<client_Id> : internal_application_mgt_update
POST api/identity/oauth2/dcr/v1.1/register : internal_application_mgt_create
DELETE api/identity/oauth2/dcr/v1.1/register/<client_Id> : internal_application_mgt_delete

Token Request :

curl --request POST 'https://api.asgardeo.io/t/<org_name>/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'scope=internal_application_mgt_create internal_application_mgt_delete internal_application_mgt_update internal_application_mgt_view'

Ex :

• GET /api/identity/oauth2/dcr/v1.1/register/{client_id}

curl --request GET 'https://api.asgardeo.io/t/<org_name>/api/identity/oauth2/dcr/v1.1/register/<application_client_id>' \
--header 'Authorization: Bearer <access_token>'

DCR API Postman Collection : https://www.getpostman.com/collections/51ceba8c2e2c429f257b

• SCIM2 /Groups Endpoints

Scopes :

GET /Groups => internal_group_mgt_view
POST /Groups => internal_group_mgt_create
GET /Groups/{id} => internal_group_mgt_view
PUT /Groups/{id} => internal_group_mgt_update
PATCH /Groups/{id} => internal_group_mgt_update
DELETE /Groups/{id} => internal_group_mgt_delete
POST /Groups/.search => internal_group_mgt_view

Token Request :

curl --request POST 'https://api.asgardeo.io/t/<org_name>/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: paf=1646191758.549.83.404117|71acb898e1e9604d7bd8c41e308eb24e' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'scope=internal_group_mgt_view internal_group_mgt_create internal_group_mgt_update internal_group_mgt_delete'

Ex :

• GET /scim2/Groups

curl --request GET 'https://api.asgardeo.io/t/<org_name>/scim2/Groups' \
--header 'Authorization: Bearer <access_token>'

SCIM2 /Groups Postman Collection: https://www.getpostman.com/collections/a445da8b9b9c53463568

Invoke APIs with an access token retrieved using Authorization code grant

The below endpoints can be invoked with an access token retrieved using an Authorization Code grant.

• SCIM /Me => RESTful API to manage Authenticated user's information
• Session Management API=> RESTful API for managing user sessions

You can retrieve the access token using the Authorization code grant by following the below steps.

1. Create a Standard-Based application with OpenID Connect protocol

• Go to the Asgardeo console and click on New Application.

• Create a new Standard-Based Application.

• Enter a name and select OAuth2.0/OpenID Connect as the protocol.
• Click Register.

• You will be redirected to the Application page.

• You can find the Client ID and Client Secret values from the Protocol tab. These values are required to retrieve an access token.
• As we are trying to retrieve tokens using the Authorization Code grant type, we need to enable the Code grant as an allowed grant type.
• As a part of the Authorization code grant flow, we need to set up the Authorized redirect URLs in our application.

• Here I have set http://localhost/callback as the redirect URL. Please note that we also need to specify http://localhost as an allowed origin.
• Click the Update button at the bottom of the page to save the changed configurations.

2. Retrieve an Access Token - Authorization Code Grant

With the Authorization code grant, we can retrieve access tokens by following below two steps.

1. Authorize request to start the authentication flow.

You can test this by replacing the values of the below-mentioned fields of the sample request with correct values.

<org_name> : Asgardeo organization name
<client_id> : Client ID of the application we created in step 1
<scopes> : scopes that required to invoke the APIs
<redirect_url> : configured Redirect URL in the step 1

Sample Authorize Request :

https://api.asgardeo.io/t/<org_name>/oauth2/authorize?response_type=code&client_id=<client_id>&scope=<scopes seperated by space>&redirect_uri=<redirect_url>

• You can use your browser tab to access that request. Please note that the redirect URL for this should not be related to running the application as we don’t need to continue the Authorization code flow after receiving the Authorization code( you will be able to get the code from the address bar of the same browser tab after the login flow is successful).
• Please note that we need to authenticate with customer accounts. You can find more information about customer accounts from the Asgardeo documentation.

Manage customers

Sample Response :

<redirect_url>/?code=08ff3c91-b32d-3886-b491-360bd8b04676&session_state=8ba6bb6225450281813ab98a120eb523c0f8d94013429790042a5ae78d3e0090.xLJXG0MzSGt20MRzaut6CA

How we can find the Scopes for a particular API?

If you are looking for the scopes required for a specific Asgardeo API, the best place to find that is the Asgardeo Documentation.

Note: If you couldn’t find the scope for any specific API from the Asgardeo documentation, you can get help from the Asgardeo community by posting your question on the IAM4DEVS Community Platform.

2. Request the access token with the authorization code received.

You can get the access token by replacing the values of the below-mentioned fields of the sample request with the correct values.

<org_name> : Asgardeo organization name
<client_id> : Client ID of the application we created in step 1
<code> : Authorization code
<redirect_url> : configured Redirect URL in the step 1
<client_secret> : Client Secret of the application

Token Request Format :

curl --location --request POST 'https://api.asgardeo.io/t/<org_name>/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'redirect_uri=<redirect_url>' \
--data-urlencode 'code=<recieved_code_after_login>' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_secret=<client_secret>'

Token endpoint response :

{
    "access_token": "626350f1-xxxx-xxxx-xxxx-0beda0360382",
    "scope": "scopes with ",
    "id_token": "<id_token>",
    "token_type": "Bearer",
    "expires_in": 3600
}

• Also, You can retrieve the access token using the below sample application. Please follow the setup guide mentioned in the Readme.md file.

GitHub - DimuthuKasunWP/React-Auth-Code-Grant-Flow-Sample: This application is to demonstrate the…

If you are testing with Postman you can use this collection and this contains the sample request with OAuth2.0 as the Authorization type.

Postman Collection: https://www.getpostman.com/collections/3c2da6b86154a20ab9a7

API Samples

• SCIM2 /Me Endpoints

Scopes :

GET /Me=> internal_login
POST /Me => internal_user_mgt_create
PUT /Me => internal_login
DELETE /Me => internal_user_mgt_delete
PATCH /Me => internal_login

Token Request :

curl --request POST 'https://api.asgardeo.io/t/<org_name>/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'scope=internal_login internal_user_mgt_create internal_user_mgt_delete'

Ex:

• GET /Me

curl --location --request GET 'https://api.asgardeo.io/t/<org_name>/scim2/Me' \
--header 'Authorization: Bearer <access_token>'

SCIM2 /Me Postman Collection: https://www.getpostman.com/collections/6e7699f450233da54e9f

If you are interested in invoking scim2/Me endpoints in React application, you can refer to my previous article below.

Manage Authenticated User’s Profile Via REST API Using Asgardeo React SDK

• Session Management /me/sessions Endpoints

Scopes :

GET /api/users/v1/me/sessions => internal_login
DELETE /api/users/v1/me/sessions => internal_login
DELETE /api/users/v1/me/sessions/{session-id} => internal_login

Token Request :

curl --request POST 'https://api.asgardeo.io/t/<org_name>/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'scope=internal_login'

Ex:

curl --location --request GET 'https://api.asgardeo.io/t/<org_name>/api/users/v1/me/sessions' \
--header 'Authorization: Bearer <access_token>'

/me/sessions Postman Collection : https://www.getpostman.com/collections/b6adf4c730bf11bf98ac

If you are wondering how can we manage authenticated user sessions in React Application, you can refer to my previous article below.

Manage Authenticated User Sessions Via REST API Using Asgardeo React SDK

Summery

We can invoke Asgardeo APIs,

1. With an access token retrieved via client_credentials grant.
2. With an access token retrieved via Authorization code grant.

Following are the APIs/Endpoints that we discussed through this article.

1. SCIM2 /Users Endpoints
2. DCR(Dynamic Client Registration) API
3. SCIM2 / Groups Endpoints
4. SCIM /Me Endpoints
5. /me/sessions Endpoints

Hope you got some idea about how we can invoke APIs in Asgardeo and the different ways of retrieving access tokens.

Thank you for reading this!