1. Using the SOAP Adapter with Oracle Integration 3
  2. SOAP Adapter Concepts
  3. Authenticate Requests for Invoking Oracle Integration Flows
  4. Use OAuth 2.0 Grants in Identity Domain Environments

Use OAuth 2.0 Grants in Identity Domain Environments

To use an OAuth 2.0 grant type with this adapter in an identity domain environment of Oracle Integration, you must perform the following prerequisites.

Access the Identity Domain

  • Log in to the Oracle Cloud Infrastructure Console with your identity domain administrator credentials.
    1. In the navigation pane, click Identity & Security.
    2. Click Domains.
    3. Select your compartment.
    4. Click the identity domain.


      The Domains page shows a Create domain button and the following two columns of a table: Name and Domain type.

    5. In the navigation pane, click Integrated applications.

      This is the location at which you create the client application for your grant type.


      The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, Users, Groups. Dynamic groups, Integrated applications, Oracle Cloud Services, Jobs, Reports, Security, Settings, Notifications, and Branding.

Prerequisites for Client Credentials and Resource Owner Password Credentials

To trigger the integration with OAuth, a client application is required. The prerequisites for the client credentials and resource owner password credentials grant types are very similar.

Configure the client application

  1. Click Add application.
  2. Select Confidential Application, then click Launch workflow.


    The Add application dialog shows selections for Application Catalog, SAML Application, Mobile Application, Confidential Application, and Enterprise Application.

  3. Enter a name. The remaining fields on this page are optional and can be ignored.
  4. Click Next.
  5. In the Client configuration box, select Configure this application as a client now.
  6. Select the grant type to use:
    1. For client credentials, select Client credentials in the Allowed grant types section.


      The Client configuration dialog shows radio buttons for Configure this application as a client now and Skip for later. The Authorization section shows the Allowed grant types. Options are available for Resource owner, Client credentials, JWT assertion, Refresh token, Device code, Authorization code, Implicit, SAML2 assertion, and TLS client authentication.

    2. For resource owner password credentials, select Resource owner and Refresh token in the Allowed grant types section.


      The Client configuration dialog shows radio buttons for Configure this application as a client now and Skip for later. The Authorization section shows the Allowed grant types. Options are available for Resource owner, Client credentials, JWT assertion, Refresh token, Device code, Authorization code, Implicit, SAML2 assertion, and TLS client authentication.

  7. Complete the following steps for either grant type:
    1. Leave the Redirect URL, Post-logout redirect URL, and Logout URL fields blank.
    2. For Client type, ensure that Confidential is selected.
    3. Bypass several fields and scroll down to the Token issuance policy section.
    4. Select Specific in the Authorized resources section.


      The Token issuance policy section shows a subsection for Authorized resources, which includes selections for All and Specific.

    5. Click the Add Resources check box.
    6. Click Add scope.
    7. Find the Oracle Integration application for your instance, and click Open details icon.
    8. Select the two scopes appended with the following details:
      • urn:opc:resource:consumer::all
      • ic/api/
    9. Click Add.

      The scopes are displayed in the Resources section.


      The Resources dialog shows tabs for Add scope and Remove. Below is a table with a column that shows check boxes, and additional columns for Resource, Protected, and Scope.

    10. Ignore the Add app roles check box. This selection is not required.
    11. Click Next, then click Finish.

    The details page for the client application is displayed.

  8. Click Activate, and then Activate application to activate the client application for use.
  9. In the General Information section, note the client ID and client secret values. These values are required for the third-party application that is communicating with the identity domain.


    The General Information section shows fields for Client ID and Client secret. Below this are links for Show secret and Regenerate.

