REST API for Oracle Cloud Infrastructure Process Automation

Use OAuth Access Token Using Authorization Code Grant Type

This topic gives an overview of how to invoke the Oracle Cloud Infrastructure Process Automation REST APIs using OAuth access token from Oracle Identity Cloud Service using Authorization Code grant type.

Prerequisites:

Configure a Confidential Application to Authenticate with OAuth

Steps

1. Get an Authorization Code

2. Base64 Encode the Client ID and Client Secret

3. Use the Authorization Code to Get an Access Token

4. Use the Access Token in REST API Calls to Oracle Cloud Infrastructure Process Automation

OAuth Authorization Code Credentials Flow

OAuth authentication with Authorization Code grant type is used for client applications that can access a browser. You don't need to share user names and passwords with clients, or manage user passwords that expire. The following steps are performed as part of OAuth authorization code credentials flow.

Step	Description
1	The user specifies the authorization request URI. The user is redirected by the user agent (browser) to the authorization URI.
2	The resource owner logs in to authenticate and provide consent to the client application to access its resources.
3	The authorization server sends a callback request to the client application and sends the authorization code.
4	The client application extracts the authorization code from the request and uses it to send another request to the authorization server to get an access token.
5	The authorization server responds to the access token request by sending an access token to the client application.
6	The client application uses the access token to make requests for protected resources.

Authorization Flow with OAuth

With OAuth, Oracle Identity Cloud Service is the identity provider and authorization server. Oracle Cloud Infrastructure Process Automation service instance is the resource server.

The following table illustrates the OAuth authorization flow to use REST APIs.

Table -

Client Application	Oracle Identity Cloud Service(Identity Provider and Authorization server)	Oracle Cloud Infrastructure Process Automation (Resource server)
1. Request authorization code with client ID and secret `https://<idcs_URL>/oauth2/v1/authorize`
	2. Check client ID and secret, prompt for user name and password to access Oracle Cloud Infrastructure Process Automation.
3. User logs in with user name and password used to access Oracle Cloud Infrastructure Process Automation.
	4. Check user credentials. If credentials are OK, return authorization code.
5. Request access token by specifying authorization code. `https://<idcs_URL>/oauth2/v1/token`
	6. Validate and return access token.
7. Use the access token to make API calls to Oracle Cloud Infrastructure Process Automation with the header `Authorization: Bearer access_token`
		8. Receive API calls and perform requested operations.

Prerequisites

Configure a Confidential Application to Authenticate with OAuth

Steps

1. Get an Authorization Code

2. Base64 Encode the Client ID and Client Secret

3. Use the Authorization Code to Get an Access Token

4. Use the Access Token in REST API Calls to Oracle Cloud Infrastructure Process Automation

1. Get an Authorization Code

What you need:

Identity Cloud Service URL: the URL of your Oracle Identity Cloud Service instance. For example: idcs-c2881.identity.myhost.example.com
Client ID: the client ID you retrieved when you registered the confidential application in Identity Cloud Service. You can find the client ID in Oracle Identity Cloud Service, in your application. Select the Configuration tab, General Information section of the confidential application you configured in Oracle Identity Cloud Service.
Response type: Specify response_type=code for Authorization code grant type.
Scope: the scope value associated with your Oracle Cloud Infrastructure Process Automation instance registered in your confidential application. You can find this information in the confidential application you registered in Oracle Identity Cloud Service in the Configuration tab, Accessing APIs from Other Applications section, under Allowed Scopes, in the scope that you added. The scope looks like something similar to this: https://CA6ABF5D.myhost.example.com:443urn:opc:resource:consumer::all
Redirect URL: URL to which the response will be sent. Make sure your redirect URL is the same URL specified in the confidential application you configured in Oracle Identity Cloud Service. You can find the redirect URL in Oracle Identity Cloud Service in the Configuration tab, Client Configuration section of the confidential application you configured in Oracle Identity Cloud Service.

Using a browser, request an authorization code from Oracle Identity Cloud Service.

Make sure to add offline_access to the scope separated by a space.

Format:

https://<idcs_URL>/oauth2/v1/authorize?client_id=<client_ID>&response_type=code&scope=<scope> offline_access&redirect_uri=<URL_to_receive_response>

Example:

https://idcs-c2881.identity.myhost.example.com/oauth2/v1/authorize?client_id=f82f71efefcaff5ce&response_type=code&scope=https://F7E102440.myhost.example.com:443urn:opc:resource:consumer::all offline_access&redirect_uri=https://www.example.com/oauth2/callback

You'll be prompted to log in to Oracle Identity Cloud service. Use the user name and password for Oracle Cloud Infrastructure Process Automation.

For the response, you'll see the browser path replaced with something like the following. The code= is what you need to request an access token. Copy the retrieved code to a file. Note that the access code expires in a very short time.

For example:

https://www.example.com/oauth2/callback?code=iEipsLiGBfl-fpyqvguBMlBxIp7wZMTEUllQCAAQIDBST9=

2. Base64 Encode the Client ID and Client Secret

You must encode the client ID and client secret when you include it in a request for an access token.

Example - Windows

There are many utilities to base64 encode on Windows, including plugins in Notepad++ for example. Use the tool that best fits your needs.

Create a file in Notepad and copy the client ID and client secret on one line, separated by a colon, and save the file. For example:
```
ff8c2aff5ce:b8fe45-97ff-bae8d558f
```
Open a command prompt and use the certutil command to encode the client ID and client secret. Specify your original file, and a new encoded file:

For example:
```
certutil -encode original_creds.txt encoded_creds.txt
```
Open your encoded file, for example, encoded_creds.txt and copy the encoded client and secret to use in your REST API calls.

Important:
For security reasons, delete the original_creds.txt and the encoded_creds.txt files after you finish.

Example - Mac and Linux

Create a file in a text editor and copy the client ID and client secret on one line, separated by a colon, and save the file. For example:
```
ff8c2aff5ce:b88fe45-97ff-bae8d558f
```
Copy the client and secret.
Launch a terminal and enter the following command, replacing clientid:clientsecret with the value that you just copied to the clipboard.
```
echo -n "clientid:clientsecret" | base64 -w 0
```
Note:
If returned value is broken into more than one line, fix this in your text editor to make sure the results are on a single line with no text wrapping.
Copy the value that is returned. You will need to specify it to get an access token.

3. Use the Authorization Code to Get an Access Token

Use the client ID and client secret for the confidential application to request the access token from Oracle Identity Cloud Service. You'll specify the access token when making REST API calls to Oracle Cloud Infrastructure Process Automation. There is one access token per user.

Launch a command prompt.
Enter the cURL command in the following format, replacing the text in brackets ( < > ) with the appropriate values:

Format:
```
curl -i  -H 'Authorization: Basic <base64_encoded_client_id:client_secret>' --request POST 'https://<idcs_url>/oauth2/v1/token' -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=authorization_code&code=<authorization_code_value>'
```
```
curl -i  -H 'Authorization: Basic NzGVjMmZkNDYjYyYMS0GEtOlNjkxZWQ0' --request POST ’https://idcs-a0287b.identity.myhost.example.com/oauth2/v1/token' -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=authorization_code&code=G0bbfB0bA-9Sa2h-DyuKpB7djF9'
```
You will receive an access token that you can use in your REST API calls. Copy what you receive to a file, including the refresh token. The access token is valid for 1 hour(3600 seconds) by default. You'll need to use the included refresh token to refresh your token when it expires. Copy the access_token value from the response to use in REST API calls to Oracle Cloud Infrastructure Process Automation.

4. Use the Access Token in REST API Calls to Oracle Cloud Infrastructure Process Automation

Make your API call and specify the access token in the authorization header.

The header has the form:

Authorization: Bearer access_token

For example, to create a new application from another version:

curl --request PUT '/process/api/v1/design/applications/TravelRequest/versions/1.0/version' --header 'Authorization: Bearer ' --header 'Content-Type: application/json' --data-raw '{"newVersion": "1.1"}'