When a user is successfully authenticated by the Spring authentication manager, OpenEdge creates a sealed CLIENT-PRINCIPAL token that is returned to the ABL application for its own use and for getting access to OpenEdge Database connections. Note that there are a few differences between the way that the generic LDAP authentication manager and the Active Directory authentication manager work to produce the CLIENT-PRINCIPAL token.

About loading additional Active Directory account information into a CLIENT-PRINCIPAL token

The generic LDAP authentication manager loads all defined Active Directory user account attributes as part of its authentication process. Those attributes are not automatically added to the CLIENT-PRINCIPAL token that is generated by PAS for OpenEdge. However, there may be some instances when the LDAP user account attributes are relevant to your ABL application and you can selectively control which attributes to add into the CLIENT-PRINCIPAL token's properties list.

You can specify these additional attributes by using the OEClientPrincipalFilter.loadAccntAttrList property in the configuration of the generic LDAP authentication manager. These attributes correspond to the Definition of the inetOrgPerson LDAP Object Class in RFC 2798, available at https://tools.ietf.org/html/rfc2798. You can specify the following user attributes to this property:

Attribute Description
cn Common name for the object instance
dn Distinguished name
sn Surname
uid User ID
mail Electronic address
employeeNumber Employee identification nummer
title Employee job title
ou Organization name
o An organization within a enterprise
givenName First name (that is, not last or middle name)
displayName User's preferred name (for example, nickname)
homePhone Home telephone
homePostalAddress Home postal address
initials Initials of user's name
mobile Mobile (or cell) phone number
postalAddress Postal address within organization
postalCode Postal code of organization address
roomNumber Offic room number at organization facility
street Street address of organization
telephoneNumber Office telephone number
token_type Type of token

Note the following when specifying the OEClientPrincipalFilter.loadAccntAttrList property:

  • The default value is is an asterisk (*), which causes all attributes to be loaded into the CLIENT-PRINCIPAL token properties.
  • You can specify mutliple attributes as a comma-separated list.
  • You can specify a blank to load no additional account attributes.
  • If a specified attribute is not present in the account object in Active Directory, nothing is loaded into the CLIENT-PRINCIPAL token properties for that attribute.

How the CLIENT-PRINCIPAL token role attribute is used

The CLIENT-PRINCIPAL token's role attribute is used by the PAS for OpenEdge ABL application URL authorization process to control access to APIs.

Support for multiple OpenEdge domains or tenants

Active Directory, like any LDAP server, is not multi-tenant enabled. It is an identity store for a single enterprise. When your ABL application uses a single OpenEdge domain or tenant, you can configure CLIENT-PRINCIPAL properties to use that single domain name and supply its access code in the domain registry file. However, when your ABL application does support multiple OpenEdge domains or multiple tenants, you must perform additional configuration work to make sure that a client cannot spoof access to tenant data to which they are not authorized.

Active Directory user accounts do not have attribute data that identifies the specific tenant of which they are members. However, when you use the generic LDAP authentication manager, you can assert direct control over the specific OpenEdge domain or tenant to which an authenticated user account is assigned or validated against. You can do this by using LDAP group memberships as a means of allowing the Active Directory administrator to control user membership in an OpenEdge domain or tenant. This uses the same principle whereby an LDAP user account is a member of an LDAP group membership and is authorized to access restricted data.

The OpenEdge domain or tenant is a collection of related users who are authorized for access to restricted data. Therefore, by using a domain and LDAP groups, you can accomplish the same type of user grouping for authorization to tenant data. Using LDAP group memberships, you can:

  • Use an LDAP group to designate the OpenEdge domain or tenant to which a simple client-provided user ID (for example, dan) must be assigned before a CLIENT-PRINCIPAL token can be created and sealed.
  • Use an LDAP group to validate that a fully-qualified client-provided user ID (for example, dan@acme.com ) is a member of the acme.com OpenEdge domain or tenant.

PAS for OpenEdge provides the ability to control the mapping of user IDs to domains and assure correct tenant database access. You can do this by using the LDAP user account’s granted group objects, which are mapped to Spring Security ROLE_* roles, to designate the domain in which the user is a member. Using LDAP group objects in Active Directory in this way maintains the secure central administration of enterprise user accounts and allows you to designate the domain name of which each Active Directory user account is a member.

The key to making this work is to create an LDAP group object in Active Directory for each OpenEdge domain. Then each time the Active Directory administrator adds a user account, they must add that account to the LDAP group that represents the OpenEdge domain or tenant of which the account owner is a member. When that user account control process is in place, you can then configure PAS for OpenEdge to assign and validate the user’s tenancy automatically.

To set up LDAP group objects in Active Directory for use and an OpenEdge domain, complete the following steps:

  1. Establish a naming format that allows OpenEdge and your application to easily distinguish between a role used for URL authorization and one that is used as the OpenEdge domain. For example:
    OED_openedge-domain-name

    In this example, OED_ is a prefix that designates that the specified name is related to an OpenEdge domain. The string openedge-domain-name corresponds to the domain name that is configured in the PAS for OpenEdge instance's domain registry as a valid domain name that includes an access code. The prefix you choose does not need to be OED_, but can be anything that the enterprise decides to use. OpenEdge strips this prefix for you before the ABL application receives the CLIENT-PRINCIPAL token that is generated.

  2. Work with the Active Directory administrator to create a LDAP droup for each OpenEdge domain that is configured in your application’s OpenEdge servers. The administrator must use the designated naming format for the group object’s CN (CommonName) subfield of its DN. Then, the administrator must assign a specific OpenEdge domain group object membership for each LDAP user account as they would usually do.
  3. Configure PAS for OpenEdge to recognize the designated naming format for the domain. You do this by using standard regular expression group pattern matching mechanism. Using the example in Step 1, you designate the regular expression group pattern as follows:
    ROLE_OED_(.*)

    In the preceding search pattern:

    • ROLE_ is the Spring Security prefix that is prepended to LDAP group object CN field values to designate it for use in URL authorization.
    • OED_ is the prefix chosen to distinguish the LDAP group that specifically represents an OpenEdge domain.
    • The remaining characters in the pattern represent the OpenEdge omain name that is used in the CLIENT-PRINCIPAL token domain property.

Specify a domain role filter in the authentication manager

When configuring the generic LDAP authentication manager, you can specify the properties listed and described in the following table to obtain OpenEdge domain names from Active Directory and to validate a user's membership in an OpenEdge domain:

Property Description
OEClientPrincipalFilter.domainRoleFilter

This property is provided as a security measure to prevent a user from spoofing their membership in an OpenEdge domain, or for providing a domain name to an unauthorized user.

When using this property, you specify a pattern using the following syntax:

ROLE_domain-identifier(.*)
  • The string domain-identifier represents the unique domain name.
  • The pattern must include the substring (.*), which designates where the domain name characters are located in the role names that are extracted from Active Directory.
  • A unique domain identifier string should be used in the role name to designate that the role name contains OpenEdge domain name information.
  • The default value for this property is "".

When an OpenEdge domain name is missing from the client-provided user ID, this property causes PAS for OpenEdge to derive the user's OpenEdge domain membership from the LDAP user account's role names.

PAS for OpenEdge also uses the specified pattern to validate that the client user ID's domain name corresponds to an LDAP user account's role.
OEClientPrincipalFilter.validateClientDomain This propery validates that the client’s user ID is mapped to a specific OpenEdge domain through role names that are loaded from Active Directory.