Retrieve Bearer Token Using Oracle Identity Cloud Service (IDCS) OAuth 2.0 REST API

To use the ERP Data Integrations REST operations appropriate authorization is required. A Bearer Token associated with the relevant Fusion Application user should be retrieved and included in the request header during the invocation of these services.

OAuth in the context of Oracle Applications uses an auto-generated token (a JSON Web Token, also known as JWT) to grant access to the required resources. The process to get a JWT token involves a few steps. In this topic, you'll find the configuration instructions along with explanatory content to help you understand the overall setup.

The OAuth 2.0 framework provides various grant types for different use cases, applications can request an access token to access protected REST endpoints in different ways depending on the grant type specified in the client application. In this case, we shall use the Client Credentials grant type to retrieve the bearer token.

Note:

Make sure that you or other required users have the necessary privileges to access the Identity and Access Management Admin Console to navigate to the identity domain. For details, see Managing Users.

Before You Proceed Further

Configuring OAuth requires you to be familiar with Oracle Cloud Infrastructure Identity and Access Management, and have experience with creating and maintaining identity domains. To learn more, see Overview of IAM.

At a high-level, the configuration involves the following:

1. Create a temporary confidential integrated application.
2. Create an IDCS application using Create an App REST API.
3. Create a Fusion Application user.
4. Get an access token using IDCS OAuth 2.0 REST API.

Step 1: Create a Temporary Confidential Integrated Application

Create a temporary Confidential Application in IDCS to generate a Client ID and Client Secret that will be used to request the access token.

1. Sign in to the Oracle Identity Cloud Service as an Administrator.
2. From the list of identity domains, click Integrated Applications and click Add application.
3. On the Add application dialog box, select Confidential Application and click Launch workflow.
4. On the Add Confidential Application page, enter a name for the application that you're adding.
5. Skip all other fields and click Next.
6. In the Configure OAuth section, skip the Resource server configuration section by selecting Skip for later.
7. In the Client configuration section, select Configure this application as a client now to proceed with the client configuration settings.
8. In the Authorization section, select the Client credentials and JWT assertion checkbox to specify the grant types.
9. Retain the Client type value as Confidential.
10. In the Token issuance policy section, select the Add app roles checkbox.
11. Click Add roles and search for the Identity Domain Administrator role. Select the role and click Add to add this role.
12. On the Configure policy page in the Web tier policy section, select Skip and do later.
13. Click Finish to complete the application creation. You're taken to the application page that you just created.
14. Click Activate. A confirmation message appears asking for a confirmation to activate the application.
15. Click Activate application. The confidential application is activated and ready for use.

Step 2: Create an IDCS Application Uing Create an App REST API

1. Generate JWT Bearer token to authorize IDCS application creation using IAM Create an App API.

   1. Navigate to the new temporary confidential application page created in Step 1.
   2. In the Resource section, click the Access token link.
   3. Click Download token to download a .tok file and save it locally.
   4. Open the file in any text editor and copy the "access_token" attribute value from the JSON text. You can use this value for authorization.
2. Create an IDCS application using Create an App REST API. You can do so using a client application such as Postman, or cURL command.

   Note:

   After the application creation, the Client ID can't be changed. Ensure that the appropriate user is used while invoking the API.
   Using cURL command

   1. Open a terminal/shell that supports the curl command.
   2. Enter the cURL command below, replacing the text in angle brackets ( < > ) with the appropriate values:

      curl -X POST -H "Authorization: Bearer <GENERATED_JWT_BEARER>" -H "Content-Type: application/json" -d '{"schemas": ["urn:ietf:params:scim:schemas:oracle:idcs:App"], "displayName": "<IDCS_APPLICATION_NAME>", "isOAuthClient": true, "description": "<ANY_DESCRIPTION_TEXT>", "active": true, "clientType": "confidential", "basedOnTemplate": {"value": "CustomWebAppTemplateId"}, "allUrlSchemesAllowed": true, "allowedScopes": [{"fqs": "<IDCS_RESOURCE_SCOPE>"}], "allowedGrants": ["client_credentials"], "showInMyApps": false, "name": "<FA_USER_NAME>"}' "https://<IDCS_HOST>/admin/v1/Apps"

      cRUL Element	Description
      GENERATED_JWT_BEARER	The Bearer token that was created from the temporary IDCS Confidential application.
      IDCS_APPLICATION_NAME	The display name of the IDCS Confidential application.
      ANY_DESCRIPTION_TEXT	Any text description of the IDCS Confidential application.
      IDCS_RESOURCE_SCOPE	The scope of the resource that you want your new app to communicate with (For example, if you want to create an app that will generate an OAuth token for accessing Core ERP Spectra service APIs, then the scope would be urn:opc:resource:fusion:cptauuaqy:erp/)
      FA_USER_NAME	The name of the Fusion Applications user to be attached to Spectra API calls. This will also be the Client ID of the new IDCS Confidential Application created by the REST API call.
      IDCS_HOST	The host of IDCS instance associated with FA environment/pod.

   3. You can expect the response in a JSON (in text format) file. That should contain the JWT Bearer token value.
   Using Postman

   1. In Postman, create a new POST request.

      https://<IDCS_HOST>/admin/v1/Apps

   2. On the Authorization tab, set the Type value to the Bearer token and provide the bearer token that was created from the temporary IDCS Confidential application.
   3. On the Body tab, choose type as raw and change the format selector from Text to JSON.
   4. Enter the below request payload, replacing the text in angle brackets ( < > ) with the appropriate values:

      {
          "schemas": [
              "urn:ietf:params:scim:schemas:oracle:idcs:App"
          ],
          "displayName": "<IDCS_APPLICATION_NAME>",
          "isOAuthClient": true,
          "description": "<ANY_DESCRIPTION_TEXT>",
          "active": true,
          "clientType": "confidential",
          "basedOnTemplate": {
              "value": "CustomWebAppTemplateId"
          },
          "allUrlSchemesAllowed": true,
          "allowedScopes": [
              {
                  "fqs": "<IDCS_RESOURCE_SCOPE>"
              }
          ],
          "allowedGrants": [
              "client_credentials"
          ],
          "showInMyApps": false,
          "name": "<FA_USER_NAME>"
      }
      

   5. Click Send to submit the API request to the IAM Admin API.
   6. If the request is successful, you will receive an HTTP 201 response in JSON format containing metadata related to the IDCS Confidential Application. You can review and verify the response body to verify all the parameters submitted in the API request body were processed correctly.
