3. Using LDAP and VAM

Introduction

The VMS Authentication Module (VAM) provides users of OpenVMS systems controlled access to both user-written applications and the OpenVMS system overall using LDAP. It can be incorporated into an OpenVMS-based platform in three ways:

· Via an API that the user incorporates into a specific application to control access to that application. The VAM API is described in detail in chapter 7, Using the VAM API.

· On a system-wide basis via use of the LGI callouts for OpenVMS LOGINOUT.EXE.

· On a system-wide basis via the use of a VAM agent for the OpenVMS ACME system on OpenVMS V8.3 and higher. See Chapter 6, Using VAM with ACME for details on configuring your system to use VAM with ACME.

SSH logins are not affected by the VAM LGI callouts.

The system console (OPA0:) is never required to use the LDAP LGI Callout interface, in order to prevent being locked-out of the system in the event of a network failure that prevents the VMS system from talking with the LDAP server system(s).

Note: This chapter assumes the user is familiar with LDAP in general; of the specifics of the user’s LDAP installation; and if using TLS/SSL, of certificates and how to obtain and use them. Due to the breadth and depth of the topics above, this chapter will not attempt to present a tutorial on those topics.

Post-Installation Steps

The following sections describe the post-installation setup required to enable the various forms of authentication.

VAM uses configuration keywords, set in the VAM:VAM_CONFIG.DAT file, to determine the location of the LDAP server, the filter to be used for lookups, etc. In this way, it presents the maximum flexibility for integration into the user’s existing LDAP environment. The VAM LDAP support must be configured for all three modes of operation (callable module, LGI callout and ACME).

The VAM LDAP LGI Callouts

VAM may be incorporated into the OpenVMS login mechanism to control access to the entire system. VAM provides an OpenVMS shareable image, which the system manager can incorporate, using supported OpenVMS mechanisms, into the OpenVMS LOGINOUT mechanism. This image uses the LDAP protocols to supplement the standard OpenVMS login processing and provides the necessary user authentication to access the system as part of the login process.

This section assumes the user has basic knowledge of how LDAP directories are constructed and work.

Sample VAM LDAP Login

The following example shows a login to a system. It assumes the configuration keyword LDAP_PW_PROMPT has been set to “LDAP Password: “:

$ SET HOST BOSTON1

Welcome to OpenVMS (TM) IA64 Operating System, Version V8.4

Username: johndoe

LDAP Password: ********

Welcome to OpenVMS IA64 V8.4

Last interactive login on Monday, 23-JAN-2022 12:04:50.21

Last non-interactive login on Friday, 2-DEC-2022 07:33:34.74

You have 1 new Mail message.

BOSTON1_$

Controlling Access to the Callout

The system manager configures the system to use the LGI callouts. This may be done in two ways:

· Define the configuration keyword REQUIRE_LDAP. If set, all users are required to use LDAP authentication.

· Add the rights identifier VAM_LGI_LDAP to the system rights database. This identifier may then be granted to those users who will be required to use LDAP authentication.

VAM LDAP Configuration Keywords

Access to LDAP via VAM requires setting several configuration options in the configuration file VAM:VAM_CONFIG.DAT. This section describes those keywords and their usage.

LDAP_CERT

This configuration item is used when performing encrypted LDAP sessions. It is set to the file name of the PEM-formatted base64 (x.509) certificate containing the root certification chain for the trusted certification authority (CA) that will be used to establish the bonafides of the VAM system.

ALLOW_DECNET_LOGIN

If set to a non-zero value, DECnet CTERM (RTAnn:) devices are required to log in using LDAP.

ALLOW_DECTERM_LOGIN

If set to a non-zero value, DECterm (FTAnn:) devices are required to log in using LDAP.

LDAP_ALLOW_NULL_PASSWORD

If set to one, this keyword allows the use of blank passwords when prompting for the LDAP password.

LDAP_NOPASSWORD_SYNC

If set to 1, this will prevent VAM from updating the user's password and password change data in the VMS UAF file after a successful LDAP login. By default, VAM synchronizes this information in the UAF file to ensure that LDAP and VMS passwords are kept in sync.

LDAP_PW_PROMPT

If set, this keyword defines the prompt to use when prompting for the LDAP password, if the default of "Password: " isn't desired.

LDAP_TIMELIMIT

This configuration item sets the maximum length of time an LDAP search will be allowed to take. The value is in seconds. If not specified, the default is 5 seconds.

LDAP_DEBUG
This keyword defines the debug level to use for the LDAP transactions. This can result in large amounts of debug information being sent to the log file, and should not normally be used or needed.

LDAP_COMMON_USERNAME

Defines the common username for a “many-to-one” mapping of LDAP usernames to a single VMS username. This is applicable to LGI callout sessions only.

Configuring VAM LDAP Server Search Criteria

VAM provides the ability to perform multiple searches on multiple LDAP servers. This is provided through the use of stanzas, which consist of an LDAP_SERVER section which describes a specific server (e.g., the server name and port), followed by one or more LDAP_SEARCH sections that describe the individual searches to be performed on that server.

Specifying Servers Using the LDAP_SERVER Keywords

The following configuration keywords are used to configure access to an LDAP server. These keywords are set in the file VAM:VAM_CONFIG.DAT.

LDAP_SERVER URI

This is the fully-qualified domain name of the LDAP server to be used in Uniform Resource Locator (URI) format. If prefaced by ldap, the URI indicates an unencrypted session will be done via port 389. If prefaced by ldaps, the URI indicates an encrypted session will be done via port 636. The port may also be explicitly specified in the URI.

For example:

ldap_server ldaps://ldap.example.com:636/

Defines a server called ldap.example.com. Port 636 will be used to communicate to the server, and the session will be encrypted.

LDAP_USE_TLS

If your LDAP server supports LDAPS (LDAP-over-TLS), setting the value of this keyword to 1 will instruct VAM to attempt to use LDAPS for user authentication. If an LDAPS connection cannot be established, a standard LDAP connection will be used to authenticate the user.

Setting the value of this keyword to 2 will force an LDAPS connection. If an LDAPS connection cannot be established, the user will receive an error and will not be able to log in.

The value may never be used when using the LDAPS form of the URI for a server to specify that the session should be encrypted.

Specifying Searches Using the LDAP_SEARCH Keywords

The following configuration keywords are used to configure searches on an LDAP server within the configuration stanza for that server. These keywords are set in the file VAM:VAM_CONFIG.DAT.

LDAP_AUTH_FILTER

Specifies the LDAP search filter used to find the directory entry for a user who is authenticating to the web user interface.

Both LDAP_BASE_DN and LDAP_AUTH_FILTER allow the following expansion tags to be used in their values:

Tag	Description
%u	The user’s login name
%d	The user’s login domain

For example, a site might set the values of LDAP_BASE_DN and LDAP_AUTH_FILTER as:

ldap_base_dn o=%d

ldap_auth_filter (&(objectclass=person)(uid=%u))

If a user logged in as bob@example.com, the values of these configuration variables would be expanded to:

ldap_base_dn: o=example.com

ldap_auth_filter: (&(objectclass=person)(uid=bob))

LDAP_AUTH_SERVER

Specifies the name of the LDAP host to search for authentication information. There is no default value.

LDAP_BASE_DN

Specifies the entry in the LDAP directory under which searches occur (sometimes also known as the search base). Consult your LDAP server's documentation set for more information specific to your implementation.

LDAP_BASE_DN supports the same tag expansions as LDAP_AUTH_FILTER.

LDAP_SEARCHACCT_DN

VAM must query the LDAP server to find the Distinguished Name of the user attempting to log in before the user can be authenticated. By default, this initial query will be done anonymously. Some directory servers (notably Microsoft's Active Directory) do not allow anonymous queries.

LDAP_SEARCHACCT_DN

Specifies the Distinguished Name of a user with search privileges on the directory server that VAM will connect as. By default, the value is NULL which indicates an anonymous login.

LDAP_SEARCHACCT_PASSWORD

Specifies the password for the search user whose Distinguished Name is specified in. LDAP_SEARCHACCT_DN. By default, the value is NULL which indicates an anonymous login.

Fetching User Attributes

VAM provides the ability to fetch a list of named attributes for a user that are stored in an LDAP directory. The search for attributes is performed on the same server on which the user has been successfully authenticated.

The form of the attribute information returned depends on the VAM interface being used. When using the VMS LOGINOUT callouts, the information will be returned as a series of logical names created in the process’s job logical name table. The form of each logical name is “VAM_ATTR_attribute_name”; for example, VAM_ATTR_logonCount would hold the logonCount attribute that was fetched for a user.

When using the VAM API, the user specifies the UserAttributes argument to the VMSAuthenticate call. This is pointer to a struct attr structure pointer. A linked list of attributes and their values is returned in the UserAttributes argument. This structure is described in the description of the VMSAuthenticate call in Chapter 7.

To configure VAM to fetch attributes, the following keywords are used in the VAM_CONFIG.DAT file:

LDAP_ATTRIBUTE

Specifies an attribute to fetch. Each LDAP_ATTRIBUTE line is of the form “attribute_name,attribute_type”. Multiple attribute lines are permitted.

The attribute_name is case-sensitive, and must be the same case as the attribute as stored in the LDAP directory.

Permitted values for attribute_type are:

· ATTRIBUTE_STRING for values that are stored in the LDAP directory as character strings. The value is returned as a null-terminated string.

· ATTRIBUTE_BINARY for values that are stored in the LDAP directory as binary values. The value is returned as a decimal number represented by a null-terminated string.

For example:

ldap_attribute MyNamedAttribute,attribute_string

will cause the character string attribute MyNamedAttribute to be fetched.

LDAP_ATTRIBUTE_BASE_DN

Specifies the entry in the LDAP directory under which the search for the LDAP attributes occurs (sometimes also known as the search base). Consult your LDAP server's documentation set for more information specific to your implementation.

LDAP_ATTRIBUTE_BASE_DN supports the same tag expansions as LDAP_BASE_DN.

LDAP_ATTRIBUTE_FILTER

Specifies the LDAP search filter used to find the attribute entry for a user who is authenticating to the web user interface.

LDAP_ATTRIBUTE_BASE_DN supports the same tag expansions as LDAP_AUTH_FILTER.

Using TLS/SSL with VAM

TLS/SSL may be used to provide secure message transfer between VAM and the LDAP server. This is recommended as LDAP transactions by default are unencrypted and may contain clear-text username/password tuples. Thus, failure to use TLS/SSL can open a network security hole.

To enable TLS/SSL support:

· The trusted root certificate chain for the CA used to sign the LDAP server’s certificate must be obtained. This certificate must be a PEM-formatted base64 (X.509) file.

· The VAM_CONFIG.DAT file must be edited to set the LDAP_CERT keyword. This keyword must point to the filename of the trusted root certificate chain.

· Ensure the server URI(s) correctly use ldaps in the URI

Note that the ldapsearch and openssl utilities (supplied in the VAM distribution) may be used to help verify the certificate chain and search criteria.

Sample LDAP Configuration

The following is an excerpt from a VAM:VAM_CONFIG.DAT file that illustrate a sample VAM LDAP configuration.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

! LDAP Configuration Keywords

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

! If the next keyword is defined, then all users will be required

! to use LDAP authentication when using the LGI$ callouts.

! This will override the checks for the LGI_LDAP

! rights identifier to determine who is required to use LDAP.

REQUIRE_LDAP 1

! The next keyword, if set to 1, will prevent VAM from updating the

! user's password and password change data in the VMS UAF file after a

! successful LDAP login.

LDAP_NOPASSWORD_SYNC 0

! Set the max time limit (in seconds) for LDAP searches. Defaults

! to 5 seconds if not defined.

! The next keyword defines the prompt to use when prompting for the

! LDAP password, if the default of "Password: " isn't desired.

LDAP_PW_PROMPT "LDAP Password:

! The next keyword is used to define the VMS username to which

! LDAP usenames will map upon successful authentication,

! providing a "many-to-one" external username to VMS username

! mapping.

!LDAP_COMMON_USERNAME johndoe"

! If set to one, the next keyword allows the use of blank passwords

! when prompting for the LDAP password.

LDAP_ALLOW_NULL_PASSWORD 0

LDAP_TIMELIMIT 10

! Define the name of the PEM-formatted base64 file containing the

! root certificate chain for the trusted CA for LDAP sessions

LDAP_CERT MYSYS$DKA100:[CERTS]CA_ROOT_CERTS.PEM

! Define keywords for LDAP attributes to be fetched. Note that

! these are case-sensitive.

LDAP_ATTRIBUTE logonCount,attribute_binary

LDAP_ATTRIBUTE cn,attribute_string

! Define the search criteria for searching for attributes.

LDAP_ATTRIBUTE_BASE_DN "CN=Users,dc=example,dc=com"

LDAP_ATTRIBUTE_FILTER "(&(objectclass=userAttrs)(sAMAccountName=%u))"

! The next keywords define the parameters for performing LDAP

! authentication, for both the LGI interface and the programmatic

! interface. They should be set to values appropriate to your location.

! Multiple servers may be specified. Each server section starts with

! an "LDAP_SERVER" label, and within each server section, searches specific

! to that server are then defined in LDAP_SEARCH sections.

! Note that the port portion of the URI is optional. If not specified,

! the port will defined to 389 for ldap and 636 for ldaps.

LDAP_SERVER ldap://ldap.example.com

LDAP_SEARCH