Skip to main content

Data provisioning

Prerequisites​

When you enable data provisioning, choose the CyberArk connector. Enter a unique name for the new connector. If you selected and configured a template connector, the configured template is stored in Omada Identity. When Omada rolls out changes to the template connectors, your configurations remain intact in your own version.

Provisioning configuration​

If the addresses for query and for entities are the same, you must leave the Entity root and Query address fields blank or empty. Instead, you must enter the full address in the Base URI field.

ParameterDescription
Base URISpecify the server address.This is the URI used to access SCIM server, for example: https://127.0.0.1/.
Entity rootThis is the URI used when entities are not in the root server directory. For example, when users are accessed using the following address: http://127.0.0.1:8888/v2/users, the Entity root is “v2”.
Authentication modeThe type of authentication to use for the REST system. Depending on the type of authentication that you choose to use, you may see more or fewer settings.The available options are: None (there are no authentication headers), Basic (username and password are required), OAuth2 (all OAuth mandatory fields must be completed with proper value). These values can be found in your external vendor’s documentation of your REST system.
OAuth grant typeThe way the authorization token is requested: Client credentials, Password credentials
URL for authorization tokenEnter the URL used to exchange an authorization grant for an access token.You can get it from your SCIM 2.0-based application.
OAuth client IDThe public client ID that is used for exchanging the authorization code for an access token.You should get it from your SCIM 2.0-based application.
OAuth client secretThe private client secret that is used for exchanging the authorization code for an access token.You should get it from your SCIM 2.0-based application.
OAuth ResourceThe name of the OAuth resource owner.
OAuth Token Revoke URLThe token revocation endpoint URL.
Token cache policyThere are three options: Always cache Expiration interval (if you select this option, you need to set the OAuth token expiration time in seconds), Never cache
UsernameThe user name for the selected type of authentication.
PasswordThe password used for authentication.
Security protocolThe security protocol of your REST system: TLS 1.2 or higher.
Content type headerChoose the format of the content. The default value is application/json.
Accept headerThe default value is application/json.
Use numeric valuesSetting this to true ensures that intType, longType, and referenceType values are sent as numeric values, and not string, in the JSON payload. For referenceType properties, the value is only set as a numeric value if the resolved value can be converted to a numeric value.
Query addressThis is the base address for querying objects. It is appended to Base URI when specified, for example: https://127.0.0.1/query.
Root resource pathThis field controls the root resource path used when references and object ids are resolved. The default is $.Resources[0] as defined in the SCIM standard.
Test connectionSelect this checkbox to perform a test of the connection before using the connector.
Test queryThis field only appears if the Test connection field is enabled. Here you can enter an optional test query used to verify the connection. The query must be relative to the base address, e.g., 'Users.' Entering a test query is important for a proper test for authentication methods which doesn't access the target system, e.g., basic authentication or static bearer token.

Data model​

The CyberArk connector is built on top of SCIM 2.0 and a generic REST connector. This connector overrides the default REST connector behavior of the Resolve Reference Property method and Resolve Object ID. The base address for both requests is taken from the URI for accessing REST query configuration parameter.

The Resolve Reference Property method​

The Resolve Reference Property method only calculates those properties that do not have the isKey property set to true. The following is the request that is sent to the SCIM server:

GET https://<scim server address>/A?filter=B eq 'C'

These are the DataModel attributes:

  • A – referenceObject
  • B – ReferenceLookupProperty
  • C – property value

The Resolve Object ID method​

The Resolve Object ID method is similar to the Resolve Reference Property method. However, it only works on the properties where isKey is set to true.

You can also have multiple properties of this kind. If you have multiple properties, the referenceKeyProperty and the referenceObject must be the same in each of them. In that case, only the AND operator is used. For example:

GET https://<scim server address>/A?filter=B eq 'C'
GET https://<scim server address>/A?filter=B eq 'C' and D eq ‘E’

The following are the DataModel attributes:

  • A – referenceObject
  • B – ReferenceLookupProperty
  • C – property value

The following are optional attributes:

  • D – another ReferenceLookupProperty
  • E – another property value

JSONPath property names​

