Name Resolution

DirX Access enables authenticating users that belong to different domains. These domains may or may not (for example, federated identity) be under the control of the system in which the DirX Access deployment resides. This configuration implies that there is no guarantee that the user identifiers of the different domains are unique. Furthermore, DirX Access needs to uniquely identify any user so that it can store long-term records to it in the internal user repository (for example, FIDO credentials, RBA records, and so on) and also to be able to provide this unique identifier to third-party systems (for example, audit systems).

Each authentication method internally retrieves a method-specific authentication identifier (for example, the username used for HTTP Basic authentication) typically from the credentials. This identifier is used to retrieve information from the related persistent user base (when “Do correlate user accounts” is set to true).

Afterwards, the domain names are determined for the authenticated subject and one of them is used as a unique name. A domain name is a structure formed from the authentication identifier, a domain identifier, and a format. Each authentication method enables the configuration of the domain identifier and the format which are used for construction of the domain name. The domain name is constructed according to the following algorithm:

  • By default, the “Autogenerate domain identifier and format” is checked. In this case, the domain name has the following form: authentication_id@authentication_method_id.

  • Otherwise, the domain name has the form defined by the “Domain name format”, where #1 and #2 are used as placeholders for authentication identifier and domain name (defined by “Domain identifier” field). For example, #1@#2 translates for username willa.sy and my-company domain identifier into willa.sy@my-company, while #2\#1 into my-company\willa.sy.

  • If “Domain name format” is left empty, the domain name is equivalent to the authentication identifier.

  • If the “Do hash authentication id” is checked, the authentication identifier is hashed before it is included into the domain name. This action results from the fact that some authentication identifiers may be in an unsupported format (too long or containing illegal characters).

After the primary domain name is created, it is used for resolution of all the other relevant domain names according to the principle: “Single subject may have multiple domain names, but only single unique name.” This process is extensible using the NameMappingCallout interface (see Name Mapping Plug-in). By default (if no NameMappingCallout is set up), the process is as follows:

  • Add the primary domain name into the set of domain names.

  • Add the persisted user identifier into the set of domain names if the authentication method is set to correlate to user repository. There is no domain identifier in this case and the format contains just the user identifier. (This is likely to change when DirX Access supports multiple user repositories to enable configuring multiple domains there.)

  • If the Application Repository is used for storing of the domain names, try to get a persisted unique name and then add it to the set of domain names.

Afterwards, the unique name is resolved:

  • If the persisted unique name has been found in the application repository, it is used.

  • Otherwise, if a correlated persisted user identifier has been found, it is used.

  • Otherwise, the primary domain name is used.

During a single session, the authentication process may occur multiple times (step up authentication, composite authentication, RBA-invoked authentication). By default, DirX Access does not apply any assumptions about the entities that are performing the authentication. However, it is necessary to perform a merging of the domain names stemming from different authentications. This task is fully customizable via the NameMappingCallout interface (see Name Mapping Plug-in). By default (if no NameMappingCallout is set up), the process is as follows: all sets of domain names already present in the session are examined against the new set of the domain names. If any of the domain names matches, the two sets are merged.

The domain names of the entity can be managed through the SCIM 2.0 REST Web Service. For successful resolution the unique name should also be one of the domain names of the entity, this is done automatically by DirX Access when an entity is created or updated when the storing of domain names is enabled, but for cases where the whole entity is created trough the SCIM 2.0 REST Web Service, the unique name should be set manually.

Migration

Previous versions of DirX Access did not contain the name resolution mechanism. Out-of-the-box backwards compatibility is achieved because the correlated persisted user identifier is represented in the domain name without any changes and the "Autogenerate domain identifier and format" is set to true.