1 About the Generic REST Connector

The Generic REST connector integrates Oracle Identity Manager with REST-based target systems.

Note:

In this guide, the connector that is deployed using the Applications option on the Manage tab of Identity Self Service is referred to as an AOB application. The connector that is deployed using the Manage Connector option in Oracle Identity System Administration is referred to as a CI-based connector (Connector Installer-based connector).

From Oracle Identity Governance release 12.2.1.3.0 onward, connector deployment is handled using the application onboarding capability of Oracle Identity Self Service. This capability lets business users to onboard applications with minimum details and effort. The connector installation package includes a collection of predefined templates (XML files) that contain all the information required for provisioning and reconciling data from a given application or target system. These templates also include basic connectivity and configuration details specific to your target system. The connector uses information from these predefined templates allowing you to onboard your applications quickly and easily using only a single and simplified UI.

Application onboarding is the process of registering or associating an application with Oracle Identity Governance and making that application available for provisioning and reconciliation of user information.

The following topics provide a high-level overview of the connector:

• Introduction to the Connector

• Certified Components

• Certified Languages

• Architecture of the Generic REST Connector

• Connector Features

• Use Cases Supported by the Generic REST Connector

1.1 Introduction to the Connector

The Generic REST connector is a solution to integrate OIM with REST-based identity-aware applications. A REST-based identity-aware application is any application that exposes its REST APIs or interfaces for identity management.

Note:

In this guide:

A REST-based identity-aware application has been referred to as the target system or REST-based target system.

The Generic REST connector provides a centralized system to streamline delivery of services and assets to your company’s consumers, and manage those services and assets in a simple, secure, and cost efficient manner by using automation. The Generic REST connector standardizes service processes and implements automation to replace manual tasks.

In order to connect with a REST-based target system, the Generic REST connector supports HTTP Basic Authentication and OAuth 2.0 authentication mechanisms. This connector also supports authenticating to the target system by using access token as an input from the user. This authentication mechanism can be useful if your target system does not provide a programmatic approach to obtain access tokens.

The connector supports the following OAuth 2.0 grant types:

• JWT

• Client Credentials

• Resource Owner Password

If your target system does not support the authentication types supported by this connector, then you can implement the custom authentication that your target system supports. You can connect this custom implementation to the connector by using the plug-ins exposed by this connector.

The Generic REST connector synchronizes data between Oracle Identity Governance and REST-based target systems by performing reconciliation and provisioning operations that parse data in the JSON format. If your target system does not support request or response payload in JSON format, then you can create your own implementation for parsing data. You can connect this custom implementation to the connector by using the plug-ins exposed by this connector.

The Generic REST connector is a connector for a discovered target system. This is because the schema of the REST-based target system with which the connector integrates is not known in advance. The Generic REST connector is not shipped with any artifacts. So during application creation, you must specify the schema of your target system and this helps the connector understand the schema of the REST-based target system and then generate the artifacts.

1.2 Certified Components

These are the software components and their versions required for installing and using the connector.

Item	Requirement for AOB Application	Requirement for CI-Based Connector
Oracle Identity Governance or Oracle Identity Manager	You can use one of the following releases: Oracle Identity Governance 12c PS4 (12.2.1.4.0) Oracle Identity Governance 12c PS3 (12.2.1.3.0)	You can use one of the following releases: Oracle Identity Governance 12c PS4 (12.2.1.4.0) Oracle Identity Governance 12c PS3 (12.2.1.3.0) Oracle Identity Manager 11g Release 2 PS3 (11.1.2.3.0) Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0)
Target System	Any identity-aware application that supports REST service	Any identity-aware application that supports REST service
Connector Server	12.2.1.3.0 Note: Connector server is optional, If you have deployed the Generic REST connector in the Connector Server, then you can download the necessary Java Connector Server 12.2.1.3.0 from the Oracle Technology Network web page.	12.2.1.3.0 Note: Connector server is optional, If you have deployed the Generic REST connector in the Connector Server, then you can download the necessary Java Connector Server 12.2.1.3.0 from the Oracle Technology Network web page.
Connector Server JDK	JDK 1.8 or later	JDK 1.8 or later

1.3 Certified Languages

The connector will support the languages that are supported by Oracle Identity Governance.

These are the languages that the connector supports:

• Arabic

• Chinese (Simplified)

• Chinese (Traditional)

• Czech

• Danish

• Dutch

• English

• Finnish

• French

• French (Canadian)

• German

• Greek

• Hebrew

• Hungarian

• Italian

• Japanese

• Korean

• Norwegian

• Polish

• Portuguese

• Portuguese (Brazilian)

• Romanian

• Russian

• Slovak

• Spanish

• Swedish

• Thai

• Turkish

Resource bundles are not part of the connector installation package as the resource bundle entries vary depending on the target system being used.

1.4 Architecture of the Generic REST Connector

The Generic REST connector is implemented using the Identity Connector Framework (ICF).

The ICF is a component that provides basic reconciliation and provisioning operations that are common to all Oracle Identity Manager connectors. In addition, ICF provides common features that developers would otherwise need to implement on their own, such as connection pooling, buffering, time outs, and filtering. The ICF is shipped along with Oracle Identity Manager.

Figure 1-1 shows the architecture of the connector.

Figure 1-1 Connector Architecture

Description of "Figure 1-1 Connector Architecture"

The primary function of the Generic REST connector is to connect to any target system that exposes its REST APIs and then synchronize user identity data between this target system and Oracle Identity Manager.

This connector is not shipped with any metadata as it is a connector for target system that is not known in advance. Depending on the schema of your target system, the connector artifacts are generated after you create the application for your target system. After the connector artifacts are created, Oracle Identity Governance communicates with your target system through the connector bundle by various provisioning and reconciliation operations.

The REST Common layer contains all the plug-ins and logic required by the connector to authenticate to the target system and parse data. Any custom implementation for authorization and data parsing can also be hooked as a plug-in in the REST Common layer.

During provisioning, adapters carry provisioning data submitted through the process form to the target system. The adapters establish a connection with the corresponding Create, Update, or Delete operations in the connector bundle which inturn establishes a connection with a target system by leveraging the REST Common layer. After the adapters establish a connection with the target system, REST calls are made to the endpoints and the required provisioning operation is performed. Subsequently, the response from the target system is returned to the adapters.

During reconciliation, a schedule task is run which calls the SearchOp operation of the connector bundle. The connector bundle establishes a connection with the target system by using the REST Common layer. Then, the connector retrieves all records that match the reconciliation criteria by calling the specific REST endpoint. This result is then passed to Oracle Identity Governance.

1.5 Connector Features

The features of the connector include support for full and incremental reconciliation, limited reconciliation, custom authentication, custom parsing, custom payload, handling multiple endpoint URLs, and SSL communication.

The following are the features of the connector:

• Support for Both Trusted Source and Target Resource Reconciliation

• Full and Incremental Reconciliation

• Limited (Filtered) Reconciliation

• Custom Authentication

• Custom Parsing

• Custom Payload

• Support for Additional HTTP Headers

• Support for Handling Multiple Endpoint URLs

• SSL Communication

1.5.1 Trusted Source and Target Resource Reconciliation

You can configure your REST-based application as a Target application or an Authoritative application for reconciliation of records into Oracle Identity Governance.

There are two versions of the connectors available to provide support for trusted source (authoritative application) and target resource (Target application) reconciliation.

You can use the Generic REST authoritative connector to integrate Eloqua as a trusted source of Oracle Identity Governance. In this mode, the connector reconciles all the person types that are supported by the Eloqua application.

In the target resource mode, you can use the Generic REST target connector to create a Target application to provision and reconcile user records from the Eloqua application.

See Configuring Reconciliation Jobs for more information.

1.5.2 Full and Incremental Reconciliation

After you create the application, you can perform full reconciliation to bring all existing user data from the target system to Oracle Identity Manager. After the first full reconciliation run, you can configure your connector for incremental reconciliation. In incremental reconciliation, only records that are added or modified after the last reconciliation run are fetched into Oracle Identity Manager.

Note:

If the target system contains an attribute, such as updatedAt for target Eloqua, that holds the timestamp at which an object is created or modified, the connector supports incremental reconciliation .

You can perform a full reconciliation any time. See Performing Full Reconciliation and Incremental Reconciliation for more information.

1.5.3 Limited (Filtered) Reconciliation

You can set a reconciliation filter as the value of the Filter Suffix attribute of the scheduled jobs. This filter specifies the subset of newly added and modified target system records that must be reconciled.

See Performing Limited Reconciliation for more information about performing limited reconciliation.

1.5.4 Custom Authentication

By default, the Generic REST connector supports HTTP Basic Authentication and OAuth 2.0 authentication mechanisms. The connector also supports an authentication mechanism in which the user provides access token as an input. The supported grant types for OAuth 2.0 authentication mechanism are JWT, Client Credentials, and Resource Owner Password. If your target system uses any of the authentication mechanisms that is not supported by the connector, then you can write your own implementation for custom authentication by using the plug-ins exposed by this connector.

See Implementing Custom Authentication for more information about creating your own implementation for the custom authentication.

1.5.5 Custom Parsing

By default, the Generic REST connector supports request and response payloads only in the JSON format. If your target system does not support request or response payload in JSON format, then you can implement a custom parsing logic by using plug-ins exposed by this connector.

See Implementing Custom Parsing for more information about custom parsing.

1.5.6 Custom Payload

The Generic REST connector provides support for handling custom formats for any attributes in the payload that do not adhere to the standard JSON format.

This can be achieved by specifying a value for the customPayload parameter of Advanced Settings. See Advanced Settings Parameters for more information about this parameter.

1.5.7 Support for Additional HTTP Headers

If your target system requires additional or custom HTTP headers in any REST call, then you can insert these HTTP headers as the value of the customAuthHeaders configuration parameter.

See Authentication Parameters for more information about this parameter.

1.5.8 Support for Handling Multiple Endpoint URLs

The Generic REST connector allows you to handle attributes of an object class (for example, a User object class) that can be managed only through endpoints other than the base endpoint URL of the object class.For example, in certain target systems, there are attributes of the User object class that can be managed using the base endpoint URL. However, some attributes (for example, email alias) can be managed only through a different endpoint URL. The connector provides support for handling all endpoint URLs associated with an object class.

This can be achieved by providing endpoint URL details of such attributes in the relURIs IT resource parameter. See  Advanced Settings Parameters for more information about this parameter.

1.5.9 SSL Communication

You can configure SSL to secure data communication between Oracle Identity Manager and the REST-based target system.

See Configuring SSL for information about configuring secure communication.

1.6 Use Cases Supported by the Generic REST Connector

The Generic REST connector can be used to integrate OIM with any target system that supports REST services. This connector can be used to load identity data into OIM from a REST service and then efficiently manage identities in an integrated cycle with the rest of the identity-aware applications in your enterprise.

As a business use case example, consider a leading logistics company that has 20+ cloud applications. Most of these cloud applications are now inefficient because data in these applications are manually entered and are managed using spreadsheets or custom-coded process flows. Therefore, this company wants to integrate its cloud applications with OIM to streamline its operations, increase its organizational efficiency, and at the same time, lower its operational costs. There are two approaches for integrating these cloud applications with OIM. One approach would be to deploy a point-to-point connector for each of these applications. The drawbacks of this approach are as follows:

• Increased time and effort to identify and deploy a point-to-point connector for each application.

• Increased administration and maintenance overheads for managing connectors for each application.

• Unavailability of point-to-point connectors for all applications. In such a scenario, one needs to develop custom connectors which increases time and effort to develop, deploy and test the custom connector.

An alternative to this approach is to use the Generic REST connector that can be used to integrate all the cloud applications with OIM. The Generic REST connector provides the ability to manage accounts across all cloud applications without spending additional resources and time on building custom connectors for each cloud application.

The Generic REST connector is a hybrid approach that helps enterprises leverage on-premise OIM deployment to integrate with target systems for identity governance. These targets systems include any application that exposes REST APIs such as SaaS, PaaS, home-grown applications and so on.

The following are some example scenarios in which the Generic REST connector is used:

• User Management

  The Generic REST Connector manages individuals who can access Cloud service by defining them as users in the system and assigning them to groups. This connector allows new users to self-provision on a Generic REST Cloud Service, while having it be controlled by IT. Users can request and provision from a catalog of cloud-based resources that is established by OIM administrators. For example, to create a new user in the target system, fill in and submit the OIM process form to trigger the provisioning operation. The connector executes the create operation against your target system and the user is created on successful execution of the operation. Similarly, operations such as delete and update can be performed.

• Entitlement Management

  The Generic REST Connector manages Cloud services objects (if exposed by the target system) as entitlements. Depending on the target system being used, this connector can be used to manage entitlements such as Groups, Roles, Licenses, Folders, Collaboration and so on. For example, you can use the Generic REST connector to automatically assign or revoke groups to users based on predefined access policies in OIM. Similarly, you can use the Generic REST Connector to manage role memberships that provide selective access to certain Cloud Service functionality or groups. Therefore, as new users are added to a specific role, they automatically gain corresponding access in the applications.