Data provisioning

When you enable data provisioning, choose the SCIM v2 connector. Enter a unique name for the new connector. The SCIM connector is based on 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

note

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.

Parameter	Description
Base URI	Specify the server address. This is the URI used to access SCIM server. Example: https://127.0.0.1/.
Entity root	This 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 mode	The 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.
Security protocol	The security protocol of your REST system: TLS 1.2 or higher.
Content type header	Choose the format of the content. The default value is application/json.
Accept header	The default value is application/json.
Headers	This field is optional. Here, you can provide JSON document specifying custom headers. For example: {"Request": {"Accept": " text/html","content-type":"application/json","SomeCustomHeaderWithValue":"custom value","SomeCustomHeaderWithoutValue": null}} Headers defined in this JSON document override the value set in the Content-type header field.
Include certificate	If selected, a client certificate will be attached to the HTTP requests. Three additional parameters are required: - Certificate (in the PEM format) -----BEGIN CERTIFICATE----- <contents> -----END CERTIFICATE----- - Private Key (in the PEM format) -----BEGIN PRIVATE KEY----- .... -----END PRIVATE KEY----- - Passphrase for private key (optional, use it if the private key was created with the passphrase )
Use numeric values	Setting 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 address	This is the base address for querying objects. It is appended to Base URI when specified. Example: https://127.0.0.1/query.
Root resource path	This 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 connection	Select this checkbox to perform a test of the connection before using the connector.
Test query	This 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, for example, Users. Entering a test query is important for a proper test for authentication methods which doesn't access the target system, for example, basic authentication or static bearer token.

Defining behavior in case of the lookup failure

You can choose the lookup failure strategy, giving you the option to define the connector behavior in such scenarios. From the Lookup failure strategy drop-down list, choose one of the following options:

• Skip property in request payload - { "name" : "ABC" }
• Stop processing with failure - requests are not sent, the provisioning task fails
• Use NULL - { "name": "ABC", "ref" : null }
• Use empty value (default behavior) - { "name" : "ABC", "ref" : "" }
• Use value used for lookup - { "name" : "ABC", "ref" : "DEF" }

Basic authentication

Parameter	Description
Username	The user name for the selected type of authentication.
Password	The password used for authentication.

Oauth2 authentication

Parameter	Description
OAuth grant type	The way the authorization token is requested: - Client credentials - JWT bearer - Password credentials - Static token - SAP username and password - Custom
URL for authorization token	Enter 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 ID	The 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 secret	The 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 Resource	The name of the OAuth resource owner.
OAuth Token Revoke URL	The token revocation endpoint URL.
Token cache policy	There 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

Password credentials grant

Parameter	Description
Username	The username for the user to authenticate with the service.
Password	The password for the user to authenticate with the service.

SAP Username and password grant

Parameter	Description
Username	Provide the SAP username for a SAP Cloud system like SAP Cloud Identity Authentication Service (IAS).
Password	Provide the SAP password for a SAP Cloud system like SAP Cloud Identity Authentication Service (IAS).

Custom

Parameter	Description
Auth request body	Raw body of the request sent to the authentication server to get the access token. Sensitive values should be replaced with the placeholders starting with #SECURE.
Auth request content type	Content type of the request sent to authentication server to get the access token.
Authentication server response format	The available options are: - Access token only - JSON - Other - XML
Access token Location	Required field if the Authentication server response format setting has value other than Access token only configured. Location of the access token in the response. Depending on the format, different kind of information is expected in this field: - property name if it is JSON - XPath if it is XML - regular expression with group if it is other, unknown format.
Authorization header	Name of the authorization header, where access token will be stored.

JWT bearer grant

Parameter	Description
JWT Issuer	JWT Issuer claim
JWT Subject	JWT Subject claim
JWT Audience	JWT Audience claim
JWT Private key (PEM format)	JWT Private key is in PEM format: -----BEGIN PRIVATE KEY----- .... -----END PRIVATE KEY----- or -----BEGINENCRYPTED PRIVATE KEY----- .... -----END ENCRYPTED PRIVATE KEY----- and thenPassphrase for Private Key needs to be provided
JWT Passphrase for private key	Passphrase for the providedPrivate key
JWT Encryption algorithm	Encryption algorithm used when signing the token.For example, RSASSA-PKCS1-v1_5 using SHA-256 (RS256)
JWT Public key ID	Public key ID for signing the JWT(Header parameter)
JWT Type	JWT Type (Header parameter)
JWT Additional claims	JWT Additional claims in format: key1,value1;key2,value2;...

Static token grant

Parameter	Description
OAuth Static Token	OAuth static bearer token
OAuth Static Token Type	Provide a custom keyword that will be supplied in front of the static token. If the field is left blank, the default Bearer value is used.

Data model

The data model is available out of the box. The SCIM 2.0 connector is built on top of a generic REST connector. This connector overrides the default 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'

or

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" muliValued="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 comapny",
              "type":"Comapny"
            },
            "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.

Reconciliation turned on

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 multivalue attributes.

Reconciliation turned off

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.

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

If there are complex objects in the data model that are contained in an array, the property name should include condition in square brackets.

example

If you have an array of emails, with each email represented by value and type, the property name should have following structure:

emails.value[type=work]

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"

Add

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".

Modify

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

Modification works only on objects, not on the array.

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

Delete

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".