1 About the Generic REST Connector

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

Oracle Identity Manager is a centralized identity management solution that provides self service, compliance, provisioning and password management services for applications residing on-premise or on the Cloud. Oracle Identity Manager connectors are used to integrate Oracle identity Manager with the external and identity-aware applications.

The following topics introduce the Generic REST connector:

• Introduction to the Generic REST Connector

• Certified Components for the Generic REST Connector

• Certified Languages for the Generic REST Connector

• Features of the Generic REST Connector

• Use Cases Supported by the Generic REST Connector

• Architecture of the Generic REST Connector

• Generic REST Connector Concepts

1.1 Introduction to the Generic REST 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.

• RELEASE_NUMBER has been used as a placeholder for the current release number of the connector. Therefore, replace all instances of RELEASE_NUMBER with the release number of the connector. For example, 11.1.1.5.0.

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 any of 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 OIM 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. Instead, it is shipped with a set of deployment utilities that help in discovering the schema of the REST-based target system and generating the artifacts.

1.2 Certified Components for the Generic REST Connector

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

Table 1-1 Certified Components

Item	Requirement
Oracle Identity Manager or Oracle Identity Governance	You can use one of the following releases of Oracle Identity Governance or Oracle Identity Manager: Oracle Identity Governance 12c (12.2.1.4.0) Oracle Identity Governance 12c (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 target system that supports REST service.
Connector Server	11.1.2.1.0 12.2.1.3.0
Connector Server JDK	JDK 1.6 or later

1.3 Certified Languages for the Generic REST Connector

The connector will support the languages that are supported by Oracle Identity Manager. Resource bundles are not part of the connector installation media as the resource bundle entries vary depending on the target system being used.

1.4 Features of the Generic REST Connector

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.4.1 Support for Both Trusted Source and Target Resource Reconciliation

The Generic REST connector includes a groovy file (a part of the metadata generator) that enables you to configure the connector to run either in the trusted source mode or target resource mode.

1.4.2 Full and Incremental Reconciliation

After you create the connector, 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:

The connector supports incremental reconciliation if the target system contains an attribute that holds the timestamp at which an object is created or modified.

You can perform a full reconciliation any time. See Full Reconciliation and Incremental Reconciliation.

1.4.3 Limited (Filtered) Reconciliation

You can reconcile records from the target system based on a specified filter criterion. To limit or filter the records that are fetched into Oracle Identity Manager during a reconciliation run, you can specify the subset of added or modified target system records that must be reconciled.

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 Limited (Filtered) Reconciliation.

1.4.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.4.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.4.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 IT resource parameter. See Additional Configuration Parameters for more information about this parameter.

1.4.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 or customAuthHeaders IT resource parameters.

See Additional Configuration Parameters for more information about these parameters.

1.4.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  Additional Configuration Parameters for more information about this parameter.

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

1.6 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-1shows 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 application that exposes its REST APIs and then synchronize user identity data between this application 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 during connector deployment. Once the connector artifacts are created, Oracle Identity Manager communicates with your target system through the connector bundle by using various adapters and scheduled tasks.

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

1.7 Generic REST Connector Concepts

Learn about the basic concepts behind the components used for generating the Generic REST connector.

Connector Generation

The Generic REST connector installation package is not shipped with any metadata or connector artifacts. It is shipped only with a set of deployment utilities that help in generating the metadata based on your target system schema. Therefore, understanding the schema of your target system is one of the important aspects in generating the connector. You must create a schema file describing the attributes of your target system to help the connector know your target system. The Generic REST connector installation package includes a Groovy file in which you can specify information about your target system. This information is used by the metadata generator to generate the connector based on the target system schema.

To generate the connector, you must create a schema file describing the attributes of your target, configure the Groovy file and generate the connector metadata package. Then, you must install the connector installation package to upload the connector bundle (org.identityconnectors.genericrest-1.0.1115.jar) to the Oracle Identity Manager database, and then install the connector metadata package containing the metadata specific to your target system..

The key to understanding the architecture of the connector generation and installation is to first understand its components. The Generic REST connector includes the following key components:

• Schema File — a user-created properties file

• Groovy File — GenericRestConfiguration.groovy

• Metadata Generator — GenericRestGenerator.cmd or GenericRestGenerator.sh

Figure 1-2 shows the architecture of the connector installation and the overall flow of the connector generation process.

Figure 1-2 Connector Generation Process Flow

Description of "Figure 1-2 Connector Generation Process Flow"

Connector Installation Package

The connector installation package contains all files required by the Connector Installer to install this connector. The connector installation package also contains files that you must update to include your target system details and files that let you generate the metadata for your connector. The connector installation package for this connector is a ZIP file named GenericREST-RELEASE_NUMBER.zip that you can download from the Oracle Technology website (OTN).

For information about the files and directories in the connector installation package, see Table C-1.

Schema File

The schema file is a properties file that must contain entries pertaining to your target system in the name-value pair format. This file is not available in the connector installation package as the target system is not known in advance. You need to create a schema file representing the structure of your target system.

The schema file must define a list of all target system fields and their details that the connector needs to perform connector operations. It must also define the target system field that must be used to identify records to be fetched during reconciliation operations.

Groovy File

The Groovy file, GenericRestConfiguration.groovy, is located in the GenericREST-RELEASE_NUMBER/metadata-generator/resources directory of the connector installation package. You use the GenericRestConfiguration.groovy file to specify values for properties that can store basic information about your target system schema.

The metadata generator uses the GenericRestConfiguration.groovy file to perform the following tasks:

• Understand the schema

• Configure the mode (trusted source or target resource) in which you want to run the connector

• Generate the connector metadata package specific to your target system

The Groovy file has one or more configuration sections. Each section begins with CONFIG_NAME {, where CONFIG_NAME is the name of the configuration. Depending on whether you want to configure the connector to run in the trusted source or target resource mode, a section in the Groovy file can be either a trusted source type or target resource type.

The GenericRestConfiguration.groovy file provided in the connector installation package contains sample configuration (one each for trusted source and target resource) with prepopulated values for most of the entries. Depending upon your requirements, you can add or modify values for entries in the sample configuration or create new sections for your configuration. The following are the sample configuration sections in the GenericRestConfiguration.groovy file:

• trusted

  You specify values for the entries in this section if you want to configure the connector for the trusted source mode.

• target

  You specify values for the entries in this section if you want to configure the connector for the target resource mode.

Metadata Generator

The metadata generator creates files that are needed during the connector installation process and contain definitions of all connector components such as process tasks, scheduled tasks, lookup definitions and so on. The metadata generator is an executable file, GenericRestGenerator.cmd or GenericRestGenerator.sh file, that is located in the genericrest-RELEASE_NUMBER/metadata-generator/bin directory.

The metadata generator uses the specified configuration section from the Groovy file as an input and creates configuration files containing connector component data specific to your target system. The configuration section in the Groovy file in turn references the schema file.

The output connector metadata package is a ZIP file containing metadata files.

For a description about each of the files in the connector metadata package, see Table C-2.