Fine Grained Access Control with OAuth Scopes

Scopes enable fine-grained access control to API resources based on user roles. You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.

For example, there can be requirements such as restricting the access to a given API resource to admin users only, while other resources of the same API access should be allowed to consumers with less privileges. Let's see how this kind of role based access control can be managed with the use of OAuth2 scopes.

Creating a Scope

The scopes can be created and applied to an API resources at API create time. Please follow below steps to create a scope.

  1. Login to API Publisher (https://localhost:9443/publisher)

  2. Start creating an API as described here.

  3. Navigate to Scope section and click on create scope button.

    Start Creating a Scope

  4. In scope creation wizard, you will be prompted to enter a scope name, scope description and optionally, allowed roles and a description. Fill in required details of the scope and click Save button. Click Save.

    Scope Key A unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.
    Scope Name A human-readable name for the scope. It typically says what the scope does.
    Roles

    The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee.

    Note that the role name is case sensitive in the DBMSs that are case sensitive, such as PostgreSQL.

    When the role you specify is in a secondary user store, you have to give the role as <userstore name>/<role name>.

    Create a Scope

Applying a Scope to an API Resource

A scopes has be applied to a resource, in order to restrict the access to a user group/groups. Please follow below steps to apply a scope to a resource.

  1. Go to API Resource section and click on the resource you would like to apply the scope.

    Select Resource

  2. Select the created scope from the drop down and click on Save button to save changes.

    Apply Scope

  3. Publish the API.

Disable role validation at scope creation

When creating scopes, it validates the added roles against the underline user store to check if they exist. However, we can override this behavior such that it does not validate the roles in the user store. For this purpose, set the Java system property disableRoleValidationAtScopeCreation to true at the server startup: This can be done in one of two ways.

Option 1: Adding in startup script

     Open <API-M_HOME>/bin/wso2server.(sh|bat) file.
     Add -DdisableRoleValidationAtScopeCreation=true at the end of the file.
     Restart the server.

Option 2: Provide as a parameter during server startup

Restart the server with the parameter set as below.

  • Linux/Mac OS

      ./wso2server.sh -DdisableRoleValidationAtScopeCreation=<boolean_value>
      ./wso2server.sh -DdisableRoleValidationAtScopeCreation=true

  • Windows

      wso2server.bat -DdisableRoleValidationAtScopeCreation=<boolean_value>
          wso2server.bat -DdisableRoleValidationAtScopeCreation=true

Obtaining Tokens with Scopes

When a scope has been assigned to an API resource, the access is getting restricted to the users who has the role/roles specified in the scope. Hence, the API consumers has to specifically request for the relevant scope when generating an access token to invoke the API resource. Please follow below steps to obtain an access token specifying the requested scopes.

  1. Login to API Portal(https://localhost:9443/devportal/)

  2. Navigate to the API which has the scope protected API resource and go to Credential section to subscribe to an application.

    Subscribe

  3. Generate production keys for the application.

    Generate App Keys

  4. Click on GENERATE ACCESS TOKEN button. Then select the scope from the prompted window and generate the access token.

    Generate App Keys

  5. If the user has the roles specified in the scope, the access token will be issued with the requested scope. Unless, only the default scopes will be returned with the access token.

    Token scopes

  6. Invoke the API resource with the above generated access token. If the user is assigned with the authorized roles, the API invocation will be successful. An API resource access by an unauthorized user will be failed giving 403 Forbidden error.

    Token scopes

Top