1 About the Connector

Oracle Identity Manager automates access rights management, and the security of resources to various target systems. Oracle Identity Manager connectors are used to integrate Oracle Identity Manager with target applications. This guide discusses the Webservices connector that connects to a target system exposing a webservice endpoint.

The target system can be used as a managed (target) resource or an authoritative (trusted) source of identity information for Oracle Identity Manager. The connector uses Oracle SOA Suite as the indirection layer and supports all versions of webservices supported by that version of SOA Suite.

Note:

In this guide, a target system that exposes webservice endpoint has been referred to as the target system. ACME Webservice is used as a sample target system to discuss the configurations and the connector objects.

In the account management (target resource) mode of the connector, data about users created or modified directly on the target system can be reconciled into Oracle Identity Manager. This data is used to provision (allocate) new resources or update resources already assigned to OIM Users. In addition, you can use Oracle Identity Manager to provision or update target resources assigned to OIM Users. These provisioning operations performed on Oracle Identity Manager translate into the creation of or updates to target system accounts.

In the identity reconciliation (trusted source) configuration of the connector, persons are created or modified only on the target system and information about these persons is reconciled into Oracle Identity Manager.

This chapter contains the following sections:

1.1 Certified Components

Table 1-1 lists the components certified for use with the connector.

Table 1-1 Certified Components

Item	Requirement
Oracle Identity Governance or Oracle Identity Manager	You can use one of the following releases of Oracle Identity Governance or Oracle Identity Manager: Oracle Identity Governance 12c (12.2.1.4.0) Oracle Identity Governance 12c (12.2.1.3.0) Oracle Identity Manager 11g Release 2 PS3 (11.1.2.3.0) Oracle Identity Manager 11g Release 2 (11.1.2.0.7) BP07 and any later BP in this release track Oracle Identity Manager 11g Release 1 (11.1.1.5.6) BP06 (with patch 15971939) and any later BP in this release track
Target system	Any target system that exposes webservice endpoints
Connector Server	11.1.2.1.0
Connector Server JDK	JDK 1.6 or later, or JRockit 1.6 or later

1.2 Certified Languages

The connector supports the following languages:

Arabic
Chinese (Simplified)
Chinese (Traditional)
Czech
Danish
Dutch
English
Finnish
French
German
Greek
Hebrew
Hungarian
Italian
Japanese
Korean
Norwegian
Polish
Portuguese
Portuguese (Brazilian)
Romanian
Russian
Slovak
Spanish
Swedish
Thai
Turkish

Note:

However, the connector does not support the entry of multibyte characters in some of the fields.

1.3 Connector Architecture

Figure 1-1 shows the architecture of the connector.

Figure 1-1 Architecture of the Connector

Description of "Figure 1-1 Architecture of the Connector"

The connector is implemented by using the Identity Connector Framework (ICF). ICF is a component that provides basic reconciliation and provisioning operations that are common to all Oracle Identity Manager connectors. In addition, ICF provides common features that developers would otherwise need to implement on their own, such as connection pooling, buffering, time outs, and filtering. The ICF is shipped along with Oracle Identity Manager. Therefore, you need not configure or modify the ICF.

The connector architecture can be described as follows:

Webservices are web APIs exposed by web applications to enable inter operability with their applications. Operations exposed by webservice can be invoked and used via SOAP protocol.
The connector uses SOA to bind and invoke operations on the target webservice. SOA acts as the indirection layer. SOA composite is wired on one end to the webservice client, represented as WSConnector Client PartnerLink in Figure 1-1. This client is the connector's webservice endpoint that exposes ICF-based operations such as create, delete, update, and search. On the other end, the SOA composite is wired to a target webservice that exposes similar operations but with it's own input and output conventions.
The WSConnector Client endpoint makes use of oracle/wss_username_token_client_policy webservice security policy for authentication.
The connector is responsible for invoking ICF operations on the SOA composite that are generated by the connector's webservice client with a specific input structure. This triggers the BPEL process for the specific type of operation, such as create, which in turn invokes the operation on the target webservice.
The output is passed to the SOA composite, which optionally can use XSLT to transform the payload into a structure that ICF understands. This transformation and wiring is handled in the SOA composite, which has to be manually configured by the user.
The webservice client that the connector interacts with exposes a contract corresponding to the ICF adapters and objects. WSDL contains definitions for the operations, the input and output schema specific to each operation, exception handling by declaring exceptions such as UnknownUidException and AlreadyExistsException, and the custom or child table attributes.

