Integrate with Generic REST

Generic REST Orchestrated System Overview

The Generic REST Orchestrated System provides a solution to integrate Oracle Access Governance with REST-based identity-aware systems. A REST-based identity-aware system is any system that exposes its REST APIs or interfaces for identity management.

The Generic REST Orchestrated System provides features including the following:

Full/incremental data load for Authoritative Sources or Managed Systems
Real-time provisioning
Cloud native serverless function integration to define REST-based identity-aware system schema, request, response, and test templates

The Generic REST Orchestrated System differs from others in that definitions for schema, request, and response are not fixed. Other Orchestrated Systems have schema, request, response, and test templates pre-loaded for the Authoritative Source or Managed System to which they apply. Since Generic REST Orchestrated Systems can apply to any REST-based identity-aware system, the schema, request, response, and test templates are loaded at runtime, rather than when the Orchestrated System is created.

For each Authoritative Source or Managed System, you will need to create the following templates:

grc-schema-template: This template defines the schema for the Authoritative Source or Managed System you want to integrate.
grc-request-template: This template defines the request format (headers, url, request parameters, request body) required to invoke the Authoritative Source or Managed System API to request identity data.
grc-response-template: This template defines the response format for identity and account data.
grc-test-template: This template defines an API to test the connectivity between Oracle Access Governance and the Authoritative Source or Managed System.

When an operation is invoked the following parameters are passed to OCI Functions.

Orchestrated system name
Entity name (identity or account)
Operation name

The OCI Function is called and returns a JSON file with the templates relevant to the Orchestrated System.

Prerequisites

Before you install and configure a Generic REST Orchestrated System, you should consider the following prerequisites and tasks.

Certified Components

The Managed System can be any one of the following:

Any identity-aware system that supports REST services

Supported Modes

Generic REST Orchestrated System supports the following configuration modes:

Authoritative Source
Managed System

Use Cases Supported by the Generic REST Orchestrated System

A Generic REST Orchestrated System can be used to on-board identity data into Oracle Access Governance from a REST service, and then efficiently manage identities in an integrated cycle with the rest of the identity-aware systems 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 Oracle Access Governance 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 Oracle Access Governance. 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 Orchestrated System to integrate all the cloud applications with Oracle Access Governance. The Generic REST Orchestrated System 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 Orchestrated System helps enterprises leverage Oracle Access Governance to integrate with Managed Systems for identity governance. These Managed 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 Orchestrated System is used:

User Management

The Generic REST Orchestrated System allows you to manage individuals who can access resources by defining them as identities in Oracle Access Governance and assigning them to identity collections and roles. Identities are created from any authoritative Orchestrated System such as Generic REST, on data load.
Access Control

The Generic REST Orchestrated System manages access control via identity collections, roles, access bundles, and policies. Depending on the orchestrated system being used, you can manage access using Oracle Access Governance self service features, specifically Request Access. For example, you can use the Generic REST Orchestrated System to automatically assign or revoke access to a system based on predefined access policies in Oracle Access Governance. As new users are added to a specific role, they automatically gain corresponding access in the systems covered by the access policy.

Setup OCI Serverless Function to Connect with REST-based Identity Aware System

The Generic REST Orchestrated System requires support from OCI Serverless Functions in order to connect to REST-based identity aware systems.

To setup OCI Functions for use with the Generic Rest Orchestrated System refer to Setup OCI Serverless Function to Connect with REST-based Identity Aware System.

Configure

You can establish an integration between REST-based identity-aware systems and Oracle Access Governance by entering details of the OCI Functions and templates to integrate the REST-based system. To achieve this, use the Orchestrated System functionality available in the Oracle Access Governance Console.

Navigate to the Orchestrated Systems Page

Navigate to the Orchestrated Systems page of the Oracle Access Governance Console, by following these steps:

From the Oracle Access Governance service home page click on the icon, and select Service Administration → Orchestrated Systems.
Click the Add an orchestrated system button to start the workflow.

Select system

On the Select system step of the workflow, you can specify which type of system you would like to onboard. You can search for the required system by name using the Search field. Select the Generic REST Connector tile. When you select this tile, a dialog page is shown outlining the steps to configure the Orchestrated System. This includes a link to a sample implementation of the OCI Functions required to connect to REST-based identity aware systems. If you have not done so, you should download the idm-agcs-generic-rest-reference-implementation.zip file and develop your own OCI Functions based on this example. For further details on the sample implementation see Setup Sample Implementation. For further details on how to develop the OCI Functions required see Setup OCI Serverless Function to Connect with REST-based Identity Aware System and Generic Rest Schema Discovery.

Once selected, a value of Generic REST Connector is displayed on the right hand side under What I've selected. Click Next.

Enter details

On the Enter Details step of the workflow, enter the details for the orchestrated system:

Enter a name for the system you want to connect to in the What do you want to call this system? field.
Enter a description for the application in the How do you want to describe this system? field.

Determine if this orchestrated system is an authoritative source, and if Oracle Access Governance can manage permissions for existing users by setting the following checkboxes.

Table - Authoritative Source/Managed System

Checkbox	Default	Description
This is the authoritative source for my identities.	Selected	If selected, this checkbox means that this orchestrated system is a trusted source for user or identity information.
I want to manage permissions for this system.	Selected	If selected, this checkbox means that Oracle Access Governance can provision accounts on the orchestrated system, and manage permissions for existing accounts residing in the system.

Click Next.

Configure

On the Configure step of the workflow, enter the configuration details required to allow Oracle Access Governance to connect to the system using the Generic REST Connector.

What is the OCI user's OCID?: Enter the Oracle Cloud Identifier (OCID) for the OCI user you will use to connect to the system. For further information regarding OCIDs see Oracle Cloud Identifier, OCID Syntax, and Where to Get the Tenancy's OCID and User's OCID. For example, ocid1.user.oc1..aabdgsegsccawmw2o6qraopae7egmlochlopclhnwxq6pctu6oocgn
What is the fingerprint for the OCI user's API Key?: Enter the fingerprint of the public key of the API Signing Key for the OCI instance you will be connecting to. Steps to retrieve the fingerprint can be found in How to Get the Key's Fingerprint, The fingerprint will look similar to this: 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef.
What is the OCI user's private API Key in PEM format?: Enter the private SSH key (.pem file) for the API Signing Key. Copy it directly from the text editor or use the cat command to open the SSH key file from console.
What is the OCI tenancy of the OCI user?: Enter the OCID for the target tenancy. For further information regarding OCIDs see Oracle Cloud Identifier, OCID Syntax, and Where to Get the Tenancy's OCID and User's OCID.
What is the OCI function's region code?: Enter the home region for the target OCI tenancy, using the region identifier. The region identifier for your home region can be found in Regions, the identifier for US East (Ashburn) is us-ashburn-1, for example. For further information on home region, see The Home Region, and How do I find my tenancy home region?.
What is the OCI function's compartment Id?: Enter the compartment ID for the function you want to integrate.
What is the OCI function's application name?: Enter the application name of the function you want to integrate.
Function Version: Enter the function version of the function you want to integrate.
Request Template Cache TTL In Minutes: Duration for which the request template will be cached. If time is set as 0, no caching will be done. When the cache expires the OCI function will be invoked to get the new template. The cache time should be less than the token expiry time to avoid dropped connections due to expired token.
Response Template Cache TTL In Minutes: Duration for which the response template will be cached. If time is set as 0, no caching will be done. When the cache expires the OCI function will be invoked to get the new template. The cache time should be less than the token expiry time to avoid dropped connections due to expired token.
Test Template Cache TTL In Minutes: Duration for which the test template will be cached. If time is set as 0, no caching will be done. When the cache expires the OCI function will be invoked to get the new template. The cache time should be less than the token expiry time to avoid dropped connections due to expired token.
Schema Template CacheTTL In Minutes: Duration for which the schema template will be cached. If time is set as 0, no caching will be done. When the cache expires the OCI function will be invoked to get the new template. The cache time should be less than the token expiry time to avoid dropped connections due to expired token.
Read Response Timeout In Seconds: Enter an integer value that specifies the number of seconds within which response must be received from the orchestrated system
Connect Timeout In Seconds: An integer value that specifies the number of seconds after which an attempt to establish the connection between the orchestrated system and Oracle Access Governance times out.
Click Add to create the orchestrated system.

Finish up

On the final step, Finish up, you are given a choice whether to further configure your Orchestrated System before running a data load, or accept the default configuration and initiate a data load. Select one from:

Customize before enabling the system for data loads
Activate and prepare the data load with the provided defaults

Post Configuration

Once you have configured your Generic REST Orchestrated System, you can navigate to the Orchestrated System page and check operations in the activity log. Some of the operations that you may see include:

Schema Discovery: The Generic REST Orchestrated System is schema-less at design and deployment time. As part of the orchestration lifecycle, schema discovery must take place to update the Orchestrated System with details of the schema and object classes for the required Authoritative Source or Managed System. For details regarding Schema Discovery see Generic Rest Schema Discovery.
Validate: This operation performs the following tasks:
- Invokes the test template, which in turn invokes the endpoint specified in the template and checks connectivity with the Managed System.
- Invokes the schema template and retrieves all the schema information for the Managed System including entities and attributes.
Lookup Data Load: If any lookups are defined, the data corresponding to the lookups is loaded.
Full Data Load: This operation will load the data for any entities specified and ingest.