Scopes

Using the scope parameter, the access token can grant different levels of access to multiple Oracle Identity Cloud Service APIs. Scopes provide a way to more specifically define a set of resources and operations than an access token allows. Scopes represent intent. When a client requests an access token, the scopes asked for indicate the kind of functionality a client wants to make use of when presenting the access token.

Additionally, different types of applications use different access token grants. Trusted applications (such as back-end services) may request access tokens directly on behalf of users. Web applications typically need to first validate the user's identity and optionally obtain the user's consent.

Use the urn:opc:idm:__myscopes__ scope when you need to obtain an access token that contains all of the permitted Oracle Identity Cloud Service scopes. Access tokens are returned that contain all applicable Oracle Identity Cloud Service scopes based on the privileges represented by the Oracle Identity Cloud Service application roles granted to the requesting client and the user being specified by the client's request (if present). This scope is not granted directly to any Oracle Identity Cloud Service administrator role.

Use the urn:opc:idm:role.<r_name> scope (for example, urn:opc:idm:role.User%20Administrator) when you need to obtain an access token that contains the applicable scopes of a given role, provided that both the client and the user are granted the given role. For example, to request an access token with a role-based scope of User Administrator and Application Administrator:

Request Example

curl -i
-H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
--request POST https://tenant-base-url/oauth2/v1/token -d 'grant_type=password&username=<user-name>&password=<password>&client_id=<client-id>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<client-assertion>&scope=urn:opc:idm:role.User%2520Administrator urn:opc:idm:role.Application%2520Administrator'

The access token generated would contain the applicable scopes for the User Administrator and the Application Administrator as long as both the client and the user are granted these roles. For example, a client has Role1, Role2, and Role3. A User has Role1, Role2, and Role 4. The scopes included in the request for the access token are Role1 and Role3. The access token generated would contain only scopes for Role1.

Scope claims can have multiple space separated scopes. If a scope name contains a space, the server can't determine the correct scope boundary. This can happen when a role name is used in the scope. In the request example, the roles "User Administrator" and "Application Administrator" have spaces that have been URL encoded: scope=urn:opc:idm:role.User%2520Administrator urn:opc:idm:role.Application%2520Administrator.

To avoid space issues in role names, you must encode the role names twice using URL encoding:

Example Java Code

String scope = "scope=urn:opc:idm:role." + URLEncoder.encode(URLEncoder.encode("User Administrator", "UTF-8"), "UTF-8");
scope = scope + " urn:opc:idm:role." + URLEncoder.encode(URLEncoder.encode("Application Administrator", "UTF-8"), "UTF-8");

No Scopes Defined for an App

If there are no scopes defined for an application (for example, wanting the user to simply sign in and acquire an OAuth access token), the following scopes can be specified in browser-based login flow requests to the /oauth2/v1/authorize endpoint:

• scope=openid: The resulting access token can be used with /oauth2/c1/userinfo, which provides the bare minimum user information.

• scope=openid approles groups: The resulting access token can be used with /oauth2/v1/userinfo to get the user's roles and groups.