Oracle Identity Cloud Service: Managing Groups Using REST API Calls

Purpose

In this tutorial, you learn to manage Oracle Identity Cloud Service groups using REST API calls.

Time to Complete

30 minutes

Background

The REST APIs provide a way to integrate Oracle Identity Cloud Service with custom applications, so they can externally integrate with and manage Oracle Identity Cloud Service users, groups, applications, and settings.

In this tutorial, you learn to manage groups using REST API calls.

Tips:

• Oracle Identity Cloud Service REST APIs comply with System for Cross-Domain Identity Management (SCIM), an open API standard for managing identities across vendors.
• For complete information about the /Groups API, visit the REST API for Oracle Identity Cloud Service documentation.

What Do You Need?

• Complete the Oracle Identity Cloud Service: First REST API Call tutorial.
• Optionally, complete the Oracle Identity Cloud Service: Managing Users Using REST API Calls tutorial so that you have a couple of test users (Teena Semmens and Jennifer Aspiom). You can also use any user from your Oracle Identity Cloud Service instance.

The access token is required for performing REST API calls in Oracle Identity Cloud Service.
Tip: If you don't know how to request access tokens, visit the Oracle Identity Cloud Service: First REST API Call tutorial.

1. In the Identity Cloud Service console, click Applications, and then click Client Application.
2. Click Generate Access Token.
3. Click Customized Scopes > Download Token.
4. Save the tokens.tok file in a temporary folder.
5. Open the tokens.tok file in a text editor. Select and copy the access token value - a long sequence of characters placed after the app_access_token property between double quotes (").

View Image

Important: You'll use this token to perform the remaining REST API requests in this tutorial. If the token get expired during the tutorial (after one hour of use), request a new one.

In this task, you search for user unique IDs in Oracle Identity Cloud Service using the /User REST API.

Notes:

• In Oracle Identity Cloud Service REST APIs, users are identified by a unique ID. This ID is randomly generated and associated with users during their creation.
• The unique ID for the user can be obtained by performing a search on the /User REST API.
• Alternatively, you can find the unique ID for the user from the Oracle Identity Cloud Service console.
  To do that, access the User Profile page. The unique ID appears in your browser's address bar with the page request (the information in bold is the unique ID):

  https://identity.oraclecloud.com/ui/v1/adminconsole/?root=users&user=2352ff98f4b044eb891abb255d13aa8b

  View Image

  

To obtain unique IDs using the /Users API:

1. In the command line, search for users using the attributes filter:

   curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Users?attributes=username" -o search_results.json

   Replace:
   • The IDCS_URL with your Oracle Identity Cloud Service url.
   • The ACCESS_TOKEN with your Access Token obtained in the previous task.
2. Open the search_results.json file. The file lists the user name and the unique ID (id field) for each Oracle Identity Cloud Service user:
   Tip: The code below is formatted for easier reading.

   {
     "schemas": ["urn:scim:api:messages:2.0:ListResponse"],
     "totalResults": 2,
     "Resources": [{
       "userName": "tsemmens@example.com",
       "id": "2352ff98f4b044eb891abb255d13aa8b"
     }, {
       "userName": "jaspiom@example.com",
       "id": "2e72a521c902482baffe164c3fe7bfcf"
     }],
     "startIndex": 1,
     "itemsPerPage": 50
   }

3. Record the unique ID from at least two users that appear in the search results.
   You will use these user IDs to add and remove their respective users from groups later.

In this task, you create a group in Oracle Identity Cloud Service.

1. Open a text editor to create the group.json file with the following content, replacing the USER_ID with a unique ID from one of your users:

   {
     "displayName": "Marketing",
     "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group": {
       "description": "Users in charge of promoting our marketing campaigns"
     },
     "members": [
       {
         "value": "USER_ID",
         "type": "User"
       }
     ],
     "schemas": [
       "urn:ietf:params:scim:schemas:core:2.0:Group",
       "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group",
       "urn:ietf:params:scim:schemas:extension:custom:2.0:Group"
     ]
   }

2. Run the create group command:

curl -k -v -X POST -H "Content-Type: application/scim+json" -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups" -d '@group.json' -o group_output.json

Replace the IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.

3. In the command output, confirm that the confirmation message appears: HTTP/1.1 201 Created.

   View Image

   

4. Optionally, review the group_output.json file. This file contains details about the Marketing group created in Oracle Identity Cloud Service.

{
  "displayName": "Marketing",
  "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group": {
    "description": "Users in charge of promoting our marketing campaigns"
  },
  "id": "f3d7e784075b4ebba55752e6eeb0d322",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group"
  ],
  "meta": {
    "resourceType": "Group",
    "created": "May 18,2016 3:44:27 PM Etc/UTC",
    "lastModified": "May 18,2016 3:44:27 PM Etc/UTC",
    "location": "https://example.identity.us.oraclecloud.com/admin/v1/Groups/f3d7e784075b4ebba55752e6eeb0d322"
  }
}

5. Access the Oracle Identity Cloud Service console, expand the Navigation Drawer , click Groups, click the Marketing group, and then click Users tab.
6. On the page, confirm that the group was created with a name, description, and a member corresponding to the unique ID that you included.

View Image



You successfully created a group using the REST API.

In this task, you search for groups in Oracle Identity Cloud Service, using search parameters and filter queries.

Tip: The search parameters and filters are features inherited from the SCIM standard.

1. At the command line, enter the following to search for all groups in Oracle Identity Cloud Service:

   curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups" -o search_results.json

   Replace the IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
2. Review the search_results.json file. This file lists the groups returned by Oracle Identity Cloud Service.

   {
   "schemas":[
     "urn:scim:api:messages:2.0:ListResponse"
     ],
     "totalResults":1,
     "Resources":[{
       "displayName":"Marketing",
   	   "meta":{
   	     "created":"2017-03-13T18:30:07.785Z",
   	     "lastModified":"2017-03-13T18:30:19.698Z",
   	     "resourceType":"Group",
   	     "location":"https://example.identity.us.oraclecloud.com/admin/v1/Groups/f826673a6f534461b8889aa7751db68b"
   	  },
   	  "idcsCreatedBy":{
   	    "type":"User",
   	    "display":"admin opc",
   	    "value":"4580ab3e9c504b82a69eb0fb61e29a1b",
   	    "$ref":"https://example.identity.us.oraclecloud.com/admin/v1/Users/4580ab3e9c504b82a69eb0fb61e29a1b"
   	  },
   	  "id":"f826673a6f534461b8889aa7751db68b",
   	  "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group":{
   	    "description":"Users in charge of promoting our marketing campaigns"
   	  },
   	  "schemas":[
   	    "urn:ietf:params:scim:schemas:core:2.0:Group",
   	    "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group"
   	  ]
   	 }
    ],
    "startIndex":1,
    "itemsPerPage":50
   }

Notes:
• The /Groups API implements the same options as the /Users API to control search pagination (index), filtering (filter), and select attributes for return (attributes). To learn more about these controls, explore the Search Users section in the Oracle Identity Cloud Service: Managing Users Using REST API Calls tutorial.
• By default, to prevent an extensive search result, the /Groups API does not return information about the group membership.
3. To search for groups, filtering the search and including group membership information in the return, enter:

   curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups?attributes=members,displayName&filter=displayName+eq+%22Marketing%22" -o search_results.json

   Replace the IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
   Notes: In this search:
   • The attributes parameter is set to return the group members and displayName.
   • The filter parameter is set to search for groups with a filter expression. The filter expression is url encoded before performing a request. URL encoding converts special characters, such as space and double-quotes, into a format that can be transmitted on GET requests.
   • In this task, the filter expression is displayName+eq+%22Marketing%22. This is the url encoded value for displayName eq "Marketing".
   • The Identity Cloud Service REST API filter expression complies with the SCIM standard. In this example, the filter displayName eq "Marketing" means that you are searching for a group with the displayName that equal Marketing.
   • The REST APIs support other types of filter expressions such as sw(starts with), ne(not equal), and co(contains). For more information about all of the filtering options, visit the REST API for Oracle Identity Cloud Service documentation.
4. Review the search_results.json file. This file now contais the Marketing group and its members.

