Oracle® Identity Manager Administrative and User Console Guide Release 9.1.0 Part Number E10360-03 |
|
|
View PDF |
This chapter discusses the best practices, or guidelines, for creating and using generic technology connectors.
Note:
Some of the best practices have been repeated at appropriate places in the rest of the guide. Detailed descriptions are provided for best practices that are discussed only in this chapter.Depending on the context in which you must apply them, the best practices are divided into the following sections:
Apply the following guidelines while specifying a name for a generic technology connector:
Summary:
Ensure that the name contains only ASCII characters. You can include the underscore (_) character, but do not include any other non-ASCII character in the name.
Description:
For most of the connector objects that are automatically created at the end of the connector creation process, the name of the generic technology connector is part of the name of the object itself. For example, if the name of the generic technology connector is WebConn
, then the name of its scheduled task is WebConn_GTC
.
In the Oracle Identity Manager database, there is no provision for storing objects with names in non-ASCII characters. Therefore, an error message is displayed if you enter non-ASCII characters while specifying the name of a generic technology connector.
Ensure that the name is not the same as the name of any connector or connector object on the Oracle Identity Manager installation.
If you plan to create the generic technology connector on a staging server and then move it to a production server, then ensure that the name of the generic technology connector does not cause naming conflicts with existing connectors or connector objects on the production server.
Before you import a generic technology connector created on a staging server to a production server, create a backup of the destination Oracle Identity Manager database to ensure that you are able to revert to a working state in the event that a connector object is overwritten.
If you select the Shared Drive Transport Provider, then you must select the CSV Format Provider.
If you select the SPML Provisioning Format Provider, then you must select the Web Services Provisioning Transport Provider.
If you select the Shared Drive Reconciliation Transport Provider, then ensure that there is data in the prescribed format on at least the first two lines of the parent and child data files provided by the target system for reconciliation. The prescribed form of data is discussed in the "Shared Drive Reconciliation Transport Provider" section.
If you select the Shared Drive Reconciliation Transport Provider, then ensure that the required permissions are set on the staging and archiving directories before reconciliation begins. The required permissions are discussed in the "Permissions to Be Set on the Staging and Archiving Directories" section.
Do not try to create more than one generic technology connector at a time, even from different sessions of the Administrative and User Console for the same Oracle Identity Manager installation.
This section describes the following known issues related to the input that you specify on the Step 2: Specify Parameter Values page:
Summary:
If you use the Shared Drive Reconciliation Transport Provider, then:
Do not specify the same path for the staging and archiving directories. Existing files in the archiving directory are deleted if you specify the same path for both directories.
Ensure that the names of files in the staging directory are different from the names of files in the archiving directory. If the file names happen to be the same, then existing files in the archiving directory are overwritten at the end of a reconciliation run.
Description:
When you use the Shared Drive Reconciliation Transport Provider, after each reconciliation run, data files are moved from the staging directory to the archiving directory. The files moved to the archiving directory are not time-stamped or marked in any way. Therefore, when you use the Shared Drive Transport Provider, bear in mind the following guidelines:
The archiving directory path and name that you specify must not be the same as the staging directory path and name. If you specify the same path and name, then the existing files in the archiving directory are deleted at the end of the reconciliation run.
During the current reconciliation run, if data files with the same names as the files used in the last reconciliation run are placed in the staging directory, then the existing files in the archiving directory are overwritten by the new files from the staging directory. This can be illustrated by the following example:
Suppose that at the end of the last reconciliation run, the following files were moved automatically from the staging directory to the archiving directory:
usrdataParentData.csv usrdataRoleData.csv usrdataGroupMembershipData.txt
For the current reconciliation run, you place the following files in the staging directory:
usrdataParentData.csv usrdataRoleData_04Feb07.csv usrdataGroupMembershipData_04Feb07.txt
At the end of the current reconciliation run, these files are moved to the archiving directory. When this happens, the old usrdataParentData.csv
file is overwritten by the new one.
Therefore, if you want to ensure that files in the archiving directory are not overwritten at the end of a reconciliation run, then you must ensure that the names of files in the staging directory are not the same as the names of files in the archiving directory.
Summary:
Metadata detection does not take place a second time if you go back to the Step 2: Specify Parameter Values page. Therefore, if required, you must manually make changes in the fields and field mappings displayed on the Step 3: Modify Connector Configuration page.
Description:
Suppose you want to change a value that you provide on the Step 2: Specify Parameter Values page. You can return to this page from the Step 4: Verify Connector Form Names or Step 5: Verify Connector Information page. However, metadata detection would not take place a second time when you click the Continue button after changing the provider parameter value. This functionality is aimed at preserving changes that you may have manually made on the Step 3: Modify Connector Configuration page.
As an extension of this functionality, metadata detection does not take place even when you modify an existing generic technology connector.
This section discusses best practices related to the following areas:
Note that the following validations are applied when you specify a field name while adding or editing fields:
Two fields that belong to the same data set (parent or child) cannot have the same name.
Two child data sets of the same parent data set cannot have the same name.
The name of a field in a parent data set cannot be the same as the name of one of its child data sets.
Two different child data sets can have fields that have the same name, regardless of whether or not the child data sets belong to the same parent data set. For example, the GroupMembership
data set and Role
data set can each have a field with the name UsrID
.
Two different parent data sets can have fields that have the same name. Similarly, these data sets can also have child data sets that have the same name.
The name of a child data set can be the same as that of one of its fields.
To ensure the security of passwords, password information must not be reconciled through a generic technology connector. In other words, you must ensure that the Source and Reconciliation Staging data sets do not contain the Password field. In addition, you must not map any field of the Reconciliation Staging data sets to the Password field of the OIM - User data set.
A password-like field is a field to which you set the Encrypted and Password Field attributes (by selecting the Encrypted and Password Field check boxes). You can create a password-like field by setting these two attributes to a field that you add to the OIM - Account data set.
To secure the contents of password-like fields, bear in mind the following guidelines while adding or editing these fields:
You can use the Password Field and Encrypted check boxes to secure the display and storage of password information in Oracle Identity Manager. However, when you map password-like fields to fields of the Provisioning Staging data set, you must take all necessary precautions to secure the data propagated in these fields. For example, you must ensure that this data is not stored in a plain-text file on the target system at the end of a provisioning operation.
Oracle recommends creating only one-to-one mappings between the password field of the OIM - Account data set and the Provisioning Staging data set. In other words, this password field must not be used as an input field for a transformation mapping with a Provisioning Staging field. The same precaution must be taken for the Password field of the OIM - User data set.
As mentioned earlier, the Password field is one of the predefined fields of the OIM - User data set. The Password Field and Encrypted attributes are set for this field. By using the Design Console, you can set the Password Field and Encrypted attributes for a UDF that you create. This would give the newly created UDF the same properties as the existing Password field. However, the generic technology connector framework treats this field the same as any other text field (with the String data type) and the contents are not encrypted in the Administrative and User Console or database.
This has also been mentioned in the "General Known Issues" section.
Apply the following best practices while working with fields of the OIM data sets:
Summary:
If you select the Translation Transformation Provider to create a mapping, then specify the name of a lookup definition in the Lookup Code Name region. If you specify a data set name and field in the Lookup Code Name region, then translation would fail during actual reconciliation or provisioning operations.
Description:
If you select the Translation Transformation Provider while creating a mapping, then the Step 2: Mapping page displays options for selecting a field from a data set and specifying a literal. Because you are using the Translation Transformation Provider, you must select the Literal option and enter the name of the lookup definition that contains the Code Key and Decode values for the translation. You must not select a data set name and field in the Lookup Code Name region. Although there is no validation to stop you from selecting a data set name and field, the translation operation would fail during actual reconciliation or provisioning operations.
Create a mapping between the ID field of the OIM - Account data set and the field that uniquely identifies records of the Reconciliation Staging data set.
Along with the ID field, other fields of the OIM - Account data set can be (matching-only) mapped to corresponding fields of the Reconciliation Staging data set to create a composite key field for reconciliation matching.
Create mappings between all fields in Provisioning Staging data sets and corresponding fields in OIM data sets.
To create a reconciliation rule, you create matching-only mappings between fields of the Reconciliation Staging data set and the OIM - User data set. If there are child data sets, then ensure that the names of fields of the Reconciliation Staging data set that are input fields for the matching-only mappings are not used in any of the Reconciliation Staging child data sets. If you do not follow this guideline, then reconciliation would fail.
This has also been mentioned in the "Step 3: Modify Connector Configuration Page" section.
A literal field can be used as one of the input fields of a transformation mapping. If you select the Literal option, then you must enter a value in the field. You must not leave the field blank after selecting it.
Apply the following best practices while working with fields of the OIM data sets:
For trusted source reconciliation, the following fields of the OIM – User data set must always hold values:
User ID
First Name
Last Name
Organization Name
Xellerate Type
Role
In addition, you can select other OIM – User fields that must be populated when a user account is created through reconciliation. For each of these fields, you must create mappings with the corresponding fields of the Reconciliation Staging data sets. During a reconciliation run, you must ensure that the fields of the target system that serve as the source for these fields always hold values.
For provisioning, you can select fields of the OIM – User and OIM – Account data sets whose values must be propagated to the target system. After you identify these fields, create mappings between them and their corresponding fields in the Provisioning Staging data sets. During a provisioning operation, you must enter values for each of these fields.
If required, add user-defined fields (UDFs) to the list of predefined OIM - User data set fields by using the Design Console.
However, do not use the Design Console to set the Password Field and Encrypted attributes for the UDF. The contents of a UDF are not encrypted if the Password Field and Encrypted attributes have been set for the field by using the Design Console.
This has also been mentioned in the "General Known Issues" section.
Do not modify or delete attributes of OIM - Account data set fields in an existing generic technology connector.
Summary
If parent records and child data records are created and linked in both the target system and Oracle Identity Manager, then you must ensure that the staging directory contains both parent data and child data files at the start of each reconciliation run.
Description
Suppose there are parent data records with associated child data records in the target system. To reconcile these records into Oracle Identity Manager, you place the parent and child data files containing these records in the staging directory. During the reconciliation run, the child data records are linked to their corresponding parent data records. Before the start of any subsequent reconciliation run, if you remove the child data files from the staging directory, then reconciliation events are not created for this form of child data record deletion. If you want to remove child data records for specific parent data records, then you must remove the child data records from the child data file. You must ensure that the child data file is placed in the staging directory for each reconciliation run, even if there are no child data records (from the third line onward) in the files.
Apply the following guideline while working with custom providers:
When you develop code for a custom Provisioning Transport Provider, ensure that the provider returns the unique field value at the end of a Create User operation. This functionality is implemented by the sendData
method of the Provisioning Transport Provider. See "Role of Providers During Provisioning" for more information.
Apply the following guidelines while working with connector objects created automatically during generic technology connector creation:
Summary:
Do not attempt to use for provisioning the resource object created automatically for a reconciliation-only generic technology connector.
Description:
Suppose you select only the Reconciliation option while creating a generic technology connector. At the end of the creation process, a resource object is one of the objects created automatically for this generic technology connector. However, you cannot provision this resource object to any user because a generic adapter is not created for a reconciliation-only generic technology connector.
Summary:
Do not attempt to provision generic technology connector resource objects to organizations defined in Oracle Identity Manager.
Description:
A resource object is one of the connector objects that get created automatically during generic technology connector creation. This resource object can be provisioned only to OIM Users. You must not attempt to provision it to organizations defined in Oracle Identity Manager.
This has also been mentioned in the "Connector Objects" section.
You can use the Design Console to customize connector objects that are automatically created during generic technology connector creation. After you customize connector objects, if you perform a Manage Generic Technology Connector operation, then all the customization done on the connector objects would be overwritten. Therefore, Oracle recommends that you to apply one of the following guidelines:
Do not use the Design Console to modify generic technology connector objects.
The exception to this guideline is the IT resource. You can modify the parameters of the IT resource by using the Design Console. However, if you have enabled the cache for the GenericConnector
and GenericConnectorProviders
categories, then you must purge the cache either before or after you modify IT resource parameters. See the "Purging the Cache" section in Oracle Identity Manager Best Practices Guide for more information.
If you use the Design Console to modify generic technology connector objects, then do not use the Manage Generic Technology Connector feature to modify the generic technology connector.
This has also been mentioned in the "Connector Objects" section.
Prepopulate adapters are not part of the set of connector objects that are created automatically when you create a generic technology connector. However, while creating a generic technology connector, you can map provisioning input to literals and user data fields. Although this feature cannot be used to prepopulate the User Defined Form, it can be used to prepopulate the provisioning data packet.
Apply the following best practices while modifying generic technology connectors:
Do not try to modify more than one generic technology connector at a time, even from different sessions of the Administrative and User Console for the same Oracle Identity Manager installation.