The connector package contains a base SOA composite template, the ICF webservice connector bundle, and the Oracle Identity Manager metadata. The Oracle Identity Manager metadata is pre-defined and can be updated as per your requirements. The metadata can be considered as a template and can be customized to suit the target accounts. The target system operations trigger ICF operations and are routed to the ICF webservice connector bundle. The wiring of the target webservices is done at the SOA composite layer. The ICF connector bundle makes a call to the respective operation at the SOA composite layer.

The connector expects operations exposed as SOAP services. The SOAP operations are offered based on a pre-defined WSDL contract. This WSDL contract has one operation each for create, update, delete, addAttributeValue, removeAttributeValue, lookupSearch, and accountSearch operations. Each operation in the BPEL process is processed within its respective branch.The connector can invoke a different webservice operation or a different target system webservice for various operations. This architecture is primarily focused to support synchronous webservices where the result is returned within the same call.

1.4 Features of the Connector

1.4.1 Support for Configuring the Connector for a New Target System

You can configure the connector to support an additional target system that exposes webservice endpoint.

The connector package contains a base SOA template composite, the ICF webservice connector bundle, and the Oracle Identity Manager metadata.

For more information, see the procedures described in Preinstallation Steps and Deploying the Connector.

1.4.2 Support for Securing the Connector

You can configure the connector in Oracle Identity Manager and in the SOA composite to secure the connector.

See Securing the Connector for security-related topics.

1.4.3 Support for Multiple Instances and Multiple Versions of Target Systems

The connector supports multiple instances and multiple versions of target systems.

You can deploy a single connector bundle on Oracle Identity Manager and create multiple IT resources for multiple instances and multiple versions of target systems. Then, you can use Oracle Identity Manager to manage accounts on these target systems. See Configuring the Connector for Multiple Instances and Multiple Versions of the Target System for more information.

1.4.4 Support for Both Target Resource and Trusted Source Reconciliation

You can use the connector to configure the target system as either a target resource or trusted source of Oracle Identity Manager.

See Configuring Reconciliation for more information.

1.4.5 Support for Both Full and Incremental Reconciliation

After you deploy the connector, you can perform full reconciliation to bring all existing user data from the target system to Oracle Identity Manager. After the first full reconciliation run, incremental reconciliation is automatically enabled from the next run of the user reconciliation.

You can perform a full reconciliation run at any time. See Performing Full Reconciliation for more information.

1.4.6 Support for Limited Reconciliation

You can set a reconciliation filter as the value of the Filter attribute of the scheduled tasks. This filter specifies the subset of newly added and modified target system records that must be reconciled.

See Performing Limited Reconciliation for more information.

1.4.7 Support for Batched Reconciliation

You can break down a reconciliation run into batches by specifying the number of records that must be included in each batch.

See Performing Batched Reconciliation for more information.

1.4.8 Validation of Data

You can configure single-valued data to be validated during provisioning and reconciliation operations.

See Configuring Validation of Data During Reconciliation and Provisioning for more information.

1.4.9 Transformation of Data

You can configure transformation of data that is brought into Oracle Identity Manager during reconciliation.

See Configuring Transformation of Data During User Reconciliation for more information.

1.4.10 Support for Resource Exclusion Lists

You can specify a list of accounts that must be excluded from reconciliation and provisioning operations. Accounts whose user IDs you specify in the exclusion list are not affected by reconciliation and provisioning operations.

Configuring Resource Exclusion Lists describes the procedure to add entries in these lookup definitions.

1.5 Lookup Definitions Used During Connector Operations

Lookup definitions used during connector operations can be categorized as follows:

1.5.1 Lookup Definitions Synchronized with the Target System

