Before You Begin
This tutorial shows you how to change the grant type for users who have access to an app, from users assigned to the app directly (user grants) to users who can access the app because they belong to a group (a group grant). Converting user grants to group grants doesn't revoke user access to the app.
This tutorial takes approximately 15 minutes to complete.
Background
For this tutorial, Alice Peterson, Anne Robb, and Clarence Saladna are employees of Vision Enterprises who have access to their company's ERP system. After an application administrator integrates the ERP system with Oracle Identity Cloud Service through the Vision Enterprises ERP app, Alice, Anne, and Clarence are synchronized from this non-authoritative app into Oracle Identity Cloud Service. If there are accounts for them in Oracle Identity Cloud Service, then they're assigned to the app. Oracle Identity Cloud Service grants them direct access to the app. These are user grants.
Vision Enterprise's security office has determined that only members of Vision's ERP System group in Oracle Identity Cloud Service should have access to the Vision Enterprises ERP app, and direct assignments (user grants) to the app aren't allowed. As a result, Alice, Anne, and Clarence must first be assigned to the group, and then the group must be assigned to the app. This is a group grant. Any additional users who are members of this group will also have access to the app because they belong to the group and the group is assigned to the app.
Removing the user grants from Alice, Anne, and Clarence and then reallocating a group grant to them for the ERP app may result in a loss of productivity because their user accounts are removed from the app, and then created again (through the group grant). This results in their access to the app being interrupted temporarily. Instead, by converting the user grants to a group grant, they'll be able to use the app without suffering any downtime.
Another advantage of granting Alice, Anne, and Clarence access to the Vision Enterprises ERP app through a group grant is that if they should no longer have access to the app, then rather than revoke each user's access rights to the app (a time-consuming and inefficient process), you can remove the group from the app. Oracle Identity Cloud Service will revoke the access rights that Alice, Anne, and Clarence have to the app, and these users will be removed from the ERP system automatically.
Group grants allow users to request access to a group instead of to the app. If the app has the account form enabled, then administrators can predefine attribute values for the form as well as app roles for the group, and these values and roles will be applied to the users assigned to the app through the group grant.
What Do You Need?
To accomplish the tasks described in this tutorial, make sure that you have:
- An Oracle Identity Cloud Service account with authorization rights to manage apps, groups, and users (by being assigned to the identity domain administrator, security administrator, or application administrator role).
- A Linux machine with the cURL utility available. For this tutorial, we're using Oracle Linux 7.2. This tutorial can be executed on other operating systems with bash terminal (such as Red Hat, Ubuntu, or OSX), or in Windows (using a bash emulator such as git bash). The commands on different operating systems may present small variations.
- Familiarity with the REST architecture style.
- An application to perform the grant conversion. For this tutorial, you'll be using the Vision Enterprises ERP app.
- To assign users to this application directly. For this tutorial, Alice Peterson, Anne Robb, and Clarence Saladna are assigned to the Vision Enterprises ERP app.
- A confidential application from which you can generate an access token.
- To assign the identity domain administrator role to this confidential application. See the Oracle Identity Cloud Service: First REST API Call tutorial for more information on adding a confidential application and assigning the identity domain administrator role to it.
Configure
Your Oracle Identity Cloud Service Environment
In this section, you create an ERP System group in Oracle Identity Cloud Service, assign Alice Peterson, Anne Robb, and Clarence Saladna to this group, and then assign the group to the Vision Enterprises ERP app.
- From the Identity Cloud Service console that you're accessing as an identity domain administrator, security administrator, or application administrator, expand the Navigation Drawer, and then click Groups.
- Click Add.
- In the Name field of the Add Group window, enter ERP System, and then click Next.
- Select the check boxes for the Alice Peterson, Anne Robb, and Clarence Saladna users, and then click Finish.
- Click Access, and then click Assign.
- In the Assign Applications window, click Assign
to the right of the Vision Enterprises ERP app.
Note: If you're assigning a managed app to the group, then an Assign Application window appears, containing an account form for the app. To populate this form:
- Enter the required values for the form.
- If the form contains multi-valued attributes, then an Add
button appears to the right of each attribute. Click Add,
and then in the Allowed Values window, select the
values for the attribute, and click OK.
- Click Save.
- Enter the required values for the form.
- Click OK.
- In the Navigation Drawer, click Applications.
- In the Applications page, search for the Vision
Enterprises ERP app, and then click the app.
- Click the Users tab, and then verify that the Alice
Peterson, Anne Robb, and Clarence Saladna users are assigned
to the app. You assigned these users to the app in What
Do You Need?
- Click the Groups tab, and then verify that the ERP
System group is assigned to the app.
In the remaining sections of this tutorial, you'll be converting the user grants for Alice Peterson, Anne Robb, and Clarence Saladna to a group grant so that they can access the Vision Enterprises ERP app because they belong to the ERP System group.
Obtain
an Access Token
To make REST API calls to Oracle Identity Cloud Service, you must authenticate your client (in this tutorial, cURL) against Oracle Identity Cloud Service, and then obtain an OAuth access token.
This access token provides a session between your client and Oracle Identity Cloud Service. Your client uses this session to perform tasks in Oracle Identity Cloud Service via REST APIs. By default, the access token has a timeout interval of 60 minutes, and then you must request a new access token to perform additional REST API calls.
In this section, you obtain an access token from the confidential application that you added in What Do You Need?
- In a text editor, prepare the cURL command, as
follows:
curl -k -X POST -u "[CLIENT_ID]:[CLIENT_SECRET]" -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__" "https://[IDCS_TENANT]/oauth2/v1/token" -o access_token.json
Replace:
- [CLIENT ID] with the Client ID of the
confidential application.
- [CLIENT_SECRET] with the Client Secret of the
confidential application.
- [IDCS_TENANT] with your Oracle Identity
Cloud Service URL (for example, idcs-1234.identity.oraclecloud.com:8943).
- [CLIENT ID] with the Client ID of the
confidential application.
- Open a Command Prompt, and then enter the cURL command.
- In a text editor, open the access token file (access_token.json),
and then make a note of the access token value, as indicated
by the ACCESS_TOKEN_VALUE below.
Tip: In this tutorial, the contents of the file are broken into multiple lines to simplify reading it.
{
"access_token":"ACCESS_TOKEN_VALUE", "token_type":"Bearer", "expires_in":3600
}The access_token.json file contains the access token request output in JSON format. The file contains three attributes: access_token, token_type, and expires_in.
- The access_token attribute identifies your
client access in Oracle Identity Cloud Service. This token
is encoded following the JSON Web Token (JWT)
standard.
Tip: To check the JWT token, copy the access token and verify its value by clicking here.
- The token_type attribute identifies the access token as a Bearer token type. In future requests, you'll use this token type to identify your token in the authorization header of your request.
- The expires_in attribute identifies the validity period of the access token (in seconds).
- The access_token attribute identifies your
client access in Oracle Identity Cloud Service. This token
is encoded following the JSON Web Token (JWT)
standard.
Now that you have obtained an access token from your confidential application, you can use it to perform subsequent REST API calls in this tutorial.
Obtain
the App ID
In this section, you obtain the ID from the app for which you want to perform the grant conversion. You'll need this app ID to change the grant type of the Alice Peterson, Anne Robb, and Clarence Saladna users who are assigned to the Vision Enterprises ERP app (from user grants to a group grant).
- In a text editor, prepare the cURL command, as
follows:
curl -k -X GET -H "Authorization: Bearer [ACCESS_TOKEN_VALUE]" "https://[IDCS_TENANT]/admin/v1/Apps?filter=displayName%20co%20%22[APP_DISPLAY_NAME]%22&attributes=username"
Replace:
- [ACCESS_TOKEN_VALUE] with the access token that
you generated in Obtain an Access
Token.
- [IDCS_TENANT] with your Oracle Identity Cloud
Service URL (for example, idcs-1234.identity.oraclecloud.com:8943).
- [APP_DISPLAY_NAME] with the display name of the
app for which you want to perform the grant conversion.
Tip: If there are spaces in the display name, then represent those spaces with %20. In this tutorial, you're performing the grant conversion for the Vision Enterprises ERP app. Replace [APP_DISPLAY_NAME] with Vision%20Enterprises%20ERP.
- [ACCESS_TOKEN_VALUE] with the access token that
you generated in Obtain an Access
Token.
- In the Command Prompt, enter the cURL command.
- Verify that the following result appears:
Tip: The contents of the output are broken into multiple lines to simplify reading it.
{"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":1,"Resources":[{"displayName":"Vision Enterprises ERP",
"isOPCService":false,"clientType":"confidential",
"basedOnTemplate":{"value":"CustomWebAppTemplateId"},
"isAliasApp":false,"id":"[APP_ID]"}],"startIndex":1,"itemsPerPage":50}The value that appears to the right of the id parameter is the ID of the Vision Enterprises ERP app.
- Copy this app ID to the clipboard. You'll need it to perform the tasks in the next section of this tutorial.
Change
the Grant Type
In this section, you change the grant type for Alice Peterson, Anne Robb, and Clarence Saladna for the Vision Enterprises ERP app from user grants to a group grant. Alice, Anne, and Clarence have transitioned into Vision's ERP System group; therefore, they shouldn't be able to access the app directly, but rather because they belong to the group.
- In a text editor, prepare the cURL command, as
follows:
curl -k -X POST -H "Authorization: Bearer [ACCESS_TOKEN_VALUE]" -H "Content-Type: application/json" "https://[IDCS_TENANT]/admin/v1/GrantConverter" -d "{\"appId\":\"[APP_ID]\",\"convertForAll\":true,\"schemas\":[\"urn:ietf:params:scim:schemas:oracle:idcs:GrantConverter\"]}"
Replace:
- [ACCESS_TOKEN_VALUE] with the access token that
you generated in Obtain an Access
Token.
- [IDCS_TENANT] with your Oracle Identity Cloud
Service URL (for example, idcs-1234.identity.oraclecloud.com:8943).
- [APP_ID] with the ID of the app for which you
want to perform the grant conversion. You retrieved this
ID in Obtain the App ID.
- [ACCESS_TOKEN_VALUE] with the access token that
you generated in Obtain an Access
Token.
- In the Command Prompt, enter the cURL command.
- Verify that the following result appears:
Tip: The contents of the output are broken into multiple lines to simplify reading it.
{"appId":"[APP_ID]","convertForAll":true,
"schemas":["urn:ietf:params:scim:schemas:oracle:idcs:GrantConverter"],
"meta":{"resourceType":"GrantConverter","location":
"https://idcs-1234.identity.oraclecloud.com:8943/admin/v1/GrantConverter"}} - Verify that the value for the convertForAll parameter is true. Oracle Identity Cloud Service changed the grant type for Alice Peterson, Anne Robb, and Clarence Saladna for the Vision Enterprises ERP app from user grants to a group grant.
Verify
the Group Grant Conversion
In this section, you verify that Alice Peterson, Anne Robb, and Clarence Saladna no longer have direct access to the Vision Enterprises ERP app. However, they can access the app because they belong to the ERP System group.
- In the Identity Cloud Service console, make sure the Vision Enterprises ERP app is active.
- Click the Users tab, and then verify that the Alice
Peterson, Anne Robb, and Clarence Saladna users no longer
appear in this tab. Alice, Anne, and Clarence can no longer
access the app directly.
Note: If Alice, Anne, and Clarence still appear in the Users tab, then refresh your web browser.
- Click the Groups tab, and then verify that the ERP System group is still assigned to the app. Alice, Anne, and Clarence can access the app because they're members of this group.
Tip: There's another way to change the grant type for users who have access to an app (from user grants to a group grant). Rather than changing the grant type for all users simultaneously, you can change it for users, one by one. Refer to REST API for Oracle Identity Cloud Service for more information about how to execute this type of conversion.
Want
to Learn More?
To learn more about REST APIs, refer to the following documentation and tutorials: