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. Select the identity domain.
    5. In the menu bar, click Integrated applications.

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


      The Details, User management, Administrators, Dynamic groups, Directory integrations, Integration applications (which is selected), Oracle cloud services, Federation, and Domain policies tabs are shown.

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, then click Launch workflow.
  3. Enter a name. The remaining fields on this page are optional and can be ignored.
  4. Click Submit.
  5. Click the OAuth configuration tab, then the Edit OAuth configuration subtab.
  6. In the Client configuration panel, select Configure this application as a client now.
  7. For JWT user assertions, select JWT assertion and Refresh token in the Allowed grant types section.


    The Edit OAuth Configuration panel is shown. The Allowed grant types section is shown. Options are available for Resource owner, Client credentials, JWT assertion (which is selected), Refresh token (which is selected), Device code, Authorization code, Implicit, SAML2 assertion, and TLS client authentication.

  8. 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 for the client to generate self-signed user assertions and import your signing certificate.
    3. In the Certificate section, import 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 Confidential in the Authorized resources section.
    6. Click the Add Resources toggle.
    7. Click Add scope.
    8. Find and expand the Oracle Integration application for your instance.
    9. Select the two scopes appended with the following details:
      • urn:opc:resource:consumer::all
      • ic/api/


      The Add scope section is shown. A table with columns for Name and Description are shown. The Oracle Integration application name is expanded to show the two types of scopes selected.

    10. Click Add.

      The scopes are displayed in the Resources section.

    11. Ignore the Add app roles check box. This selection is not required.
    12. Click Submit.

      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 the Client ID and Client secret values. The Client secret value is available through the Actions menu.

  9. In the menu bar, click Oracle cloud services.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, User management, Administrators. Dynamic groups, Directory integrations, Integrated applications, Oracle Cloud Services, Federation, and Domain policies.

  10. Click the specific application corresponding to the Oracle Integration instance.
  11. In the navigation pane, click Application roles.
  12. Expand ServiceInvoker, then click Actions Actions icon next to Assigned applications.


    Tabs for Details, OAuth configuration, Web tier policy, Application roles (which is selected), Access token, Users, and Groups are shown. The Application roles section shows buttons for Import and Export, and a Search section. Below is a table with a column of check boxes, and additional columns for Name, Description, Assigned users, Assigned groups, and Assigned applications. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Manage users, Manage groups, and Manage applications.

  13. Select ServiceInvoker, then click Manage users or Manage groups.
  14. Based on your selection, click Assign users or Assign groups to select the users or groups, then click Assign.

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 menu bar, click Security.


    The Domains tab is selected in the left navigation pane. To the right are tabs for Federation, Domain policies, Security (which is selected), Authentication, and Branding. The title Network perimeters appears below.

  2. Scroll down to the Trusted partner certificates section.
  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 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.
  3. Enter a name. The remaining fields on this page are optional and can be ignored.
  4. Click Submit.
  5. Click the OAuth configuration tab, then the Edit OAuth configuration subtab.
  6. In the Client configuration panel, select Configure this application as a client now.
  7. Select the grant type to use:
    1. For client credentials, select Client credentials in the Allowed grant types section.


      The Edit OAuth Configuration panel is shown. The radio button Configure this application as a client now is selected. The Allowed grant types section is shown. Options are available for Resource owner, Client credentials (which is selected), 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 Edit OAuth Configuration panel is shown. The Allowed grant types section is shown. Options are available for Resource owner, Client credentials, JWT assertion, Refresh token (which is selected), Device code, Authorization code, Implicit, SAML2 assertion, and TLS client authentication.

  8. 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 Confidential in the Authorized resources section.
    5. Click the Add Resources toggle.
    6. Click Add scope.
    7. Find and expand the Oracle Integration application for your instance.
    8. Select the two scopes appended with the following details:
      • urn:opc:resource:consumer::all
      • ic/api/


      The Add scope section is shown. A table with columns for Name and Description are shown. The Oracle Integration application name is expanded to show the two types of scopes selected.

    9. Click Add.

      The scopes are displayed in the Resources section.

    10. Ignore the Add app roles check box. This selection is not required.
    11. Click Submit.

    The details page for the client application is displayed.

  9. From the Actions menu at the top, select Activate, and then Activate application to activate the client application for use.
  10. 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 the Client ID and Client secret values. The Client secret value is available through the Actions menu.

