Oracle Identity Cloud Service: Managing Users Using REST API Calls


Options



Before You Begin

Purpose

In this tutorial you learn to manage Oracle Identity Cloud Service's users 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 users using REST API calls.

Tips:

What Do You Need?

Request an Access Token

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, expand the Navigation Drawer , 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 (").
  6. Text editor with the access token highlighted and mouse over the copy button.
    Description of this 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.

Create Users

  1. Create manually or download (right-click file name and click Save Link As) the following files with their respective content:
  2. List of files for download or manual creation. These files will be used to create users via REST API.
    File name and link Contents
    file1.json
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "userName": "csaladna@example.com",
      "name": {
        "familyName": "Saladna",
        "givenName": "Clarence",
        "middleName": "Jane"
      },
      "emails": [{
        "value": "csaladna@example.com",
        "type": "work",
        "primary": true
      }]
    }
    file2.json
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "userName": "tsemmens@example.com",
      "name": {
        "familyName": "Semmens",
        "givenName": "Teena"
      },
      "emails": [{
        "value": "tsemmens@example.com",
        "type": "work",
        "primary": true
      }]
    }
    file3.json
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "userName": "jaspiom@example.com",
      "name": {
        "familyName": "Aspiom",
        "givenName": "Jennifer"
      },
      "emails": [{
        "value": "jaspiom@example.com",
        "type": "work",
        "primary": true
      }]
    }
  3. Launch a terminal and run the create user command:
  4. curl -k -v -X POST -H "Content-Type: application/scim+json" -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Users" -d 'FILE_NAME' -o user_output.json
    Replace:
    • The IDCS_URL with your Oracle Identity Cloud Service url.
    • The ACCESS_TOKEN with your access token obtained in the previous task.
    • The FILE_NAME with @ plus the file containing a user for creation. In this case @file1.json.
  5. In the command output, confirm that the confirmation message HTTP/1.1 201 Created is displayed.
    Screenshot from the terminal showing the 201 created message
    Description of this image
  6. Optionally, review the user_output.json contents. This file contains details about the user Clarence Saladna created in Identity Cloud Service.
  7. {
      "displayName": "Clarence Saladna",
      "name": {
        "givenName": "Clarence",
        "formatted": "Clarence Jane Saladna",
        "middleName": "Jane",
        "familyName": "Saladna"
      },
      "urn:ietf:params:scim:schemas:oracle:idcs:extension:userState:User": {
        "locked": {
          "on": false
        }
      },
      "userName": "csaladna@example.com",
      "id": "611e3ded55144d50be025185ccb53049",
      "active": true,
      "emails": [{
        "value": "csaladna@example.com",
        "type": "recovery",
        "verified": false,
        "primary": false
      }, {
        "value": "csaladna@example.com",
        "type": "work",
        "verified": false,
        "primary": true
      }],
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:extension:userState:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "meta": {
        "resourceType": "User",
        "created": "May 18,2016 2:16:45 AM Etc/UTC",
        "lastModified": "May 18,2016 2:16:45 AM Etc/UTC",
        "location": "https://example.identity.us.oraclecloud.com/admin/v1/Users/611e3ded55144d50be025185ccb53049"
      }
    }
  8. Repeat the create user command, replacing the FILE_NAME variable with @file2.json and @file3.json respectively.
  9. Access the Identity Cloud Service console, expand the Navigation Drawer , click Users, and confirm that the three users (Clarence Saladna, Teena Semeens, and Jennifer Aspiom) are created.
    Users page with users created using REST API displayed
    Description of this image

Search Users