3. You have successfully created a new IDCS application. Get the Client ID and Client Secret associated with the new IDCS application.

   1. Sign in to the Fusion Applications identity domain as an Administrator.
   2. From the list of identity domains, click Integrated Applications and verify that the new application is in Active status.
   3. Note the Client ID and Client secret associated with the new IDCS application.
   4. You can delete the temporary IDCS application created in prior Step 1 if there is no requirement to create more IDCS Confidential Applications for the environment/pod.

Step 3: Create a Fusion Applications User

This step is required if the generated token is used with a service that verifies the token using both Fusion Applications and IDCS.

1. Login to Fusion Applications with the appropriate credentials to access the Security Console.

2. Navigate to Tools > Security Console > Users.

3. Click Add User Account.

4. Enter all the relevant user information. For User Name, enter the Client ID of the IDCS Confidential application created Step 2.

5. To import the changes submit the Import User and Role Application Security Data ESS program.

   1. Navigate to Tools > Scheduled Process, and click Schedule New Process.

   2. Search and submit the Import User and Role Application Security Data job.

6. You are ready to invoke the dependent Spectra APIs using the new IDCS Confidential application.

Step 4: Get an Access Token Using IDCS OAuth 2.0 REST API

Get an access token using IDCS OAuth2 REST API. You can do so using a cURL command or client application such as Postman and Postman's Configure New Token OAuth 2.0 feature.

Using cURL command

• Open a terminal/shell that supports the curl command. For example, the Terminal app on MacOS.

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

  curl -X POST -u <CLIENT_ID>:<CLIENT_SECRET> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&scope=<SCOPE>" "https://<IDCS_HOST>/oauth2/v1/token"

  In the above command, <SCOPE> refers to a URL-safe concatenation of the IDCS resource audience and scope. For example, for a Spectra-ERP resource whose audience is usually urn:opc:resource:fusion:<POD>:erp and scope is usually /, the URL safe scope above would be –urn%3Aopc%3Aresource%3Afusion%3Acptauuaqy%3Aerp%2F for the CPTAUUAQY pod.

• If the API is successfully invoked, it returns a JSON (in text format) containing the JWT Bearer token value.

Using Postman

1. In Postman, create a new POST request.

   https://<IDCS_HOST>/oauth2/v1/token

2. On the Authorization tab, select Basic Auth as the Authorization Type.
3. In the Username field, enter the IDCS Confidential Application Client ID that you have created. Enter the Client Secret of the same IDCS Confidential Application in the Password field.
4. On the Body tab, choose the type as x-www-form-urlencoded and add the following key-value pairs to the body (variable values are italicized):

   Key	Value
   grant_type	client_credentials
   scope	The audience + scope of the target resource for the generated token. For example, urn:opc:resource:fusion:<POD_NAME>:erp/ for Spectra ERP.

5. Click Send to submit the IDCS OAuth2.0 API request. If the request is successful, an HTTP 200 response is received in JSON format with the following details:
   • access_token: Provides the JWT Bearer token with the specified user as the subject/principal. You can use this token for future API invocations until it expires.
   • token_type: Indicates the type of token.
   • expires_in: Indicates the Time (in seconds) for which the access token will be valid for authentication. Typically, this will be 3600 unless that setting is changed during the IDCS Confidential Application creation.

Using Postman's Configure New Token OAuth 2.0 feature

1. In Postman, create a new POST request.
2. On the Authorization tab, select OAuth 2.0 as the Authorization Type.
3. In the Configure New Token section, enter the following client configuration:
   • Token Name: Enter a generic name for the token. The JWT Bearer token will be saved with this name in Postman.
   • Grant Type: Set the grant type to Client Credentials.
   • Access Token URL: Enter <IDCS_HOST>/oauth2/v1/token. Replacing the text in angle brackets ( < > ) with the appropriate values.
   • Client ID: The Client ID of the IDCS Confidential Application created earlier.
   • Client Secret: The Client secret of the IDCS Confidential Application created earlier.
   • Scope: The audience + scope of the target resource for the generated token. For example, urn:opc:resource:fusion:<POD_NAME>:erp/ for Spectra ERP.
   • Client Authentication: Set the client authentication to Send as Basic Auth header.
4. Click Get New Access Token. Postman passes on the information to the identity domain to authenticate and returns the access token.
5. If the request is completed successfully, a confirmation message will be displayed and the user will be provided an option to use the token for the current request. The token is also saved automatically and available for other API requests, it can be selected from the list of Available Tokens when OAuth 2.0 authorization is configured.