During a provisioning operation, you use a lookup field on the process form to specify a single value from a set of values. For example, you use the Date Format lookup field to select a date format from the list of supported date formats. When you deploy the connector, lookup definitions corresponding to the lookup fields on the target system are automatically created in Oracle Identity Manager. Lookup field synchronization involves copying additions or changes made to the target system lookup fields into the lookup definitions in Oracle Identity Manager.

The lookup reconciliation scheduled job is used to synchronize value of lookup definitions with the target system. See Scheduled Task for Lookup Field Synchronization for more information.

While performing a provisioning operation on the Administrative and User Console, you select the IT resource for the target system on which you want to perform the operation. When you perform this action, the lookup definitions on the page are automatically populated with values corresponding to the IT resource (target system installation) that you select.

1.5.2 Preconfigured Lookup Definitions

This section discusses the other lookup definitions that are created in Oracle Identity Manager when you deploy the connector. These lookup definitions are either prepopulated with values or values must be manually entered in them after the connector is deployed. The other lookup definitions are as follows:

Note:

The names of the lookup definitions are determined by the SHORT_CODE of the connector name you provide while building the connector.

For example, in this guide, ACME is the SHORT_CODE name of the connector provided while building the connector.

If you use CRM as the SHORT_CODE, then the lookup definitions will be Lookup.CRM.UM.ReconAttrMap and so on.

1.5.2.1 Configuration Lookup Definitions

The Lookup.ACME.Configuration and Lookup.ACME.Configuration.Trusted lookup definitions hold connector configuration entries that are used during reconciliation and provisioning operations.

Table 1-2 lists the default entries in this lookup definition.

Table 1-2 Entries in the Configuration Lookup Definitions

Code Key	Decode	Description
Bundle Name	org.identityconnectors.webservices	This entry holds the name of the connector bundle package. Do not modify this entry.
Bundle Version	1.0.112	This entry holds the version of the connector bundle class. Do not modify this entry.
Connector Name	org.identityconnectors.genericws.GenericWSConnector	This entry holds the name of the connector class. Do not modify this entry.
internalPolicyReference	false	Internal OWSM policy reference for the connector during standalone operations.
User Configuration Lookup	For target resource mode: Lookup.ACME.UM.Configuration For trusted mode: Lookup.ACME.UM.Configuration.Trusted	This entry holds the name of the lookup definition that contains user-specific configuration properties. Do not modify this entry.

1.5.2.2 Lookup.ACME.UM.Configuration

The Lookup.ACME.UM.Configuration lookup definition holds configuration entries that are specific to the user object type. This lookup definition is used during user management operations when your target system is configured as a target resource.

Table 1-3 lists the default entries in this lookup definition.

Table 1-3 Entries in the Lookup.ACME.UM.Configuration Lookup Definition

Code Key	Decode	Description
Provisioning Attribute Map	Lookup.ACME.UM.ProvAttrMap	This entry holds the name of the lookup definition that maps process form fields and target system attributes. See Lookup.ACME.UM.ProvAttrMap for more information about this lookup definition.
Recon Attribute Map	Lookup.ACME.UM.ReconAttrMap	This entry holds the name of the lookup definition that maps resource object fields and target system attributes. See Lookup.ACME.UM.ReconAttrMap for more information about this lookup definition.

1.5.2.3 Lookup.ACME.UM.Configuration.Trusted

The Lookup.ACME.UM.Configuration.Trusted lookup definition holds configuration entries that are specific to the user object type. This lookup definition is used during user management operations when your target system is configured as a trusted source.

Table 1-4 lists the default entries in this lookup definition.

Table 1-4 Entries in the Lookup.ACME.UM.Configuration.Trusted Lookup Definition

Code Key	Decode	Description
Recon Attribute Defaults	Lookup.ACME.UM.ReconDefaults.Trusted	This entry holds the name of the lookup definition that maps process form fields and target system attributes.
Recon Attribute Map	Lookup.ACME.UM.ReconAttrMap.Trusted	This entry holds the name of the lookup definition that maps resource object fields and target system attributes.

1.5.2.4 Lookup.ACME.UM.ProvAttrMap

The Lookup.ACME.UM.ProvAttrMap lookup definition holds mappings between process form fields and target system attributes. This lookup definition is used during provisioning. This lookup definition is preconfigured. Table 1-7 lists the default entries.