In this task, you search for users 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. Return to the command line.
  2. To search for all users in Identity Cloud Service, enter:
    curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Users" -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.
  3. Review the search_results.json contents. This file will list the users returned by Oracle Identity Cloud Service.
  4. Tip: The Users REST API implements by default return pagination with up to 50 users retrieved by search. To control the search pagination results, you can use:

    • The count attribute to control how many entries will be retrieved in a search.
    • The startIndex attribute to control what will be the first entry returned in a search.
    • The count and the startIndex attributes combined for a full pagination. For example, to return 30 users from a search with 10 users returned by page, you make 3 REST API calls:
    • IDCS_URL/admin/v1/Users?count=10&startIndex=0
      IDCS_URL/admin/v1/Users?count=10&startIndex=10
      IDCS_URL/admin/v1/Users?count=10&startIndex=20
  5. To filter the search results to display less attributes, you can use the attributes filter. To use the attributes filter for usernames:
    curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Users?attributes=userName" -o search_results.json
    Replace the the IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
  6. Review the search_results.json contents. The file will list the user name and the id for each Identity Cloud Service user:
    Tip: The code below is formatted for better reading.
    {
      "schemas": ["urn:scim:api:messages:2.0:ListResponse"],
      "totalResults": 3,
      "Resources": [{
        "userName": "tsemmens@example.com",
        "id": "2352ff98f4b044eb891abb255d13aa8b"
      }, {
        "userName": "csaladna@example.com",
        "id": "ac7a646392aa43feaaa92b44a77b01cc"
      }, {
        "userName": "jaspiom@example.com",
        "id": "2e72a521c902482baffe164c3fe7bfcf"
      }],
      "startIndex": 1,
      "itemsPerPage": 50
    }
  7. To filter the search results, you can include the filter parameter as follows:
  8. curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Users?attributes=userName&filter=userName+sw+%22csaladna%22" -o search_results.json
    Replace the IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
    Notes:
    • The filter parameter expression must be url encoded before performing a request. In this task, the filter expression is userName+sw+%22csaladna%22. This is the url encoded value for userName sw "csaladna".
    • The Identity Cloud Service REST API filter expression complies with the SCIM standard. In this example, the filter userName sw "csaladna" means that you are searching for users with the userName starting with csaladna.
    • The REST APIs support other types of filter expression such as eq (equals), ne (not equal), and co (contains). For complete information about all the filtering options, visit the Identity Cloud Service REST API documentation.
  9. Review the search_results.json contents. The file list only one Clarence Saladna:
    Tip: The code below is formatted for better reading.
    {
      "schemas": ["urn:scim:api:messages:2.0:ListResponse"],
      "totalResults": 1,
      "Resources": [{
        "userName": "csaladna@example.com",
        "id": "ac7a646392aa43feaaa92b44a77b01cc"
      }],
      "startIndex": 1,
      "itemsPerPage": 50
    }
  10. Make a note of Clarence Saladna's id displayed in the search results (in this example, ac7a646392aa43feaaa92b44a77b01cc). This information is required for the remaining tasks in this tutorial.

Update Users

In this task, you modify a user using the REST API.

Tip: In this tutorial, you modify a user using the method PATCH. This method updates only the user values you sent. The User REST API also supports modification using the PUT method. This method updates the user values you sent and clears other values within the user you didn't send.
  1. Create or download the update1.json file with the following content:
  2. {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
      ],
      "Operations": [
        {
          "op": "add",
          "path": "phoneNumbers",
          "value": [
            {
              "value": "555-555-1111",
              "type": "home"
            }
          ]
        }
      ]
    }
  3. Using a text editor, prepare the cURL command as follows:
  4. curl -k -X PATCH -H "Content-Type: application/scim+json" -H "Authorization: Bearer ACCESS_TOKEN" "IDCS_URL/admin/v1/Users/CSALADNA_ID" -d '@update1.json' -o user_output.json
    Replace:
    • The IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
    • The CSALADNA_ID with Clarence Saladna's user id attribute, retrieved in the previous search (for example, ac7a646392aa43feaaa92b44a77b01cc).
  5. Return to the command prompt and run the cURL command.
  6. Optionally, verify the user_output.json. This file contains new details about Clarence Saladna, including her new home phone number.
  7. Access the Identity Cloud Service console, open the Clarence Saladna user, and confirm that the new home phone number is displayed.
    Oracle Identity Cloud Service administrative UI displaying a new Home Phone Number for Clarence Saladna
    Description of this image

Delete Users

In this task, you delete Clarence Saladna in Identity Cloud Service.

  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/Users/CSALADNA_ID"
    Replace:
    • The IDCS_URL and the ACCESS_TOKEN as you did on previous tasks.
    • The CSALADNA_ID with Clarence Saladna's user id attribute (for example, ac7a646392aa43feaaa92b44a77b01cc).
  2. On the return, confirm that the http code HTTP/1.1 204 No Content is displayed. This means that Clarence Saladna is deleted.
  3. Optionally, access the Oracle Identity Cloud Service UI and click Users. Clarence Saladna no longer appear under users.

Want to Learn More?

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

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: