Authentication Support

The following sections describe REST Adapter authentication capabilities in more detail.

Topics:

• Authenticate Requests for Invoking Oracle Integration Flows

• Authentication Types

• Role-Based Connections

• Extensibility Support for Multiple OAuth Providers

Authenticate Requests for Invoking Oracle Integration Flows

Integrations support multiple authentication methods suited to different applications and use cases. The adapters used as a trigger connection to stand up the endpoints/listener for a specific integration can support one or multiple authentication methods.

The following sections discuss the use cases, pros and cons, prerequisites, and instructions necessary for sending a request for each of the supported authentication methods.

Topics:

• About Requests to Invoke Integrations

• About OAuth 2.0 Grants

• Use OAuth 2.0 Grants in Oracle Identity Cloud Service Environments

• Use OAuth 2.0 Grants in Identity Domain Environments

See OAuth Grant Types.

About Requests to Invoke Integrations

All integrations using this adapter as a trigger connection are protected by default using HTTP Basic Authentication and OAuth token-based authentication.

You currently can authenticate your requests to invoke integrations in either of the following ways:

• Using HTTP Basic Authentication by sending the credentials of the user (that is, created in Oracle Identity Cloud Service) through the HTTP authorization header
• Sending an OAuth access token in the header while invoking an Oracle Integration endpoint after acquiring the access token from Oracle Identity Cloud Service that serves as the OAuth authorization provider

You must have the ServiceUser role in Oracle Identity Cloud Service to invoke integrations.

Invoke Integration Endpoints Using HTTP Basic Authentication

This authentication method allows the credentials belonging to an Oracle Integration user to send the request to invoke an integration. You must create this user in the Oracle Integration identity provider Oracle Identity Cloud Service and ensure that the user was granted the role for invoking an integration.

The user can be:

• Human - representing a business user such as a sales representative, technician, or any other person for invoking an integration
• Nonhuman - representing a service integration account used by an external client application for invoking an integration

Even though it's easy to implement the authentication scheme, this is the least secure way to send a request to Oracle Integration for invoking an integration. Also, Oracle Integration doesn't recommend this authentication scheme.

In addition, the customer must ensure the credentials, when reset, are provided to the client application that invokes the integration to ensure a new set of credentials are being used from then on.

Assign 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.)

1. From the menu on the Oracle Cloud Infrastructure home page, select Identity & Security, then select Federation.
2. In the Federation table, click OracleIdentityCloudService.
3. In the Oracle Identity Cloud Service Console field, click the URL.
4. Click the applications page icon.
   
   
   
   
5. Click the application.
6. To assign a user, go to the Application Roles section of Oracle Identity Cloud Service.
   
   
   Description of the illustration oauth_grant1.png
   
   
7. Make a request to trigger an endpoint.

   curl --location --request GET 'https://OIC host/OIC endpoint' \
   --header 'Authorization: Basic <base64-encoded username:password>'

Invoke Integration Endpoints Using OAuth Token-Based Authentication

This authentication scheme allows the external client to acquire a token that is also sent as part of the request sent to invoke an integration.

The most important step for an application in the OAuth flow is how the application receives an access token (and optionally a refresh token). A grant type is the mechanism used to retrieve the token. OAuth defines several different access grant types that represent different authorization mechanisms.

Applications can request an access token to access protected endpoints in different ways, depending on the type of grant type specified in the Oracle Identity Cloud Service application. A grant is a credential representing the resource owner's authorization to access a protected resource.

The following sections discuss the various grant types and their pros/cons, along with instructions on how to configure the specific grant type.

About OAuth 2.0 Grants

There are several OAuth 2.0 grant types you can use in Oracle Integration. Review the following information to identify the grant type to use for your use case.

