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

Use OAuth 2.0 Grants in Oracle Identity Cloud Service Environments

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

Note:

The following instructions apply only to cloud tenancies that still use Oracle Identity Cloud Service. Most cloud tenancies have been migrated to identity domains, which require different configuration instructions. See Use OAuth 2.0 Grants in Identity Domain Environments. If you are unsure of your environment, check with your administrator.

Note:

Understand the following restrictions before performing OAuth 2.0 grants.
  • Do not let external client applications use the system-created Oracle Identity Cloud Service application to authenticate against Oracle Integration endpoints.
  • The scope of the client application is for accessing all deployed integrations in that service instance. There is no support for limiting access to a subset of integrations.

Prerequisites for All Grants

Perform the following tasks for each grant type you use.

  • Obtain the Oracle Identity Cloud Service URL.
    1. Go to the URL for your Oracle Integration instance.
      For example, if your Oracle Integration instance is https://myhost.example.com/ic/home, when you go to that URL, you are redirected to a URL such as:
       https://idcs-c2881.identity.myhost.example.com/ui/v1/signin
    2. Replace /signin with /adminconsole to access Oracle Identity Cloud Service.
      For example:
      https://idcs-c2881.identity.myhost.example.com/ui/v1/adminconsole

      You'll be prompted to sign in again to the Oracle Identity Cloud Service Console.

    3. Log in to the Oracle Identity Cloud Service Console with your identity domain administrator credentials.
  • Check the Oracle Integration application in Oracle Identity Cloud Service.

    When an Oracle Integration instance is provisioned, an Oracle Identity Cloud Service application is created for that Oracle Integration instance. The application name is OICINST_service_instance_name.

    1. Log in to the Oracle instance to get the service instance name.
      https://myhost.example.com/ic/home
    2. Log in to Oracle Identity Cloud Service to get the application.
    3. Go to Applications and find the application with the above name to access the application.

    Alternatively, you can find the application through the Oracle Cloud Dashboard. When you click the IDCS Application link on the details page of the Oracle Integration instance (for this example, named OIC), it opens the Oracle Identity Cloud Service application for Oracle Integration that is already created.
    Overview tab with fields for Status, Active, Integration Cloud Edition, Service Identifier, License, Version, Feature Set, Message Packs and IDCS Application (which is selected)

Prerequisites for JWT User Assertion

Perform the following tasks.

  • Validate the Oracle Integration application and user roles.
    1. Verify that the Is Refresh Token Allowed option is enabled for the Oracle Identity Cloud Service application.
    2. Check under the Configuration > Resources section of the application. Note also that there is a special scope predefined (urn:opc:resource:consumer::all), which can trigger integrations using OAuth.
      Description of ropc1.png follows
      Description of the illustration ropc1.png

    3. Add the appropriate user(s) to the various Oracle Integration roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Roles in Provisioning and Administering Oracle Integration Generation 2.)
    4. To assign the user, go to the Application Roles section of the application.
      Description of oauth_grant1.png follows
      Description of the illustration oauth_grant1.png

  • Generate the key:
    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. In the Oracle Identity Cloud Service Console, go to the Application section to create a new application that allows you to trigger an integration with OAuth.


      Applications page with Select All, Add, and Remove buttons. The cursor is hovering over the Add button and the tooltip Create an Application is being displayed.

      The application is added as a confidential application.


      Description of oauth_grant61.png follows
      Description of the illustration oauth_grant61.png

    2. Complete the Details section, and go to the Client section.
      Description of oauth_grant7.png follows
      Description of the illustration oauth_grant7.png

    3. In the Client section, select Configure this application as a client now and add the following.
      1. Select Client Credentials and JWT Assertion for the Allowed Grant Types.
      2. In the Security section, select Trusted Client and upload the certificate created in the previous section (Generate the key - Step 2).
      3. Select Specific in the Authorized Resources section.
        Description of add_conf_app.png follows
        Description of the illustration add_conf_app.png

      4. Click Add Scope under the Resources section.
        Add Scope button

      5. Find the Oracle Integration application, and click >.
        Select Scope page shown with resources for this tenant. A table in which you can select the resource (application) and click the > icon is displayed.

      6. Add the scope containing urn:opc:resource:consumer::all, and click >.

        The scope containing urn:opc:resource:consumer::all is added.
        Resources section, with an Add Scope button and a table with columns for Resource, Protected, and Scope.

      7. Save your changes.
    4. Skip the rest of the wizard steps and save the application.
    5. Activate the application for use.
  • Add a certificate as a trusted partner:

    Even though you imported the signing certificate in the application, Oracle Identity Cloud Service requires you to also have the certificate as a trusted partner certificate. Upload the certificate created in the previous section. (See Generate the key - Step 2.)

  • 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 Oracle Identity Cloud Service 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 in Oracle Identity Cloud Service.
  • Validate the client application:
    1. Once you generate the JWT user assertion, generate the Oracle Identity Cloud Service 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://<IDCS-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

Perform the following tasks.

  • Validate the Oracle Integration application and user roles:
    1. Verify that the Is Refresh Token Allowed option is enabled for the Oracle Identity Cloud Service application.
    2. Check the Configuration > Resources section of the application. Note also that there is a special predefined scope (urn:opc:resource:consumer::all) that permits triggering of the Oracle Integration integrations using OAuth.
      Description of ropc1.png follows
      Description of the illustration ropc1.png

    3. Add the appropriate user(s) to the various Oracle Integration roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Roles in Provisioning and Administering Oracle Integration Generation 2.)
    4. To assign the user, go to the Application Roles section of the application.
      Description of oauth_grant1.png follows
      Description of the illustration oauth_grant1.png

  • Configure the client application:

    To allow you to trigger the Oracle Integration integration with OAuth, the client application is required.

    1. In the Oracle Identity Cloud Service Console, go to the Application section to create a new application that allows you to trigger the Oracle Integration integration with OAuth.
      Applications page with Select All, Add, and Remove buttons. The cursor is hovering over the Add button and the tooltip Create an Application is being displayed.

      The application is added as a confidential application.
      Description of oauth_grant6.png follows
      Description of the illustration oauth_grant6.png

    2. Complete the Details section, and go to the Client section.
      Description of oauth_grant71.png follows
      Description of the illustration oauth_grant71.png

    3. In the Client selection, select Configure this application as a client now and add the following.
      1. Select Refresh Token and Authorization Code for Allowed Grant Types.
      2. Set the redirect URL to the URL of the client application (for example, https://sample_client_app/oauth2/callback). After user login, Oracle Identity Cloud Service redirects to this URL with the authorization code.
      3. Select Specific in the Authorized Resources section.
        Description of authorization.png follows
        Description of the illustration authorization.png

      4. Click Add Scope under the Resources section.
        Add Scope button in the Resources section.

      5. Find the Oracle Integration application, and click >.
        Select Scope page shown with resources for this tenant. A table in which you can select the resource (application) and click the > icon is displayed.

      6. Add the scope containing urn:opc:resource:consumer::all, and click >.
        Select Scope page in which the selected resource (application) is displayed. A table in which you can select the scope for the resource is displayed.

        The scope containing urn:opc:resource:consumer::all is added.
        Resources section, with an Add Scope button and a table with columns for Resource, Protected, and Scope.

      7. Save your changes.
    4. Skip the rest of the wizard steps and save the application.
    5. Activate the application for use.
  • Validate the client application:
    1. To fetch the authorization code, make the following request from the browser.
      ##Syntax
GET https://<IDCS-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://<idcs-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, Oracle Identity Cloud Service challenges the user to authenticate. Oracle Identity Cloud Service checks the user's credentials. (For authentication, the user assigned the ServiceUser Role must be used.)
      Post successful authentication, Oracle Identity Cloud Service redirects back to the client redirect URL 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 Oracle Identity Cloud Service 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://<IDCS-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://<idcs_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 to Oracle Identity Cloud Service.
    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://<IDCS-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://IDCS-Service-Instance.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc='

Prerequisites for Resource Owner Password Credentials

Perform the following tasks.

  • Validate the Oracle Integration application and user roles:
    1. Verify that the Is Refresh Token Allowed option is enabled for the Oracle Integration Oracle Identity Cloud Service application.
    2. Check under the Configuration > Resources section of Application. Note also that there is a special predefined scope (urn:opc:resource:consumer::all) that allows the triggering of integrations with OAuth.
      Description of ropc1.png follows
      Description of the illustration ropc1.png

    3. Add the appropriate user(s) to the various Oracle Integration roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Roles in Provisioning and Administering Oracle Integration Generation 2.)
    4. To assign the user, go to the Application Roles section of the application.
      Description of oauth_grant1.png follows
      Description of the illustration oauth_grant1.png

  • Configure the client application:
    1. In the Oracle Identity Cloud Service console, Go to the Application section to create a new application that allows you to trigger an integration with OAuth. The application is added as a confidential application.
      Description of oauth_grant6.png follows
      Description of the illustration oauth_grant6.png

    2. Complete the Details section, and go to the Client section.
      Description of oauth_grant71.png follows
      Description of the illustration oauth_grant71.png

    3. In the Client selection, select Configure this application as a client now and add the following.
      1. Select Resource Owner and Refresh Token for Allowed Grant Types.
      2. Select Specific in the Authorized Resources section.
        Description of ropc2.png follows
        Description of the illustration ropc2.png

      3. Click Add Scope under the Resources section.
        Token Issuance Policy section, with an Authorized Resources subsection with values of All, Tagged, and Specific (which is selected). Below this is a Resources section with an Add Scope button.

      4. Find the Oracle Integration application.
        Select Scope page shown with resources for this tenant. A table in which you can select the resource (application) and click the > icon is displayed.

      5. Add the scope containing urn:opc:resource:consumer::all, and click >.
        Select Scope page in which the selected resource (application) is displayed. A table in which you can select the scope for the resource is displayed.

        The scope containing urn:opc:resource:consumer::all is added.
        Resources section, with an Add Scope button and a table with columns for Resource, Protected, and Scope.

      6. Save your changes.
    4. Skip the rest of the wizard steps and save the application.
    5. Activate the application for use.
  • Validate the client application:
    1. To fetch the access client, make a request to Oracle Identity Cloud Service 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://<IDCS-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 serviceuser 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://<idcs_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 to Oracle Identity Cloud Service.
    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://<IDCS-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://<IDCS-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc='