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:
  1. From the Oracle Access Governance navigation menu icon Navigation menu, select Service Administration → Orchestrated Systems.
  2. 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:
  1. Enter a name for the system you want to connect to in the What do you want to call this system? field.
  2. Enter a description for the system in the How do you want to describe this system? field.
  3. Determine if this orchestrated system is an authoritative source, and if Oracle Access Governance can manage permissions by setting the following checkboxes.
    • This is the authoritative source for my identities
    • I want to manage permissions for this system
    The default value in each case is Selected.
  4. Click Next.

Add owners

You can associate resource ownership by adding primary and additional owners. This drives self-service as these owners can then manage (read, update or delete) the resources that they own. By default, the resource creator is designated as the resource owner. You can assign one primary owner and up to 20 additional owners for the resources.

Note:

When setting up the first Orchestrated System for your service instance, you can assign owners only after you enable the identities from the Manage Identities section.
To add owners:
  1. Select an Oracle Access Governance active user as the primary owner in the Who is the primary owner? field.
  2. Select one or more additional owners in the Who else owns it? list. You can add up to 20 additional owners for the resource.
You can view the Primary Owner in the list. All the owners can view and manage the resources that they own.

Account settings

On the Account settings step of the workflow, enter details of how you would like to manage accounts with Oracle Access Governance when configured as a managed system:
  1. Select where to send notification emails when an account is created. The default setting is User. You can select one, both, or none of these options. If you select no options then notifications will not be sent when an account is created.
    • User
    • User manager
  2. When an identity moves within your enterprise, for example when moving from one department to another, you may need to adjust what accounts the identity has access to. In some cases the identity will no longer require certain accounts which are not relevant to their new role in the enterprise. You can select what to do with the account when this happens. Select one of the following options:
    • Disable
    • Delete
  3. When an identity leaves your enterprise you should remove access to their accounts. You can select what to do with the account when this happens. Select one of the following options:
    • Disable
    • Delete

Note:

If you do not configure your system as a managed system then this step in the workflow will display but is not enabled. In this case you proceed directly to the Integration settings step of the workflow.

Note:

If your orchestrated system requires dynamic schema discovery, as with the Generic REST and integrations, then only the notification email destination can be set (User, Usermanager) when creating the orchestrated system. You cannot set the disable/delete rules for movers and leavers. To do this you need to create the orchestrated system, and then update the account settings as described in Configure Orchestrated System Account Settings.

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.

  1. 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
  2. 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.
  3. 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.
  4. 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.
  5. 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?.
  6. What is the OCI function's compartment Id?: Enter the compartment ID for the function you want to integrate.
  7. What is the OCI function's application name?: Enter the application name of the function you want to integrate.
  8. Function Version: Enter the function version of the function you want to integrate.
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. 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
  14. 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.
  15. 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.