Grant Type	About the Grant Type	Use Cases and Risks
JWT user assertion (recommended)	A user assertion is a user token that contains identity information about the user. The user can either represent a human or a service integration account created for identifying a specific calling application. The user assertion is used directly as an authorization grant to obtain an access token. The client details are provided either as an authentication header in the request or as a client assertion. The user assertion grant is more secure than the resource owner password credentials grant because the user’s credentials are never exposed. The user assertion workflow: Is used with confidential clients. The OAuth clients are trusted to assert a user/service integration account identity on behalf of the user/service integration account. The resource owner's credentials (Oracle Integration user) are never accessible to the client application. It just uses the assertion of the resource owner. It isn’t redirection-based. It takes a request only from the client application to the authorization server. The user is not redirected between interfaces to authorize the request. This user assertion grant works as follows: The client requests an access token by providing a user assertion. The client details are provided either as an authentication header in the request or as a client assertion. The OAuth service authenticates the client and, if valid, supplies an access token. The JWT user assertion characteristics are as follows: Does not require the client to have knowledge of user credentials. There is no browser-based end user interaction. A refresh token is allowed. An access token is in the context of the end user. In this OAuth flow: A user attempts to access a client application by sending a generated user assertion. The client application requests an access token, and often a refresh token, by providing a user assertion or a third-party user assertion. The Oracle Identity Cloud Service authorization server returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	This grant is used by applications that want to programmatically invoke integrations without any user intervention. The client application impersonates the user by sending the user assertion to Oracle Identity Cloud Service while requesting token access. An access token is returned in the user context. The user can either represent a human or a service integration account created for identifying a specific calling application. Oracle Integration recommends the use of this grant for acquiring an OAuth access token by the applications that must programmatically start the integration without any user intervention. Risks Carefully use this grant (only with first party/trusted clients) because it allows for trivial impersonation to more highly privileged accounts on services. Usage See Prerequisites for JWT User Assertions.
Authorization code	The authorization code grant type is used by web and mobile applications. It differs from most of the other grant types by first requiring the application to launch a browser to begin the integration. At a high level, the integration consists of the following steps: The application opens a browser to send the user to the OAuth server. The user sees the authorization prompt and approves the application request. The user is redirected back to the application with authorization code in the query string. The application exchanges the authorization code for an access token. The authorization code has the following characteristics: Does not require the client to have knowledge of user credentials. Is a browser-based end user interaction. A refresh token is allowed. An access token is in the context of the end user. In this OAuth flow: A user clicks a link in a web server client application to request access to protected resources. The client application redirects the browser to the Oracle Identity Cloud Service authorization endpoint with a request for an authorization code: oauth2/v1/authorize The Oracle Identity Cloud Service authorization server returns an authorization code to the client application through a browser redirect after the resource owner gives consent. The client application subsequently exchanges the authorization code for an access token, and often a refresh token. The Oracle Identity Cloud Service authorization server returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	This grant is used by the applications such as web portals and mobile applications involving user interactions that may end up invoking the integrations. In this type of use case, the user signing in to the web portal/mobile application explicitly provides the consent by authenticating against Oracle Integration to let their application start the integration. Usage See Prerequisites for Authorization Code.
Resource owner password credential (ROPC)	The resource owner’s password credentials (that is, the user name and password) can be used by the OAuth client directly as an authorization grant to obtain an access token. The resource owner password credentials grant type is suitable for cases where the resource owner has a trust relationship with the OAuth client. When using the resource owner password credentials grant, the user provides the credentials (user name and password) directly to the application. The application then uses the credentials to obtain an access token from the OAuth token service. The resource owner password credentials grant is a grant workflow where the client application, together with its client identifier and secret, sends the user name and password in exchange for an access token. Instead of the user having to log in and approve the authorization request in a web interface, the user can enter the user name and password in the client application user interface directly. This workflow has different security properties than other OAuth workflows. The primary difference is that the user’s password is accessible to the application. This requires a strong trust of the application by the user. The resource owner password credentials grant has the following characteristics: The client is required to have knowledge of user credentials. Is not a browser-based end user interaction. A refresh token is allowed. An access token is in the context of the end user. In this OAuth flow: The user clicks a link in the client application requesting access to protected resources. The client application requests the resource owner's user name and password. The user logs in with their user name and password. The client application exchanges those credentials for an access token, and often a refresh token, from the Oracle Identity Cloud Service authorization server. The Oracle Identity Cloud Service authorization server returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	This grant can be used by applications that want to programmatically invoke the integration without any user intervention. Use this grant only with trusted first-party clients that securely handle user credentials. Even though this grant type can be used by client applications to acquire an OAuth access token to use for sending the request to invoke an integration in a programmatic manner, Oracle Integration does not recommend the resource owner password credential grant because of the following risks: Risks This grant type carries a higher risk than other grant types because it maintains the password anti-pattern this protocol seeks to avoid. The client can abuse the password or the password can unintentionally be disclosed to an attacker (for example, through log files or other records kept by the client). The application can request a scope with complete access to user resources once it possesses the password credential. Passwords expire. This grant is currently in a deprecated state. Usage See Prerequisites for Resource Owner Password Credentials.

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.

