ICF Custom Connector

Introduction

Identity connectors are components developed to link Oracle Identity Cloud Service with external stores of applications, directories, and databases.

Prerequisite

Copying the customer connector bundle to the Bridge.

Stop the Bridge.
Copy the customer connector bundle to BRIDGE_HOME/bundle_home.
If the integration requires third-party libraries, follow steps #4 to #6.
Create a folder customconnector/lib under thirdparty-lib (under BRIDGE_HOME).
Copy the required libraries to the directory created in Step #4.
Run below command from BRIDGE_HOME.

On a Linux Machine:

sh updateJar.sh <customer-connector-bundle-name> ./thirdparty-lib/ customconnector

On a Windows Machine:

updateBundleJarWithThirdPartyLib.bat <customer-connector-bundle-name> D:\devBridge\thirdparty-lib\customconnector
Start the Bridge.

Create an ICF Custom Connector

Create LocalConnectorBundle.

Create the LocalConnectorBundle so that Oracle Identity Cloud Service knows the details of the connector.

POST /LocalConnectorBundles

{
  "schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:LocalConnectorBundle"
  ],
  "bundleName": "${connectorKey.bundleName}",
  "bundleVersion": "${connectorKey.bundleVersion}",
  "connectorName": "${connectorKey.connectorName}",
  "displayName": "${connectorInfo.connectorDisplayName}"
}

Create the Identity Bridge and start the Bridge.

See Create a Provisioning Bridge and Start a Provisioning Bridge for more information.

Create CustomConnectorInfo using the LocalConnectorBundle ID and the Identity Bridge ID.

This will return the created application ID. Get the application and write down the AccountObjectClass ID, get the AccountObjectClass and write down the outboundMappedAttributesId.

POST /CustomConnectorInfos

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:CustomConnectorInfo"
  ],
  "identityBridge": {
    "value": "${bridgeId}"
  },
  "connectorBundle": {
    "value": "${connectorBundleId}"
  },
  "appDisplayName": "${appDisplayNameValue}",
  "appDescription": "${appDisplayNameValue} custom connector app"
}

Patch the application with the bundleConfigurationProperties values.

Provide bundle configuration property values so that Oracle Identity Cloud Service can retrieve the schema info from the connector using the endpoint /admin/v1/ManagedAppSchemaDiscovery.

The following code is an example for a Database Table connector.

PATCH /Apps/{appId}

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "path": "urn:ietf:params:scim:schemas:oracle:idcs:extension:managedapp:App:bundleConfigurationProperties",
            "value": [
                {
                "value": [
                    "1521"
                ],
                "icfType": "String",
                "required": false,
                "helpMessage": "PORT_HELP",
                "confidential": false,
                "displayName": "PORT_DISPLAY",
                "name": "port"
            },
[PORTIONS OF THE CODE SAMPLE HAVE BEEN REMOVED.]
            {
                "icfType": "String",
                "required": false,
                "helpMessage": "UPDATE_SCRIPT_HELP",
                "confidential": false,
                "displayName": "UPDATE_SCRIPT_DISPLAY",
                "name": "updateScript"
            },
            {
                "icfType": "String",
                "required": false,
                "helpMessage": "ADDATTR_SCRIPT_HELP",
                "confidential": false,
                "displayName": "ADDATTR_SCRIPT_DISPLAY",
                "name": "addMultiValuedAtributeScript"
            },
            {
                "icfType": "String",
                "required": true,
                "helpMessage": "KEY_COLUMN_HELP",
                "confidential": false,
                "displayName": "KEY_COLUMN_DISPLAY",
                "name": "keyColumn",
                "value": [
                    "ID"
                ]
            },
            {
                "icfType": "ArrayOfString",
                "required": false,
                "helpMessage": "MULTIVALUE_TABLES_HELP",
                "confidential": false,
                "displayName": "MULTIVALUE_TABLES_DISPLAY",
                "name": "multivalueTables",
                "value": [
                    "CC_DEPARTMENT"
                ]
            }
            ]
        }
    ]
}

Activate the application.

PUT /AppStatusChanger/{appId}

{
  "active":${isActive},
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AppStatusChanger"
  ]
}

Run schema discovery.

The connector must implement the SchemaOp interface for the /ManagedAppSchemaDiscovery endpoint to work. See Understanding the Identity Connector Framework for more information.

PUT /ManagedAppSchemaDiscovery
```
{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:ManagedAppSchemaDiscovery"
  ]
}
```

Set AccountObjectClass.schema.idcsManaged to true.

The application is configured with object classes discovered from the previous step. This step is to select and add the desired schema attributes to be managed by Oracle Identity Cloud Service.

PATCH /AccountObjectClasses/{aocId}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
  {
     "op":"replace",
     "path": "schema[name eq "${attrName}"].idcsManaged",
     "value": true
  },
  {
     "op":"replace",
     "path": "schema[name eq "${attrName}"].idcsManaged",
     "value": true
  }
  ]
}

Update outboundMappedAttribute/inboundMappedAttribute.

If the application is configured as an authoritative source (of Identity Cloud Service resources), then Identity Cloud Service applies any inbound MappedActions and inbound MappedAttributes configured on that AccountObjectClass. This step is to define inbound MappedAttributes to apply the attributes-values of the ManagedObject to the Identity Cloud Service Resource.

If the application is configured as a non-authoritative source (of Identity Cloud Service resources), then define any outbound MappedAttributes to apply the attributes-values of the Identity Cloud Service Resource to the ManagedObject.

a. PUT /MappedAttributes/{outboundMappedAttributesId}

{
      "idcsResourceType" : "User",
      "direction": "outbound",
      "refResourceType" : "AccountObjectClass",
      "attributeMappings" : [
          {
              "managedObjectAttributeName": "FIRSTNAME",
              "idcsAttributeName": "\$(user.name.givenName)",
              "appliesToActions": [
                "create",
                "update"
              ]
          },
          {
              "managedObjectAttributeName": "LASTNAME",
              "idcsAttributeName": "\$(user.emails[primary=true].value)",
              "appliesToActions": [
                "create",
                "update"
              ]
          },
    [PORTIONS OF THE CODE SAMPLE HAVE BEEN REMOVED.]
          {
              "managedObjectAttributeName": "BIGDECIMALCOLUMN",
              "idcsAttributeName": "123.456",
              "appliesToActions": [
                "create"
              ]
          },
          {
              "managedObjectAttributeName": "GUARDEDSTRINGCOLUMN",
              "idcsAttributeName": "guardedString",
              "appliesToActions": [
                 "create"
              ]
          },
          {
              "managedObjectAttributeName": "GUARDEDBYTEARRAYCOLUMN",
              "idcsAttributeName": "guarded",
              "appliesToActions": [
                "create"
              ]
          }
      ],
    "schemas" : ["urn:ietf:params:scim:schemas:oracle:idcs:MappedAttribute"]
  }

b. PUT /MappedAttributes/{inboundMappedAttributesId}

{
      "idcsResourceType" : "User",
      "refResourceType" : "AccountObjectClass",
      "direction": "inbound",
      "attributeMappings" : [
          {
              "managedObjectAttributeName": "$(account.FIRSTNAME)",
              "idcsAttributeName": "name.givenName",
              "appliesToActions" : [
                    "create",
                    "update"
                ]
          },
          {
              "managedObjectAttributeName": "$(account.active)",
              "idcsAttributeName": "active",
              "appliesToActions" : [
                    "create",
                    "update"
                ]
          },
[PORTIONS OF THE CODE SAMPLE HAVE BEEN REMOVED.]
          {
              "managedObjectAttributeName": "$(account.active)",
              "idcsAttributeName": "urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:isFederatedUser",
              "appliesToActions" : [
                    "create",
                    "update"
                ]
          },
          {
              "managedObjectAttributeName": "$(account.active)",
              "idcsAttributeName": "urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:doNotShowGettingStarted",
              "appliesToActions" : [
                    "create",
                    "update"
                ]
          }
      ] ,
    "schemas" : [
"urn:ietf:params:scim:schemas:oracle:idcs:MappedAttribute"]
  }

Update the correlation rule if necessary.

Identity Cloud Service applies any correlation-policy configured for the AccountObjectClass to correlate the ManagedObject with an Identity Cloud Service user.

PATCH /Rules/{correlationRuleId}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
     {
      "op": "replace",
       "path":"return[name eq \"filter\"]",
      "value": [
        {
            "name": "filter",
            "value": "emails[primary eq true].value eq \"$(account.name)\""
        }
    ]
    }
  ]
}