Add roles to the client application

  1. In the navigation pane, click Oracle Cloud Services.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, Users, Groups. Dynamic groups, Integrated applications, and Oracle Cloud Services.

  2. Select the specific application corresponding to the Oracle Integration instance.
  3. In the navigation pane, click Application roles.
  4. If configuring the client credentials grant type, select the following:
    1. Expand ServiceInvoker, then click Manage next to Assigned applications.


      The Application roles dialog shows buttons for Import and Export. Below is a table with a column of check boxes, and additional columns for Name and Description. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Assigned users, Assigned groups, and Assigned applications. Each entry includes a link named Manage.

    2. Click Show available applications.
    3. Select the application you just created and click Assign, then click Close.
  5. If configuring the resource owner password credentials grant type, select the following:
    1. Expand ServiceInvoker, then click Manage next to either Assigned users or Assigned groups. For example, if you click Assigned users:


      The Application roles dialog shows buttons for Import and Export. Below is a table with a column of check boxes, and additional columns for Name and Description. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Assigned users, Assigned groups, and Assigned applications. Each entry includes a link named Manage.

    2. Click Show available users.
    3. Select the user and click Assign, then click Close.
  6. Validate the client application for the grant type you are using.
    1. For the client credentials grant type:
      1. Fetch the access client to make an access token request with the client credentials.
        ##Syntax
curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=client_credentials&scope=<app scope>'
###where
#### <base64-clientid-secret> - Base 64 encode clientId:ClientSecret
#### <app scope> - Scope added while creating application in client configuration section (Ends with urn:opc:resource:consumer::all)
 
##Example
curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<identity_domain_host>/oauth2/v1/token -d 'grant_type=client_credentials&scope=https://<Resource APP Audience>urn:opc:resource:consumer::all'

        Where Identity_Domain_Service_Instance is the value in the Domain URL field.


        The Overview page for the domain shows buttons for Change domain type, Edit domain, Add tags, and Reset all passwords. Below are the Domain information and Tags tabs. Below this are Labels (and their values) for OCID, Domain type, Description, Domain replication, Created, Show domain on login, Domain URL, and Status.

      2. Capture the access_token from the response.
        {
    "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
    "token_type": "Bearer",
    "expires_in": 3600
}
      3. Use the access_token in the authorization header to invoke the trigger endpoint.
        curl --location --request GET 'https://OIC host/OIC endpoint' \
--header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'
    2. For the resource owner password credentials grant type:
      1. To fetch the access client, make a request with the user name and password in the payload.
        ##Syntax
curl -i -H 'Authorization: Basic <base64Encoded_clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=password&username=<user-name>&password=<password>&scope=<App_Scope>%20offline_access'
 
###where
#### <base64-clientid-secret> - Base 64 encode clientId:ClientSecret
#### <username> - user for token needs to be issued (must be in serviceinvoker role).
#### <password> - password for above user
#### <app_scope> - Scope added while creating application in client configuration section (Ends with urn:opc:resource:consumer::all)
##Example
curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<identity_domain_host>/oauth2/v1/token -d 'grant_type=password&username=sampleUser&password=SamplePassword&scope=https://<Resource_APP_Audience>urn:opc:resource:consumer::all%20offline_access'
      2. Capture the access_token and refresh_token from the response.
        {
    "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc="
}
      3. Use the access_token in the authorization header to invoke the Oracle Integration trigger endpoint.
        curl --location --request GET 'https://OIC host/OIC endpoint' \
--header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'
      4. To update the access token, use the refresh token and make a request.
      5. Capture the access_token and refresh_token from the response for further use.
        curl -i -H 'Authorization: Basic <base64-clientid-secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=<refresh_token>'
 
##Example
curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc='

Prerequisites for JWT User Assertion

Generate the key

You must first generate the key to import when you configure the client application for the JWT user assertion.

  1. Generate the self-signed key pair. 
    keytool -genkey -keyalg RSA -alias <your_alias> -keystore <keystore_file> -storepass <password> -validity 365 -keysize 2048
 
##example
keytool -genkey -keyalg RSA -alias assert -keystore sampleKeystore.jks -storepass samplePasswd -validity 365 -keysize 2048
  2. Export the public key for signing the JWT assertion.
    keytool -exportcert -alias <your_alias> -file <filename> -keystore <keystore_file> -storepass <password>
 
##example
keytool -exportcert -alias assert -file assert.cer -keystore sampleKeystore.jks -storepass samplePasswd
 
## This should show a success message e.g. Certificate stored in file <assert.cer>
  3. Convert the keystore to P12 format.
    keytool -importkeystore -srckeystore <filename> -srcstorepass <password> -srckeypass <password> -srcalias <your_alias> -destalias <your_alias> -destkeystore <destFileName> -deststoretype PKCS12 -deststorepass <password> -destkeypass <password>
 
##example
keytool -importkeystore -srckeystore sampleKeystore.jks -srcstorepass samplePasswd -srckeypass samplePasswd -srcalias assert -destalias assert -destkeystore assert.p12 -deststoretype PKCS12 -deststorepass samplePasswd -destkeypass samplePasswd
 
## This should show a success message e.g. Importing keystore sampleKeystore.jks to assert.p12...
  4. Export the private key from the P12 keystore.
    openssl pkcs12 -in <destFileName> -nodes -nocerts -out <pem_file>
 
##example
openssl pkcs12 -in assert.p12 -nodes -nocerts -out private_key.pem
 
## This should show a success message: MAC verified OK

Configure the client application

To trigger the integration with OAuth, a client application is required.

  1. Click Add application.
  2. Select Confidential Application, and click Launch workflow.


    The Add application dialog shows selections for Application Catalog, SAML Application, Mobile Application, Confidential Application, and Enterprise Application.

  3. Enter a name. The remaining fields on this page are optional and can be ignored.
  4. Click Next.
  5. In the Client configuration box, select Configure this application as a client now.
  6. For JWT user assertions, select JWT assertion and Refresh token in the Allowed grant types section.


    The Client configuration dialog shows radio buttons for Configure this application as a client now and Skip for later. The Authorization section shows the Allowed grant types. Options are available for Resource owner, Client credentials, JWT assertion, Refresh token, Device code, Authorization code, Implicit, SAML2 assertion, and TLS client authentication.

  7. Complete the following steps for the grant type:
    1. Leave the Redirect URL, Post-logout redirect URL, and Logout URL fields blank.
    2. In the Client type section, select Trusted.


      The Client type section shows options for Trusted and Confidential. Below this is the Certificate section, with a button for Import certificate. Below this is the Allowed operations section, with options for Introspect and On behalf of.

    3. Upload the certificate created in section Generate the key. This action adds the certificate as a trusted partner.
    4. Bypass several fields and scroll down to the Token issuance policy section.
    5. Select Specific in the Authorized resources section.


      The Token issuance policy section shows a subsection for Authorized resources, which includes selections for All and Specific.

    6. Click the Add Resources check box.
    7. Click Add scope.
    8. Find the Oracle Integration application for your instance, and click Open details icon.
    9. Select the two scopes appended with the following details:
      • urn:opc:resource:consumer::all
      • ic/api/
    10. Click Add.

      The scopes are displayed in the Resources section.


      The Resources dialog shows tabs for Add scope and Remove. Below is a table with a column that shows check boxes, and additional columns for Resource, Protected, and Scope.

    11. Ignore the Add app roles check box. This selection is not required.
    12. Click Next, then click Finish.

      The details page for the client application is displayed.

    13. Click Activate, and then Activate application to activate the client application for use.
    14. In the General Information section, note the client ID and client secret values. These values are required for the third-party application that is communicating with the identity domain.


      The General Information section shows fields for Client ID and Client secret. Below this are links for Show secret and Regenerate.

  8. In the navigation pane, click Oracle Cloud Services.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, Users, Groups. Dynamic groups, Integrated applications, and Oracle Cloud Services.

  9. Select the specific application corresponding to the Oracle Integration instance.
  10. In the navigation pane, click Application roles.
  11. Expand ServiceInvoker, then click Manage next to either Assigned users or Assigned groups. For example, if you click Assigned users:


    The Application roles dialog shows buttons for Import and Export. Below is a table with a column of check boxes, and additional columns for Name and Description. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Assigned users, Assigned groups, and Assigned applications. Each entry includes a link named Manage.

  12. Click Show available users.
  13. Select the user and click Assign, then click Close.

Add a certificate as a trusted partner

