Oracle by Example brandingConvert User Grants to Group Grants

section 0Before 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.

section 1Configure 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.

  1. 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.
  2. Click Add.
  3. In the Name field of the Add Group window, enter ERP System, and then click Next.
  4. Select the check boxes for the Alice Peterson, Anne Robb, and Clarence Saladna users, and then click Finish.
  5. Click Access, and then click Assign.
  6. 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:

    1. Enter the required values for the form.
    2. 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.
    3. Click Save.

  7. Click OK.
  8. In the Navigation Drawer, click Applications.
  9. In the Applications page, search for the Vision Enterprises ERP app, and then click the app.
  10. 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?
  11. 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.

section 2Obtain 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?

  1. 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).

  2. Open a Command Prompt, and then enter the cURL command.
  3. 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).

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.

section 3Obtain 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).

  1. 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.

  2. In the Command Prompt, enter the cURL command.
  3. 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.

  4. Copy this app ID to the clipboard. You'll need it to perform the tasks in the next section of this tutorial.

section 4Change 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.

  1. 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.
  2. In the Command Prompt, enter the cURL command.
  3. 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"}}
  4. 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.

section 5Verify 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.

  1. In the Identity Cloud Service console, make sure the Vision Enterprises ERP app is active.
  2. 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.

  3. 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.

more informationWant to Learn More?

To learn more about REST APIs, refer to the following documentation and tutorials: