1. Using the SOAP Adapter with Oracle Integration 3
  2. SOAP Adapter Concepts
  3. 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 an Oracle Identity Cloud Service environment of 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.

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 users to the various Oracle Integration roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Service Roles in Provisioning and Administering Oracle Integration 3.)
    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 Applications 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.
    2. Click Add.
    3. Select Confidential Application.


      Description of oauth_grant6.png follows
      Description of the illustration oauth_grant6.png

    4. Complete the Details page, and go to the Client page.
      Description of oauth_grant7.png follows
      Description of the illustration oauth_grant7.png

    5. On the Client page, 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 >.
        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.
    6. Click through the remaining wizard pages without making changes and save the application.
    7. 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.)
    Description of trusted_partner_cert.png follows
    Description of the illustration trusted_partner_cert.png

  • 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 users to the various Oracle Integration roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Service Roles in Provisioning and Administering Oracle Integration 3.)
    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 Applications 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.
    2. Select Confidential Application.


      Description of oauth_grant6.png follows
      Description of the illustration oauth_grant6.png

    3. Complete the Details page, and go to the Client page.
      Description of oauth_grant7.png follows
      Description of the illustration oauth_grant7.png

    4. On the Client page, 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. After user login, Oracle Identity Cloud Service redirects to this URL with the authorization code.

        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. 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.
    5. Click through the remaining wizard pages without making changes and save the application.
    6. 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.)
      After authentication is successful, 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 Applications. 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 users to the various Oracle Integration roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Service Roles in Provisioning and Administering Oracle Integration 3.)
    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 trigger the integration with OAuth, a client application is required.

    1. In the Oracle Identity Cloud Service Console, go to the Applications 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.
    2. Click Add.
    3. Select Confidential Application.
      Description of oauth_grant6.png follows
      Description of the illustration oauth_grant6.png

    4. Complete the Details page, and go to the Client page.
      Description of oauth_grant7.png follows
      Description of the illustration oauth_grant7.png

    5. On the Client page, 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.
    6. Click through the remaining wizard pages without making changes and save the application.
    7. 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='

Prerequisites for Client Credentials

  • Configure the client application.
    1. In the Oracle Identity Cloud Service Console, go to the Applications 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.
    2. Click Add.
    3. Select Confidential Application.
    4. Complete the Details page, and click Next.
    5. On the Client page, select Configure this application as a client now, and complete the following:
      1. Select Client Credentials from the Allowed Grant Types list.
      2. Select Specific in the Authorized Resources area of the Token Issuance Policy section.
      3. Click Add Scope under the Resources section.
      4. Find the Oracle Integration application, and click >.
        The Select Scope dialog shows a table with each Oracle Integration application. The > link for the application just created is being selected.

      5. Add the scope containing urn:opc:resource:consumer::all.
      6. Save your changes.
    6. Click through the remaining wizard pages without making changes and save the application.
    7. Activate the application for use.
  • Add roles to the client application.
    1. Go to the Application Roles tab of the Oracle Identity Cloud Service application.
    2. Select Assign Applications for the ServiceUser role.
      The Details, Configuration, Web Tier Policy, Application Roles, Design, and Users tabs are shown. Below this, the Search field, Select All check box, Import link, and Export list are shown. Below this is a table with a service role names column, number of users assigned column, and number of applications assigned column. A drop down list with Assign Applications is being selected for the ServiceUser role.

  • Validate the client application.
    1. Fetch the access client to make an access token request to Oracle Identity Cloud Service 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://<IDCS-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://<idcs_host>/oauth2/v1/token -d 'grant_type=client_credentials&scope=https://<Resource APP Audience>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 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'