Oracle Cloud Infrastructure Documentation

Configure Integration with Generic REST (Standard UI-driven)

Establish a connection between target applications and Oracle Access Governance using REST APIs as a managed system. Use the Generic REST(Standard UI-driven) orchestrated system in the Oracle Access Governance Console.

Before you Begin - Prerequisites

Before configuring Generic REST(Standard UI-driven), ensure that the required OCI resources, authentication credentials, flat file storage (optional), and target REST API details are available.

Create a bucket in the OCI Object Storage service for Flat File Data Load

Perform this step only when you use flat files for full data loads during Integration settings.

To load data using flat file into Oracle Access Governance you need to place the data files in a bucket created using the OCI Object Storage service. This bucket can be created in any compartment of the OCI tenancy. For details regarding OCI Object Storage, see Managing Buckets.

Enter the bucket details specified in the Use Flat File for Full Data Load and copy the exact policies in the root compartment of the tenancy as displayed on the Console. See Creating a Policy for details on how to apply the policies.

Create OCI Vault and Secret

Perform this step only when you use OCI Vault during the Integration settings. Use the OCI Vault service to store target credentials for authentication. Oracle Access Governance retrieves the credentials at runtime using the configured secret OCID.

This method is recommended for secure credential management. Alternatively, you can use the User entered option to store credentials directly in Oracle Access Governance. You must have:
  • Permission to create vaults, keys, and secrets in the target compartment.
  • Permission to use keys to encrypt secrets.
  1. Sign in to the Oracle Cloud Infrastructure Console as a tenancy administrator.
  2. Open the navigation menu  and select Identity & Security → Key Management & Secret Management.
  3. Create a vault.
  4. Create an encryption key when the vault is in active state. See Creating a Master Encryption Key.
  5. From the navigation menu , select Identity & Security, then Secret Management.
  6. Select Create secret.
  7. Select the compartment to create the secret.
  8. Enter meaningful secret name. For example, agcs-grest.
  9. Select the Vault compartment and Vault name.
  10. Select the Encryption key compartment.
  11. In the Encryption key field, select the key that you created.
  12. Select Manual secret generation.
  13. In the secret contents: 
    {
  "username": <username>,
  "password": <example-password>
}
  14. Select Create secret.
  15. Enter the OCI vault details in the Integration settings. This generates the required IAM policy on the Console. To find secret details, see Viewing Secret Details.
  16. Copy the exact statements in the root compartment of the tenancy where you have created the vault.

Configure

Navigate to the Orchestrated Systems Page

The Orchestrated Systems page of the Oracle Access Governance Console is where you start configuration of your orchestrated system.

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. Select 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 integrate with Oracle Access Governance.

You can search for the required system by name using the Search field.

  1. Select Generic REST (Standard UI-driven).
  2. Select Next.

Add details

Add details such as name, description. You can only manage permissions for Generic REST (Standard UI-driven) orchestrated system.

On the Add 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 Name field.
  2. Enter a description for the system in the Description field.
  3. Select Next.

Add Owners

Add primary and additional owners to your orchestrated system to allow them to manage resources.

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

Outline details of how to manage account settings when setting up the orchestrated system, such as managing existing accounts.

  1. Manage accounts that aren't created by Access Governance: Select to manage accounts that are created directly in the orchestrated system. With this, you can reconcile existing accounts and manage them from Oracle Access Governance.
  2. Select Next.

Integration settings

Enter connection details in the Generic REST system.

  1. On the Integration settings step of the workflow, enter the details to connect to the Generic REST system.

    Integration settings
    Parameter Name Mandatory? Description
    Authentication Type Yes Select the authentication method to authenticate to the target system. Select:
    • Bearer: Bearer Token authentication uses an access token to authorize requests
    • Basic: Uses username and password to authenticate REST API requests.
    Access credentials source Yes Specify how credentials are provided.
    • OCI Vault(recommended): Uses a secret stored in OCI Vault. See Create OCI Vault and Secret.
    • User entered: Enter credentials manually and stored in Oracle Access Governance
    OCI tenancy OCID hosting the vault secret Enter the OCID of the tenancy that contains the vault secret. This field is required when OCI Vault is selected.
    Secret OCID for access credentials Enter the OCID of the secret that stores the authentication credentials. This field is required when OCI Vault is selected.
    Username Enter username to authenticate. This field is required when User entered is selected.
    Password Enter password to authenticate. This field is required when User entered is selected.
    Use flat files for full data loads Select to use flat file for the full data instead of configuring listing APIs. If not selected, you must configure REST APIs to ensure data load is performed using APIs. See Use Flat File for Full Data Load.
Use Flat File for Full Data Load
Field Description
What is the OCI tenancy of the object storage bucket? Add the tenancy OCID for the Object Storage bucket containing the flat files you want to import.
What is the namespace for the bucket? Enter the bucket namespace of the tenancy
Bucket Name Enter the name of the bucket where the flat file is stored in OCI Object Storage
What is the OCI tenancy's home region code? Enter the home region code of the tenancy. For example, us-ashburn-1. See The Home Region, and How do I find my tenancy home region?.
Encoding Encoding info. Default is UTF-8
Field Delimiter Enter the field delimiter character used in the Flat File. Default is ,.
Sub Field Delimiter Enter the sub field delimiter character. Default is #.
Multi Value Delimiter Enter the multivalue delimiter character used in the Flat File. Default is ;.
Text Qualifier Enter the character used in the Flat File to act as a text qualifier. Default is ".
Date Format Enter the Java data format in which date type fields are included in the Flat File, for example dd/MM/yyyy. If no date format is specified, the date field would be assumed to be of data type Long.
Copy the exact policies in the root compartment as displayed on the Console. See Creating a Policy for details on how to apply the policies.
Note

The required policies vary depending on where the Object Storage and the Oracle Access Governance instance are hosted (for example, in the same tenancy compared to different tenancies).
  1. Select Test Integration to verify the connection.
  2. Select Add. The orchestrated system would be saved in the Draft mode.

Finish Up

Finish up configuration of the orchestrated system by providing details of whether to perform further customization, or activate and run a data load.

The final step of the workflow is Finish Up.

Select I'm done. The orchestrated system is saved in the Draft mode.

After the orchestrated system is created, Oracle Access Governance displays the Next steps section on the Console to perform remaining configuration tasks required before activation.

Post Configuration

After creating the Generic REST orchestrated system, define permissions, lookups, account attributes, and configure REST APIs to complete the account lifecycle setup.

Create Permissions for the Generic REST System

  1. From the Oracle Access Governance navigation menu  icon navigation menu, select Service Administration → Orchestrated Systems.
  2. Select the Manage integration option from the navigate navigation menu . to view the configuration of a specific orchestrated system. This displays the configuration page for the selected orchestrated system.
  3. From the Data settings section of the page, select Manage on the Permissions tile.
  4. Enter name and display name.
  5. Select Create.
  6. Add attributes for permissions.
    Note

    You can't delete a permission if it's referenced in account attributes or configured REST APIs for the orchestrated system.
    Each permission includes uid and name attributes. You can define more attributes based on the permission structure.
  7. Based on the configuration, use one of the following for data load for permissions:
    • REST API-based data load: Configure Search API using the REST API settings. To fetch permissions from the target system, use Request JSON: 
      {
  "id": "5e5b2cfa-6ef7-4c75-bdf1-e3deddd014fc", //autogenerated
  "name": "Search Users",
  "paginationType": "NONE",
  "method": "GET",
  "url": "<target-system-search-endpoint>",
  "queryParameters": [],
  "headers": [],
  "body": {
    "type": "NONE",
    "textBody": ""
  },
  "subRequests": []
}

      Response JSON

      {
  "items": "<json-path-to-array>",
  "responseValues": [],
  "attributes": [
    {
      "name": "uid",
      "value": "<json-path-to-unique-id>"
    },
    {
      "name": "name",
      "value": "<json-path-to-display-name>"
    }
  ]
}
      See Group Search API.
    • Flat file-based data load: If you have configured flat file integration during setup, upload data using CSV file in the inbox folder. The CSV column names must match the permission schema attribute names.

      After activation of the orchestrated system, you can download the schema from the sample folder of the bucket. Add the CSV data and place these in the inbox for data load. For details, see Flat File Bucket Folder Structure

      For CSV example: 
      __UID__,__NAME__,.....
ANL-23456,Analyst_Permission
MGR-54321,Manager_Permission
HR-65432,HR_Permission
MOD-98765,Moderator_Permission
VWR-12345,Viewer_Permission

Manage Lookups

Use lookups to define reference data used for account attribute mapping, such as countries or languages.

