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 two 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 6, "Using the VAM API".
• On a system-wide basis via use of the LGI callouts for OpenVMS LOGINOUT.EXE.
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.
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 both the callable module and LOGINOUT callout support.
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.
The following example shows a login to a system:
$ SET HOST VOODOO
Welcome to OpenVMS (TM) IA64 Operating System, Version V8.2-1
Username: johndoe
Password:
Welcome to OpenVMS IA64 V8.2-1
Last interactive login on Monday, 23-JAN-2006 12:04:50.21
Last non-interactive login on Friday, 2-DEC-2005 07:33:34.74
You have 1 new Mail message.
VOODOO_$
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.
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 PKCS7 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, determines DECnet CTERM (RTAnn:) devices are required log in using LDAP
ALLOW_DECTERM_LOGIN
If set to a non-zero value, determines that DECterm (FTAnn:) devices are required log in using LDAP
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_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.
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 nodename and port), followed by one or more LDAP_SEARCH sections that describe the individual searches to be performed on that server.
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 <servername URI>
This is the fully-qualified domain name of the LDAP server to be used in Uniform Resource Locator (URI) format. If prefeaced 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 explicily specified in the URI.
For example:
ldap_server ldaps://my.ldap.server.org:636/
Defines a server called my.ldap.server.org. 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.
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
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 jdoe@example.com, the values of these configuration variables would be expanded to:
ldap_base_dn: o=example.com
ldap_auth_filter: (&(objectclass=person)(uid=jdoe))
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.
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 will "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 ia 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 description of the VMSAuthenticate call in chapter 6.
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:
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 certifcate must be obtained. This certificate must be a PEM-formatted PKCS7 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..
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.
!
LDAP_TIMELIMIT 10
!
! Define the name of the PEM-formatted PKCS7 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=limabeansdomain,dc=beans,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://LIMA.BEANS.COM
LDAP_SEARCH
LDAP_AUTH_FILTER "(&(objectclass=user)(sAMAccountName=%u))"
LDAP_BASE_DN "CN=Users,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_DN "cn=Admin,CN=Users,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_PASSWORD "secretpassword"
LDAP_SEARCH
LDAP_AUTH_FILTER "(&(objectclass=user)(sAMAccountName=%u))"
LDAP_BASE_DN "CN=OtherUsers,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_DN "cn=Mgr,CN=Users,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_PASSWORD "secretpassword"
LDAP_SEARCH
LDAP_AUTH_FILTER "(&(objectclass=user)(sAMAccountName=%u))"
LDAP_BASE_DN "CN=MoreUsers,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_DN "cn=JohnDoe,CN=Users,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_PASSWORD "secretpassword"
!
LDAP_SERVER LDAPS://PINTO.BEANS.COM
LDAP_SEARCH
LDAP_AUTH_FILTER "(&(objectclass=user)(sAMAccountName=%u))"
LDAP_BASE_DN "CN=Users,dc=domain,dc=beans,dc=com"
LDAP_SEARCHACCT_DN "cn=Admin,CN=Users,dc=pdomain,dc=beans,dc=com"
LDAP_SEARCHACCT_PASSWORD "secretpassword"
LDAP_SEARCH
LDAP_AUTH_FILTER "(&(objectclass=user)(sAMAccountName=%u))"
LDAP_BASE_DN "CN=MoreUsers,dc=pdomain,dc=beans,dc=com"
LDAP_SEARCHACCT_DN "cn=SYSMAN,CN=Users,dc=pdomain,dc=beans,dc=com"
LDAP_SEARCHACCT_PASSWORD "secretpassword"
LDAP_SEARCH
LDAP_AUTH_FILTER "(&(objectclass=user)(sAMAccountName=%u))"
LDAP_BASE_DN "CN=MoreUsers,dc=pdomain,dc=beans,dc=com"
LDAP_SEARCHACCT_DN "cn=SYSMAN,CN=Users,dc=pdomain,dc=beans,dc=com"
LDAP_SEARCHACCT_PASSWORD "secretpassword"
The following unsupported tools, provided in the OpenLDAP distribution, are supplied in the VAM directory. These tools are supplied as a convenience to the user and are not supported by Process Software.
Documentation for these tools may be found at http://www.openldap.org. The supplied tools include:
openssl
