EIM lookup operations

An application or an operating system uses an EIM API to perform a lookup operation so that the application or operating system can map from one user identity in one registry to another user identity in another registry. An EIM lookup operation is a process through which an application or operating system finds an unknown associated user identity in a specific target registry by supplying some known and trusted information.

Applications that use EIM APIs can perform these EIM lookup operations on information only if that information is stored in the EIM domain. An application can perform one of two types of EIM lookup operations based on the type of information the application supplies as the source of the EIM lookup operation: a user identity or an EIM identifier.

When applications or operating systems use the eimGetTargetFromSource() API to obtain a target user identity for a given target registry, they must supply a user identity as the source of the lookup operation. To be used as the source in a EIM lookup operation, a user identity must have either an identifier source association defined for it or be covered by a policy association. When an application or operating system uses this API, the application or operating system must supply three pieces of information:
  • A user identity as the source, or starting point of the operation.
  • The EIM registry definition name for the source user identity.
  • The EIM registry definition name that is the target of the EIM lookup operation. This registry definition describes the user registry that contains the user identity that the application is seeking.
When applications or operating systems use the eimGetTargetFromIdentifier() API to obtain a user identity for a given target registry, they must supply an EIM identifier as the source of the EIM lookup operation. When an application uses this API, the application must supply two pieces of information:
  • An EIM identifier as the source, or starting point of the operation.
  • The EIM registry definition name that is the target of the EIM lookup operation. This registry definition describes the user registry that contains the user identity that the application is seeking.

For a user identity to be returned as the target of either type of EIM lookup operation, the user identity must have a target association defined for it. This target association can be in the form of an identifier association or a policy association.

The supplied information is passed to EIM and the EIM lookup operation searches for and returns any target user identities, by searching EIM data in the following order, as Figure 10 illustrates:
  1. Identifier target association for an EIM identifier. The EIM identifier is identified in one of two ways: It is supplied by the eimGetTargetFromIdentifier() API. Or, the EIM identifier is determined from information supplied by the eimGetTargetFromSource() API.
  2. Certificate filter policy association.
  3. Default registry policy association.
  4. Default domain policy association.

Figure 10: EIM lookup operation general processing flow chart

Process flow chart for a mapping lookup operation
Note: In the following flow, lookup operations first checks the individual registry definition, such as the specified source registry or target registry. If lookup operations fail to find a mapping using the individual registry definition, it determines whether the individual registry definition is a member of a group registry definition. If it is a member of a group registry definition, the lookup operation checks the group registry definition to satisfy the mapping lookup request.
The lookup operation search flows in this manner:
  1. The lookup operation checks whether mapping lookups are enabled. The lookup operation determines whether mapping lookups are enabled for the specified source registry, the specified target registry, or both specified registries. If mapping lookups are not enabled for one or both of the registries, then the lookup operation ends without returning a target user identity.
  2. The lookup operation checks whether there are identifier associations that match the lookup criteria.If an EIM identifier was provided, the lookup operation uses the specified EIM identifier name. Otherwise, the lookup operation checks whether there is a specific identifier source association that matches the supplied source user identity and source registry. If there is one, the lookup operation uses it to determine the appropriate EIM identifier name. The lookup operation then uses the EIM identifier name to search for an identifier target association for the EIM identifier that matches the specified target EIM registry definition name. If there is an identifier target association that matches, the lookup operation returns the target user identity defined in the target association.
  3. The lookup operation checks whether the use of policy associations are enabled. The lookup operation checks whether the domain is enabled to allow mapping lookups using policy associations. The lookup operation also checks whether the target registry is enabled to use policy associations. If the domain is not enabled for policy associations or the registry is not enabled for policy associations, then the lookup operation ends without returning a target user identity.
  4. The lookup operation checks for certificate filter policy associations. The lookup operation checks whether the source registry is an X.509 registry type. If it is an X.509 registry type, the lookup operation checks whether there is a certificate filter policy association that matches the source and target registry definition names. The lookup operation checks whether there are certificates in the source X.509 registry that satisfy the criteria specified in the certificate filter policy association. If there is a matching policy association and there are certificates that satisfy the certificate filter criteria, the lookup operation returns the appropriate target user identity for that policy association.
  5. The lookup operation checks for default registry policy associations.The lookup operation checks whether there is a default registry policy association that matches the source and target registry definition names. If there is a matching policy association, the lookup operation returns the appropriate target user identity for that policy association.
  6. The lookup operation checks for default domain policy associations.The lookup operation checks whether there is a default domain policy association defined for the target registry definition. If there is a matching policy association, the lookup operation returns the associated target user identity for that policy association.
  7. The lookup operation is unable to return any results.

To learn more about Enterprise Identity Mapping lookup operations view the following examples: