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.

CLIENT-PRINCIPAL token expiration

By default, CLIENT-PRINCIPAL tokens have no expiration interval. However, you can set the LOGIN-EXPIRATION -TIMESTAMP attribute to specify when a CLIENT-PRINCIPAL token expires. When a CLIENT-PRINCIPAL token expires, the token can no longer represent a user identity, and any started login session for the object ends. Note that OpenEdge evaluates the value of this attribute only at the times when OpenEdge either attempts to seal or validate the object.

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. This implementation follows the standard inetOrgPerson LDAP object class as defined in RFC2798; consult the applicable RFCs for details about the underlying schema. 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 number
title Employee job title
ou Organization name
o An organization within an enterprise
givenName Employee's first name
displayName Employee's preferred name (nickname)
homePhone Home telephone number
homePostalAddress Home postal address
initials Employee's initials
mobile Mobile phone number
postalAddress Organization's postal address
postalCode Organization's postal code
roomNumber Office number at the organization's facility
street Organization's street address
telephoneNumber Office telephone number
token_type Type of token

Note the following when you specify the OEClientPrincipalFilter.loadAccntAttrList property:

  • The default value 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, then 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 ensure 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 way to allow 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 to access restricted data. Therefore, by using a domain and LDAP groups, you can accomplish the same type of user grouping for authorization to tenant data. With 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.
  • 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 ensure 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:

  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_. It 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 an LDAP group 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 common name (CN) 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 a standard, regular-expression, group-pattern-matching mechanism. Using the example in Step 1, you designate the regular expression group pattern:
    ROLE_OED_(.*)

    In the preceding search pattern:

    • ROLE_ is the Spring Security prefix that is prefixed 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 domain name that is used in the CLIENT-PRINCIPAL token domain property.

Specify a domain role filter in the authentication manager

The primary use case for the domain role filter is to support multi-tenancy in OpenEdge. If you deploy a multi-tenant ABL application or configure a multi-tenant database, note that Windows itself is not multi-tenant; however, role name mapping can be used to support multi-tenancy. When you configure 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 to provide a domain name to an unauthorized user.

When you use 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 property validates that the client’s user ID is mapped to a specific OpenEdge domain through role names that are loaded from Active Directory.