Based on the orchestrated system configuration, lookup data can be loaded using one of the following methods:

  • Flat file-based data load: Lookup data is loaded only using flat files.

  • REST API-based data load
    If REST API-based integration is configured, you can load lookups data using:
    • REST APIs for dynamic lookup synchronization
    • Static file upload for lookup values
  1. From the Oracle Access Governance navigation menu  icon navigation menu, select Service Administration → Orchestrated Systems.
  2. Select the Manage integration option from the navigate navigation menu . to view the configuration of a specific orchestrated system. This displays the configuration page for the selected orchestrated system.
  3. From the Data settings section of the page, select Manage on the Lookups tile.
  4. Select Create Lookup.
  5. Enter name and display name.
  6. Select Create.
  7. Based on the configuration, lookup data can be loaded using one of the following methods:
    1. REST APIs for dynamic lookup. See Country Lookup API.
    2. Flat file (CSV-based lookup values). After activation of the orchestrated system, you can download the schema from the sample folder of the bucket. Add the CSV data and place these in the inbox for data load. For details, see Flat File Bucket Folder Structure
    3. For static file lookup, upload the sample CSV
      Sample CSV for Static Lookup
      uid,name
US,United States
IN,India
UK,United Kingdom
DE,Germany
FR,France
    Note

    You can't delete a lookup if it's referenced in account attributes or REST API configurations.
    Use the lookups defined at the orchestrated-system level for account attributes.

Define Account Attributes

Define account attributes to support outbound transformation or account provisioning operations. You can also use these account attributes to define the account profile required for provisioning.

You can define account attributes using one of the following methods:

  • Manually create attributes using the Console. See Configure Account Attributes. Use the lookups defined at the orchestrated-system level to populate reference values for an account attribute.
  • Import a schema by uploading a JSON file. When you use the Import schema option, the uploaded schema replaces any existing account attributes.
  1. From the Oracle Access Governance navigation menu  icon navigation menu, select Service Administration → Orchestrated Systems.
  2. Select the Manage integration option from the navigate navigation menu . to view the configuration of a specific orchestrated system. This displays the configuration page for the selected orchestrated system.
  3. From the Account settings section of the page, select Manage on the Account attributes tile.
  4. Select Import schema.
  5. Upload a JSON file that defines the account structure. For example: 
    {
        "type": "TARGETACCOUNT",
        "name": "Account",
        "displayName": "Account",
        "attributes":
        [
            {
                "name": "uid",
                "dataType": "TEXT",
                "nature":
                [
                    "REQUIRED"
                ],
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "User ID",
                    "labelHint": "User ID",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "name",
                "dataType": "TEXT",
                "nature":
                [
                    "REQUIRED"
                ],
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "User Name",
                    "labelHint": "User Name",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "email",
                "dataType": "TEXT",
                "nature":
                [
                    "REQUIRED"
                ],
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "Email",
                    "labelHint": "Email",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "firstName",
                "dataType": "TEXT",
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "First Name",
                    "labelHint": "First Name",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "lastName",
                "dataType": "TEXT",
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "Last Name",
                    "labelHint": "Last Name",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "displayName",
                "dataType": "TEXT",
                "nature":
                [
                    "REQUIRED"
                ],
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "Display Name",
                    "labelHint": "Display Name",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "password",
                "dataType": "TEXT",
                "nature":
                [
                    "REQUIRED",
                    "SENSITIVE"
                ],
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "USER",
                    "widget": "PASSWORD",
                    "title": "Password",
                    "labelHint": "Password",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "userType",
                "dataType": "TEXT",
                "usage":
                [
                    "READ"
                ]
            },
            {
                "name": "status",
                "dataType": "FLAG",
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "uiProperties":
                {
                    "inputType": "AUTO",
                    "widget": "TEXT",
                    "title": "Status",
                    "labelHint": "Status",
                    "minLength": 1,
                    "maxLength": 256
                }
            },
            {
                "name": "groups",
                "displayName": "Groups",
                "dataType": "TEXT",
                "nature":
                [
                    "MULTIVALUED"
                ],
                "usage":
                [
                    "READ",
                    "PROVISION"
                ],
                "relationship":
                {
                    "relatedTo": "Group",
                    "relatedBy": "uid",
                    "relationshipProperties":
                    []
                },
                "uiProperties":
                {
                    "inputType": "ADMIN",
                    "widget": "REPEATABLE_FIELD_SET",
                    "title": "Groups",
                    "labelHint": "Groups",
                    "minLength": 1,
                    "maxLength": 256
                }
            }
        ]
}
  6. Review the attributes and save.

Configure Authentication - For Bearer Token

The following steps show how to configure a Bearer Token API in the Oracle Access Governance Console. A Bearer Token API is required only when Bearer Token authentication is selected. The exact steps might vary based on the REST API implementation.

Oracle Access Governance retrieves credentials from OCI Vault, generates an access token using the configured Bearer Token API, and uses that token to invoke account, permission, and lookup APIs at runtime.

  1. From the Oracle Access Governance navigation menu  icon navigation menu, select Service Administration → Orchestrated Systems.
  2. Select the Manage integration option from the navigate navigation menu . to view the configuration of a specific orchestrated system. This displays the configuration page for the selected orchestrated system.
  3. From the Data settings section of the page, select Manage on the REST APIs tile.
  4. Select Bearer token API.
  5. Enter the details either in the JSON format or use the Console to enter the request and response details.
  6. Use Console, enter the details, such as:
      • Name: Get Token API
      • Method: POST
      • URL: <token-endpoint>
  7. Configure Headers
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: <<CREDENTIALS>>. Credentials are resolved at runtime using OCI Vault or user-entered credentials.
  8. Select Request body type
    • None: REST API doesn't require a request body
    • JSON: Send the request body in JSON format.
    • Form: Send the request body as form parameters.
  9. Configure body. For example: 
    grant_type=client_credentials&scope=<scope>
    grant_type=password&username=<username>&password=<password>
  10. Configure response. For example: 
    Name: accessToken Value: <JP>$.access_token</JP>
  11. Select Save.

Configure REST APIs for Entities

After defining permissions, account attributes, and lookups, configure REST APIs for these entities to support provisioning, reconciliation, and data load operations based on the selected configuration.

Use runtime expressions in the request and response. See REST API Runtime Expressions and examples.
  1. From the Oracle Access Governance navigation menu  icon navigation menu, select Service Administration → Orchestrated Systems.
  2. Select the Manage integration option from the navigate navigation menu . to view the configuration of a specific orchestrated system. This displays the configuration page for the selected orchestrated system.
  3. From the Data settings section of the page, select Manage on the REST API tile.
  4. Select the required API category (for example, Bearer token or Test connection).
  5. Select an API (for example, Get) or select Create API.
  6. Enter the details either in the JSON format or use the Console.
  7. In the Console, enter the following details based on the API:
    • Name: Enter a name for the API (for example, Get Token API)
    • Method: Select the HTTP method (GET, POST, PUT, PATCH, DELETE)
    • URL: Enter the endpoint URL
    • Enter Headers, Parameters, Body, Response, Request, Subrequests.
  8. Select Save.

REST API Runtime Expressions

Use runtime expressions to dynamically retrieve values during REST API execution.

Syntax Desciption Example
<<CREDENTIALS>> Resolves authentication credentials configured in Integration Settings at runtime. Credentials can be retrieved from OCI Vault or User entered configuration. Used in REST API headers for authentication. 
{
  "name": "Authorization",
  "value": "<<CREDENTIALS>>"
}
<EL>...</EL> Expression Language (EL) to retrieve attribute values at runtime. Used in request payloads, headers, parameters, or URLs when values must be populated dynamically from attributes. 
<EL>attributes.get('name').get(0)</EL>
Note

The name attribute must be present in the account attribute schema.
<JP>...</JP> JSON Path (JP) expression to extract values from REST API responses. Used in response mappings to retrieve values returned by target REST APIs. 
<JP>$.access_token</JP>
UQ: Value must be inserted into the payload without quotation marks. Used for literal values such as boolean and numbers 
UQ:<EL>attributes.get('status').get(0)</EL>

Activate Orchestrated System

On the Manage orchestrated system page, select Activate.

Activate the orchestrated system after completing all tasks listed in the Next Steps section. If Flat File for Full Data Load is configured, access the Flat File folder structure under the configured Object Storage bucket and upload the input CSV files for Permissions, Lookups and Target Account after activation, as needed.

Configure Outbound Transformations for Generic REST (Standard UI Driven)

Use outbound transformations to map Oracle Access Governance identity attributes to target system account attributes during provisioning operations.

Outbound transformations dynamically populate values used in REST API request payloads for operations such as Create Account or Update Account.

For configuring outbound transformation, see Apply Outbound Transformations for Identity Attributes.

Examples
user.getName().getGivenName() user.getName().getFamilyName()

For all utility methods, see Transformation Utilities for Outbound Data Transformation and Examples for Outbound Data Transformation.