In addition to importing the signing certificate into the client application, you are also required to include the certificate as a trusted partner certificate.
  1. In the navigation pane, click Settings.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, Users, Groups. Dynamic groups, Integrated applications, Oracle Cloud Services, Jobs, Reports, Security, and Settings.

  2. Click Trusted partner certificates.
  3. Click Import certificate to upload the certificate created in section Generate the key.

Generate the JWT user assertion

  1. Generate the JWT user assertion using the generated private key and simple Java code.

    Note:

    You can use the https://github.com/jwtk/jjwt library to generate the user assertion. There are many libraries listed at https://jwt.io/ for multiple technologies. 
    Sample:
header:
{
"alg": "RS256",
"typ": "JWT",
"kid": "assert"
}
 
payload:
{
"sub": "ssaInstanceAdmin",
"jti": "8c7df446-bfae-40be-be09-0ab55c655436",
"iat": 1589889699,
"exp": 1589909699,
"iss": "d702f5b31ee645ecbc49d05983aaee54",
"aud": "https://identity.oraclecloud.com/"
}
    Where:
    • sub specifies the user name for whom user assertion is generated.
    • jti is a unique identifier
    • iat is issued (epoch seconds).
    • exp is the token expiry (epoch seconds).
    • iss is the client ID.
    • aud must include the identity domain audience https://identity.oracle.com/. The signing algorithm must be RS256.
    • kid specifies the key to use to verify the signature. Therefore, it must match with the uploaded certificate alias.

Validate the client application

  1. Once you generate the JWT user assertion, generate the access token as follows.
    ##Syntax
curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<user assertion>&scope=<app_scope>'
  
###where
#### grant type - urn:ietf:params:oauth:grant-type:jwt-bearer
#### <base64-clientid-secret> - Base 64 encode clientId:ClientSecret
#### <user assertion> - User assertion generated
#### <app scope> - Scope added while creating application in client configuration section (Ends with urn:opc:resource:consumer::all)
  2. Capture the access_token from the response.
    {
    "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
    "token_type": "Bearer",
    "expires_in": 3600
}
  3. Use an access_token in the authorization header to invoke the Oracle Integration trigger endpoint.
    curl --location --request GET 'https://OIC host/OIC endpoint' \
--header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'

Prerequisites for Authorization Code

Configure the client application

To trigger the integration with OAuth, a client application is required.

  1. Click Add application.
  2. Select Confidential Application. then click Launch workflow.


    The Add application dialog shows selections for Application Catalog, SAML Application, Mobile Application, Confidential Application, and Enterprise Application.

  3. Enter a name. The remaining fields on this page are optional and can be ignored.
  4. Click Next.
  5. In the Client configuration box, select Configure this application as a client now.
  6. Select the grant type to use:
    1. For authorization code, select Refresh token and Authorization code in the Allowed grant types section.


      The Client configuration dialog shows radio buttons for Configure this application as a client now and Skip for later. The Authorization section shows the Allowed grant types. Options are available for Resource owner, Client credentials, JWT assertion, Refresh token, Device code, Authorization code, Implicit, SAML2 assertion, and TLS client authentication.

    2. In the Redirect URL field, enter the redirect URL of the client application. After user login, this URL is redirected to with the authorization code. You can specify multiple redirect URLs. This is useful for development environments in which you have multiple instances, but only one client application due to licensing issues.

      Note:

      If you don't know the following information, check with your administrator:

      • If your instance is new or upgraded from Oracle Integration Generation 2 to Oracle Integration 3.
      • The complete instance URL with the region included (required for new instances).
      For Connections… Include the Region as Part of the Redirect URL? Example of Redirect URL to Specify…
      Created on new Oracle Integration 3 instances Yes. 
      https://OIC_instance_URL.region.ocp.oraclecloud.com/icsapis/agent/oauth/callback

      Created on instances upgraded from Oracle Integration Generation 2 to Oracle Integration 3

      		 No.

      This applies to both:

      • New connections created after the upgrade
      • Existing connections that were part of the upgrade
      		 
      https://OIC_instance_URL.ocp.oraclecloud.com/icsapis/agent/oauth/callback
    3. In the Client type section, click Confidential.
    4. Select Specific in the Authorized resources section.


      The Token issuance policy section shows a subsection for Authorized resources, which includes selections for All and Specific.

    5. Click the Add Resources check box.
    6. Click Add scope.
    7. Find the Oracle Integration application for your instance, and click Open details icon.
    8. Select the two scopes appended with the following details:
      • urn:opc:resource:consumer::all
      • ic/api/
    9. Click Add.

      The scopes are displayed in the Resources section.


      The Resources dialog shows tabs for Add scope and Remove. Below is a table with a column that shows check boxes, and additional columns for Resource, Protected, and Scope.

    10. Ignore the Add app roles check box. This selection is not required.
    11. Click Next, then click Finish.

      The details page for the client application is displayed.

    12. Click Activate, and then Activate application to activate the client application for use.
    13. In the General Information section, note the client ID and client secret values. These values are required for the third-party application that is communicating with the identity domain.


      The General Information section shows fields for Client ID and Client secret. Below this are links for Show secret and Regenerate.