You can use the JSONPath to update existing field values in the request. This feature is useful for reconciliation or when utilizing request template object details.

Limitation

The JSONPath properties can be utilized with appropriate fields present in the JSON file path. The JSONPath can't create new fields.

note

If you don't use reconciliation, add other properties to build localization of this JSON Path.

The property names starting with $. are interpreted by the connector as a JSON path. The values of those properties can be either text or JSON format. In the latter instance the connector adds an appropriate structure in the designated location. The JSONPath properties can be combined with the existing properties and they are applied on top of the prepared request.

Example
<properties>
  <property name="$.added[0].loginId" />
  <property name="$.added[0].roles" multiValued="true" />
  <property name="$.added[0].sampleArray" multiValued="true" />
</properties>

Request templates​

You can provide JSON request template in the object details with the request template being defined per operation.

The following convention should be followed when naming a detail:

{Operation}Request,

As shown in the example below values should be stored within the <largeDataField> element.

Example
<object name="SampleUser">
  <objectDetails>
    <objectDetail name="CreateRequest">
      <largeDataField>
      {
        "added":[
          {
            "organization":{
              "name":"my company",
              "type":"Company"
            },
            "roles":[
              {
                "name":"Role 1"
              },
              {
                "name":"Role 2"
              }
            ],
        "sampleArray":[],
            "loginId":"myLogin"
          }
        ]
      }
      </largeDataField>
    </objectDetail>

Schemas​

Schemas describe which properties you can expect in a specific request. The difference between SCIM 2.0 and other REST systems are that schemas in SCIM 2.0 are an integral part of any request to the SCIM server.

For every operation, for example, Create a User, Add/Delete assignments, one of the JSON body properties must be schemas, and this defines how the request looks like.

Reconciliation​

The SCIM 2.0 Connector has a feature called Object Reconciliation which is triggered in the data model by setting objectDetails with names ReconcileOnUpdate or ReconcileOnDelete to have the value True. For example:

<objectDetail name="ReconcileOnUpdate" value="True"/>

<objectDetail name="ReconcileOnDelete" value="True"/>

This setting works on a per object basis, so it is possible to have it enabled for certain objects and disabled for others.

If the operation is Update or Delete, and the relevant property is set to True, the connector merges between the current object in the external system and operations defined in Task Mapping.

When Reconciliation is turned off, a request is created based on task mapping alone. Each task mapping rule is converted to a JSON property (or array entry). The request is then sent out to a server.

When Reconciliation is turned on, the first step is taking the object/entity that is being read from an external system (SCIM server). Then, each task mapping rule is merged into this object based on the action and multivalued attributes.

The result of this operation is then sent to the external system.

Task Mappings​

You can apply the following action attributes to task mappings: Add, Modify, Delete.

The Multivalue attribute can be set to true or false.

In the entity taken from an external system, the task mapping name attribute points to a JSON property. The dot character (“.”) indicates a child of a parent property.

In the following example, the name attribute performs an operation on the members array item and in the value property.

<fieldMapping name="members[].value"

Addition​

In this action attribute, the SCIM 2.0 Connector searches for a property on an existing structure. If the parent property is an array, it adds elements to it. If the parent property is an object, it adds the property to this object.

The property is only added when there is no property of that name and it does not add duplicates. If the Multivalue attribute is set to true, the SCIM 2.0 Connector does not gather all the properties, which also has the Multivalue attribute set to true and has the same parent path.

The addition of properties to the Multivalue attribute works only on array. When you add properties, they create an entry based on all the multivalue fields that have the same parent path. If there is a duplicate entry, a new one is not added.

This is the addition action attribute: action=”add”.

Modification​

In this action attribute, the SCIM 2.0 Connector searches for a property on the existing structure and modifies it accordingly.

note

Modification works only on objects, not on the array.

This is the modification action attribute: action=”modify”.

Deletion​

In this action attribute, the SCIM 2.0 Connector searches for a property on the existing structure. If the parent property is array, it searches for an array element with the property that matches the value.

If the SCIM 2.0 Connector finds the array element, it removes the entire entry. If the parent property is an object, it removes the property if it exists in the object.

This is the deletion action attribute: action=”remove”.