Using OAuth 2 to Access the REST API

Step 1: Register a Confidential Application in Identity Domains Using the Console

When you register a confidential application in the identity domain Console, you obtain some of the key parameters that you need to work with OAuth 2.0: Client ID, Client Secret, and Scopes. OAuth 2.0 is a standard for implementing delegated authorization, and 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. When you register a web application in an identity domain, you add scopes. In the following example, the required scopes to request User searches, edits, creates, and deletes are added. But, if you were to do other things-for example, manage Audit Events, that would require other scopes.

To create and register a confidential application access the OCI Console and then complete the following steps:

1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
2. Click the name of the identity domain that you want to work in. You might need to change the compartment to find the domain that you want. Then, click Integrated applications.
3. Click Add application.
4. In the Add application dialog box, select Confidential Application, and then click Launch workflow.
5. On the Add application details page, enter an application name and description, and then click Next.
6. On the Configure OAuth page, under Client configuration, select Configure this application as a client now.
7. Under Authorization, select only Client Credentials as the Allowed Grant Type.
8. At the bottom of the page, select Add app roles and then click Add roles.
9. In the Add app roles panel, select Identity Domain Administrator, and then click Add.
10. Click Next and then click Finish.
11. On the application detail page, scroll down to General Information. Copy the Client ID and the Client Secret and store it in a safe place.
12. After the application is created, click Activate.

Step 2: Base64 Encode the Client ID and Client Secret

Windows

1. Launch Notepad, and then paste the client ID and client secret into Notepad.

2. Place the client ID and client secret on the same line and insert a colon between them: clientid:clientsecret

   Note
   
   Ensure that no spaces are the clientid:clientsecret attribute.

3. Save the file to C:\temp and name the file appCreds.txt.

4. In Windows Explorer, right-click C:\temp, and then select CMD Prompt Here from the context menu.

5. Enter the following command to encode the client ID and client secret:

   certutil -encode appCreds.txt appbase64Creds.txt

6. In Notepad, open C:\temp\appbase64Creds.txt, copy its contents, and then close the file.

   Note
   
   For security reasons, delete the appCreds.txt and the appbase64Creds.txt files after you finish.

Mac and Linux

1. Launch your preferred note utility (for example, Mac Notes, Gedit Linux, or Vi), and then paste the client ID and client secret into the note utility.

2. Place the client ID and client secret on the same line and insert a colon between them: clientid:clientsecret.

   Note
   
   Ensure no spaces in the clientid:clientsecret.
   statement.

3. Copy the clientid:clientsecret line.

4. Launch a terminal and enter the following command, replacing clientid:clientsecret with the value that you copied to the clipboard.

   echo -n "clientid:clientsecret" | base64 -w 0

   Note
   
   For Linux, add -w 0 to the command to remove line breaks.
5. Copy the value that's returned.

   Note
   
   If the value that's returned is broken into more than one line, return to your text editor and ensure the entire results are on a single line with no text wrapping.

Step 3: Obtain an Access Token

The next step in this process is to request the access token.

1. Launch a command prompt.

2. Enter the cURL command below, replacing the text in brackets ( < > ) with the appropriate values:

      curl -i
      -H "Authorization: Basic <base64encoded clientid:secret>"
      -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
      --request POST https://<domainURL>/oauth2/v1/token
      -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__"

   Note
   
   If you're 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 that the default expiration of the token is 3600 seconds from the time of the request.
   Note
   
   Optionally, run the following cURL command to have the access token value accessible through a UNIX variable called AccessTokenValue in your environment:

      export AccessTokenValue=`curl -i
      -H "Authorization: Basic <base64encoded clientid:secret>"
      -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
      --request POST https://<domainURL>/oauth2/v1/token
      -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__" | awk -F"\"" '{print $4}' |  tail -n +16`

   You can then run echo $AccessTokenValue command to get the access token value.

   Text in Brackets	Value
   base64encoded clientid:secret	Replace with the encoded credentials that you generated in the Base64 Encode the client ID and client secret section. Ensure no spaces in the clientid:clientsecret credentials.
   IDCS_Service_Instance	Replace with your identity domain URL (for example, https://<domainURL>/).

   Note
   
   The urn:opc:idm:__myscopes__ scope in the command is used as a tag by identity domain clients requesting access tokens from the OAuth authorization server. Access tokens are returned that contain all applicable identity domains scopes based on the privileges represented by the identity domains administrator roles granted to the requesting client and the user being specified by the client's request (if present). This scope isn't granted directly to any identity domains administrator role.

3. Copy the access_token value from the response. Ensure to copy only the actual token, which is the access_token value between the quotation marks:

   Status: 200
   "access_token":"eyJ4NXQiOiI4Wk. . ."
   "token":"Bearer",
   "expires_in":3600
   

   Note
   
   The response includes the expires_in: 3600 parameter. This means that your token is no longer valid after one hour from the time that you generate it. After one hour, you must refresh the token or get a new access token. To refresh the token, enter the cURL command below, replacing the text in brackets ( < > ) with the appropriate values:

   curl -i
     -H "Authorization: Basic <base64 encoded client ID and secret>"
     -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
     --request POST https://<domainURL>/oauth2/v1/token
     -d "grant_type=refresh_token&refresh_token=<token_value>"

Step 4: Make a REST Request to the Environment

After you obtain the OAuth 2.0 access token, you can use the token in a cURL command to send a REST request to the identity domains REST API. The following command returns a list of users in an identity domain.

   curl -X GET
   -H "Content-Type:application/scim+json"
   -H "Authorization: Bearer <access_token>"
   https://<domainURL>admin/v1/Users