Validate the Oracle Integration application and user roles

  1. In the navigation pane, click Oracle Cloud Services.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, Users, Groups. Dynamic groups, Integrated applications, and Oracle Cloud Services.

  2. Select the specific application corresponding to the Oracle Integration instance.
  3. In the navigation pane, click Application roles.
  4. Expand ServiceInvoker, then click Manage next to either Assigned users or Assigned groups. For example, if you click Assigned users:


    The Application roles dialog shows buttons for Import and Export. Below is a table with a column of check boxes, and additional columns for Name and Description. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Assigned users, Assigned groups, and Assigned applications. Each entry includes a link named Manage.

  5. Click Show available users.
  6. Select the user and click Assign, then click Close.

Validate the client application

  1. To fetch the authorization code, make the following request from the browser.
    ##Syntax
GET https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=<app_scope>%20offline_access&nonce=<nonce-value>&state=<unique_value>
 
###where
#### <client-id> - ID of Client application generated.
#### <client-redirect-uri> - Redirect URI, in client application.
#### <app_scope> - scope added while creating application in client configuration. (Ends with urn:opc:resource:consumer::all)
#### nonce - Optional, unique value to mitigate replay attacks
#### state - Recommended, Opaque to IDCS. Value used to maintain state between the request and the callback
##Example
GET https://<identity_domain_host>/oauth2/v1/authorize?client_id=<clientID>&response_type=code&redirect_uri=https://app.getpostman.com/oauth2/callback&scope=https://<Resource_APP_Audience>urn:opc:resource:consumer::all%20offline_access&nonce=121&state=12345544
  2. If the user is not already logged in, you are challenged to authenticate your user credentials. (For authentication, the user assigned the ServiceInvoker role must be used.)
    After authentication is successful, the client URL is redirected to with the authorization code and state added to the URL.
    ##Response URL
https://<redirect_URL>?code=<code_value>=&state=<state_value>
 
###Client should validate state received is same as one sent in request.
  3. Capture the code value from the above response and make the following request to get the access token.
    ##Syntax
curl -i -H 'Authorization: Basic <base64-clientid-secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=authorization_code&code=<authz-code>&redirect_uri=<client-redirect-uri>
 
###where
#### <base64-clientid-secret> - BAse 64 encode clientId:ClientSecret
#### <authz-code> - code value received as response on redirect.
#### <client-redirect-uri> - Redirect URI, in client application.
 
##Example
curl -i -H 'Authorization: Basic MDMx..NGY1' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<identity_domain_host>/oauth2/v1/token -d 'grant_type=authorization_code&code=AQAg...3jKM4Gc=&redirect_uri=https://app.getpostman.com/oauth2/callback
  4. Capture the access_token and refresh_token from the response.
    {
    "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc="
}
  5. Use the access_token in the authorization header to invoke the Oracle Integration trigger endpoint.
    curl --location --request GET 'https://OIC host/OIC endpoint' \
--header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'
  6. To update the access token, use the refresh token and make the request.
  7. Capture the access_token and refresh_token from a response for further use.
    curl -i -H 'Authorization: Basic <base64-clientid-secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=<refresh_token>'
 
 
##Example
curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc='