3 Installing and Configuring the Generic SCIM Connector

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:

3.1 Preinstallation

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.

The preinstallation steps include the following optional procedures:

3.1.1 Implementing Custom Authentication

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

To implement a custom authentication:
  1. Create a Java class for implementing custom authentication. This class must implement the org.identityconnectors.scimcommon.auth.spi.AuthenticationPlugin interface.
    Note down the name of this Java class. You will provide the name of the Java class while configuring the IT resource for your target system which is described later in this guide.
  2. Override the Map<String, String> getAuthHeaders(Map<String, Object> authParams) method in the custom Java class.
    This method must implement the custom authentication logic that returns the authorization header in the form of a map For example, { Authorization = Bearer XXXXXXXXXX }. The authorization header contains the access token received from the target.
  3. Package the Java class implementing the custom authentication into a JAR file.
  4. Package the JAR file containing the custom authentication implementation with the connector bundle JAR as follows:

    Note:

    Ensure to package all the JARs for any other custom implementations that you may have.
    1. Extract the contents of the org.identityconnectors.genericscim-1.0.1115.jar file into a temp directory. This file is located in the GenericSCIM-RELEASE_NUMBER\bundle directory.
    2. Copy the JAR file containing the custom authentication (from Step 3) to the lib directory.
    3. Regenerate the connector bundle (org.identityconnectors.genericscim-1.0.1115.jar) by running the following command:
      jar -cvfm org.identityconnectors.genericscim-1.0.1115.jar META-INF/MANIFEST.MF * 
      

      Note:

      While updating the connector bundle, ensure that META-INF\MANIFEST.MF file is unchanged.
  5. Run the Oracle Identity Manager Delete JARs utility to delete any existing JARs in Oracle Identity Manager database before you upload the regenerated connector bundle. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.
    • For Microsoft Windows:OIM_HOME/server/bin/DeleteJars.bat

    • For UNIX: OIM_HOME/server/bin/DeleteJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being deleted, and the location from which the JAR file is to be deleted. Specify 4 (ICF Bundle) as the value of the JAR type.

  6. Run the Oracle Identity Manager Upload JARs utility to upload the regenerated connector bundle to Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.
    • For Microsoft Windows:OIM_HOME/server/bin/UploadJars.bat

    • For UNIX: OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 (ICF Bundle) as the value of the JAR type.

  7. Restart Oracle Identity Manager.
This completes the procedure for implementing a custom authentication.

3.1.2 Implementing Custom Parsing

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.

To implement custom parsing:
  1. Create a Java class for implementing the custom parser. This class must implement the org.identityconnectors.scimcommon.parser.spi.ParserPlugin interface.
    Note down the name of this Java class. You will provide the name of the Java class while configuring the IT resource for your target system which is described later in this guide.
  2. Override the String parseRequest(Map<String, Object> attrMap) and List<Map<String, Object>> parseResponse(String response, Map<String, String> parserConfigParams) methods in the custom Java class.
    The String parseRequest(Map<String, Object> attrMap) method implements the logic for parsing an attribute and generates a string request payload.
    The List<Map<String, Object>> parseResponse(String response, Map<String, String> parserConfigParams) method implements the logic for parsing the string response received from the target in this class.
  3. Package the Java class implementing the custom parser into a JAR file.
  4. Package the JAR file containing the custom parser implementation with the connector bundle JAR as follows:

    Note:

    Ensure to package all the JARs for any other custom implementations that you may have.
    1. Extract the contents of the org.identityconnectors.genericscim-1.0.1115.jar file into a temp directory. This file is located in the GenericSCIM-RELEASE_NUMBER\bundle directory.
    2. Copy the JAR file containing the custom authentication (from Step 3) to the lib directory.
    3. Regenerate the connector bundle (org.identityconnectors.genericscim-1.0.1115.jar) by running the following command:
      jar -cvfm org.identityconnectors.genericscim-1.0.1115.jar META-INF/MANIFEST.MF * 
      

      Note:

      While updating the connector bundle, ensure that META-INF\MANIFEST.MF file is unchanged.
  5. Run the Oracle Identity Manager Delete JARs utility to delete any existing JARs in Oracle Identity Manager database before you upload the regenerated connector bundle. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.
    • For Microsoft Windows:OIM_HOME/server/bin/DeleteJars.bat

    • For UNIX: OIM_HOME/server/bin/DeleteJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being deleted, and the location from which the JAR file is to be deleted. Specify 4 (ICF Bundle) as the value of the JAR type.

  6. Run the Oracle Identity Manager Upload JARs utility to upload the regenerated connector bundle to Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.
    • For Microsoft Windows:OIM_HOME/server/bin/UploadJars.bat

    • For UNIX: OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 (ICF Bundle) as the value of the JAR type.

  7. Restart Oracle Identity Manager.
This completes the procedure for implementing custom parsers.

3.2 Installing the Generic SCIM Connector

You must install the connector in Oracle Identity Manager. If necessary, you can also deploy the connector in a Connector Server.

3.2.1 Understanding Installation of the Generic SCIM 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.

3.2.1.1 Summary of Steps to Install the Connector

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:

  1. Run the connector installer to install the connector bundle included in the installation media. This procedure is described later in this chapter.
  2. Run the connector installer to install the connector package (specific to your target system) that you had generated while performing the procedure described in Generating the Generic SCIM Connector. The procedure to install the connector package is described later in this guide.
  3. Configure the IT resource. See Configuring the IT Resource for the Target System.

3.2.1.2 About Installing the Generic SCIM Connector Locally and Remotely

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.

3.2.2 Running the Connector Installer

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:

  1. If you are installing the connector included in the installation media, then copy the contents of the connector installation media to the following directory:

    OIM_HOME/server/ConnectorDefaultDirectory

  2. If you are installing the connector from the generated connector package, then copy the unzipped connector package (generated in Generating the Generic SCIM Connector) to the following directory:

    OIM_HOME/server/ConnectorDefaultDirectory

  3. Log in to Oracle Identity System Administration.
  4. In the left pane, under Provisioning Configuration, click Manage Connector.
  5. In the Manage Connector page, click Install.
  6. From the Connector List, select one of the following connectors:
    • If are installing the connector included in the connector installation media, then select Generic SCIM Connector-RELEASE_NUMBER.

    • If you are installing the generated connector, then select the name of the connector package (generated by running the metadata generator).

    This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory in Step 1.

    If you have copied the installation files into a different directory, then:

    1. In the Alternative Directory field, enter the full path and name of that directory.

    2. To repopulate the list of connectors in the Connector List list, click Refresh.

    3. From the Connector List list, select the relevant connector name depending on whether you are installing the connector included in the connector installation media or the generated connector.

  7. Click Load.
  8. To start the installation process, click Continue.

    The following tasks are performed in sequence:

    1. Configuration of connector libraries

    2. Import of the connector XML files (Using Deployment Manager).

    3. Compilation of Adapter Definitions

    On successful completion of a task, a check mark is displayed for the task. If a task fails, then an X mark and a message stating the reason for failure are displayed. Depending on the reason for the failure, make the required correction and then perform one of the following steps:

    • Retry the installation by clicking Retry.

    • Cancel the installation and begin again from Step 1.

    If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed.

  9. Click Exit to close the installation page.

    When you run the Connector Installer, it processes the script in the GenericSCIM-CI.xml file located in the configuration directory. This file is listed in Files and Directories of the Generic SCIM Connector.

3.2.3 Configuring the IT Resource for the Target System

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.

The list of IT resource parameters for the Generic SCIM connector can be grouped into the following categories:
  • 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:

3.2.3.1 About IT Resource Parameter Categories

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.

3.2.3.2 IT Resource Parameters

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 lists the connection-related IT resource 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: www.example.com

port

Port number at which the target system is listening.

Sample value: 80

proxyHost

Proxy host is the name of the proxy host used to connect to an external target system.

Sample value: www.example.com

proxyPort

Proxy port number

Sample value: 80

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: 100000

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: 100000

baseURI Base URI refers to the base relative URL of the SCIM target system.

For example if the URL is http://host:port/hcmCoreSetupApi/scim/User, then baseURI is /hcmCoreSetupApi/scim.

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: OBJ_CLASS.ATTR_NAME

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 parameter holds the content type expected by the target system in the header. The content type can be application/scim+json.

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, OBJ_CLASS is the name of the object class for which a response payload is being parsed. OUTER_ATTR_NAME is the name of the outer tag in the response payload.

For example, consider the following JSON value for a User object:

"Resources":
"{ "user1":"{value1}", 
"user2":"{value2}" 
}
From this example, the value of the jsonResourcesTag parameter is __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 __ACCOUNT__ object class must be mapped to the __GROUP__ object class, then enter __ACCOUNT__.groups=__GROUP__.

Sample value: __ACCOUNT__.groups=__GROUP__

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 lists the set of IT resource parameters for which you must enter values when the grantType parameter is set to basic.

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: johnsmith

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: password

Table 3-3 lists the set of IT resource parameters for which you must enter values when the grantType parameter is set to 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: https://www.example.com/oauth2/v3/token

iss

Enter a value that uniquely identifies the entity that issued the JWT.

Sample value: 527901474-ugnvd5uh21p598cf9h6cd@developer.example.com

scope

Enter the scope of the access token being issued.

Sample value: https://www.example.com/auth/adm.direct.group, https://www.example.com/auth/adm.direct.user

sub

Enter a value that identifies the principal to which the JWT is being issued.

Sample value: admin@example.com

privateKeyLocation

Enter the absolute path to the private key used to sign the access token.

Sample value: D:\\SCIM Connector — 1595b926.p12

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:3600

signatureAlgorithm

Enter the algorithm used for signing the access token.

Sample value: RS265

privateKeyFormat

Enter the format of the private key used to sign the access token.

Sample Value:PKCS12

Table 3-4 lists the set of IT resource parameters for which you must enter values when the grantType parameter is set to 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: XDWTh0r2eWuULCDVt

clientSecret

Enter the value used to authenticate the identity of your client application.

Sample value: clZsdZisTOoYN5NITirarIDepDkiJTGHdzNFT0m

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: https://api.example.com/oauth2/token

Table 3-5 lists the set of IT resource parameters for which you must enter values when the grantType parameter is set to 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: johnsmith

password

Enter the password of the resource owner.

Sample value: password

clientId

Enter the client identifier issued to the client during the registration process.

Sample value: XDWTh0r2eWuULCDVt

clientSecret

Enter the client secret used to authenticate the identity of the client application.

Sample value: clZsdZisTOoYN5NITirarIDepDkiJTGHdzNFT0m

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: https://api.example.com/oauth2/token

Table 3-6 lists the set of IT resource parameters that are displayed when the grantType parameter is set to 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 lists the set of IT resource parameters when the data from your target system is reconciled in a custom parser implementation, other than JSON format.

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:

  • For attributes: OBJ_CLASS.OP=REL_URL

  • For special attributes: OBJ_CLASS.ATTR_NAME.OP=REL_URL

  • For attributes that have the same relative URL for multiple operations: OBJ_CLASS=REL_URL or OBJ_CLASS.ATTR_NAME=REL_URL

  • If you have to pass the unique ID of the user as part of endpoint URL, use $(__UID__)$.

  • If you have to pass any attribute other than the unique ID of the user, then represent it in one of the following formats:
    • For a single-valued attribute: $(firstname)$

    • For an embedded object: $(OBJ_CLASS.ATTR_NAME)$

      For example, $(__GROUP__.id)$.

Note: All values in this parameter must be comma separated.

Sample value: "__ACCOUNT__.CREATEOP=/admin/directory/v1/users","__ACCOUNT__.SEARCHOP=/admin/directory/v1/users/$(Filter Suffix)$","__ACCOUNT__=/admin/directory/v1/users/$(__UID__)$","__GROUP__.CREATEOP=/admin/directory/v1/groups","__GROUP__=/admin/directory/v1/groups/$(__UID__)$","__GROUP__.SEARCHOP=/admin/directory/v1/groups/$(Filter Suffix)$","__ACCOUNT__.alias=/admin/directory/v1/users/$(__UID__)$/aliases","__ACCOUNT__.alias.DELETEOP=/admin/directory/v1/users/$(__UID__)$/aliases/$(alias)$","__GROUP__.alias.DELETEOP=/admin/directory/v1/groups/$(__UID__)$/aliases/$(alias)$","__ACCOUNT__.__GROUP__=/admin/directory/v1/groups/$(__GROUP__.id)$/members","__ACCOUNT__.__GROUP__.DELETEOP=/admin/directory/v1/groups/$(__GROUP__.id)$/members/$(__UID__)$","__ACCOUNT__.__GROUP__.SEARCHOP=/admin/directory/v1/groups?userKey=$(__UID__)$"

customHeaders

