OIC Gen3 - About OAuth setup to call integration and Factory APIs

Before we dive deep into the concept of OAuth2.0, lets first understand with below two terminologies:

• Authentication.
• Authorization.

Authentication(who you are):

• Authentication is the process of proving your own identity to third party service. It verifies whether a person’s identity is the same as he or she had declared himself or herself to be.

Example: So when we are trying to log in to Facebook or Google, we are required to first enter the email and password to verify our identity. This is what Authentication is.

Authorization(What access of resources you have):

• Authorization is the process of giving someone permission to do something or have something. In this process, a person grants another person to have some of its resources or use some of its resources.
• It is done after successful Authentication. Here an Authorization server is providing access to third-party services to use some of its resources.

Example:

the Authorization server is Google who is providing access to Tableau Desktop(Third-party service)  to use some of its resources.

So OAuth or OAuth 2.0 is an industry standard protocol for authorization, not for authentication. It is meant for service to authorize another service.

OAuth Flow

The requesting, granting, and life management of this tokens are often referred to as a “flow”. The OAuth specification allows for several ways of obtaining and validating tokens, and not all flows are meant for all types of clients.

There are more than one flows available for OAuth. 

Here, we will mainly discuss for below two flows:

1. Client Credential Flow
2. Authorization Code Flow

Client Credential Flow:

1. First the client application register itself with the OCI IAM authorization server. As a part of the registratration, the client chooses the flow or grant_type as the client credential(client id and secrect) and chooses the app role or roles(service developer or service invoker) that it needs to access the APIs
2. Client (an application or machine) requests access token using its credentials
3. OCI IAM validates and generates a token.
4. Access token is sent back to the client.
5. Client use access token as authentication to call the APIs
6.  Return the APIs data to the client.

Authorization Code Flow:

1. First the client application register itself with the OCI IAM authorization server. As a part of the registratration, the client chooses the flow or grant_type as the client credential(client id and secrect) and chooses the app role or roles(service developer or service invoker) that it needs to access the APIs
2. The Client (A user over mobile or web application) submits an authorization request through a browser to the authorization server's authorization endpoint. 
3. The authorization server authenticates the user and approve or deny consent for the client to access the user's resource.
4. In return, the client gets an authorization code that it exchanges for an access token at the token endpoint. 
5. The client uses the access token to invoke the API and gets the protected data in return.

Key Parameters required by Client Application

Grant Type: Client Credentials/Authorization Code

Access Token URL: https://<idcs url>/oauth2/v1/token

Client ID: xxxxxx

Client Secret: xxxxxx

Scope: https://xxxxxx:opc:resource:consumer::all

Auth URL*: https://<idcs url>/oauth2/v1/authorize

Redirect URL*: https://<oic url>/icsapis/agent/oauth/callback

Note: * for Autorizarion code only

What is IDCS url?

In oci domain where you have provisioned the oracle integration cloud service, its the domain url.

Navigation

Identity & security >> domains >> default domains >> domain url.

What is OIC URL?

Service console url.

Integration instances >> click the oracle integration instance >> service console url

How to create confidential application for Client Credential flow?

High level Steps :

1. Add application details(application name)
2. Configure OAuth
1. Config as client flow
2. Select client credential and refresh token authrization
3. Client ip address anywhere
4. Add resources >> add scope for the oic integration instance.
3. Configure policy if needed
4. Add app roles

Navigattion:

Identity & Security >> domain >> integrated application >> add application >>confidential application 

Testing from postman:

How to create confidential application for Authorization Code flow?

High level Steps :

1. Add application details(application name)
2. Configure OAuth
1. Config as client flow
2. Select client credential and refresh token authrization
3. Client ip address anywhere
4. Add resources >> add scope for the oic integration instance.
3. Configure policy if needed

Navigattion:

Identity & Security >> domain >> integrated application >> add application >>confidential application 

Test from postman:

OIC Factory APIs:

• Oauth is mandatory in OIC 3.
• Recommnended to use Design time url with parameter integrationinstance

The Oracle Integration Cloud (OIC) Factory APIs are APIs provided by Oracle for automating and managing integrations and other tasks within Oracle Integration Cloud. These APIs offer capabilities for developers and administrators to programmatically control OIC environments, allowing for tasks such as creating, deploying, managing, and monitoring integrations.

Key Use Cases for OIC Factory APIs

• Managing Integrations: List, activate, deactivate, or delete integrations.
• Monitoring: Check the status of integrations, view errors, and retrieve logs.
• Instance Management: Manage and monitor specific integration instances.
• Connections and Adapters: Manage connections and adapters, including creation, update, and deletion.
• Error Handling: Fetch and manage error details for integration runs.

Example Use Cases and API Requests

1. List Integrations

This API lists all the integrations available in OIC.

Request

GET /ic/api/integration/v1/integrations

Headers:

- Authorization: Bearer <access_token>

Example Response

[

   {

      "id": "INT-123",

      "name": "Example_Integration",

      "status": "ACTIVE",

      "version": "01.00.0000",

      "lastUpdated": "2023-08-20T15:45:00Z"

   },

   {

      "id": "INT-124",

      "name": "Another_Integration",

      "status": "INACTIVE",

      "version": "01.00.0001",

      "lastUpdated": "2023-07-18T10:10:00Z"

   }

]

2. Activate an Integration

Activating an integration makes it available to process instances.

Request

POST /ic/api/integration/v1/integrations/{integrationId}/activate

Headers:

- Authorization: Bearer <access_token>

Example Request

POST /ic/api/integration/v1/integrations/INT-123/activate

Response

{

   "status": "SUCCESS",

   "message": "Integration activated successfully."

}

Rest connection example created in OIC:

Example1:

OIC - Convert DateTime from one timezone to another with Daylight saving in OIC

Usecase: 

Here, we will demonstrate how to convert one timezone to another considering the daylight saving time.

Here, we will see UTC to Australia timezone change.

Implementation steps:

1. Create 2 javascript functions
1. 1st one will determine whether the datetime under DST or not. Response will be in True or False.
2. 2nd one will add UTC +11.00  or UTC+10.00 depends on the daylight saving.
2. Import it to OIC library
3. Create an integration and feed a datetime
4. Feed the input date time to javascript and get the the converted timezone from the integration.

Javascript code used: (save .js extension)

function isDaylightSavingsInEffect(dateTimeInput) {

    var dateTime = new Date(dateTimeInput);

    var month = dateTime.getMonth();

    month = month + 1;

    var year = dateTime.getFullYear();

    var day = dateTime.getDate();

    var hours = dateTime.getHours();

    var firstDateofSunday = 0;

    var flag = false;

   // get first Sunday of any Month

    var firstSunday = new Date(year, month - 1, 1);

    var dayOfWeek = firstSunday.getDay();

    if (dayOfWeek == 0) {

        firstDateofSunday = 1;

    } else {

        firstDateofSunday = 7 - (dayOfWeek - 1);

    }

    // return for DST Eligibility

    if (month < 4 || month > 10 || (month == 10 && day >= firstDateofSunday) || (month == 4 && day <= firstDateofSunday)) {

        flag = true;

    } else {

        flag = false;

    }

    return flag;

}

// returns date and time YYYY-MM-DD HH:MM:SS 

function sc_convertUTC2AEST (utcDate) {
var inDate = new Date(utcDate);
var offset = 0;
var response = '';
if (!isNaN(inDate)) {
offset = isDaylightSavingsInEffect(inDate) ? 11 : 10; // Using your function to decide offset
inDate.setHours(inDate.getHours() + offset);
string ='';
response= string.concat(inDate.getUTCFullYear(), '-', (('0' + (inDate.getUTCMonth() + 1)).slice(-2)),'-', ('0' + inDate.getUTCDate()).slice(-2),' ', ('0' +
inDate.getUTCHours()).slice(-2), ('0' + inDate.getUTCMinutes()).slice(-2), ('0' + inDate.getUTCSeconds()).slice(-2))
}
return response;
}

Detailed screenshots:

Js Codes:

Testing:

Import .js file to libraries and save.

Create a integration and take js action and choose the javascript 2nd function >> feed the input UTC date time.

Map the js action response.

Note: Instead of using Javascript action, we can also call the function from xslt mapper.

OIC - How to convert from one timezone to another timezone

Usecase: Here we will demonstrate how to convert from UTC to IST timezone. We can convert to any other timezones.

Currently my oic instance timezone is in UTC and I have one requitement to convert it to IST timezone.

We have to use below functions:

• Adjust-dateTime-to-timeZone() 
• dayTimeDurarion()

Solution code:

fn:string(fn:adjust-dateTime-to-timezone(fn:current-dateTime(), ns0:dayTimeDuration('PT5H30M')))

Screenshots:

Notes:

How to get the duration:

From https://www.worldtimebuddy.com >> add place or timezone and can see the time difference with the UTC. Like for IST, its showing +5.5 hrs difference.

Duration syntax:

Now question is how to get the PT5H30M value and what syntax it follows:

• P is the duration designator (for period) placed at the start of the duration representation.
• Y is the year designator that follows the value for the number of years.
• M is the month designator that follows the value for the number of months.
• W is the week designator that follows the value for the number of weeks.
• D is the day designator that follows the value for the number of days.
• T is the time designator that precedes the time components of the representation.

So P means 'Period' and because there are no date-components it only has a 'Time'. You could interpret this as 'Period of Time'

The details for the time component are:

• H is the hour designator that follows the value for the number of hours.
• M is the minute designator that follows the value for the number of minutes.
• S is the second designator that follows the value for the number of seconds.

Example

durarion("P1Y2M3DT10H30M") : represents a duration of 1 year, 2 months, 3 days, 10 hours and 30 minutes.

Duration("PT2000H") : represents a duration of 2000 hours.

We not only convert from date time, we can also convert from date to timezone or time to timezone. To achieve this, OIC has OOTB below functions:

• adjust-dateTime-to-timeZone()
• adjust-date-to-timeZone()
• adjust-time-to-timeZone()

Example of fomatting after the timezone change.

xp20:format-dateTime (fn:adjust-dateTime-to-timezone (fn:current-dateTime(), xsd:dayTimeDuration ("PT8H") ), "[D01][M01][Y0001][H01][m01][s01]" )