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.
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.
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.
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. |
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.
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.
Client ID: b9f132f3b9eb44e3aebe3454573efd00 Client Secret: e856256a-99d9-405a-a914-6c433330ec62
echo -n "b9f132f3b9eb44e3aebe3454573efd00:6ce580be-3dfe-4894-bc40-178856b6baae" | base64
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__"
{"access_token":"eyJ4NXQ[A large section was removed to reduce clutter] n8idMxlHS8","token_type":"Bearer","expires_in":3600}
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
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.
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:
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.
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.
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