The procedure to generate the Generic SCIM connector is divided across three stages namely defining the schema, configuring the Groovy file, and generating the connector.
You can define the schema of your target system to let the connector understand the underlying schema of the target system database.
Note:
Defining a schema is optional. When schema is not defined, the Generic SCIM connector fetches all attributes that are returned by the endpoint of the target system.The schema file is a properties file that is used to represent the structure of your target system. This file is used as an input to the metadata generation utility. Before running the metadata generation utility, you must populate the schema file in the specified format.
Note:
Creating a schema is optional. When a custom schema is not available, the Generic SCIM connector fetches all attributes that are returned by the endpoint of the target system. Properties of the fields mentioned in the schema file take a higher preference over the properties returned by the schema endpoint of the Generic SCIM connectorThe schema file contains details such as datatypes, mandatory attributes, and the uid attribute that are specific to your target system. This file restricts the list of field names which are managed from the Generic SCIM connector. It is necessary to create a schema.properties file to help the connector understand the target system schema.
The schema file is a properties file and consists of name-value pairs. By default, the metadata generation utility generates metadata for an __ACCOUNT__ object class that is used to manage Users, groups, and organizations.
Account qualifiers describe certain attributes of an account in your target system. These qualifiers are common for the target system.
You can define the schema of your target system by using the following qualifiers:
Field Names
This is a mandatory qualifier. It is a comma-separated list of attributes that the connector must fetch from the target system. All child form names, single-valued and multivalued attributes, including the attribute used for performing incremental reconciliation must be specified here.
The following is a sample value for the FieldNames qualifier:
FieldNames=UserId,UserName,FirstName,LastName,email,Description,Salary, JoiningDate,status,Groups,Roles
UidAttribute
This is a mandatory qualifier. It refers to the name of the attribute that corresponds to the unique ID of the account.
For example: UidAttribute=UserId
NameAttribute
This is a mandatory qualifier. This refers to the name of the attribute that corresponds to a descriptive name of the account.
For example: NameAttribute=UserName
PasswordAttribute
This is a mandatory qualifier if your target system supports password management of user accounts. This qualifier refers to the name of the password attribute of the account.
For example: PasswordAttribute=accountPwd
StatusAttribute
This is a mandatory qualifier if your target system supports management of user account statuses. This qualifier refers to the attribute which denotes the status of the account.
For example: StatusAttribute=status
Field qualifiers are specific to each field and are usually specified by predefined formats.
The following is the format for parent form fields:
<FIELDNAME>.<FIELDQUALIFIER>=<VALUE>
Example: UserId.Required=true
The following is the format for complex child form fields:
<FIELDNAME>.<SUBFIELDNAME>.<FIELDQUALIFIER>=<VALUE>.
Example: Roles.fromdate.DataType=Long
The following are the field qualifiers for which values can be specified:
Required
This field qualifier specifies if the mentioned attribute is mandatory. If the value of this qualifier is set to true, the parser will skip processing the records that do not contain this field name.
For example: UserId.Required=true
Multivalued
This field qualifier specifies if the mentioned attribute is a multivalued field.
For example: Roles.Multivalued=true
DataType
This field qualifier is used to specify the datatype of the field name. If you do not specify the data type for any field, then it is considered as a String data type by default.
The following are the possible values for this qualifier:
String
Long
Character
Double
Float
Integer
Boolean
Byte
BigDecimal
bigInteget
Date
For example: startDate.DataType=Date
Subfields
This field qualifier specifies the subfields in a multivalued attribute if they are present.
For example: Roles.Subfields=roleid,fromdate,todate
EmbeddedObjectClass
This field qualifier specifies the object class name of child forms that have more than one subfield. The value of this qualifier is used internally by ICF and is mandatory for all complex child forms.
For example: Roles.EmbeddedObjectClass=Roles
You can create a schema file for your target system by describing the structure, by adding mandatory qualifier entries and lastly by providing values for the newly created entries.
Note:
You must create the schema.properties file on the computer on which you intend to run the metadata generation utility.The Generic SCIM connector is shipped with a groovy file named GenericScimConfiguration.groovy.
This GenericScimConfiguration.groovy file is located in the genericscim-RELEASE_NUMBER/metadata-generator/resources directory of the connector installation ZIP. You use the GenericScimConfiguration.groovy file to specify values for properties that can store basic information about your target system schema.
This file is used by the Generic SCIM Generator to perform the following tasks:
Understand the schema
Configure the mode (trusted source or target resource) in which you want to run the connector
Generate the connector package specific to your target system
The procedure for running the Generic SCIM Generator and directory structure of the generated connector package is discussed later in this chapter.
The GenericScimConfiguration.groovy file contains sample configuration (one each for trusted source and target resource) with prepopulated values for most of the entries. Depending upon your requirements, specify or modify values for entries in this file or create new sections for your configuration. The following are the predefined sections in the GenericScimConfiguration.groovy file:
trusted
You specify values for the entries in this section if you want to configure the connector for the trusted source mode.
target
You specify values for the entries in this section if you want to configure the connector for the target resource mode.
The entries in the predefined sections, trusted and target, of the GenericScimConfiguration.groovy file are defined in this section.
Note:
Unless specified, all entries described here are common to both sections.
If you do not want to specify a value for any of the optional entries or attributes in the GenericScimConfiguration.groovy file, then comment out that entry or attribute by prefixing it with the double-slash symbol (//).
The following are a list of entries:
itResourceDefName
This is a mandatory entry. Enter the name of the IT resource type for the target system. Note that the value that you specify for this entry determines the name of the connector package, connector configuration file, and connector installer file. For example, if you specify GenSCIMTrusted as the value of this entry, then the name of the connector package directory is GenSCIMTrusted.zip.
itResourceName
This is an optional entry. Enter the name of the IT resource for the target system. If this entry is commented, then the IT resource name will be the same as the value of the ITResourceDefName entry.
Default value: "$itResourceDefName"
Note:
The value of this entry must be unique for each connector that you create for your target system, if you plan to install or use the connectors in the same Oracle Identity Manager environment. In addition, this value will be a part of the names for all connector components (defined in the connector configuration XML file, which is created after you run the metadata generator) such as lookup definitions, resource objects, process forms, and scheduled tasks.
For example, if you specify GenSCIMTrusted as the value of itResourceName entry, then after you deploy the connector, the configuration lookup definition is created and its name will be Lookup.GenSCIMTrusted.Configuration.
applicationInstanceName
This is an optional entry and present only in the section for target resource configuration. Enter the name of the application instance for your target system that the connector must generate. If this entry is commented, then the application instance name will be the same as the value of the ITResourceDefName entry.
Default value: "$itResourceDefName"
connectorDir
This is an optional entry. This entry is the complete path to the directory that must contain the connector package that is generated when you run the metadata generator. By default, the name of the directory containing the generated connector package is the same as the value of the itResourceDefName entry.
Sample value: "/scratch/jdoe/OIMPS3/mw4318/idm7854/server/ConnectorDefaultDirectory/GenSCIMTrusted"
xmlFile
This is an optional entry. Enter the name and relative path of the XML file that must contain definitions of the connector objects. If you do not specify a value for this entry, then the file name is generated in the following format:
IT_RES_DEF_NAME-ConnectorConfig.xml
In this format, IT_RES_DEF_NAME is the value of the itResourceDefName entry.
For example, if you have not specified a value for this entry and GenSCIM is the value of the itResourceDefName entry, then the name of the XML file that is generated is GenSCIM-ConnectorConfig.xml.
Note:
To easily identify files of a specific target system installation, it is recommended that the names of this generated XML file be prefixed with the name of the IT resource for the target system.
Sample value: GenSCIM-ConnectorConfig.xml
configFileName
This is an optional entry. Enter the name and relative path of the XML file that contains the configuration information of the connector objects. If you do not specify a value for this entry, then the file name is generated in the following format:
IT_RES_DEF_NAME-CI.xml
In this format, IT_RES_DEF_NAME is the value of the itResourceDefName entry.
For example, if you have not specified a value for this entry and GenSCIM is the value of the itResourceDefName entry, then the name of the XML file that is generated is GenSCIM-CI.xml.
propertiesFile
This is an optional entry. Enter the name and relative path of the .properties file which contains the resource bundle translations. If you do not specify a value for this entry, then the file name is generated in the following format:
IT_RES_DEF_NAME-generator.properties
In this format, IT_RES_DEF_NAME is the value of the itResourceDefName entry.
For example, if you have not specified a value for this entry and GenSCIMTarget is the value of the itResourceDefName entry, then the name of the properties file that is generated is GenSCIMTarget-generator.properties.
version
This is an optional entry. Enter the release number of the connector.
Sample value: 11.1.1.5.0
trusted
This is a mandatory entry and present only in the section for trusted source configuration. Set the value of the entry to true, if you are configuring the connector to run in the trusted source mode.
bundleJar
This is a mandatory entry. Enter the name and relative path of the JAR file containing the ICF bundle that the metadata generator will use.
Default value: ../lib/org.identityconnectors.genericSCIM-1.0.11150.jar
Do not change the value of this entry.
config
This is a mandatory entry in which you specify information about the connector configuration. This connector configuration contains information about the manner in which the connector must behave and connect to the target system.
Table 2-1 lists and describes the properties of the Config entry.
Note:
By default, the config entry contains only the schemaFile property. Depending on the target system and the authentication mechanism being used, you can add any or all of the properties described in this table. All the config entry properties that you add to the groovy file are displayed as IT resource parameters. It is recommended that you add the properties in the groovy file and specify their values from the Manage IT resources page of the Identity System Administration. See Configuring the IT Resource for the Target System for more information about properties specific to your target system and its authentication mechanism.
In this guide, an attribute in an object class that can be managed only through a separate rest endpoint rather than the same endpoint of the base object class has been referred to as a special attribute.
Table 2-1 Properties of the Config Entry
| Property | Description |
|---|---|
|
schemaFile |
Enter the name and relative path of the schema file that you want to use. See Defining the Schema for information about the schema file that you created. Note: This attribute is an optional attribute. |
| host | Host name or IP address of the computer hosting the target system. |
|
port |
Port number at which the target system is listening |
|
baseURI |
Base URI refers to the base relative URL of the SCIM target system. For example, consider the URL:
http://host:port/hcmCoreSetupApi/scim/Users In the preceding case, the baseURI is
/hcmCoreSetupApi/scim |
|
nameAttributes |
Specifies the mapping between the _NAME_ connector attribute and the corresponding target system attribute for each object class that the connector handles. Format: Note: All values in this parameter must be comma separated. |
|
uidAttributes |
Enter the mapping between the _UID_ (GUID) connector attribute and target attribute for each object class that the connector handles.
Format: Note: All values in this parameter must be comma separated. |
|
statusAttributes |
Enter the mapping between the _ENABLE_ connector attribute the target attribute that holds the status for each object class this connector handles. Format: Note: All values in this parameter must be comma separated. |
|
grantType |
Specifies the authorization grant used by your target system. The following are the supported grant types and the possible values for this property: – HTTP Basic Authentication — basic —OAuth2.0 JWT — jwt – OAuth 2.0 Client Credentials — client_credentials – OAuth 2.0 Resource Owner Password — password – If you have written your own custom implementation for authentication, then the value is custom. |
|
contentType |
This entry holds the content type expected by the target system in the header. The content type can be |
|
acceptType |
This entry holds the accept type expected by the target system in the header. The accept type can be |
|
jsonResourcesTag |
Specifies the json tag value that is used during reconciliation for parsing multiple entries in a single response payload. |
|
scimVersion |
This entry holds the SCIM version of the target system. The valid range for this attribute is 1 to 19. |
|
attrToOClassMapping |
This entry is used to map an attribute of one object class with another object class. For example, if the groups attribute of the Sample value: |
lookupAttributeList
This is an optional entry and is present only in the section for target resource configuration. Enter the list of attributes in your target system that must be handled as lookup fields.
The connector creates a lookup field for each of the attributes specified in this entry and associates it with the corresponding lookup fields on the Oracle Identity Manager User process form.
If you want to create a lookup field for a single-valued or multivalued field, then enter the value in the following format:
['FIELD_NAME']
In this format, replace FIELD_NAME with the name of the single or multivalued field.
If you want create a lookup field for a multivalued field that is embedded then, enter the value in the following format:
['OBJ_CLASS.SUB_FIELD_NAME']
In this format, replace:
OBJ_CLASS with the EmbeddedObjectClass name for the child form as specified in the schema file.
SUB_FIELD_NAME with the subfield name for the child form as specified in the schema file.
The sample value of this entry is:
['_ACCOUNT_.groups.value']
You can modify the default value to meet the requirements in your environment.
For each of the attributes listed in the lookupAttributeList entry, the connector creates a lookup definition and scheduled job in the following format:
Lookup definition format:
Lookup.${IT_RES_NAME}.${FIELD_NAME}
This lookup definition holds the lookup values reconciled from the target system.
Scheduled job format:
IT_RES_NAME Target FIELD_NAME Lookup Reconciliation
This scheduled job is used to load or reconcile lookup values from your target system. See Scheduled Job for Lookup Field Synchronization for more information about the attributes of the scheduled job for lookup reconciliation.
In both the formats, the connector replaces:
IT_RES_NAME with the value of the itResourceDefName entry.
FIELD_NAME with the name of the field for which the lookup field is created.
entitlementAttributeList
This is also an optional entry and is present only in the section for target resource configuration. Enter the list of fully qualified attributes in the target system that must be tagged as entitlements.
The connector creates a lookup field for each of the attributes specified in this entry, assigns the lookup fields to a process form, and adds all the required properties of entitlements.
If you want to tag entitlements for multivalued fields, then enter the value in the following format:
["MULTIVALUED_FIELD_NAME"]
If you want to tag entitlements for a multivalued field that is embedded, then enter the value in the following format:
["OBJ_CLASS.SUB_FIELD_NAME"]
In this format, replace:
OBJ_CLASS with the EmbeddedObjectClass name for the child form as specified in the schema file.
SUB_FIELD_NAME with the subfield name for the child form as specified in the schema file.
Sample value: ["__ACCOUNT__.groups~__ACCOUNT__.groups~value"]
You can modify the default value based on your schema.
In this value, groups.value is an embedded object class field and value is a multivalued field.
dateAttributeList
This is an optional entry. Enter the list of attributes that must be handled as date on the process form. Ensure that the data type of the attributes listed here is set to Long in the schema file.
The connector creates a date editor for each of the attributes specified in this entry.
If you want to handle single-valued or multivalued fields as date, then enter the value in the following format:
["FIELD_NAME"]
In this format, replace FIELD_NAME with the name of the single or multivalued field.
If you want to handle an embedded multivalued field as date, then enter the value in the following format:
["OBJ_CLASS.SUB_FIELD_NAME"]
In this format, replace:
OBJ_CLASS with the EmbeddedObjectClass name for the child form as specified in the schema file.
SUB_FIELD_NAME with the subfield name for the child form as specified in the schema file.
Sample value: ["JoiningDate","Roles.fromdate","Roles.todate"]
In this value, Roles.fromdate and Roles.todate are embedded multivalued fields.
objectClassAlias
If you want to generate the metadata for an object class other than __ACCOUNT__ and _GROUP_, then enter an alias for your object class.
alias
This is a mandatory entry. The metadata generator uses aliases to create relationships between the attributes in the target system and resource object field names in Oracle Identity Manager. In addition, the metadata generator uses aliases to shorten long database names to meet the character-length restrictions on form names and form field names in Oracle Identity Manager. Aliasing can be used on column name, form name, and form field name levels. Note that the target system attributes are represented as connector attributes.
Depending on the type of configuration, specify values for one of the following sections:
For trusted source configuration
In the trusted source configuration section, you use the alias entry to map connector attributes or target system attributes to the Oracle Identity Manager User form field names. The mappings that you specify here are used to populate entries in the Recon Attribute map lookup definition for trusted source reconciliation.
Note that some of the Oracle Identity Manager User form field names do not have the same display name internally. For such fields, you must ensure that you map the connector attribute or target system attribute to the internal name rather than the display name. The following table lists the names of the Oracle Identity Manager User form display names and their corresponding internal names:
Table 2-2 lists and describes the properties of the Alias entry.Table 2-2 Alias
| Display Name | Internal Name |
|---|---|
|
Organization |
Organization Name |
|
Manager |
Manager Login |
|
|
|
The following is the default value of the alias entry:
['__NAME__':'User Login', 'LastName':'Last Name','Organization':'Organization Name', 'Employee Type':'Xellerate Type', 'Role':'Role']
In the default value, note that the Organization connector attribute has been mapped to Organization Name, which is the internal name.
You cannot delete existing mappings in the sample value. However, you can modify these mappings.
If you want to add mappings for fields other than the ones already present in the alias entry, then you can add them either to the existing values in the alias entry, or add them to the alias + entry.
The following is the default value of the alias + entry:
['__ENABLE__':'Status', 'FirstName':'First Name', 'email':'Email', 'JoiningDate':'Start Date]
The following is the format in which you must specify values for the alias and alias + entry:
['CONN_ATTR1': 'OIM_FIELD1', 'CONN_ATTR2': 'OIM_FIELD2', . . . 'CONN_ATTRn': 'OIM_FIELDn']
In this format:
CONN_ATTR is the connector attribute name.
OIM_FIELD is the name of the field on the Oracle Identity Manager User form.
For target resource configuration
In the target resource configuration section, you use the alias entry for one or all of the following purposes:
To map connector attributes or target system attributes to fields of the process form. The mappings that you specify here are used to populate entries in the Recon Attribute map and Prov Attribute map lookup definitions for target resource reconciliation.
To set an alias (a unique and shortened name) for the IT resource name specified in the itResourceName entry.
To specify a short name for a lengthy process form field name.
When the number of characters in a process form is more than 11, the metadata generator automatically truncates the process form name to 10 characters and then suffixes it with the digit 0. Subsequently, for every process form that results in the same name after truncating, the suffix is incremented by 1. The metadata generator prevents any two process forms from having the same name by using autonumbering. To gain control over the autogenerated form name and to have meaningful form names, you can use an alias to specify a shortened process form name.
This is illustrated by the following example:
Assume that the resource name is GENDB and contains child data that is represented as USER_ROLES in the schema.
When you run the metadata generator, the process form is created and the form name is UD_GENDB_USER_ROLES. As the number of characters in this process form name is more than 11, the metadata generator automatically truncates it to UD_GENDB_U0. The truncated form name, UD_GENDB_U0, is not meaningful.
To avoid encountering such issues or forms with autogenerated names, you can use the alias entry to specify short and meaningful process form names.
The following is the default value of the alias entry in the target resource configuration section:
[‘__UID__':'userId', '__NAME__':'userName']
You cannot delete existing mappings in the default value as they are mandatory. However, you must modify the default value to match the values of the UidAttribute and NameAttribute qualifiers in the schema file. For example, in the schema file, if you have set the values of the UidAttribute and NameAttribute qualifiers to UID and primaryEmail respectively, then you must set the value of the alias entry to the following:
['__UID__':'UID', '__NAME__':primaryEmail]
If you want to add mappings for fields other than the ones already present in the alias entry (in other words, optional aliases), then you can add them either to the existing values in the alias entry, or add them to the alias + entry.
The following is the default value of the alias + entry in the target resource section:
['Generic Scim Target':'GST', 'comments':'Description', 'Family Name':'Last Name', 'Visibility':'Status']
The following is the format in which you must specify values for the alias and alias + entries:
['CONN_ATTR1': 'ALIAS_FIELD1', 'CONN_ATTR2': 'ALIAS_FIELD2', . . . 'CONN_ATTRn': 'ALIAS_FIELDn']
In this format:
CONN_ATTR is the connector attribute name.
ALIAS_FIELD is the alias corresponding to the connector attribute or target system attribute.
prepopulate
This is an optional entry that is present only in the section for target resource configuration. Specify a value for this entry if you want Oracle Identity Manager to prepopulate connector's process form fields from Oracle Identity Manager User fields while provisioning a enterprise target system resource.
The sample value of this entry is as follows:
['__NAME__':'User Login', 'FIRST_NAME':'First Name', 'LAST_NAME':'Last Name', '__PASSWORD__':'Password']
This means that the groovy file is configured to prepopulate the following fields by default:
User Login
First Name
Last Name
Password
You can add fields to or remove fields from the preceding list. The following is the format in which you must specify values for the prepopulate entry:
['CONN_ATTR1 or TARGET_ATTR1': 'OIM_FIELD1', 'CONN_ATTR2 or TARGET_ATTR2': 'OIM_FIELD2', . . . 'CONN_ATTRn or TARGET_ATTRn': 'OIM_FIELDn']
In this format:
CONN_ATTR is the connector attribute name.
TARGET_ATTR is the target system attribute name.
OIM_FIELD is the name of the field on the Oracle Identity Manager User form.
See Working with Prepopulate Adapters in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for more information about attaching and removing prepopulate adapters.
You generate a connector package zip for your target system by running the metadata generator.
After configuring the GenericScimConfiguration.groovy file, you must run the metadata generator to generate the connector package based on your target system schema.
The metadata generator is the GenericSCIMGenerator.cmd or GenericSCIMGenerator.sh file that is located in the genericscim-RELEASE_NUMBER/metadata-generator/bin directory.
To run the metadata generator, in a command window, change to the genericscim-RELEASE_NUMBER/metadata-generator/bin directory (for example, genericscim-11.1.1.5.0/bin) and run one of the following commands depending on the operating system that you are using:
For Microsoft Windows
GenericSCIMGenerator.cmd CONFIG_FILE CONFIG_NAME
For UNIX
GenericSCIMGenerator.sh CONFIG_FILE CONFIG_NAME
In this command, replace:
CONFIG_FILE with the absolute or relative path name of the GenericScimConfiguration.groovy file.
CONFIG_NAME with the name of the configuration within the GenericScimConfiguration.groovy file, being used for the target system. The predefined configurations within this file are trusted and target. You can create additional custom configurations with different names depending on your requirements.
Sample command: GenericSCIMGenerator.cmd ..\resources\GenericScimConfiguration.groovy target
In this command, target denotes the name of the section in the GenericScimConfiguration.groovy file for which values have been specified. In other words, the connector is being configured for the target resource mode. If you encounter any errors while running the metadata generator, then you must fix it and then resume running the metadata generator.
The connector package is a ZIP file that is generated in the GenericSCIM-RELEASE_NUMBER/metadata-generator/ directory. For example, if you have specified GenSCIM as the value of the itResourceDefName entry in the GenericScimConfiguration.groovy file, then the connector package ZIP (GenSCIM.zip) file is generated in the GenericSCIM-11.1.1.5.0/metadata-generator/directory.
The directory structure of the connector package is as follows:
CONNECTOR_PACKAGE/ configuration/ IT_RES_DEF-CI.xml resources/ genericscim-generator.properties xml/ IT_RES_DEF-ConnectorConfig.xml
In this directory structure:
CONNECTOR_PACKAGE is replaced with the name of the IT resource definition specified as the value of the itResourceDefName entry in the GenericScimConfiguration.groovy file.
IT_RES_DEF is replaced with the name of the IT resource definition specified as the value of the itResourceDefName entry in the GenericScimConfiguration.groovy file.
The following behavior is observed after generation of the connector configuration XML file:
The length of a field (column) from the target system is not fetched into the process form. Therefore, except for the Unique ID and Password fields, the length of all other data fields (of the String data type) on the process form is always set to 255 characters. The length of the Unique ID and Password fields is set to 40 characters.