{
"schemas":[
	"urn:scim:api:messages:2.0:ListResponse"
	],
	"totalResults":1,
	"Resources":[{
		"displayName":"Marketing",
		"id":"f826673a6f534461b8889aa7751db68b",
		"members":[{
			"value":"55da1589051d4b8f898af32ded25b3f6",
			"type":"User",
			"name":"tsemmens@example.com",
			"display":"Teena Semmens",
			"$ref":"https://example.identity.us.oraclecloud.com/admin/v1/Users/55da1589051d4b8f898af32ded25b3f6"
			},
			{
			"value":"0f74193f26b04f37ac5ebcc3ce29131e",
			"type":"User",
			"name":"csaladna@example.com",
			"display":"Clarence Saladna",
			"$ref":"https://example.identity.us.oraclecloud.com/admin/v1/Users/0f74193f26b04f37ac5ebcc3ce29131e"
			}
		]
	}],
	"startIndex":1,
	"itemsPerPage":50
}

5. Record the Marketing group ID that appears in the search results (in this example,f826673a6f534461b8889aa7751db68b). This information is required for the remaining tasks in this tutorial.

In this task, you modify the Marketing group via REST API.

Tip: In this tutorial, you modify a group using the method PATCH. This method updates only the user values that you sent. The Groups API also supports modification via the PUT method. This method updates the group values that you sent and clears the values that you didn't send within the group.

1. Open a text editor and create the update1.json file with the following content:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Marketing Users"
    }
  ]
}

2. In a text editor prepare the cURL command:

curl -k -X PATCH -H "Content-Type: application/scim+json" -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups/GROUP_ID" -d '@update1.json' -o group_output.json

Replace:
• The IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
• The GROUP_ID with the Marketing group ID attribute that appeared in the previous search result (for example,f826673a6f534461b8889aa7751db68b).
3. At the command prompt, run the cURL command.
4. Optionally, verify the group_output.json. This file contains new details about the Marketing group, including its new displayName (Marketing Users).
5. In the Oracle Identity Cloud Service UI, navigate to Groups and confirm that the Marketing group appears with a new name (Marketing Users).

   View Image

   

You've successfuly modified a group using the REST API.

In this task, you include and remove a user from the Marketing Users group via REST API.
Tip: The steps in this task are similar to the ones executed to update a group via REST API.

 

Include a Member

1. Update the update.json file with the following content and save it as update1.json file:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "USER_ID",
          "type": "User"
        }
      ]
    }
  ]
}

Replace the USER_ID with a unique id from a user that is not yet a member of the Marketing group.
2. In a text editor, prepare the cURL command:

curl -k -X PATCH -H "Content-Type: application/scim+json" -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups/GROUP_ID" -d '@update1.json' -o group_output.json

Replace:
• The IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
• The GROUP_ID with the Marketing group ID.
3. Return to the command prompt and run the cURL command.
4. Access the Oracle Identity Cloud Service UI, navigate to Groups, open the Marketing Users group, and then click Users.
5. On the page, confirm that the group displays the new member that you've just included via REST API.

View Image

 

Remove a Member

In this task, you remove a member from the Marketing Users group. The steps are similar to the ones executed to include a member in the group.

1. Update the update1.json file with the following content:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"USER_ID\"]"
    }
  ]
}

Replace the USER_ID with the same unique ID that you used in the previous request to add a user as a member of the Marketing group.
2. In a text editor, prepare the cURL command:

curl -k -X PATCH -H "Content-Type: application/scim+json" -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups/GROUP_ID" -d '@update1.json' -o group_output.json

Replace The IDCS_URL, the ACCESS_TOKEN, and the GROUP_ID as you did on previous tasks.
3. Return to the command prompt and run the cURL command.
4. Access the Oracle Identity Cloud Service UI, refresh the Marketing Users group page, and then click Users.
5. On the page, confirm that the user is removed from the group.

View Image

You successfuly included and removed users from the Marketing Users group using the REST API.

In this task, you delete the Marketing Users group.

1. Return to the command prompt and enter the delete command:

   curl -k -v -X DELETE -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Groups/GROUP_ID"

   Replace the IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
   Replace the GROUP_ID with the Marketing group ID attribute.
2. To verify that the Marketing Users group was deleted, access the Oracle Identity Cloud Service UI and click Groups. The Marketing Users group no longer appears.

To learn more about the REST APIs, explore the following tutorials and documents:

• Oracle Identity Cloud Service: REST API documentation
• Oracle Identity Cloud Service: First REST API Call
• Oracle Identity Cloud Service: Managing Users Using REST API Calls

To learn more about how to use the REST APIs for Federated SSO (using OpenID Connect plus OAuth 2.0), and Authorization scenarios (using OAuth 2.0), explore the following tutorials:

• Integrating a Custom Client Application
• Integrating a Custom Resource Server Application