You must configure the connector to let Oracle Identity Manager connect to the target system. You must also configure the connector to set it up to perform reconciliation and provisioning operations.
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 REST connector can be grouped into the following categories:
Connection-related parameters
Authentication parameters
Parser parameters
Additional configuration parameters
This section provides information about the following topics related to IT resource configuration:
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:
Connection parameters are used by the connector to establish a connection between Oracle Identity Manager and your target system for exchange of identity information.
Table 4-1 Connection IT Resource Parameters
| Parameter | Description |
|---|---|
|
Configuration Lookup |
Name of the lookup definition that holds connector configuration entries that are used during connector operations. Note: This is a mandatory parameter. |
|
Connector Server Name |
If you have deployed the Generic RESTconnector in the Connector Server, then enter the name of the IT resource for the Connector Server. |
|
host |
Host name or IP address of the computer hosting the target system. Sample value: Note: This is a mandatory parameter. |
|
port |
Port number at which the target system is listening. Sample value: Note: This is a mandatory parameter. |
|
proxyHost |
Name of the proxy host used to connect to an external target system. Sample value: |
|
proxyPort |
Proxy port number Sample value: |
|
proxyUser |
Proxy user name 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: |
Authentication parameters are used by the target system to authenticate an application. The set of IT resource parameters for which you must specify values depends on the value that you enter for the authenticationType parameter.
The authenticationType parameter holds the type of authentication used by your target system. By default, the connector supports the following types of authentication:
HTTP Basic Authentication
OAuth 2.0 JWT
OAuth 2.0 Client Credentials
OAuth 2.0 Resource Owner Password
Manually input access token and refresh token
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 the authenticationType parameter:
Note:
This section provides information about IT resource parameters for all authentication types. Enter values only for IT resource parameters corresponding to the authentication type you specify.HTTP Basic Authentication
basic.
Table 4-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: |
OAuth 2.0 JWT
jwt.
Table 4-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: |
OAuth 2.0 Client Credentials
client_credentials.
Table 4-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: |
OAuth 2.0 Resource Owner Password
Table 4-5 OAuth 2.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: Note: This is an optional parameter. |
|
clientSecret |
Enter the client secret used to authenticate the identity of the client application. Sample value: Note: This is an optional parameter. |
|
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: |
Manual Input of Access Tokens and Refresh Tokens
This section discusses the IT resource parameter for which you must enter a value when the authenticationType parameter is set to other.
In this authentication mechanism, the connector expects the value of the access token and refresh token to be directly passed through the customAuthHeaders IT resource parameter. The customAuthHeaders parameter must hold the access token and refresh token values that must be passed through an HTTP authorization header.
Custom Authentication
This section discusses the IT resource parameter for which you must enter a value when the authenticationType parameter is set to custom.
If you have implemented custom authentication, then you must enter a value for the customAuthClassName parameter. The customAuthClassName parameter must hold the name of the class implementing the custom authentication logic that you created while performing the procedure described in Implementing Custom Authentication.
By default, the Generic REST 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.
Table 4-6 lists the IT resource parameters related to parsing
Table 4-6 Parser IT Resource Parameters
| Parameter | Description |
|---|---|
| jsonResourcesTag |
Enter the JSON tag value that is used for parsing a response payload. The connector will consider the value that you enter in this parameter as an unwanted outer tag while parsing responses. You can skip entering a value for this parameter if there is no unwanted outer tag in your response payload. Enter a value for this 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}"
}
Because the name of the object class for a User object is __ACCOUNT__, for the given example, the value of the jsonResourcesTag parameter is 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. |
| customParserClassName | Enter the name of the class implementing the custom parser logic that you created while performing the procedure described in Implementing Custom Parsing.
Note: Enter a value for this parameter only if you are using a custom parser implementation. |
All additional configuration IT resource parameters are target system specific. Table 4-7 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, UPDATEOP, ADDATTRIBUTE, and REMOVEATTRIBUTE. You must use the ADDATTRIBUTE or REMOVEATTRIBUTE operations only if you want to use a separate request payload for each child table add and remove operation. Otherwise, use the UPDATEOP or DELETEOP operations.
Note:
In this guide, attributes in an object class that can be managed only through a separate rest endpoint rather than the same endpoint of the base object class have been referred to as special attributes.Table 4-7 Configuration IT Resource Parameters
| Parameter | Description |
|---|---|
|
simpleMultivaluedAttributes |
Enter a comma-separated list of simple multivalued attributes to be managed by the connector. You must enter values for this parameter in the following format: Sample value: |
|
opTypes |
Enter the HTTP operation type for each object class that is to be managed by the connector. Values must be comma separated and in the following format: In this format, OBJ_CLASS is the connector object class, OPERATION is the connector operation (for example, CreateOp, UpdateOp, or SearchOp), and HTTP_OP is the HTTP operation (for example, GET, PUT, or POST). Sample value: |
|
relURIs |
Enter the relative URLs for all operations of each object class. Enter a value for this parameter in one of the following formats:
Sample value: |
|
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: Note: All values in this parameter must be comma separated. |
|
uidAttributes |
Enter the __UID__ attribute for each object class that the connector handles. A __UID__ attribute is a target system attribute that uniquely identifies an account in the target system. This target system attribute name must be unique and need not be autogenerated. Format: In this format, OBJ_CLASS is the connector object class and ATTR_NAME is the name of the attribute that uniquely identifies an account in the target system. 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: Sample value: Note: All values in this parameter must be comma separated. |
|
statusDisableValue |
Enter the boolean value that indicates the value that must be sent to the target system during a disable operation. Note: You must enter a value for this parameter only if the target system expects a different value for a disable operation, from what OIM sends by default. Sample values: |
|
statusEnableValue |
Enter the boolean value that indicates the value that must be sent to the target system during an enable operation. Note: You must enter a value for this parameter only if the target system expects a different value for an enable operation, from what OIM sends by default. Sample values: |
|
specialAttributeHandling |
Enter the list of special attributes whose values must be sent to the target system in separate calls, one at a time. If you do not specify a value for this parameter, then the connector will send all values for a given special attribute in a single call. Format: Note: All values in this parameter must be comma separated. Sample value: |
|
specialAttributeTargetFormat |
Enter the format in which a special attribute is present in the target system. Format: In this example, TARGET_FORMAT is the format in the format of the special attribute in the target system. For example, consider the following target endpoint value: {
"kind": "admin#directory#aliases",
"etag": etag,
"aliases": [
"kind": "admin#directory#alias",
"id": string,
"etag": etag,
"primaryEmail": string,
"alias": string
]
}
In this example, the alias attribute is present as aliases.alias in the target system endpoint. Therefore, you must set the value of this parameter to Sample value: |
|
httpHeaderContentType |
This parameter holds the content type expected by the target system in the header. The content type can be |
|
httpHeaderAccept |
This parameter holds the accept type expected by the target system in the header. The content type can be |
|
sslEnabled |
If the target system requires SSL connectivity, set the value of this parameter to |
|
customHeaders |
Enter any custom or additional header values that must be sent to the target system. Format: |
|
customAuthHeaders |
Enter any additional header values that must be sent to the target system only during authentication. |
|
customPayload |
Enter a comma-separated list of request payload formats for target system attributes that do not adhere to the standard JSON format. Format: Note: If you must pass the unique ID of the user as part of a custom payload, then represent it as Sample value: |
|
targetObjectIdentifier |
Enter the name of the attribute used for identifying the required target object during reconciliation. Format: |
|
passwordAttribute |
Enter the name of the target system attribute that is mapped to the __PASSWORD__ attribute of the connector in OIM. |
|
uriPlaceHolder |
Enter a comma-separated list of key-value pairs for replacing place holders in the relURIs. Format: |
|
customAuthConfigParams |
Enter any configuration parameters that you may use in the custom authentication class. Format: |
|
customParserConfigParams |
Enter any configuration parameters that you may use in the custom parser class. Format: |
|
enableEmptyString |
Enter a boolean string which indicates that an empty string must be sent to the target system, rather than a null value. |
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 section 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 the 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.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 REST 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 GenericRestConfiguration.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 set a log level based on Oracle Java Diagnostic Logging and enable logging in the Oracle WebLogic Server.
The following topics contain detailed information:
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 4-8.
Table 4-8 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='genericrest-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.GENERICREST" level="[LOG_LEVEL]" useParentHandlers="false">
<handler name="genericrest-handler"/>
<handler name="console-handler"/>
</logger>
Replace both occurrences of [LOG_LEVEL] with the ODL message type and level combination that you require. Table 4-8 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='genericrest-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/genericrestLogs.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.GENERICREST" level="NOTIFICATION:1" useParentHandlers="false"> <handler name="genericrest-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.
You must configure SSL to secure data communication between Oracle Identity Manager and your target system.
You can localize UI form field labels by creating and using a file containing localized versions for your target system fields.
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: