Skip to main content

The most recent patch for this version is 6.3.1.  Learn more  

Mapping configuration

This is the second part of the configuration, where the attribute-specific configuration is managed.

XML element or attributeDescriptionSupported format
xacmlAttributeThe XACML attribute to be fetched from this attribute source.A valid XACML-format attribute contains XML attributes for AttributeId, Category, DataType, and Issuer.
searchSelectionThe name of the target LDAP attribute that will return the value of the mapped XACML attribute.LDAP attribute name
searchBaseThe base in the LDAP directory tree from which the search filter will be applied. The search base can be static (that is, a fixed node) or dynamic in which case it will depend on attribute values in the request.
A dynamic search base is created by inserting one or more question marks (?) in the search base DN. Each question mark is substituted for the value of a specified XACML attribute.
See the Dynamic search base section below for details.		A valid LDAP distinguished name with optional question marks (?) used to denote attribute value substitution when a dynamic search base is used.
searchBaseKeyA sequence of XACML attributes used to replace the question mark in the search base.See xacmlAttribute in this table.
searchScopeThree search scopes can be specified using one of the following values:
0 - Stands for OBJECT_SCOPE: This value is used to indicate searching only the entry at the base DN, resulting in only that entry being returned
1 - Stands for ONELEVEL_SCOPE: This value is used to indicate searching all entries exactly one level under the base DN. This does not include the base DN.
2 - Stands for SUBTREE_SCOPE: This value is used to indicate searching all entries at all levels under and including the specified base DN.		One of 0, 1, and 2.
searchFilterThe LDAP attribute and value that is used to filter the result set. The values of the key that are used in the query are denoted by a ? symbol and need to be mapped to an XACML attribute.
See the Search filters section below for details.		A valid LDAP filter with optional question marks (?) used to denote attribute value substitution.
keyA sequence of XACML attributes used to replace the question mark in the search filter.See xacmlAttribute in this table.
uIdAn identifier used to distinguish otherwise identical mappings for the purpose of caching. The element is required, but can contain an arbitrary value.

The following shows an example of how the XML elements can be implemented. It is an extract from the sample XML-format configuration file supplied in the appendix XML Configuration.

  <pip:mapping>
    <pip:xacmlAttribute AttributeId="employeeType" Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer=""/>
    <pip:nativeAttribute>
      <pip:searchSelection>sn</pip:searchSelection>
      <pip:searchBase>dc=axiomatics,dc=com</pip:searchBase>
      <pip:searchBaseKey><pip:xacmlAttribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer=""/></pip:searchBaseKey>
      <pip:searchScope>2</pip:searchScope>
      <pip:searchFilter>cn=?</pip:searchFilter>
      <pip:key allowMultiple="false">
        <pip:xacmlAttribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer=""/>
      </pip:key>
    </pip:nativeAttribute>
  </pip:mapping>

Mapping configuration example

note

The attribute allowMultiple is deprecated and does not have any functionality. It remains in the XML configuration for reasons of compatibility.

Search filters​

To search for the value of a target attribute, the Attribute Connector will in most cases need to make use of the value of other attributes from the specific request context. These attributes can be made available either in the request itself or by another search.

These "runtime" values filter the full result set into the specific value of the target attribute. For example, an LDAP search can look for a username in the directory given the "userid" value.

Two steps are required to define a supplement attribute as a desired filter for an LDAP search:

  1. Define the LDAP attribute to be used as a the LDAP filter attribute

  2. Map the defined LDAP attribute to the corresponding source XACML attribute that will have to be made available in the specific request context.

The LDAP filter is specified using the following syntax:

LDAP-attribute=?

For instance in our previous example with username and userid the definition would look like this:

userid=?

Map the defined LDAP attribute to the corresponding source XACML attribute, which will have to be made available in the specific request context.

Dynamic search base​

A dynamic search base is an LDAP search base that can change depending on the value of one or more XACML attributes from the request context or from any configured attribute that can be fetched by means of an Attribute Finder.

A dynamic search base is constructed by inserting one or more question marks (?) in the DN string wherever substitution for an attribute value is needed. As soon as a question mark is entered in the search base string, a corresponding key mapping field is added in the search base key associations table.

An XACML attribute has to be selected for each question mark. Before performing an LDAP search for this attribute, the attribute connector will substitute the question marks for the values of the specified XACML attributes.

If XACML attributes are used in a dynamic search base, the attribute connector will run the query multiple times to cover all combinations of the values in the sets and return a set containing the union of the results (the Cartesian product).

Mapping and conversion of dateTime field formats​

Generally, dateTime fields are stored on an LDAP server using the Generalized Time format. That is also the default format for LDAP attribute connector operations. However, the LDAP attribute connector can also use the XACML dateTime data type (as defined in XMLSchema 1.0).

When an XACML attribute of type dateTime is mapped to an LDAP field of type Generalized Time (see IETF 4517 §3.3.13Opens in a new tab, the LDAP attribute connector is able to convert back and forth between their representations.

  • Generalized Time format representation - 19840730000000.0Z

  • XACML dateTime format representation - 1984-07-30T00:00:00.0Z

This is handled via a toggle feature that controls which format will be used for the mapping and conversion of dateTime fields. The default operation uses Generalized Time as the format. When the toggle is enabled, the XACML format of the dateTime field will be used, which is the way it has been represented up to and including version LDAP AC 6.1.1.

The mapping for dateTime is carried out in both directions, that is, when reading dateTime fields from an LDAP server and when performing queries towards the LDAP server.

This conversion only supports the dateTime data type. It does not support the XACML data types date or time, for which there are no obvious corresponding types in LDAP. This means that for these two XACML types, the LDAP attribute connector will continue to perform a mapping based on the XML Schema textual representations.

Use cases​

When querying LDAP and one of the filter parameters is of XACML dateTime type​

  • If the toggle is disabled: The attribute connector tries to convert the attribute to Generalized Time format.

  • If the toggle is enabled: The attribute connector uses the value provided as is.

When the returning attribute is of XACML dateTime type​

  • If the toggle is disabled: The connector converts the retrieved attribute to Generalized date time format

  • If the toggle is enabled: No conversion takes place. The value is returned as is.

Configuration via a Java system property​

The toggle is configured primarily via a Java system property.

PropertyDescriptionDefault value
com.axiomatics.ldap.use.xacml.datetime.format.toggleThe property controls whether to use Generalized Time or XACML as the format for the dateTime field.
The default value is false (Generalized Time is used).
When the property has the value true, the feature is enabled.		false
Configuration via an environment variable​

An alternative way to configure this feature is via an operating system environment variable called

COM_AXIOMATICS_LDAP_USE_XACML_DATETIME_FORMAT_TOGGLE. It takes the values true and false, with false being the default value.

Important

A Java system property has higher precedence than an OS environment variable.