Skip to content

API Authorization with Role Based Access Control (RBAC)

Role Based Access Control (RBAC) lets organizations grant limited access to its API resources based on the assigned roles of a user.

WSO2 Identity Server uses the following terms to define various components of API authorization.

Term Description
API resources Defines an API and its permissions(in the form of scopes). This could be a business API or a management/organization API exposed by WSO2 Identity Server.
Permissions Also known as scopes, are the actions an application can perform on the API, on behalf of the user. Applications should request for an authorized token before performing these actions.
Roles Used to group permissions for API resources. In WSO2 Identity Server you can define application roles (for a specific application) and organization roles (for multiple applications). See manage roles for more information.
User Groups A collection of users with the same privileges. See manage groups for more information.
IdP Groups Groups of an external identity provider connected with the application. Learn how to add IdP groups for a connection.

The relationship between these entities is as follows:

  • Management/Organization APIs and business APIs along with their permissions are defined in the form of API resources.
  • The administrator does the following to enforce RBAC to an application.

    1. Authorize an application to consume certain API resources and permissions.
    2. Select the role audience for the application. (This decides whether the application consumes application roles defined specifically for it or organization roles available throughout the organization.)

    3. Create an application/organization role that grants permissions for selected APIs.

    4. Collect users who should be granted this role and create a group.
    5. Assign users individually or as a group to the role so that members of the group inherit the permissions defined in the role.
    6. Optionally, select external groups that should be assigned to the above role when logging in with an external identity provider.
  • Users logging into the application can then perform actions on the selected APIs based on the role.

Learn more with a sample scenario

The following diagram depicts a sample use case of RBAC.

The relationship between terms

The Library application lets users log in and use its services in the form of a book API to manage books and a user API to manage users. The library application also wants to let users of an external library to log in to the application. The administrator wishes to employ RBAC to protect the application's API resources as follows,

1. Reader and Writer are application roles associated with the Library application.
2. Admin is an organization role.

1. The Reader role has GET permissions to both books API and the users API.
2. The Writer role has GET and ADD permissions to both books API and the users API.

1. Members of the Librarian group are assigned with the Writer permissions.
2. Any other user logging into an application is assigned Reader permissions.
3. The Librarians group in the external IdP are assigned Writer permissions.

When logging into the Library application under these conditions,
1. John, a member of the Librarians group can read, add books and view, add users.
2. Bob, a user can read books and view users.
3. Members of the external Librarian group can read, add books and view, add users.

In WSO2 Identity Server, you can follow the steps below to enforce RBAC for users logging in to an application.

Register a business API

Apart from the APIs exposed by WSO2 Identity Server, administrators can define their own API resources and their scopes as API resources.

To register an API resource,

  1. On the WSO2 Identity Server Console, go to API Resources.
  2. Click + New API to register a new API resource.
  3. Enter the following details and click Next:

    Parameter Description
    Identifier This value will be used as the aud attribute in the issued JWT token. Although any value is acceptable, it's recommended to use the URI of the API resource.
    Display Name A meaningful name to identify your API resource in WSO2 Identity Server.

  4. To register the scopes for your API, enter the following details and click Add Scope .

    Parameter Description
    Scope (Permission) Defines an action for your API resource. This value should match the scopes defined in your application. (Applications use this scope to request for an access token).
    Display Name A meaningful name for your scope (permission). This will be displayed on your application's user consent page.
    Description A description for your scope (permission). This will be displayed on your application's user consent page.

  5. Repeat step 4 for all your scopes. Once done, click Next.

  6. If your API requires authorization, enable Requires authorization. Disable the option to proceed with no authorization policy.

  7. Click Finish to complete the API resource registration.

Authorize apps to consume API resources

Applications, by default, do not have permissions to use APIs. Administrators can selectively grant authorization for applications to use selected APIs and their scopes. Hence, users logging into the application will have access to that API resource provided they are assigned to a role that grants the necessary permissions.

To authorize an application to consume an API resource:

  1. On the WSO2 Identity Server Console, go to Applications.

  2. Select the application and go to its API Authorization tab.


    You cannot authorize API resources for a SAML application.

  3. Click Authorize an API Resource.

  4. Enter the following details:

    Parameter Description
    API Resource Select an API resource from the list of business APIs or management/organization APIs
    Authorized Scopes Select the scopes for the API.
    Authorization Policy Management/Organization APIs of WSO2 Identity Server or business APIs with Requires autheorization enabled will default to Role-Based Access Control (RBAC). Other APIs can alternatively proceed with No Authorization Policy.

  5. Click Finish.

    Successfully authorized an API resource in the app

Set the role audience for apps

In WSO2 Identity Server, applications can be configured to work with one of the following roles.

  • Application roles - Roles tailored to a specific application. Used to control access to API resources authorized for the application.

  • Organization roles - Roles that are available throughout the organization and used to control access to API resources of an organization.


Learn more about roles Manage roles.

To select the application audience,

  1. On the WSO2 Identity Server Console, go to Applications.

  2. Select the application and go to its Roles tab.

  3. Under Roles > Role Audience,

    1. If the choice is set to Application, all application roles created for the application appear under Assigned Roles. Click the X icon if you wish to delete an application role. Click New Role if you wish to add more roles.

    2. Selecting Organization allows applications to consume organization-level roles.


    If you switch the role audience to Organization, application roles created for the application will be permanently deleted.


    In WSO2 Identity Server versions prior to update level 25, if the application's role audience is set to organization, users were required to manually assign organization-level roles to the application . This behavior has since changed. Now, all organization-level roles are automatically assigned to the application by default. If you are experiencing the previous behavior, download the updated product pack to receive the latest changes.

Create roles and assign users

Once the application is authorized to consume APIs and its role audience is set, administrators can create roles and enforce RBAC policies in the organization.

To enforce RBAC policies,

  • If the application's role audience is set to Application, create application-specific roles and assign necessary permissions out of the APIs authorized for the application.

  • If the application's role audience is set to Organization, any organization role you create can be used to control access to the application.


Learn how to manage roles.

Try it out

Imagine you have an issue management application. For this you employ the issues API that let users perform view, create and delete operations on the issues. In order to enforce RBAC on the issues API, you create the following application roles.

  • Reporters can view, create and delete issues.

  • Reviewers can only read issues.

Follow the steps below to use the WSO2 Identity Server's React sample application to see this scenario in action.

  1. Register the issues API as an API resource with scopes for reading, creating and deleting issues.

  2. Register the issue management application in WSO2 Identity Server and authorize the application to use the issues API.

    Successfully authorized an API resource in the app

  3. Set the role audience of the application to Application (This is the logical choice if you only have one application using the roles you create).

  4. Create application roles for Reporter and Reviewer. The following shows the permissions for the Reviewer role

    Reporter permissions

  5. Create users and assign them to each role. For this example, let's say John is a reporter and Jane is a reviewer.

  6. Copy the scopes authorized for the application, configure the application to request scopes and run it.

  7. Access the application URL.

  8. Login as John (a reporter), you will see the following scopes in his profile.

    Reporter permissions

  9. Login as Jane (a reviewer), you will see the following scopes in her profile.

    Reporter permissions