Enter any custom or additional header values that must be sent to the target system.

Format: "HEADER_NAME1=VALUE1"," HEADER_NAME2=VALUE2", . . . "HEADER_NAMEn=VALUEn"

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: "X-REQUESTED-BY=test"

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 $(__UID__)$. If you must pass the value of any other attribute, then represent it as $(ATTRIBUTE_NAME)$ .

Sample value: "__ACCOUNT__.__GROUP__.UPDATEOP={ \"user\": { \"id\": \"$(__UID__)$\"}, \"group\": { \"id\": \"$(id)$\" } }"

dateAttributes Specifies a list of date attributes available on the target system.

Sample value: "Users=meta.lastModified","Groups=meta.lastModified”

passwordAttribute

Specifies the mapping between __PASSWORD__ (password) of the connector with the target system attribute for each object class.

Format: objectClass=attributeName

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: MMM d, yyyy h:mm:ss a z

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 : "__ACCOUNT__.password.UpdateOp=PUT"

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

3.2.3.3 Specifying Values for the IT Resource Parameters

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:

  1. Log in to Oracle Identity System Administration.
  2. In the left pane, under Configuration, click IT Resource.
  3. In the IT Resource Name field on the Manage IT Resource page, enter the name of the IT resource, and then click Search. The name of the IT resource is the value of the itResourceName property in the GenericScimConfiguration.groovy file.
  4. Click the edit icon for the IT resource.
  5. From the list at the top of the page, select Details and Parameters.
  6. Specify values for the parameters of the IT resource. See the Configuring the IT Resource for the Target System section for information about IT resource parameters.
  7. To save the values, click Update.

3.3 Postinstallation

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.

3.3.1 Configuring Oracle Identity Manager

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:

3.3.1.1 Creating and Activating a Sandbox

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.

3.3.1.2 Creating a New UI Form

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.

3.3.1.3 Associating the Form with the Application Instance

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:

  1. In the System Administration, deactivate the sandbox.
  2. Log out of the System Administration.
  3. Log in to the Self Service and activate the sandbox that you deactivated in Step 1.
  4. In the Catalog, check for the Application Instance UI (form fields) and ensure that it appears correctly.
  5. Publish the application instance only if everything appears correctly. Otherwise, fix the issues and then publish the application instance. See Publishing an Application Instance to Organizations in Oracle Fusion Middleware Administering Oracle Identity Manager.

3.3.1.4 Publishing a Sandbox

Before you publish a sandbox, perform the following procedure as a best practice to validate all sandbox changes made till this stage as it is hard to revert changes once a sandbox is published:
  1. In the System Administration, deactivate the sandbox.
  2. Log out of the System Administration.
  3. Log in to the Self Service using the xelsysadm user credentials and then activate the sandbox that you deactivated in Step 1.
  4. In the Catalog, ensure that the Generic SCIM application instance form appears with correct fields.
  5. Publish the sandbox. See Publishing a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

3.3.1.5 Harvesting Entitlements and Sync Catalog

To harvest entitlements and sync catalog:
  1. Run the scheduled jobs for lookup field synchronization discussed in Scheduled Job for Lookup Field Synchronization.
  2. Run the Entitlement List scheduled job to populate Entitlement Assignment schema from child process form table.
  3. Run the Catalog Synchronization Job scheduled job.

    See Also:

    Predefined Scheduled Tasks in Oracle Fusion Middleware Administering Oracle Identity Manager .

3.3.2 Localizing Field Labels in UI Forms

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.

