Sun Identity Manager Deployment Guide

PrototypeXML String

The prototypeXML string in the adapter Java file is the XML definition of a resource. This string must contain the resource name and all of the resource attributes that you want to display in the Identity Manager user interface. The prototypeXML string also defines resource objects stored in the Identity Manager repository.

The following table describes the different prototypeXML information types that you use to define a resource in Identity Manager.


Note –

Some of these information types are specific to Active Sync-enabled adapters.


Table 9–3 prototypeXML Information Types

Type 

Description 

Resource 

Defines top-level characteristics of the resource. Keywords include: 

  • syncSource: If true, then adapter must be Active Sync-enabled.

  • facets: Specifies the modes enabled for this resource.

Resource attributes

XML elements that are defined with the <ResourceAttribute> element and used by Identity Manager to configure the resource.

For more information, see Resource Attributes.

Account attributes

Defines the default schema map for basic user attributes. 

You use the <AccountAttribute> element to define account attributes. You map standard Identity Manager account attribute types differently than you map custom attributes.

For more information about mapping account attributes to resource attributes, see Map the Attributes.

Identity template

Defines how the account name for the user is built. Use the <Template> tag to define this template. Account names are typically in one of the following forms:

  • An accountId is typically used for resources with a flat namespace such as Oracle.

  • A complete distinguished name (DN) of the user in the form: cn=accountId,ou=sub-org,ou=org,o=company. Use this form for hierarchical namespaces such as directories.

    For more information, see Identity Template.

Login configuration

(Standard resource adapter only) Defines values to support pass-through authentication for the resource. Use the <LoginConfigEntry> element to define this value.

For more information about pass-through authentication, see the Resource Reference. 

Form 

(Active Sync-enabled adapters only) Designates a form object that processes data from the Active Sync-enabled adapter before the data is integrated into Identity Manager. A form is optional, but in most cases a form provides flexible changes in the future and can be used to transform incoming data, map data to other user attributes on other resource accounts, and cause other actions in Identity Manager to occur.

Resource Attributes

Only available to Administrators defining the resource.

Resource attributes define the connection information on the resource being managed. Resource attributes typically include the resource host name, resource administrator name and password, and the container information for directory-based resources. Identity Manager attributes such as the list of resource approvers and the number of times to retry operations on the resource are also considered resource attributes.

When writing custom adapters, you use resource attributes to define:

You can modify these values from the Identity Manager interface when creating a specific instance of this resource type.

Defining Resource Attributes

You use the <ResourceAttribute> element, as shown in the following example, to define resource attributes in the prototypeXML string of the adapter Java file:


<ResourceAttribute name=’"+RA_HOST+"’ type=’string’ multi=’false’\n"+
description=’&lt;b&gt;host&lt;/b&gt;&lt;br&gt;Enter the resource host name.’>\n"+

Where the description field identifies the item-level help for the RA_HOST field and must not contain the < character. In the preceding example, the < characters are replaced by &lt; and &apos;.

The following table describes the keywords you can use in <ResourceAttribute> element.

Table 9–4 <ResourceAttribute> Element Keywords

Keyword 

Description 

name

Identifies the name of the attribute. 

NOTE: The name keyword is a reserved word in views and should not be used as a Identity System User Attribute on resource schema maps.

type

Identifies the data type used. 

multi

Specifies whether multiple values can be accepted for the attribute. If true, a multi-line box displays.

description

Identifies the item-level help for the RA_HOST field. Identity Manager displays help with the item being described (host in this case) in bold text. Because the HTML brackets necessary to do this (< and >) interfere with XML parsing, they are replaced by &lt; and &gt;. After the binary is translated, the description value looks like:

Description=’<b>host</b> Enter the resource host name.’

facets

Specifies the usage of this resource attribute. Valid values are 

  • provision: Used in standard processing (default value).

  • activesync: Used in Active Sync processing for an Active Sync-enabled adapter.

The ResourceAttribute> element may also contain a ValidationPolicy element. A validation policy ensures the value a user specifies on the Resource Parameters page meets the requirements defined in a separate policy object.

The following sample causes the adapter to use the Port Policy to ensure the specified value is valid. The default Port Policy checks the value is an integer between 1 and 65536.

 <ResourceAttribute name='Port' value='123'>
    <ValidationPolicy>
      <ObjectRef type='Policy' id='#ID#PortPolicy' name='Port Policy'/>
    </ValidationPolicy>
  </ResourceAttribute>

Overwriting Resource Attributes

When you are working with resource adapters and adapter parameters, you can use one of the following strategies to overwrite resource attributes:

In the following example, the user form must override the resource attribute value for template during the creation of each user. When implementing similar code in a production environment, you would probably include more detailed logic to calculate this template value within your user form.


Example 9–1 Overwriting the Resource Attribute Value for template


<Field name=’template’>
   <Display class=’Text’>
      <Property name=’title’ value=’NDS User Template’/>
   </Display
</Field>
<!-- Change NDS for the name of your NDS resource -->
<!-- Template is the name of the attribute field, as viewed in the resource xml -->
<Field name=’accounts[NDS].resourceAttributes.Template’>
   <Expansion>
      <ref>template</ref>
   </Expansion>
</Field>

Required Resource Attributes

The following table describes required resource attributes that are supplied in the skeleton adapter files.

Table 9–5 Resource Attributes in Skeleton Adapter Files

Required Resource Attribute 

Description 

RA_HOST

Resource host name. This attribute corresponds to the Host field on the Resource Parameters page. 

RA_PORT

Port number used to communicate with the resource. This attribute corresponds to the Port field on the Resource Parameters page. 

RA_USER

Name of a user account that has permission to connect to the resource. The field name varies on the Resource Parameters page. 

RA_PASSWORD

Password for the account specified by RA_USER. This attribute corresponds to the Host field on the Resource Parameters page.

The next table describes required Active Sync-specific attributes that are defined in the ACTIVE_SYNC_STD_RES_ATTRS_XML string of the Active Sync class.

Table 9–6 Active Sync-Specific Attributes Defined in ACTIVE_SYNC_STD_RES_ATTRS_XML

Required Resource Attribute  

Description  

RA_PROXY_ADMINISTRATOR

Identity Manager administrator for authorization and logging. This attribute corresponds to the Proxy Administrator field in the Identity Manager display. You do not define this value in the adapter Java file. Instead, an administrator enters this information when defining a specific instance of this resource type. 

RA_FORM

Form that processes incoming attributes and maps them to view attributes. This attribute corresponds to the Input Form field. 

RA_MAX_ARCHIVES

Specifies the number of log files to retain. 

  • If you specify 0, then a single log file is re-used.

  • If you specify -1, then log files are never discarded.

RA_MAX_AGE_LENGTH

Specifies the maximum time before a log file is archived. 

  • If you specify zero, then no time-based archival occurs.

  • If the RA_MAX_ARCHIVES value is zero, then the active log is truncated and reused after this time period.

RA_MAX_AGE_UNIT

Specify seconds, minutes, hours, days, weeks, or months. Use this value with RA_MAX_AGE_LENGTH.

RA_LOG_LEVEL

Logging level (0 disabled; 4 very verbose). This attribute corresponds to the Log Level field in the Identity Manager display. 

RA_LOG_PATH

Absolute or relative path for the log file. This attribute corresponds to the Log File Path field in the Identity Manager display. 

RA_LOG_SIZE

Maximum log file size. This attribute corresponds to the Maximum Log File Size field in the Identity Manager display. 

RA_SCHEDULE_INTERVAL

Pop-up menu of the supported scheduling intervals (second, minute, hour, day, week, month). 

RA_SCHEDULE_INTERVAL_COUNT

Number of intervals between scheduled periods (for example, 10 minutes has an interval count of 10 and an interval of minute). Not necessary for Active Sync-enabled adapters. 

RA_SCHEDULE_START_TIME

Time of the day to run. For example, if you specify 13:00 and set the interval to week, the adapter runs at 1 P.M. once a week. Not necessary for Active Sync-enabled adapters. 

RA_SCHEDULE_START_DATE

Date to start scheduling. Setting date to 20020601, the interval to month, and the time to 13:00 starts the adapter on June 1st and runs once a month at 1 P.M. Not necessary for Active Sync-enabled adapters.

This table describes required Active Sync-specific attributes that are defined in the ACTIVE_SYNC_EVENT_RES_ATTRS_XML string of the Active Sync class.

Table 9–7 Active Sync-Specific Attributes Defined in ACTIVE_SYNC_EVENT_RES_ATTRS_XML

Required Resource Attribute 

Description 

RA_PROCESS_RULE

Name of a TaskDefinition or a rule that returns the name of a TaskDefinition to run for every record in the feed. This attribute overrides all others.

RA_CORRELATION_RULE

Rule that returns a list of strings of potentially matching users/accountIDs, based on the resource account attributes in the account namespace. 

RA_CONFIRMATION_RULE

Rule that confirms whether a user is a match. 

RA_DELETE_RULE

Rule that determines whether a delete detected on the resource is processed as an IAPI delete event, or as an IAPI update event. 

RA_CREATE_UNMATCHED

  • If set to true, creates unmatched accounts.

  • If false, do not create the account unless the process rule is set and the workflow it identifies determines that a create is warranted. Default is true.

RA_RESOLVE_PROCESS_RULE

Rule that determines the workflow to run when there are multiple matches using the confirmation rule on the results of the correlation rule. 

RA_POPULATE_GLOBAL

Indicates whether to populate the global namespace in addition to the activeSync namespace. Default is false.

Identity Manager Account Attributes

Only available to Administrators defining the resource.

Identity Manager account attributes describe the default user attributes supported for the resource.

With an Active Sync-enabled adapter, account attributes are the attributes that are available to update the Identity Manager user account. The Active Sync-enabled adapter collects these attributes and stores them in the global area for the input form.

Identity Manager supports the following types of account attributes:

Binary attributes include graphic files, audio files, or certificates. Not all adapters support binary account attributes. Generally, only certain directory, flat file, and database adapters can process binary attributes.


Note –