• Prerequisites for All Grants
• Prerequisites for JWT User Assertion
• Prerequisites for Authorization Code
• Prerequisites for Resource Owner Password Credentials

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.
  
  

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 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 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.

     
     
     

     The application is added as a confidential application.

     
     
     Description of the illustration oauth_grant61.png
     

  2. Complete the Details section, and go to the Client section.
     
     
     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 the illustration add_conf_app.png
        
        
     4. Click Add Scope under the Resources section.
        
        
        
        
     5. Find the Oracle Integration application, and click >.
        
        
        
        
     6. Add the scope containing urn:opc:resource:consumer::all, and click >.

        The scope containing urn:opc:resource:consumer::all is added.
        
        

     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 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 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.
     
     

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

  2. Complete the Details section, and go to the Client section.
     
     
     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 the illustration authorization.png
        
        
     4. Click Add Scope under the Resources section.
        
        
        
        
     5. Find the Oracle Integration application, and click >.
        
        
        
        
     6. Add the scope containing urn:opc:resource:consumer::all, and click >.
        
        
        
        

        The scope containing urn:opc:resource:consumer::all is added.
        
        

     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 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 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 the illustration oauth_grant6.png
     
     
  2. Complete the Details section, and go to the Client section.
     
     
     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 the illustration ropc2.png
        
        
     3. Click Add Scope under the Resources section.
        
        
        
        
     4. Find the Oracle Integration application.
        
        
        
        
     5. Add the scope containing urn:opc:resource:consumer::all, and click >.
        
        
        
        

        The scope containing urn:opc:resource:consumer::all is added.
        
        

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

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
• Prerequisites for Resource Owner Password Credentials
• Prerequisites for JWT User Assertion
• Prerequisites for Authorization Code

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.

     
     
     

  5. In the navigation pane, click Integrated applications.

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

     
     
     

Prerequisites for Resource Owner Password Credentials

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

• Configure the client application
• Add roles to the client application

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 Next.
5. In the Client configuration box, select Configure this application as a client now.
6. For resource owner password credentials, select Resource owner and Refresh token in the Allowed grant types section.

   
   
   

7. Complete the following steps:
   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.

      
      
      

   5. Click the Add Resources check box.
   6. Click Add scope.
   7. Find the Oracle Integration application for your instance, and click .
   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.

      
      
      

   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.

   
   
   

Add roles to the client application

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

   
   
   

2. Select the specific application corresponding to the Oracle Integration instance.
3. In the navigation pane, click Application roles.
4. Select the following for the resource owner password credentials grant type:
   1. Expand ServiceInvoker, then click Manage next to either Assigned users or Assigned groups. For example, if you click Assigned users:

      
      
      

   2. Click Show available users.
   3. Select the user and click Assign, then click Close.
5. Validate the client application 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
• Configure the client application
• Add a certificate as a trusted partner
• Generate the JWT user assertion
• Validate the client application

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.

   
   
   

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.

   
   
   

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.

      
      
      

   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.

      
      
      

   6. Click the Add Resources check box.
   7. Click Add scope.
   8. Find the Oracle Integration application for your instance, and click .
   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.

       
       
       

   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.

       
       
       

8. In the navigation pane, click 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:

    
    
    

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.

   
   
   

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
• Validate the Oracle Integration application and user roles
• Validate the client application

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 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.

      
      
      

   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 Generation 2 to Oracle Integration Generation 2.
      • 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 Generation 2 instances	Yes.	https://OIC_instance_URL.region.ocp.oraclecloud.com/icsapis/agent/oauth/callback
      Created on instances upgraded from Oracle Integration Generation 2 Generation 2 to Oracle Integration Generation 2	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.

      
      
      

   5. Click the Add Resources check box.
   6. Click Add scope.
   7. Find the Oracle Integration application for your instance, and click .
   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.

      
      
      

   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.

       
       
       

Validate the Oracle Integration application and user roles

1. In the navigation pane, click 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:

   
   
   

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

Authentication Types

The REST Adapter supports the following types of authentication:

• For scenarios when the REST Adapter invokes an external REST endpoint:

  • Basic Authentication

  • OAuth Client Credentials (two-legged flow)

  • OAuth Resource Owner Password Credentials (two-legged flow)

  • OAuth Authorization Code Credentials (three-legged flow)

  • OAuth Custom Three Legged Flow

  • OAuth Custom Two Legged Flow

  • API Key Based Authentication

  • OAuth 1.0 One Legged Authentication

  • Amazon Web Services (AWS) Signature Version 4

  • Oracle Cloud Infrastructure (OCI) Signature Version 1

• For scenarios when the REST Adapter is used to create a REST endpoint to trigger an integration:

  • Basic Authentication

  • OAuth 2.0
  • OAuth 2.0 or Basic Authentication

See Configure Connection Security for more information about these security policies.

Role-Based Connections

The REST Adapter is bidirectional. You can configure the REST Adapter depending on the context in which you want to use the connection.

• Trigger: The REST Adapter is used to create a REST endpoint to trigger an integration. You select Trigger from the Role list on the Create New Connection dialog. When configured as a trigger, a base URI is not required. The security policy defined in the inbound direction accepts credentials configured in the identity domain. Therefore, you are not required to provide the applicable credentials. When configuring security on the Connections page, you only provide the security policy that must be attached to the inbound endpoint. The following security policies are available:

  • Basic authentication
  • OAuth 2.0
  • Basic authentication and OAuth 2.0

  Agent configuration is not applicable on a connection with the trigger role.

• Invoke: The REST Adapter is used to invoke external REST endpoints. A base URI and security configuration for accessing external protected resources are required. You are prompted for these additional details on the Connections page. You cannot use an invoke connection on the trigger side.

• Trigger and invoke: The REST Adapter is used in both the trigger and invoke directions of an integration. This connection requires invoke and trigger values. Basic Authentication can be used in both trigger and invoke connections.

See Create a Connection.

Extensibility Support for Multiple OAuth Providers

You can use the extensibility framework of the REST Adapter to access the OAuth-protected resource of endpoints. This framework enables you to access endpoints that have implemented their own variations of OAuth.

The OAuth standard provides flexibility for endpoints to define specific aspects of their OAuth flows. For example:

• Create their own properties.

• Decide when to use these properties in an OAuth flow. For example, some custom properties may be required with the authorization request, while others may be required for the access token request or for the refresh of the access token after its expiration.

• Decide how to pass these properties in an OAuth flow. For example, whether a property is passed as a header, query parameter, or payload.

To address these challenges, Oracle Integration provides two custom security policies that enable you to specify each step in the OAuth flow when you create the REST Adapter connection:

• OAuth custom two-legged flow: The client application directly interacts with the authorization server on behalf of a resource owner.

• OAuth custom three-legged flow: The client application redirects the owner to a separate resource URL where the resource owner authenticates and provides consent for the flow to continue.

This enables you to adapt to most OAuth framework scenarios and integrate with many third-party applications without writing additional code.

• During design-time, the access token is obtained, validated, and stored in the CSF. The security token is also stored in the CSF.

• During runtime, the access token is retrieved, applied, and managed. A valid access token is applied to the request before invoking the REST endpoint.

Specify the OAuth custom two-legged flow and three-legged flow security policies. See Configure Connection Security and REST Adapter Use Cases.

Note:

This extensibility feature is an advanced feature, and not for business users. Users of this feature should use a tool such as postman to configure the necessary properties.