IDCS OAuth 2.0 and REST API

Introduction

This article is to help expand on topics of integration with Oracle’s Cloud Identity Management service called Identity Cloud Service (IDCS).  IDCS 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 IDCS 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 IDCS user interface you can probably do it using the IDCS 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 IDCS 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. 1. Login to the IDCS 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 IDCS, the following sequence diagram will help to illustrate the OAuth 2.0 authorization flow according to how we will access the IDCS 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 IDCS REST API otherwise things can get convoluted.

The table below includes some important OAuth 2.0 parameters we will be working with IDCS 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 IDCS admin console.
Client Secret <client_secret> Required. A private key similar to a password that is generated when registering your application in the IDCS admin console; do not share this value.
Access Token URL /oauth2/v1/token An endpoint used to obtain an access token from IDCS.
Auth URL /oauth2/v1/authorize An endpoint to obtain an authorization code from IDCS 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 Web Application in IDCS

Registering a web application in the IDCS 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 web application in IDCS 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 web application in IDCS.

 

1. Login as an Administrator to the IDCS admin console
2. Select the Applications tab
3. Click the Add button
4. Use the default Web Application and click Next
5. Enter a Name (5 characters or more) and also give some Description
6. Select Allowed Grant Types: Client Credentials
7. At the bottom check the Grant the client access to Identity Cloud Service Admin APIs and add the following scopes:  Me, Identity Domain Administrator
8. Click the Finish button
9. You should get a prompt with the Client ID and Client Secret, copy these to use later.

 

  1. Application Added
    1. 10. Click the Close button
      11. Click the Activate button and click Activate Application to confirm
      12. Click the Save button; you should get a confirmation.

 

STEP 2:  Use cURL to get our OAuth 2.0 Token

Now that our application is registered with IDCS, 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. 1. From the IDCS Web Application that was registered get your Client ID and Client Secret; below is an example.
  2.      Client ID:          3ebb5563c01246e28450b371fc16cebe
         Client Secret:    e856256a-99d9-405a-a914-6c433330ec62 
  3. 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.
  4.      echo -n “12b844740cec48068a8892dccc3f96e9:6ce580be-3dfe-4894-bc40-178856b6baae” | base64
  5. 3. Use the base64 encoded value from the previous step and the following cURL command to get your OAuth 2.0 token.  Please remove all the line breaks “ \ ” below if you are using Windows.  The response should be your Bearer Token.
  6.      curl \
         -H “Authorization: Basic <your base64 encoded client id/secret>” \
         -H “Content-Type: application/x-www-form-urlencoded;charset=UTF-8” \
         –request POST tenant1.idcs.internal.oracle.com:8990/oauth2/v1/token \
         -d “grant_type=client_credentials&scope=urn:opc:idm:__myscopes__”
  7. 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.
  8.      {“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 IDCS 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:port tenant1.mycompany.com:8990
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 IDCS 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>” \
     http://tenant1.idcs.internal.oracle.com:8990/admin/v1/Users

 

BONUS: If you are using a UNIX OS, you can append “ | python –m json.tool “ at the end of the cURL command to format the JSON response in a pretty format.  Windows will have to install python or use something else.

 

STEP 4: The JSON Output from the IDCS 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 IDCS.

 

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 <http/https>://<tenant hostname:port>/oauth2/v1/authorize
Access Token URL <http/https>://<tenant hostname:port>/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 IDCS URL with some REST API endpoint; e.g.
https://tenant.mycompany.com:8990/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 IDCS REST API search the official IDCS 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 IDCS 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 IDCS 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.

Add Your Comment