You define Identity Manager account attributes in the AttributeDefinition object of the resource’s schema map, and use the prototypeXML string in the adapter file to map incoming resource attributes to account attributes in Identity Manager. For example, you would map the LDAP sn resource attribute to the lastname attribute in Identity Manager. Identity Manager account attributes include

Standard Adapter Schema Maps

You use the Account Attributes page, or schema map, to map Identity Manager account attributes to resource account attributes. The list of attributes varies for each resource. You generally remove all unused attributes from the schema map page. If you add attributes, you will probably need to edit user forms or other code.

The attribute mappings specified in the resource schema map determine which account attributes can be requested when you are creating a user. Based on the role selected for a user, you will be prompted for a set of account attributes that are the union of attributes of all resources in the selected role.


Note –

To view or edit the Identity Manager schema for users or roles, you must be a member of the IDM Schema Configuration AdminGroup and you must have the IDM Schema Configuration capability.


Active Sync-Enabled Adapter Schema Maps

The Active Sync resource schema map is an optional utility that enables you to edit inputs to an Active Sync-enabled adapter, which are often database column names or directory attribute names. Using the schema map and an Active Sync form, you can implement Java code to handle a resource type, defining details of the resource configuration in the map and form.

Identity Manager uses an Active Sync resource’s schema map in the same way that it uses a typical schema map. The schema map specifies which attributes to fetch from the resource and their local names. All attribute names that are listed in the schema map (that is, all attributes that exist on the resource) are made available to the Active Sync form and the user form with the activeSync.name attribute. If the Active Sync resource does not use a form, all attributes are named global to ensure that all attributes automatically propagate to attributes with the same name on all resources. Use a form rather than the global namespace.


Tip –

Do not put the accountId attribute in the global namespace because this special attribute is used to identify waveset.account.global.

If you are creating the resource account for the first time, the accountId attribute also becomes a resource’s accountId directly and it bypasses the identity template.


For example, if a new Identity Manager user is created through the Active Sync-enabled adapter and that user has an LDAP account assigned to it, the LDAP accountID will match the global.accountId instead of the correct DN from the DN template.

Using the Schema Map

After creating a resource instance, administrators can subsequently use a schema map to:

You can view Identity Manager account attributes from the Edit Schema page in the Identity Manager user interface by clicking the Edit Schema button located at the bottom of the Edit/Create Residenource page.

For more information about creating a resource or editing a resource schema map, see the Business Administrator's Guide.

Identity Template


Note –

An identity template is only available to Administrators who are defining the resource.

To view or edit the Identity Manager schema for Users or Roles, you must be a member of the IDM Schema Configuration AdminGroup and you must have the IDM Schema Configuration capability.


You use the identity template (or account DN) to define a user’s default account name syntax when creating the account on the resource. The identity template translates the Identity Manager user account information to account information on the external resource.

You can use any schema map attribute (an attribute listed on the left side of the schema map) in the identity template, and you can overwrite the user identity template from the User form, which is commonly done to substitute organization names.

Identity Manager users have an identity for each of their accounts, and this identity can be the same for some or for all of these accounts. The system sets the identity for an account when the account is provisioned. The Identity Manager user object maintains a mapping between a user’s identities and the resources to which they correspond.

The user has a primary accountId in Identity Manager that is used as a key and as a separate accountId for each of the resources on which that user has an account. The accountId is denoted in the form of accountId:<resource name>, as shown in the following table.

Table 9–8 accountID Examples

Attribute 

Example 

accountId

maurelius

accountId:NT_Res1

marcus_aurelius

accountId:LDAP_Res1

uid=maurelius,ou=marketing,ou=employees,o=abc_company

accountId:AIX_Res1

maurelius

Account user names are in one of two forms:

Flat Namespaces

You typically use the accountId attribute for systems with a flat namespace, which include:

For resources with flat namespaces, the identity template can simply specify that the Identity Manager account name be used.

Hierarchical Namespaces

You use distinguished names (DNs) for systems with a hierarchical namespace. DNs can include the account name, organizational units, and organizations.

Account name syntax is especially important for hierarchical namespaces. For resources with hierarchical namespaces, the identity template can be more complicated than that of a flat namespace, which allows you to build the full, hierarchical name. The following table shows examples of hierarchical namespaces and how they represent DNs.

Table 9–9 Hierarchical Namespace Examples

System 

Distinguished Name String 

LDAP 

cn=$accountId,ou=austin,ou=central,ou=sales,o=comp

Novell NDS 

cn=$accountId.ou=accounting.o=comp

Microsoft Windows 2000 

CN=$fullname,CN=Users,DC=mydomain,DC=com

For example, you can specify the following for a resource identity template with a hierarchical namespace such as LDAP:

uid=$accountID,ou=$department,ou=People,cn=waveset,cn=com

Where:

Login Configuration

Login Configuration defines parameters that are used if you are going to use the resource for pass-through authentication. Typically, these parameters are username and password, but some resources use different parameters. For example, SecurId uses user name and passcode.

The Login Configuration information type helps define the resource, but it is not easily modified by administrators.

For more information about pass-through authentication, see Enabling Pass-Through Authentication for Resource Types and the Resource Reference.