1. Integration Guide
  2. OAuth 2

OAuth 2

OAuth 2 Client Credentials flow is available as the authentication protocol for inbound REST API and XML integration using HTTP POST. The authorization service is managed by Oracle Identity Cloud Service (IDCS) (also used for single sign-on application user accounts).

The following steps must be followed to configure an external integration application to use OAuth 2 for inbound integration.

  1. Configure external integration application in IDCS to obtain client ID and secret
  2. Assign client ID generated in step 1 above as Nickname for Transportation and Global Trade Management Cloud integration user account, i.e. user account authorized to process inbound integration messages for all required application resources.

IDCS Configuration

Note: The following instructions assume that the user has already obtained a valid account and URL for access to the IDCS Administration console.

The following steps are taken from the online documentation for Oracle Identity Cloud Service. Refer to the online documentation for up-to-date steps.

  1. Log in to IDCS administration console using the credentials provided.
  2. Under Identity domain click Applications.
  3. Click Add application.
  4. Select Confidential Application and click Launch workflow.
  5. Provide a Name and click Next.
  6. Resource Server Configuration
    1. Select "Configure this application as a resource server now" .
    2. Provide a value for Access token expiration.
    3. Provide a value for the Primary Audience, e.g. https://{host-id}/ where {host-id} is the Transportation and Global Trade Management Cloud server. The actual value may depend on whether the target application is REST API - https://{host-id}/logisticsRestApi/ - or XML integration - https://{host-id}/logisticsXmlApi/.
    4. Select Add scopes and click Add.
    5. Enter a unique name for the Scope. This can be any text, this scope name will be selected or used at later steps.
  7. Client Configuration
    1. Select Configure this application as a client now and Client Credentials as the Allowed Grant Types.
  8. Select Next.
  9. Under Web tier policy select Skip and do later.
  10. Click Finish.
  11. Click Edit OAuth configuration.
  12. Under Client configuration > Token Issuance policy select “Add resources".
  13. Click Add scope, select the drop-down against the Confidential application we are created and select the available scope under this application and click Add.
  14. Click Save Changes.
  15. Click Activate and Activate application.
  16. Make a secure note of the Client ID and Client Secret. These will be used by the external application to authenticate with IDCS when using the target application and when configuring the application user Nickname.

Transportation and Global Trade Management Cloud Configuration

  1. Obtain the Client ID associated with target application previously configured in IDCS.
  2. Edit the integration user account via the User Manager page.
  3. Place the Client ID in the Nickname field.
  4. Save.

Runtime Authentication

The OAuth 2 Client Credentials protocol works by completing the following stages, which MUST be performed using HTTPS:

  1. Client submits Authorization request to obtain a token.
  2. Client requests resource and pass token.

The first step requires the URL for the IDCS instance:

https://<IDCS-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token

The HTTP request will use HTTP Authentication (Basic) header to pass the Client ID and Client Secret. The message body will use the “x-www-form-url-encoded” content type to send the following name/value parameters in the message body:

  • grant_type=client_credentials
  • scope=[Copy the scope from the Confidential Application Client configuration > Token Issuance policy > Resources > Scope.]

A successfully authenticated request will receive the HTTP 200 status code and a JSON message body containing the required "Access Token". This access token must then be passed as the HTTP "Authorization: Bearer" header.