To localize field label that is added to the UI forms:
  1. Create a properties file (for example, GS_ja.properties) containing localized versions for the column names in your target system (to be displayed as text strings for GUI elements and messages in the Oracle Identity Self Service).
  2. Log in to Oracle Enterprise Manager.
  3. In the left pane, expand Application Deployments and then select oracle.iam.console.identity.sysadmin.ear.
  4. In the right pane, from the Application Deployment list, select MDS Configuration.
  5. On the MDS Configuration page, click Export and save the archive to the local computer.
  6. Extract the contents of the archive, and open the following file in a text editor:

    SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle_en.xlf

  7. Edit the BizEditorBundle.xlf file in the following manner:
    1. Search for the following text:

      <file source-language="en"
      original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
      datatype="x-oracle-adf">
      
    2. Replace with the following text:

      <file source-language="en" target-language="LANG_CODE"
      original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
      datatype="x-oracle-adf">
      

      In this text, replace LANG_CODE with the code of the language that you want to localize the form field labels. The following is a sample value for localizing the form field labels in Japanese:

      <file source-language="en" target-language="ja"
      original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
      datatype="x-oracle-adf">
      
    3. Search for the application instance code. This procedure shows a sample edit for Generic SCIM application instance. The original code is:
      <trans-unit
      id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_ACMEGSAP_APP_DFLT_HOME__c_description']}">
      <source>APP_DFLT_HOME</source>
      <target/>
      </trans-unit>
      <trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.ACMEFORM.entity.ACMEFORMEO.UD_ACMEGSAP_APP_DFLT_HOME__c_LABEL">
      <source>APP_DFLT_HOME</source>
      <target/>
      </trans-unit>
      
    4. Open the properties file created in Step 1 and get the value of the attribute, for example, global.udf.D_ACMEGSAP_APP_DFLT_HOME=\u4567d.

    5. Replace the original code shown in Step c with the following:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_ACMEGSAP_APP_DFLT_HOME__c_description']}">
      <source>APP_DFLT_HOME</source>
      <target>\u4567d</target>
      </trans-unit>
      <trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.ACMEFORM.entity.ACMEFORMEO.UD_ACMEGSAP_APP_DFLT_HOME__c_LABEL">
      <source>APP_DFLT_HOME</source>
      <target>\u4567d</target>
      </trans-unit>
      
    6. Repeat Steps 7.a through 7.d for all attributes of the process form.

    7. Save the file as BizEditorBundle_LANG_CODE.xlf. In this file name, replace LANG_CODE with the code of the language to which you are localizing.

      Sample file name: BizEditorBundle_ja.xlf.

    8. Repackage the ZIP file and import it into MDS.

      Note:

      See Deploying and Undeploying Customizations in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for more information about exporting and importing metadata files.
    9. Log out of and log in to Oracle Identity Manager.

3.3.3 Clearing Content Related to Connector Resource Bundles from the Server Cache

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:

  1. In a command window, switch to the OIM_HOME/server/bin directory.
  2. Enter one of the following commands:
    • On Microsoft Windows: PurgeCache.bat All

    • On UNIX: PurgeCache.sh All

    When prompted, enter the user name and password of an account belonging to the SYSTEM ADMINISTRATORS group. In addition, you are prompted to enter the service URL in the following format:

    t3://OIM_HOST_NAME:OIM_PORT_NUMBER

    In this format:

    • Replace OIM_HOST_NAME with the host name or IP address of the Oracle Identity Manager host computer.

    • Replace OIM_PORT_NUMBER with the port on which Oracle Identity Manager is listening.

    You can use the PurgeCache utility to purge the cache for any content category.

3.3.4 Managing Logging for the Generic SCIM Connector

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:

3.3.4.1 Understanding Log Levels

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.

3.3.4.2 Enabling Logging

To enable logging in Oracle WebLogic Server:

  1. Edit the logging.xml file as follows:

    1. 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>
      
    2. 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.

  2. Save and close the file.

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

  4. Restart the application server.

3.3.5 Configuring SSL for the Generic SCIM Connector

Configure SSL to secure data communication between Oracle Identity Manager and the target system

  1. Obtain the SSL public key certificate for the SCIM-based target system.
  2. Copy the public key certificate of the SCIM-based target system to the computer hosting Oracle Identity Manager.
  3. Run the following keytool command to import the target system certificate into the Oracle WebLogic Server keystore:
    keytool -import -keystore KEYSTORE_NAME -storepass PASSWORD -file CERT_FILE_NAME -alias ALIAS
    In this command:
    • KEYSTORE_NAME is the full path and name of the DemoTrust keystore.

    • PASSWORD is the password of the keystore.

    • CERT_FILE_NAME is the full path and name of the certificate file.

    • ALIAS is the target system certificate alias.

    The following is a sample value for this command:

    keytool -import -keystore WEBLOGIC_HOME/server/lib/DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase —file /home/target.cert —alias serverwl

    Note:

    • Change the parameter values passed to the keytool command according to your requirements. Ensure that there is no line break in the keytool arguments

    • Ensure that the system date for Oracle Identity Manager is in sync with the validity date of the SSL certificate to avoid any errors during SSL communication.