Add roles to the client application

  1. In the menu bar, click Oracle cloud services.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, User management, Administrators. Dynamic groups, Directory integrations, Integrated applications, Oracle Cloud Services, Federation, and Domain policies.

  2. Click the specific application corresponding to the Oracle Integration instance.
  3. In the menu bar, click Application roles.
  4. If configuring the client credentials grant type, select the following:
    1. Expand ServiceInvoker, then click Actions Actions icon next to Assigned applications.


      Tabs for Details, OAuth configuration, Web tier policy, Application roles (which is selected), Access token, Users, and Groups are shown. The Application roles section shows buttons for Import and Export, and a Search section. Below is a table with a column of check boxes, and additional columns for Name, Description, Assigned users, Assigned groups, and Assigned applications. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Manage users, Manage groups, and Manage applications.

    2. Select to assign users, groups, and applications to the instance application.
  5. If configuring the resource owner password credentials grant type, select the following:
    1. Select ServiceInvoker, then click Manage users or Manage groups.
    2. Based on your selection, click Assign users or Assign groups to assign users or groups to the instance application, then click Assign.
  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 of the Details tab of the instance application.


        The Details (which is selected), User management, Administrators. Dynamic groups, Directory integrations, Integrated applications, and Oracle Cloud Services tabs are shown. The Details section for the domain shows fields for OCID, Domain type, Description, Domain replication, Home region, Created, Show domain on login, and Domain URL.

      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 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.
  3. Enter a name. The remaining fields on this page are optional and can be ignored.
  4. Click Submit.
  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 Edit OAuth Configuration panel is shown. The Allowed grant types section is shown. Options are available for Resource owner, Client credentials, JWT assertion, Refresh token (which is selected), Device code (which is selected), 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. Bypass several fields and scroll down to the Token issuance policy section.
    5. Select Confidential in the Authorized resources section.
    6. Click the Add Resources check box.
    7. Click Add scope.
    8. Find and expand the Oracle Integration application for your instance.
    9. Select the two scopes appended with the following details:
      • urn:opc:resource:consumer::all
      • ic/api/


      The Add scope section is shown. A table with columns for Name and Description are shown. The Oracle Integration application name is expanded to show the two types of scopes selected.

    10. Click Add.

      The scopes are displayed in the Resources section.

    11. Ignore the Add app roles check box. This selection is not required.
    12. Click Submit.

      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 the Client ID and Client secret values. The Client secret value is available through the Actions menu.

Validate the Oracle Integration application and user roles

  1. In the menu bar, click Oracle cloud services.


    The Identity domain navigation pane shows entries. The Overview option is selected. Below this are selections for Overview, User management, Administrators. Dynamic groups, Directory integrations, Integrated applications, Oracle Cloud Services, Federation, and Domain policies.

  2. Click the specific application corresponding to the Oracle Integration instance.
  3. In the navigation pane, click Application roles.
  4. Expand ServiceInvoker, then click Actions Actions icon next to Assigned applications.


    Tabs for Details, OAuth configuration, Web tier policy, Application roles (which is selected), Access token, Users, and Groups are shown. The Application roles section shows buttons for Import and Export, and a Search section. Below is a table with a column of check boxes, and additional columns for Name, Description, Assigned users, Assigned groups, and Assigned applications. The Name column lists all Oracle Integration application roles. The ServiceInvoker role is expanded to include entries for Manage users, Manage groups, and Manage applications.

  5. Select to manage users, groups, and applications for the instance application.
  6. Based on your selection, click Assign users or Assign groups to select the users or groups, then click Assign.

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='