Oracle by Example brandingUsing the Oracle Identity Cloud Service REST APIs with Postman

section 0Before You Begin

This tutorial shows you how to make REST application programming interface (API) calls to Oracle Identity Cloud Service using Postman, software typically used for REST API tests. This tutorial takes approximately 15 minutes to complete.

Background

The Oracle Identity Cloud Service REST APIs provide a way to integrate Oracle Identity Cloud Service with REST clients so that they can manage users, groups, applications, and settings, and perform federated single sign-on (SSO) and authorization in the cloud. The APIs support the OAuth 2.0, OpenID Connect, and System for Cross-Domain Identity Management.

What Do You Need?

  • Access to Oracle Identity Cloud Service with the Identity Domain Administrator or Application Administrator roles
  • Familiarity with the REST architecture style
  • Native Postman client installed (This tutorial uses the native Postman extension because Google plans to end support for Chrome apps for Windows, Mac, and Linux users in late 2017. If you use the Postman extension, the steps in this tutorial may be slightly different.)
  • REST samples in the idm-samples repository

section 1Register a Client Application

In this section, you register an application in Oracle Identity Cloud Service. This task is required to obtain the credentials (Client ID and Client Secret) that are used for authentication in REST API calls. The credentials are equivalent to service credentials (ID and password) that your client uses to communicate with Oracle Identity Cloud Service. This task also helps you determine which requests are authorized through the REST API.

  1. In the Oracle Identity Cloud Service administration console, expand the Navigation Drawer , click Applications, and then click Add.
  2. In the Add Application dialog box, select Trusted Application or Confidential Application.
  3. In the App Details section on the Add Trusted Application page, enter an application name and description, and then click Next.
  4. Select Configure this application as a client now, and then, in the Authorization section that appears, select only Client Credentials as the Allowed Grant Type.
  5. Scroll down, and click the Add button below Grant the client access to Identity Cloud Service Admin APIs.
  6. In the Add App Role dialog window, select Identity Domain Administrator in the list, and then click Add.
  7. Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
  8. In the Application Added dialog box, copy the Client ID and the Client Secret to a text file, and then click Close.
  9. Click Activate, and then click Activate Application.

section 2Set the Environment Parameters in Postman

  1. Open Postman, and click Import.
  2. In the Import dialog box, select Import From Link, paste the following GitHub environment variables URL into the box, and then click Import:

    https://github.com/oracle/idm-samples/raw/master/idcs-rest-clients/example_environment.json

  3. Click Environment options Environment Options icon, and then select Manage Environments.
  4. In the Manage Environments dialog box, to the right of the example.identity.oraclecorp.com environment, click Duplicate Environment Duplicate Environment icon.
  5. Click example.identity.oraclecorp.com copy, which appears below the original environment.
  6. To update the environment variables, enter the following values, and then click Update.
    • NAME: Environment A for REST API Testing
    • HOST: Oracle Identity Cloud Service UI address; for example, https://example.identity.oraclecorp.com
    • CLIENT_ID and CLIENT_SECRET: The Client ID and the Client Secret that you copied into a text file from your Oracle Identity Cloud Service trusted application
    • USER_LOGIN and USER_PW: Your user login and password
      • Modified Postman environment variables
      Description of the illustration modify_environment_variables.png
  7. Click the Environment drop-down list, and then select the updated environment from the list.
    8. Environment Drop-Down List
    Description of the illustration environment_drop_down_list.png

section 3Import the Postman Collection and Global Variables

  1. To import the Oracle Identity Cloud Service REST API Postman collection, on the Postman main page, click Import.
  2. In the Import dialog box, select Import From Link, paste the following GitHub Postman collection URL into the box, and then click Import:

    https://github.com/oracle/idm-samples/raw/master/idcs-rest-clients/REST_API_for_Oracle_Identity_Cloud_Service.postman_collection.json

    3. The collection appears beneath the Collections tab.
    Description of the illustration collection_in_left_panel.png
  3. To import the global variables file, click Import.
  4. In the Import dialog box, select Import From Link, paste the following GitHub Postman Globals URL into the box, and then click Import:

    https://github.com/oracle/idm-samples/raw/master/idcs-rest-clients/oracle_identity_cloud_service_postman_globals.json

  5. To view the imported variables, click Environment options Environment Options icon, and then select Manage Environments from the drop-down list.
  6. In the Manage Environments dialog box, click Globals.

section 4Request an Access Token

To make API calls to Oracle Identity Cloud Service, you must authenticate your client against Oracle Identity Cloud Service, and then obtain an OAuth access token.

The access token provides a session between a client (in this tutorial, Postman) and Oracle Identity Cloud Service. 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.

  1. On the Collections tab, expand OAuth, and then OAuth Tokens - Get (Authorize).
  2. Select Obtain access_token (client credentials), and then click Send. The access token is returned in the response from Oracle Identity Cloud Service.
  3. Highlight the access token content between the quotation marks, and then right-click. In the shortcut menu, select Set: example.identity.oraclecloud.com. In the secondary menu, select access_token. The highlighted content is assigned as the access token value.
    4. Access token highlighted in the response.
    Description of the illustration assign_access_token_variable.png

Subsequent REST API calls to Oracle Identity Cloud Service contain the access token as well as additional information about the request. The additional information is sent through a request Universal Resource Identifier, a header, parameters, or JSON code, and varies according to the REST API call and method that you request.

section 5Create a User

  1. On the Collections tab, expand Users, and then Create.
  2. Select Create a user. The request information appears.
  3. Click Body, and then click Send.
    4. Body tab with JSON code.
    Description of the illustration modify_request_body_content.png
  4. In the response, confirm that the status 201 Created appears and that the response body displays details about the user that was successfully created in Oracle Identity Cloud Service.

section 6Test Other User API Calls

To test other user calls, you can set the user as a variable for reference.

  1. In the response body, select and right-click the id. In the shortcut menu, select Set: Globals, and then select userid. The unique id is assigned as the userid value.
    2. Setting the userid
    Description of the illustration set_global_variables.png
  2. On the Collections tab, expand Users, and then Search.
  3. Select Search specific user, and click Send.
  4. Scroll down and verify that the response body displays status 200 Ok and details about the user.

more informationWant to Learn More?