Scope-based Authorization for Internal REST APIs¶

WSO2 Identity Server supports API authentication using OAuth2 common flows, where users can obtain a token using an oauth2 flow and use it to invoke the API.

Authorization for the APIs in WSO2 Identity Server is enforced at the endpoint level using permissions. Each secured endpoint has a predefined minimum level of permission that is required to be able to consume the endpoint. In order to access a particular endpoint, the user has to belong to a role that includes the defined permissions. WSO2 Identity Server now supports scope-based API authorization for internal REST APIs.

When obtaining a token to consume the API, you can define the scope corresponding to the permission required to consume the API.

For example, let's assume that a user whose username is Bob, wants to retrieve the challenges available by calling the /{user-id}/challenges GET API available in Challenge Question REST API. This requires the user-id as an input. To retrieve the challenges, Bob requires /permission/admin/manage/identity/identitymgt/view permission and internal_identity_mgt_view scope. Hence, Bob can invoke the following cURL command with scope=internal_identity_mgt_view and obtain a token.

Request

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

Example Request

curl -k -X POST -H "Authorization: Basic MUxGVzl5NERkYzZxaHVGQnBLX1JyOHA0WU1FYTpDUGl5V0hTeVp6VmJmRTFzanFNc2Vrc053Szhh" -k -d "grant_type=password&username=bob&password=bob123&scope=internal_identity_mgt_view" -H "Content-Type: application/x-www-form-urlencoded" 'https://localhost:9443/oauth2/token'

When the above cURL command is called, a token of the following format will be generated. If the user that requests the token has sufficient permissions to the scope defined in the request, the response will contain the scope specified in the above command.

Example Response

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

If the response with the generated token contains the scope specified in the cURL request, the received access token can be used to consume the API that requires the particular scope.