You can add entries in this lookup definitions if you want to map new target system attributes for provisioning. See Adding Custom Attributes for Provisioning for more information.

1.5.2.5 Lookup.ACME.UM.ReconAttrMap

The Lookup.ACME.UM.ReconAttrMap lookup definition holds mappings between resource object fields and target system attributes. This lookup definition is used during reconciliation. This lookup definition is preconfigured. Table 1-5 lists the default entries.

You can add entries in this lookup definitions if you want to map new target system attributes for reconciliation. See Adding Custom Attributes for Reconciliation for more information.

1.5.2.6 Lookup.ACME.UM.ReconAttrMap.Trusted

The Lookup.ACME.UM.ReconAttrMap.Trusted lookup definition holds mappings between resource object fields and target system attributes. This lookup definition is used during reconciliation in trusted mode.

This lookup definition contains the following entries:

Code Key	Decode
First Name	FirstName
Last Name	LastName
Status[TRUSTED]	Status
Unique Id	__UID__

1.5.2.7 Lookup.ACME.UM.ReconDefaults.Trusted

The Lookup.ACME.UM.ReconDefaults.Trusted lookup definition holds mappings between process form fields and target system attributes. This lookup definition is used during reconciliation in trusted mode.

This lookup definition contains the following entries:

Code Key	Decode
Empl Type	Full-Time
Organization Name	Xellerate Users
Status	Active
User Type	End User

1.6 Connector Objects Used During Reconciliation

The User Target Reconciliation and User Trusted Reconciliation scheduled jobs are used to initiate reconciliation runs. These scheduled jobs are discussed in Scheduled Tasks.

1.7 Connector Objects Used During Provisioning

Provisioning involves creating or modifying user data on the target system through Oracle Identity Manager.

This section discusses the following topics:

1.7.1 User Provisioning Functions

Table 1-6 lists the supported user provisioning functions and the adapters that perform these functions. The functions listed in the table correspond to either a single or multiple process tasks.

Function	Task Adapter
Create a user account	adpACMEWEBSERVICECREATEOBJECT
Delete a user account	adpACMEWEBSERVICEDELETEOBJECT
Enable a user account	adpACMEWEBSERVICEENABLEUSER
Disable a user account	adpACMEWEBSERVICEDISABLEUSER
Update an attribute	adpACMEWEBSERVICEUPDATEATTRIBUTEVALUE
Bulk update of attributes	adpACMEWEBSERVICEBULKUPDATE
Add a child table value	adpACMEWEBSERVICEADDCHILDTABLEVALUE
Remove a child table value	adpACMEWEBSERVICEREMOVECHILDTABLEVALUE
Update a child table value	adpACMEWEBSERVICEUPDATECHILDTABLEVALUE

1.7.2 User Attributes for Provisioning

The Lookup.ACME.UM.ProvAttrMap lookup definition maps process form fields with single-valued target system attributes.

The Code Key column holds the names of process form fields.

The Decode column stores the names of the target system attributes.

Table 1-7 lists the entries in this lookup definition.

Table 1-7 Entries in the Lookup.ACME.UM.ProvAttrMap Lookup Definition

Process Form Field	Target System Attribute
Address	Address
Common Name	CommonName
Country	Country
Department Number	DepartmentNumber
Deprovisioning Date[DATE]	DeprovisioningDate
Display Name	DisplayName
Email	Email
Employee Number	Empno
End Date[DATE]	EndDate
Fax	Fax
First Name	FirstName
Generation Qualifier	GenerationQualifier
Hire Date[DATE]	HireDate
Home Address	HomeAddress
Home Phone	HomePhone
Initials	Initials
Last Name	LastName
Locality	Locality
Login	__NAME__
Manager	Manager
Middle Name	MiddleName
Mobile	Mobile
Organization	Organization
Pager	Pager
Password	__PASSWORD__
PO Box	POBox
Provisioning Date[DATE]	ProvisioningDate
Start Date[DATE]	StartDate
State	State
Status	Status
Street	Street
Telephone Number	TelephoneNumber
Title	Title
UD_ACME_CH~Role	Role
Unique Id	__UID__
User Type	UserType