Identity Cloud Services OAuth 2.0 and REST API

November 17, 2016 | 9 minute read
Tim Melander
A-Team Cloud Solution Architect
Text Size 100%:

Introduction

This article is to help expand on topics of integration with Oracle’s Cloud Identity Management service called Identity Cloud Services. Identity Cloud Services delivers core essentials around identity and access management through a multi-tenant Cloud platform.  One of the more exciting features of IDCS is that you can interact with it using a REST API.  REST, or REpresentational State Transfer, is a stateless, client-server, architectural style that runs over HTTP.   The Identity Cloud Services REST APIs support SCIM 2.0 compliant endpoints with standard SCIM 2.0 core schemas and Oracle schema extensions to programmatically manage users, groups, applications and identity functions like password management and administrative tasks to name a few.  In fact, if you can do it in the Identity Cloud Services user interface you can probably do it using the Identity Cloud Services REST API.  This article is to get you started on the basics of using OAuth 2.0 authorization to access the REST API.  Consider this a building block to start your journey with the Identity Cloud Services REST API.

 

Working with OAuth 2.0 to access the IDCS REST API

OAuth 2.0 is a standard for implementing delegated authorization. Authorization is based on the access token required to access a resource. The access token can be issued for a given scope, which defines what the access token can do and what resources it can access. As a quick prelude to working with OAuth 2.0 to access the IDCS REST API, there are four steps to complete.

  1. Login to the Identity Cloud Services admin console
     
  2. Create an OAuth client application
     
  3. Use the client ID and client secret to create the access token
     
  4. Include the access token in the HTTP header when sending requests to the REST API

Once a client application is registered in Identity Cloud Services, the following sequence diagram will help to illustrate the OAuth 2.0 authorization flow according to how we will access the Identity Cloud Services REST API.

IDCS OAuth 2.0 Flow

I want to point out that the diagram could get more elaborate to include things like token expiration, revocation, refresh, other grant types, etc., but I want to keep the focus on a basic example to making requests to the Identity Cloud Services REST API otherwise things can get convoluted.

The table below includes some important OAuth 2.0 parameters we will be working with Identity Cloud Services to get started. It is not an exhaustive list, but a starting point to work with OAuth 2.0 and IDCS.

 

Parameter Value Comments
Authorization Header Basic <base64_clientid_secret> Used by client as a Basic authentication scheme to transmit the access token in a header.  The access token value needs to be a base64 UTF-8 encoded value of the Client ID and Client Secret concatenated using a colon as a separator; e.g. clientID:clientSecret.
Client ID <client_id> Required. A unique “API Key” generated when registering your application in the Identity Cloud Services admin console.
Client Secret <client_secret> Required. A private key similar to a password that is generated when registering your application in the Identity Cloud Services admin console; do not share this value.
Access Token URL /oauth2/v1/token An endpoint used to obtain an access token from Identity Cloud Services.
Auth URL /oauth2/v1/authorize An endpoint to obtain an authorization code from Identity Cloud Services to be further used during a 3-legged OAuth flow.
Grant Type client_credentials Required. It means the REST API to be invoked is owned by the client application.
Scope (required) urn:opc:idm:__myscopes__ This scope returns all the grants given to your application, other scopes could be used to get specific grants if necessary.

 

STEP 1: Registering a Confidential Application in Identity Cloud Services

Registering a confidential application in the Identity Cloud Services admin console will provide some key items to working with OAuth 2.0, which are Client ID, Client Secret, and Scopes.   An important step I want to mention when registering a confidential application in Identity Cloud Services is the step below that adds scopes in a field called “Grant the client access to Identity Cloud Service Admin APIs”.  In my example, and for the purposes of this article, I am giving certain scopes required to request User searches, edits, creates, and deletes, but if you were to do other things, for example manage Audit Events, that will require other scopes.  So let’s get started by registering a confidential application in Identity Cloud Services.

  1. Login as an Administrator to the Identity Cloud Services admin console
     
  2. Select the Applications tab
     
  3. Click the Add button
     
  4. Select Confidential Application
     
  5. Enter a Name (5 characters or more), optionally give a Description , and click Next
     
  6. Select Configure this application as a client now
     
  7. Select from Allowed Grant Types: Client Credentials
     
  8. From the Grant the client access to Identity Cloud Services Admin APIs click the Add button and select the following scopes:  Me, Identity Domain Administrator (Optionally you can select which makes sense in your case.)
     
  9. Click the Next button
     
  10. At the Expose APIs to Other Applications leave the default Skip for later and click the Next button.
     
  11. At the Web Tier Policy leave the default Skip for later and click the Next button.
     
  12. At the Authorization leave the default Skip for later and click the Next button.
     
  13. Click the Finish button.
     
  14. Click should get a prompt with the Client ID and Client Secret, copy these to use later.

     
  15. Click the Close button
     
  16. Click on the Activate button and choose Activate Application to confirm.

 

STEP 2:  Use cURL to get our OAuth 2.0 Token

Now that our application is registered with Identity Cloud Services, we will use the Client ID and Client Secret with the cURL command to request an OAuth 2.0 token.

IMPORTANT: The command cURL is something UNIX versions of operating systems like Linux, Solaris, macOS, etc. have built-in, but if you are using Windows you will need to download it https://curl.haxx.se/download.html in order to execute it from the command line.

 

  1. From the Identity Cloud Services Web Application that was registered get your Client ID and Client Secret; below is an example.
    Client ID: b9f132f3b9eb44e3aebe3454573efd00 Client Secret: e856256a-99d9-405a-a914-6c433330ec62
  2. Now concatenate the Client ID and Client Secret with a colon separator, and base64 encode it in UTF-8 format using the following command.  Note that the command below will only work on UNIX operating systems, so for Windows you may need to use the site https://www.base64encode.org to do the same thing.  This should generate a single value to use in the next step.
    echo -n "b9f132f3b9eb44e3aebe3454573efd00:6ce580be-3dfe-4894-bc40-178856b6baae" | base64
  3. Use the base64 encoded value from the previous step and the following cURL command to get your OAuth 2.0 token. It is important to use the leading "https://" in front of your tenant URL otherwise it will hang.  Note if you are using Windows please remove all the line breaks “ \ ” below.  The response should be your Bearer Token.
    curl -H "Authorization: Basic \ (insert your base64 encoded client id/secret here)" \ -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \ --request POST https://idcs-2efaaa80344742228b8eff451cce65be.identity.oraclecloud.com/oauth2/v1/token \ -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__"
  4. The OAuth 2.0 Token from the previous step needs to be copied.  Make sure to only copy the actual token which is the value shown below in bold blue, and not anything highlighted in red.  ALERT: Notice in the output it shows an expiration; i.e. “expires_in”:3600.  This means your token will no longer be valid after 1 hour from the time you generated it. After 1 hour you will either have to refresh the token or get a new one.
    {"access_token":"eyJ4NXQ[A large section was removed to reduce clutter] n8idMxlHS8","token_type":"Bearer","expires_in":3600}
BONUS: If you are using a UNIX OS, you can append “| awk -F"\"" '{print $4}’”  to the end of the cURL command to parse out just the Bearer token.  Just remember the default expiration of the token will be 3600 seconds from the time of the request.

 

STEP 3: Use the OAuth 2.0 Token and cURL to Send a REST Request

Now that we have our OAuth 2.0 token from the previous step, we can use the token with the cURL command again to send a REST request to the Identity Cloud Services REST API in order to do something.  Before I show you the cURL command let's break it into parts to help explain the request using the following table.

 

# Option Example
1 Method -X GET
2 Content Type Header -H "Content-Type:application/scim+json"
3 Authorization Header -H “Authorization: Bearer <your token>”
4 HTTP Protocol http or https (recommend https)
5 IDCS hostname https://idcs-2efaaa80344742228b8eff451cce65be.identity.oraclecloud.com
6 IDCS REST Endpoint /admin/v1/Users
7 IDCS Querystring ?filter=userName+co+%22tim%22 (username contains tim)

 

Now let’s use our token with the cURL command to send a request to the Identity Cloud Services REST API.  The following cURL command will work with UNIX, but for Windows please remove all the line breaks “ \ ” shown below.  If everything is successful you will get a response with a list of users in a JSON format.

curl \ -X GET \ -H "Content-Type:application/scim+json" \ -H "Authorization: Bearer (your oauth2.0 token)" \ https://idcs-2efaaa80344742228b8eff451cce65be.identity.oraclecloud.com/admin/v1/Users

 

STEP 4: The JSON Output from the Identity Cloud Services REST API

In the previous step the REST request sent using cURL returned a response in a JSON format.  JSON is an open standard that can be formatted or parsed per your needs like getting specific attributes required by your application.  This site http://www.json.org has more information to learn more about JSON and I am sure there are many more sites to provide helpful information.  Below is an example JSON response from Identity Cloud Services.

JSON Response

Using Postman to Send REST Requests

There are various tools than can be used to send REST requests that make it easier than cURL, and one very useful tool is Postman.  Postman https://www.getpostman.com/docs/will run natively on a Mac or as an add-on in the Chrome Internet browser, so if you can run Chrome you can run Postman.  I don’t want to get deep into all the things Postman can do, but if you want to try it I will show you the configurations needed to setup Postman in order to automate getting the required OAuth 2.0 token to send REST requests.  This little tip will save you a lot of time.

1. Install Postman whether it be on a Mac or an add-on in the Chrome browser

2. Click on the Headers tab

3. Add the two new Header and Value as follows.

Key Value
Authorization Bearer
Content-Type application/scim_json

4. Click on the Authorization tab

5. From the Type drop menu, select OAuth 2.0

6. Click on the button “Get New Access Token”

7. Now enter the following GET NEW ACCESS TOKEN values:

GET NEW ACCESS TOKEN

Parameter Value
Callback URL <use the default>
Token Name Bearer
Auth URL https://<tenant hostname>/oauth2/v1/authorize
Access Token URL https://<tenant hostname>/oauth2/v1/token
Client ID <Your IDCS Client ID>
Client Secret <Your IDCS Client Secret>
Scope (IDCS Required) urn:opc:idm:__myscopes__
Grant Type Client Credentials

 

8. Click the Request Token button

9. Select the Bearer row

10. Click the Use Token; this will update your Authorization header Bearer value.

11. Select the Headers tab and you will see your Authorization Bearer value updated getting

12. Above you should see GET and if not drop the menu and select it

13. Enter an Identity Cloud Services URL with some REST API endpoint; e.g.
https://idcs-2efaaa80344742228b8eff451cce65be.identity.oraclecloud.com/admin/v1/Users?filter=userName sw "tim"

14. Click the Send button.

If everything goes correctly, you should get the data you requested in a JSON response.  Note that besides the GET method shown above, the SCIM REST API allow other methods like POST, PUT, DELETE, PATCH just to name a few.  To learn more about all the possibilities of the Identity Cloud Services REST API search the official Identity Cloud Services Oracle documents.

 

IMPORTANT:Your OAuth 2.0 token you get in step 7 and 8 above will expire after 1 hour.  After 1 hour you will need to click on the Get New Access Token button again, click the Request Token, select the new Bearer token row, and finally click the Use Token button again.  You can then resend a request by clicking on the Send button.

 

Summary

Hopefully, you now have some basics on using OAuth 2.0 to access the IDCS REST API.  I used cURL because it is pretty simple to use and it helps you understand all the necessary steps needed to work with the OAuth 2.0 steps though I also introduced Postman which is a great tool.  Something else I hope I illustrated in this article are some basics in sending REST requests to the Identity Cloud Services REST API endpoints.  As I mentioned in the beginning of this article, this is really a foundational building block to using OAuth 2.0 in order to work with the Identity Cloud Services REST API.  My next article is going to expand more on the endpoints related to querying Audit Events. Until then enjoy and feel free to play around with Postman to try out some other end points and queries.

Tim Melander

A-Team Cloud Solution Architect

I started with Oracle in 2005 and been a member of the Oracle A-Team since 2012 though have worked in Identity and Access Management since 1999.  My journey with security continues the cloud that heavily includes Oracle Infrastructure Cloud (OCI).  I enjoy writing articles built on real life use cases to help in areas where a standard document may not provide. I am a strong believer in learning by example to which I try to incorporate as many helpful tips, excellent diagrams, and instructional steps as I can.


Previous Post

Identity Cloud Services Audit Reports using Visual Analyzer

Tim Melander | 12 min read

Next Post


Identity Cloud Services Audit Event REST API

Tim Melander | 10 min read