Invoking APIs in Asgardeo

Photo by NASA on Unsplash

APIs should always be secure. In this article, I will show you how to invoke endpoints of SCIM, DCR, and 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 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, and scope values in the token request with the correct values.

How Can We Find the Scope for a Particular API?

If you are looking for the scopes required for a specific Asgardeo API, the best place to find that is in 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 an 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 these 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 Applicationpage.

• 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 https://localhost/callback as the redirect URL. Please note that we also need to specify https://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.

• 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.

Sample Response :

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

• 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 this sample application. Please follow the setup guide mentioned in the Readme.md file.

• 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 this article.

• 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 want to find out how to manage authenticated user sessions in a React application, you can refer to this article.

Summary 

Here are ways that can invoke Asgardeo APIs:

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

The following are the APIs/Endpoints that we discussed in this article.

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