Before 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.
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
Register 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.
- In the Oracle Identity Cloud Service administration console, expand the Navigation Drawer , click Applications, and then click Add.
- In the Add Application dialog box, select Trusted Application or Confidential Application.
- In the App Details section on the Add Trusted Application page, enter an application name and description, and then click Next.
- 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.
- Scroll down, and click the Add button below Grant the client access to Identity Cloud Service Admin APIs.
- In the Add App Role dialog window, select Identity Domain Administrator in the list, and then click Add.
- Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
- In the Application Added dialog box, copy the Client ID and the Client Secret to a text file, and then click Close.
- Click Activate, and then click Activate Application.
Set the Environment Parameters in Postman
- Open Postman, and click Import.
- In the Import dialog box, select Import From Link, paste the following GitHub environment variables URL into the box, and then click Import:
- Click Environment options , and then select Manage Environments.
- In the Manage Environments dialog box, to the right of the example.identity.oraclecorp.com environment, click Duplicate Environment .
- Click example.identity.oraclecorp.com copy, which appears below the original environment.
- To update the environment variables, enter the following values, and then click Update.
Environment A for REST API Testing
- HOST: Oracle Identity Cloud Service UI address; for example,
- 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
Import the Postman Collection and Global Variables
- To import the Oracle Identity Cloud Service REST API Postman collection, on the Postman main page, click Import.
- In the Import dialog box, select Import From Link, paste the following GitHub Postman collection URL into the box, and then click Import:
- To import the global variables file, click Import.
- In the Import dialog box, select Import From Link, paste the following GitHub Postman Globals URL into the box, and then click Import:
- To view the imported variables, click Environment options , and then select Manage Environments from the drop-down list.
- In the Manage Environments dialog box, click Globals.
Request 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.
- On the Collections tab, expand OAuth, and then OAuth Tokens - Get (Authorize).
- Select Obtain access_token (client credentials), and then click Send. The access token is returned in the response from Oracle Identity Cloud Service.
- 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.
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.
Create a User
- On the Collections tab, expand Users, and then Create.
- Select Create a user. The request information appears.
- Click Body, and then click Send.
- In the response, confirm that the status
201 Createdappears and that the response body displays details about the user that was successfully created in Oracle Identity Cloud Service.
Test Other User API Calls
To test other user calls, you can set the user as a variable for reference.
- 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
- On the Collections tab, expand Users, and then Search.
- Select Search specific user, and click Send.
- Scroll down and verify that the response body displays status
200 Okand details about the user.
Want to Learn More?
- About the REST APIs
- Integrating a Custom Client Application
- Integrating a Custom Resource Server Application
- About Postman Global Variables