You must install the connector in Oracle Identity Manager. If necessary, you can also deploy the connector in a Connector Server.
The following topics provide details to install and configure the Generic SCIM connector:
Preinstallation for the Generic SCIM connector involves custom authentication implementation and custom parsing implementation. For the SCIM connector, the preinstallation steps are performed before the metadata generation.
If your target system uses an authentication mechanism that is not supported by this connector, then you must implement the authentication that your target system uses and then attach it to the connector by using the plug-ins exposed by this connector. Implementing custom authentication involves creating a Java class, overriding the Map<String, String> getAuthHeaders(Map<String, Object> authParams) method that returns the authorization header in the form of a map, and updating the connector installation media to include the new Java class. All the target system configuration and authentication details that may be required for obtaining the authorization header are passed to the Map<String, String> getAuthHeaders(Map<String, Object> authParams) method through specific IT resource parameters. All the configuration properties exposed by this connector are accessible within this method as a part of "authParams".
By default, the connector supports only JSON parsing during reconciliation runs. If the reconciliation data from your target system is not in JSON format, then you must write a custom parser implementation for your data format.
You must install the connector in Oracle Identity Manager. If necessary, you can also deploy the connector in a Connector Server.
The following topics provide details on installing the connector:
The procedure to understand installation of the Generic SCIM Connector is divided across two stages namely summary of steps to install the connector and about installing the Generic SCIM connector locally and remotely.
Installing this connector requires you to install the connector bundle that is included in the installation media and then install the connector package (specific to your target system) that you had generated while performing the procedure described in Generating the Generic SCIM Connector section.
The following is a summary of steps to install the Generic SCIM connector:
You can run the connector code either locally in Oracle Identity Manager or remotely in a Connector Server.
Depending on where you want to run the connector code (bundle), the connector provides the following installation options:
Run the connector code locally in Oracle Identity Manager.
In this scenario, you deploy the connector in Oracle Identity Manager. Deploying the connector in Oracle Identity Manager involves performing the procedures described in Running the Connector Installer and Configuring the IT Resource for the Target System.
Run the connector code remotely in a Connector Server.
In this scenario, you deploy the connector in Oracle Identity Manager, and then, deploy the connector bundle in a Connector Server. See Using an Identity Connector Server in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for information about installing, configuring, and running the Connector Server, and then installing the connector in a Connector Server.
When you run the Connector Installer, it automatically copies the connector files to directories in Oracle Identity Manager, imports connector XML files, and compiles adapters used for provisioning.
As discussed in one of the earlier sections, you must first install the connector bundle that is included in the installation media and then install the connector bundle that is a part of the connector package that you generated. The procedure to install both connector bundles is the same except for the following differences:
Before running the connector installer to install the connector bundle from the installation media, you must copy the contents of the connector installation media to the OIM_HOME/server/ConnectorDefaultDirectory directory.
Before running the connector installer to install the generated connector, you must copy the unzipped connector package (generated in Generating the Generic SCIM Connector) to the OIM_HOME/server/ConnectorDefaultDirectory directory.
You must install the connector in Oracle Identity Manager by using the Connector Installer. To do so:
The IT resource for your target system is created after you install the connector. An IT resource is composed of parameters that store connection and other generic information about a target system. Oracle Identity Manager uses this information to connect to a specific installation or instance of your target system and perform reconciliation and provisioning operations.
Connection-related parameters
Authentication parameters
Parser parameters
Additional configuration parameters
Note:
The list of parameters that are displayed on the IT resource page depends on the properties that you added to the Config entry of the GenericSCIMConfiguration.groovy file. At any point in time, you can update the list of IT resource parameters by modifying the IT Resource Type definition using Oracle Identity Manager Design Console. There is no need to re-create and install the connector when you update the IT Resource Type definition.The following topics related to IT resource configuration are discussed in this section:
An IT resource is composed of parameters that store connection and other generic information about a target system. Oracle Identity Manager uses this information to connect to a specific installation or instance of your target system.
The list of IT resource parameters for this connector can be grouped into the following categories:
Connection-related parameters
Authentication parameters
Parser parameters
Configuration parameters
Connection Parameters
Connection parameters are used by the connector to establish a connection between Oracle Identity Manager and your target system for exchange of identity information.
Authentication Parameters
Authentication parameters are used by the target system to authenticate the application. The IT resource parameters for authentication vary depending on the value of the grantType parameter. The grantType parameter holds the type of authentication used by your target system. By default, the connector supports the following types of authentication:
Basic authentication
OAuth2.0 JWT
OAuth2.0 Client Credentials
OAuth2.0 Resource Owner password
Apart from the authentication types listed, if you target system uses any other authentication type, then you must write your own implementation which requires development effort. The following are the possible values for this parameter:
For HTTP Basic Authentication: basic
For OAuth 2.0 JWT: jwt
For OAuth 2.0 Client Credentials: client_credentials
For OAuth 2.0 Resource Owner Password: password
For custom authentication implementation: custom
Parser Parameters
By default, the connector supports only JSON parsing during reconciliation runs. If the reconciliation data from your target system is not in JSON format, then you must write a custom parser implementation for your data format. If the data from your target system is in JSON format, then the connector uses JSON parsing and you must provide a value for the jsonResourcesTag parameter. The jsonResourcesTag parameter must contain the json tag value that is used during reconciliation for parsing multiple entries in a single response payload. If you are using a custom parser implementation, then you must provide values for the parameters listed in table Table 3-7.
Additional Configuration Parameters
All additional configuration parameters are target system specific.
The IT resource for the target system contains connection information about the target system. Oracle Identity Manager uses this information during provisioning and reconciliation.
Connection Parameters
Table 3-1 Connection IT Resource Parameters
| Parameter | 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. |
|
username |
User name or ID of the target system user account that Oracle Identity Manager uses to connect to the target system. |
| host |
Host name or IP address of the computer hosting the target system. Sample value: |
|
port |
Port number at which the target system is listening. Sample value: |
|
proxyHost |
Proxy host is the name of the proxy host used to connect to an external target system.
Sample value: |
|
proxyPort |
Proxy port number Sample value: |
|
proxyUser |
Proxy user ID of the target system user account that Oracle Identity Manager uses to connect to the target system. |
|
proxyPassword |
Password of the proxy user ID of the target system user account that Oracle Identity Manager uses to connect to the target system. |
|
connectionTimeOut |
An integer value that specifies the number of milliseconds after which an attempt to establish the connection between the target system and Oracle Identity Manager times out. Sample value: |
|
socketTimeOut |
An integer value that specifies the number of milliseconds after which the wait for a response from the target system times out. Sample value: |
| baseURI | Base URI refers to the base relative URL of the SCIM target system.
For example if the URL is |
| nameAttributes | Enter the name attribute for all object classes that are handled by the connector. This value specifies the mapping between the _NAME_ connector attribute and the corresponding target system attribute for each object class that the connector handles.
Format: OBJ_CLASS.ATTR_NAME 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: OBJ_CLASS.ATTR_NAME 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 |
| contentType |
This parameter holds the content type expected by the target system in the header. The content type can be |
| acceptType | This parameter holds the accept type expected by the target system in the header. The accept type can be application/scim+json. |
|
scimVersion |
This entry holds the SCIM version of the target system. The valid range for this attribute is 1 to 19. |
| jsonResourcesTag | Enter the JSON tag value that is used for parsing a response payload. The value mentioned in this parameter will be considered as an unwanted outer tag while parsing response. You can skip entering a value for this parameter if there is no unwanted outer tag in your response payload.
Enter a value for the parameter in the following format: OBJ_CLASS=OUTER_ATTR_NAME In this format, For example, consider the following JSON value for a User object: "Resources":
"{ "user1":"{value1}",
"user2":"{value2}"
}__ACCOUNT__=Resources.
Note: You must enter a value for this parameter only if the data from your target system is in JSON format. For more than one JSON tag, the values must be comma separated. |
| 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: |
Authentication Parameters
As discussed in one of the earlier sections, IT resource parameters for authentication vary depending on the value that you specify for the grantType parameter.
Table 3-2 HTTP Basic Authentication IT Resource Parameters
| Parameter | Description |
|---|---|
|
username |
User name or User ID of the account that Oracle Identity Manager must use to connect to and access the target system during reconciliation and provisioning operations.
Sample value: |
|
password |
Password of the account that Oracle Identity Manager must use to connect to and access the target system during reconciliation and provisioning operations.
Sample value: |
jwt.
Table 3-3 OAuth 2.0 JWT IT Resource Parameters
| Parameter | Description |
|---|---|
|
aud |
Enter the intended audience of the JWT. The value can either be a URI or token endpoint URL of the authorization server. Sample value: |
|
iss |
Enter a value that uniquely identifies the entity that issued the JWT. Sample value: |
|
scope |
Enter the scope of the access token being issued. Sample value: |
|
sub |
Enter a value that identifies the principal to which the JWT is being issued. Sample value: |
|
privateKeyLocation |
Enter the absolute path to the private key used to sign the access token. Sample value: |
|
privateKeySecret |
Enter the secret key for the private key that is being used to sign the access token. |
|
tokenLifespan |
Enter the life span of the access token in milliseconds. Sample value: |
|
signatureAlgorithm |
Enter the algorithm used for signing the access token. Sample value: |
|
privateKeyFormat |
Enter the format of the private key used to sign the access token. Sample Value: |
client_credentials.
Table 3-4 OAuth2.0 Client Credentials IT Resource Parameters
| Parameter | Description |
|---|---|
|
clientId |
Enter the client identifier (a unique string) issued by the authorization server to the client during the registration process. Sample value: |
|
clientSecret |
Enter the value used to authenticate the identity of your client application. Sample value: |
|
authenticationServerURL |
Enter the URL of the authorization server that authenticates the client (by validating the client ID and client secret), and if valid, issues an access token. Sample value: |
password.
Table 3-5 OAuth2.0 Resource Owner Password IT Resource Parameters
| Parameter | Description |
|---|---|
|
username |
Enter the user name or user ID of the resource owner. Sample value: |
|
password |
Enter the password of the resource owner. Sample value: |
|
clientId |
Enter the client identifier issued to the client during the registration process. Sample value: |
|
clientSecret |
Enter the client secret used to authenticate the identity of the client application. Sample value: |
|
authenticationServerUrl |
Enter the URL of the authorization server (token endpoint) that authenticates the client (by validating client ID and client secret) and the resource owner credentials, if valid, issues an access token. Sample value: |
custom.
Table 3-6 Custom Implementation IT Resource Parameters
| Parameter | Description |
|---|---|
|
customAuthClassName |
Enter the name of the class implementing the custom authentication logic that you created while performing the procedure described in Implementing Custom Authentication. |
|
customAuthConfigParams |
Enter any configuration parameters that you may use in the custom authentication class PARAM_NAME1=VAL1,PARAM_NAME2=VAL2, . . . PARAM_NAMEn=VALn |
Parser Parameters
Table 3-7 Custom Parser IT Resource Parameters
| Parameter | Description |
|---|---|
|
customParserClassName |
Enter the name of the class implementing the custom parser logic that you created while performing the procedure described in Implementing Custom Parsing. |
|
customParserConfigParams |
Enter any configuration parameters that you may use in the custom parser class. You must enter a value for this parameter in the following format: PARAM_NAME1=VAL1,PARAM_NAME2=VAL2, . . . PARAM_NAMEn=VALn |
Additional Configuration Parameters
All additional configuration parameters are target system specific. Table 3-8 lists the IT resource parameters related to target system configuration. The supported operation types for all the parameters listed in this table are CREATEOP, DELETEOP, SEARCHOP, and UPDATEOP.
Table 3-8 Configuration IT Resource Parameters
| Parameter | Description |
|---|---|
|
sslEnabled |
Specifies whether SSL communication is enabled between Oracle Identity Manager and your target system. Enter yes if SSL is configured. Otherwise, enter no. |
|
relURLs |
Enter the relative URLs for all operations of each object class. Enter a value for this parameter in one of the following formats:
Note: All values in this parameter must be comma separated. Sample value: |
|
customHeaders |
Enter any custom or additional header values that must be sent to the target system. Format: Note: If you are using a SCIM target as Oracle Identity Governance 12c (12.2.1.4.0), then enter an additional header for post request. For example: |
|
customAuthHeaders |
Enter any additional header values that must be sent to the target system only during authentication. If you are entering a value for this parameter as you have set the grantType parameter to other, then enter the access token and refresh token values that must be passed through an HTTP authorization header. |
|
customPayload |
Enter a comma-separated list of request payload formats for target system attributes that do not adhere to the standard JSON format. Format: OBJ_CLASS.ATTRNAME.OP=PAYLOAD_FORMAT Note: If you must pass the unique ID of the user as part of a custom payload, then represent it as Sample value: |
| dateAttributes | Specifies a list of date attributes available on the target system.
Sample value: " |
|
passwordAttribute |
Specifies the mapping between Format: Note: All values in this parameter must be comma separated. |
| dateFormat | Specifies date format of the date attributes available on the target system.
Sample value: |
| lookupObjectClasses | Specifies a list of object class that is used for scheduled tasks. This list of object class is not available by default on the target system. |
| httpOperationTypes |
Specifies the type of HTTP Operation that needs to be performed for a particular operation on the attribute of an object class. Sample Value : Note: The connector supports only the PATCH method to perform Modify or Update operations from Oracle Identity Manager to a SCIM-based target system. |
| defaultBatchSize | This holds the default page/batch size for the GET operations.
Default value: 500 |
| reconSortByAttrs | Specifies an attribute name and the value. Based on this value, the sorting of the GET operation is performed by the target system.
Sample value: Users=id","Groups=id |
The IT resource for the target system contains connection information about the target system. Oracle Identity Manager uses this information during provisioning and reconciliation.
When you run the metadata generator, the IT resource corresponding to this connector is automatically created in Oracle Identity Manager. You must specify values for the parameters of this IT resource as follows:
Postinstallation for the connector involves configuring Oracle Identity Manager, enabling logging to track information about all connector events, and configuring SSL. It also involves performing some optional configurations such as localizing the user interface.
This topic discusses the following postinstallation procedures:
You must create a UI form and an application instance for the resource against which you want to perform reconciliation and provisioning operations. In addition, you must run entitlement and catalog synchronization jobs.
Note:
Perform the procedures described in this section only if you are using the connector in the target resource configuration mode.You must create a UI form and an application instance for the resource against which you want to perform reconciliation and provisioning operations. In addition, you must run entitlement and catalog synchronization jobs. These procedures are described in the following sections:
You must create and activate a sandbox to begin using the customization and form management features. You can then publish the sandbox to make the customizations available to other users.
See Creating a Sandbox and Activating and Deactivating a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.
See Creating Forms by Using the Form Designer in Oracle Fusion Middleware Administering Oracle Identity Manager for instructions on creating a new UI form. While creating the UI form, ensure that you select the resource object corresponding to the Generic SCIM connector that you want to associate the form with. In addition, select the Generate Entitlement Forms check box.
By default, an application instance is automatically created after you install the connector. The name of this application instance is the one that is specified as the value of the applicationInstanceName entry in the GenericScimConfiguration.groovy file. If you did not specify a value for the applicationInstanceName entry, then the application instance name will be the same as the value of the ITResourceDefName entry.
You must associate this application instance with the form created in Creating a New UI Form.
See Managing Application Instances in Oracle Fusion Middleware Administering Oracle Identity Manager for instructions on modifying an application instance to associate it with a form.
After updating the application instance, you must publish it to an organization to make the application instance available for requesting and subsequent provisioning to users. However, as a best practice, perform the following procedure before publishing the application instance:
You can localize UI form field labels by using the resource bundle corresponding to the language you want to use. Resource bundles are available in the connector installation media.
When you deploy the connector, the resource bundles are copied from the resources directory on the installation media into the Oracle Identity Manager database. Whenever you add a new resource bundle to the connectorResources directory or make a change in an existing resource bundle, you must clear content related to connector resource bundles from the server cache
To clear content related to connector resource bundles from the server cache you can either restart Oracle Identity Manager or run the PurgeCache utility. The following is the procedure to clear the server cache by running the PurgeCache utility:
Oracle Identity Manager uses Oracle Diagnostic Logging (ODL) logging service for recording all types of events pertaining to the connector.
The following topics provide detailed information about logging:
When you enable logging, Oracle Identity Manager automatically stores in a log file information about events that occur during the course of provisioning and reconciliation operations.
Oracle Identity Manager uses Oracle Java Diagnostic Logging (OJDL) for logging. OJDL is based on java.util.logger. To specify the type of event for which you want logging to take place, you can set the logs to one of the following available levels:
SEVERE.intValue()+100
This level enables logging of information about fatal errors.
SEVERE
This level enables logging of information about errors that might allow Oracle Identity Manager to continue running.
WARNING
This level enables logging of information about potentially harmful situations.
INFO
This level enables logging of messages that highlight the progress of the application.
CONFIG
This level enables logging of information about fine-grained events that are useful for debugging.
FINE, FINER, FINEST
These levels enable logging of information about fine-grained events, where FINEST logs information about all events.
These log levels are mapped to ODL message type and level combinations as shown in Table 3-9.
Table 3-9 Log Levels and ODL Message Type:Level Combinations
| Log Level | ODL Message Type:Level |
|---|---|
|
SEVERE.intValue()+100 |
INCIDENT_ERROR:1 |
|
SEVERE |
ERROR:1 |
|
WARNING |
WARNING:1 |
|
INFO |
NOTIFICATION:1 |
|
CONFIG |
NOTIFICATION:16 |
|
FINE |
TRACE:1 |
|
FINER |
TRACE:16 |
|
FINEST |
TRACE:32 |
The configuration file for OJDL is logging.xml, which is located at the following path:
DOMAIN_HOME/config/fmwconfig/servers/OIM_SERVER/logging.xml
Here, DOMAIN_HOME and OIM_SERVER are the domain name and server name specified during the installation of Oracle Identity Manager.
To enable logging in Oracle WebLogic Server:
Edit the logging.xml file as follows:
Add the following blocks in the file:
<log_handler name='genericscim-handler' level='[LOG_LEVEL]' class='oracle.core.ojdl.logging.ODLHandlerFactory'> <property name='logreader:' value='off'/> <property name='path' value='[FILE_NAME]'/> <property name='format' value='ODL-Text'/> <property name='useThreadName' value='true'/> <property name='locale' value='en'/> <property name='maxFileSize' value='5242880'/> <property name='maxLogSize' value='52428800'/> <property name='encoding' value='UTF-8'/> </log_handler>
<logger name="ORG.IDENTITYCONNECTORS.GENERICSCIM" level="[LOG_LEVEL]" useParentHandlers="false">
<handler name="genericscim-handler"/>
<handler name="console-handler"/>
</logger>
Replace both occurrences of [LOG_LEVEL] with the ODL message type and level combination that you require. Table 3-9 lists the supported message type and level combinations.
Similarly, replace [FILE_NAME] with the full path and name of the log file in which you want log messages specific to connector operations to be recorded.
The following blocks show sample values for [LOG_LEVEL] and [FILE_NAME] :
<log_handler name='genericscim-handler' level='NOTIFICATION:1' class='oracle.core.ojdl.logging.ODLHandlerFactory'> <property name='logreader:' value='off'/> <property name='path' value='/<%OIM_DOMAIN%>/servers/oim_server1/logs/genericScriptLogs.log>" <property name='format' value='ODL-Text'/> <property name='useThreadName' value='true'/> <property name='locale' value='en'/> <property name='maxFileSize' value='5242880'/> <property name='maxLogSize' value='52428800'/> <property name='encoding' value='UTF-8'/> </log_handler> <logger name="ORG.IDENTITYCONNECTORS.GENERICSCIM" level="NOTIFICATION:1" useParentHandlers="false"> <handler name="genericscim-handler"/> <handler name="console-handler"/> </logger>
With these sample values, when you use Oracle Identity Manager, all messages generated for this connector that are of a log level equal to or higher than the NOTIFICATION:1 level are recorded in the specified file.
Save and close the file.
Set the following environment variable to redirect the server logs to a file:
For Microsoft Windows: set WLS_REDIRECT_LOG=FILENAME
For UNIX: export WLS_REDIRECT_LOG=FILENAME
Replace FILENAME with the location and name of the file to which you want to redirect the output.
Restart the application server.