April 19, 2023

Using LDAP Authentication in Apache 2.2

Brad NicholesSr. Software Engineer, Novell Inc.Member, Apache Software Foundationbnicholes@apache.org

© Novell Inc, 2006

2

Agenda

• Introduction and Status• Mod_Authnz_LDAP (Authentication)

• Directives• LDAP URL & Search Filters

• Mod_Authnz_LDAP (Authorization)• Directives• Authorization: not just a “valid-user”

• Using Mod_Authnz_LDAP with other Authn/Authz Modules

• Mod_LDAP (aka. Util_LDAP)• Directives• Enabling SSL/TLS Support• Connection and Credential Caching• LDAP Cache Monitor

© Novell Inc, 2006

3

What is Mod_Authnz_LDAP

• Authentication module that allows Apache to authenticate a user against an LDAP compliant directory

• Allows for complex authentication and authorization policies rather than just user ID and password

• Can be used to extract additional LDAP object attributes that can be referenced by downstream CGI modules or scripts

• Built on top of Mod_LDAP and APR-Util LDAP APIs• Handles all LDAP client/server communication• Maintains an LDAP connection pool• Allows and manages monitoring of the various credential caches

© Novell Inc, 2006

4

Status – Mod_Authnz_LDAP Apache 2.2

• Moved out of experimental status• Re-architected to fit into the new

authentication module structure• New authorization directives• Supports SSL, StartTLS and Client

Certificates • Supports OpenLDAP, Novell LDAP,

iPlant(Netscape) LDAP, Microsoft LDAP SDK’s

© Novell Inc, 2006

5

New “Authnz” Architecture

Terms / Authnz Elements:• Authentication Type – Type of protocol used during

transport of the authentication credentials (Basic or Digest)

• Authentication Method/Provider - Process by which a user is verified to be who they say they are

• Authorization - Process by which authenticated users are granted or denied access based on specific criteria

Previous to Apache 2.2, every authentication module had to implement all three elements

• Choosing an AuthType limited which authentication and authorization methods could be used

• Potential for inconsistencies across authentication modules

© Novell Inc, 2006

6

“Authnz” Architecture Differences Apache 2.0 -> 2.2

• The functionality of each Apache 2.0 authentication module has been split out into the three Authnz elements for Apache 2.2

• Overlapping functionality among the modules was simply eliminated in favor of a base implementation

• The module name indicates which element of the Authnz functionality it performs

• Mod_auth_xxx – Implements an Authentication Type• Mod_authn_xxx – Implements an Authentication Method or

Provider• Mod_authz_xxx – Implements an Authorization Method

© Novell Inc, 2006

7

What Are The Advantages?

Flexibility: • Ability to choose between Authentication Type vs. Authentication Method

vs. Authorization Method• Ability to use multiple different authorization methods• Mixing and matching is not a problem

Consistency: • Authorization methods are guaranteed to work the same no matter which

authentication method is chosen• Ability to use the same authentication and authorization methods for all

authentication types

Reuse: • Implementing a new authentication provider module does not require the

reimplementation or duplication of existing authorization methods • The inverse of the above statement is also true• Ability to create your own custom authentication providers and reuse them

throughout your configuration

© Novell Inc, 2006

8

Why a Single Mod_Authnz_LDAP Module?

• Too many shared resources• Connection pools• Various credential caches• Overlapping configuration directives• Internal data structures

• Would not recommend combining Authn & Authz functionality into a single auth module

• Problems occur when Authn is used without the corresponding Authz (Vice-Versa)

© Novell Inc, 2006

9

Directives – Mod_Authnz_LDAP Authentication

AuthLDAPBindDNOptional DN to use when binding to the LDAP server

AuthLDAPDereferenceAliasesSpecifies when the module will de-reference aliases

AuthLDAPBindPasswordPassword used in conjunction with the bind DN

AuthLDAPRemoteUserIsDNUse the DN of the user name to set the REMOTE_USER environment variable

AuthLDAPCharsetConfigLanguage to charset conversion file

AuthLDAPUrlURL specifying the LDAP search parameters

© Novell Inc, 2006

10

Directives – Mod_Authnz_LDAP Authorization

AuthLDAPCompareDNOnServerUse the LDAP server to compare the DNs

Require ldap-userSpecifies which users have access to the resource

AuthLDAPGroupAttributeSpecifies which LDAP attributes will be used to check for group membership

Require ldap-groupSpecifies the LDAP group whose members are allowed access to the resource

AuthLDAPGroupAttributeIsDNUse the DN of the user name when checking for group membership

Require ldap-dnGrants access based on a fully distinguished user name

AuthzLDAPAuthoritativePrevent other authz modules from authenticating the user

Require ldap-attributeGrants access based on the attributes of the authenticated user

Require ldap-filterGrants access based on an LDAP search filter

© Novell Inc, 2006

11

Required Modules

LoadModule auth_basic_module modules/mod_auth_basic.soLoadModule authz_user_module modules/mod_authz_user.soLoadModule authnz_ldap_module modules/mod_authnz_ldap.soLoadModule ldap_module modules/mod_ldap.so

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory>

Modules that provide each element of

authentication and authorization must

be loaded

© Novell Inc, 2006

12

Directive Usage

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory>

Specify which authentication provider(s) are enabled for this

directory or location

© Novell Inc, 2006

13

Directive Usage

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory>

Connect to the specified LDAP

server and search within the context

© Novell Inc, 2006

14

Directive Usage

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldap://ldap-server/o=ctx?cn?sub AuthzLDAPAuthoritative OFF require valid-user</Directory> Search for the user

based on the specified attribute

and through all sub-contexts

© Novell Inc, 2006

15

Directive Usage

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory> Authoritative must be

set to “OFF” if the required

authorization is something other than

the ldap-xxx types

© Novell Inc, 2006

16

Directive Usage

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPBindDN cn=ldapuser,o=ctx AuthLDAPBindPassword mY_SecrEt AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative ON require ldap-attribute dept=sales</Directory>

Bind to the LDAP server for all

operations using a specific user ID and

password

© Novell Inc, 2006

17

LDAP URL

• The LDAP Url syntax is defined by RFC 2255• The Url format is: scheme://host:port/basedn?

attributes?scope?filter• Scheme – “ldap://” for regular or unsecured ldap connections or

“ldaps://” for secured connections• Host:port – name/port of the ldap server. Multiple hosts can be

specified (port defaults 389 for ldap:// or 636 for ldaps://)• Basedn – base DN of the branch of the directory where the

searches should begin• Attributes – attribute to search for. If multiple attributes are listed,

separated by a comma, only the first will be used (default “uid”)• Scope – can be either “one” or “sub” meaning search within a

single context or search all sub contexts (default “sub”)• Filter – LDAP search filter (default “objectClass=*”)

© Novell Inc, 2006

18

LDAP URL Examples

• Allow access to anyone who exists in the LDAP directory

ldap://ldap1.airius.com/ou=People,o=Airius

• Note: above example assumes defaults– Port: 389– Attribute: uid– Scope: sub– Filter: (objectClass=*)

• Use redundant LDAP servers

“ldap://ldap1.airius.com ldap2.airius.com/ou=People,o=Airius”

• Note: Since the host names are separated by a space, this Url must be surrounded by double-quotes when used in the AuthLDAPUrl directive

© Novell Inc, 2006

19

LDAP URL Examples

• Allow access to all users whose sn attribute does not start with “jo”

ldap://ldap.airius.com/ou=People,o=Airius?cn?sub?(!(sn=jo*))

• Note: The search is based on cn rather than the default uid attribute

• Extract additional attributes from the authenticated user object

ldap://ldap.airius.com/ou=People,o=Airius?cn,sn,email,phone

• Note: The value of each attribute will be added to the environment as AUTHENTICATE_<ATTR-NAME>

• Note: the listed attributes might not be public. The directives AuthLDAPBindDN and AuthLDAPBindPassword may be necessary to allow Mod_Authnz_LDAP access to the LDAP attributes

© Novell Inc, 2006

20

LDAP Filter

• Defines which entries within a scope to retrieve and send back to the requesting application

• Search filter is written as an ABNF formatted string• Search filter syntax is described in RFC 2254• The default filter if none is specified in the LDAP URL

is (objectClass=*)• Filter grammar operators include

= (Equality and presence matching)<= or >= (Less-than or Greater-than matching)~= (Approximate matching)&, |, ! (Boolean operators)

© Novell Inc, 2006

21

LDAP Filter Examples

• (objectClass=*)Allow all objects to be searched

• (&(objectClass=inetOrgPerson)(telephoneNumber=*))Return all inetOrgPerson objects which have a telephoneNumber attribute

• (&(cn=mary*)(!(sn=jones)))Find all objects whose cn attribute begins with the value “mary” except for those objects whose sn attribute is equal to “jones”

© Novell Inc, 2006

22

Extended Character Set Support

• Allows a user name containing extended characters to be properly converted and authenticated

• AuthLDAPCharsetConfig provides a conversion table that maps from the character set used by the browser to “utf-8” supported by the LDAP directory• AuthLDAPCharsetConfig conf/charset.conv

• Requires the APR-iconv library

© Novell Inc, 2006

23

Extended Character Set Support

Maps the “Accept-Language” value to a character set

# Lang-abbv Charset Language #-------------------------------------en ISO-8859-1 Englishth Cp874 ThaiJa SJIS JapaneseKo Cp949 KoreanZh Cp950 Chinese-Traditionalzh-cn GB2312 Chinese-Simplifiedzh-tw Cp950 ChineseCs ISO-8859-2 CzechHu ISO-8859-2 HungarianHr ISO-8859-2 Croation

© Novell Inc, 2006

24

LDAP Alias Objects

• AuthLDAPDereferenceAliases defines when and how aliases are dereferenced

• There are 4 different dereference values:• Never - aliases are not dereferenced• Searching - aliases are dereferenced during the search but not

when locating the base object of the search• Finding - aliases are dereferenced when locating the base object

but not during the search• Always - aliases are dereferenced during the search and while

locating the base object (default)

• Some LDAP directories may require that “Alias Dereferencing” be enabled on the server

© Novell Inc, 2006

25

AuthLDAPDereferenceAliases

<Directory sys:/webpages/secure2> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPBindDN cn=ldapuser,o=ctx AuthLDAPBindPassword mY_SecrEt AuthLDAPDereferenceAliases finding AuthLDAPURL ldap://192.168.0.50/o=dev?cn AuthzLDAPAuthoritative OFF require valid-user</Directory>

Dereference only when

finding the base object

Search using the “cn”

attribute since alias objects don’t have a

“uid”

© Novell Inc, 2006

26

Authorization: Not Just a “Valid-User”

• The “Require” directive can be used to grant authorization in several different ways

• Valid-user – authorizes any user with valid LDAP credentials (*mod_authz_user module must be loaded)

• ldap-user – specifies which users names are allowed access by performing an LDAP compare operation

• ldap-group – specifies an LDAP group whose members are allowed access

• ldap-dn – allows access based on fully distinguished names• ldap-attribute – Grants access based on the attributes of

the authenticated user• ldap-filter - Grants access based on an LDAP search filter

© Novell Inc, 2006

27

Authorization: Require ldap-user

• Require ldap-user – Allows multiple users• Specify multiple users by listing each user name separated

by a space• If the user name contains a space then it must be enclosed

by double-quotes and the directive can not list more than one

• Multiple users can be specified through multiple “Require ldap-user” directives

© Novell Inc, 2006

28

Authorization: Require ldap-group

• Require ldap-group – use a fully distinguished name

• Do not surround the group name with quotes• Behavior of this directive can be modified with:

– AuthLDAPGroupAttribute– Specifies additional attributes used to check for group membership

– Default attributes are “member” and “uniqueMember”

– AuthLDAPGroupAttributeIsDN– If set to “ON” then use the fully distinguished name of the user when checking

membership

– Default is “ON”

© Novell Inc, 2006

29

Authorization: Require ldap-dn

• Require ldap-dn – use a fully distinguished user name

• Compares the distinguished name retrieved from the LDAP directory against the specified name

• The behavior of this directive can be modified with– AuthLDAPCompareDNOnServer

– If set to “ON” then mod_authnz_LDAP will search the directory for the specified DN and then compare it with the user DN retrieved during the authentication phase

– Otherwise mod_authnz_LDAP does a simple string comparison

© Novell Inc, 2006

30

Authorization: Require ldap-attribute

• Require ldap-attribute – grant access if the user object contains a matching attribute value

• Compares the attributes of the authenticated user with the listed attribute values

• If the value of a matching attribute contained by the user object is equal to the specified value then access is granted

• If multiple attributes are listed, access is granted if any one of the values matches a specified attribute value. (ie. This is an ‘OR’ operation)

• If a specified attribute value contains a space, the value must be enclosed in double-quotes (“ “)

© Novell Inc, 2006

31

Authorization: Require ldap-filter

• Require ldap-filter – access is granted based on an ldap filtered search

• Same syntax used by the filter portion of the AuthLDAPUrl directive

• If the user object returned by the filtered search matches the authentcated user then access is granted

© Novell Inc, 2006

32

Using Multiple Authentication Providers

LoadModule auth_basic_module modules/mod_auth_basic.soLoadModule authn_file_module modules/mod_authn_file.soLoadModule authz_user_module modules/mod_authz_user.soLoadModule authnz_ldap_module modules/mod_authnz_ldap.soLoadModule ldap_module modules/mod_ldap.so

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider file ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory> Use both file and

ldap authentication, checking each in

the order that they are listed

© Novell Inc, 2006

33

Mixing Different Types of Authentication With Authorization

LoadModule auth_basic_module modules/mod_auth_basic.soLoadModule authn_file_module modules/mod_authn_file.soLoadModule authz_user_module modules/mod_authz_user.soLoadModule authnz_ldap_module modules/mod_authnz_ldap.soLoadModule ldap_module modules/mod_ldap.so LoadModule authz_groupfile_module modules/mod_authz_groupfile.soLoadModule authnz_owner_module modules/mod_authz_owner.so

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider file ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF AuthGroupFile /www/users/group.dat require file-group</Directory>

Use both file and ldap authentication

but only grant access if the

authenticated user is a member of the

same group to which the

requested file belongs

© Novell Inc, 2006

34

What is Mod_LDAP (aka. Util_LDAP)

• Provides common services for LDAP based modules

• Enhances the performance of LDAP connections and operations

• Provides LDAP connection pooling• Provides LDAP credential and operations

caching• Supports SSL connections between the web

server and the LDAP server• Dependant on LDAP support through apr-util

© Novell Inc, 2006

35

Directives – Mod_LDAP

LDAPCacheEntriesMaximum number of entries allowed in the primary LDAP cache

LDAPSharedCacheFileSpecifies the shared memory cache file

LDAPCacheTTLMaximum time that cached items remain valid

LDAPSharedCacheSizeSize in bytes of the shared-memory cache

LDAPConnectionTimeoutSpecifies the LDAP socket connection timeout in seconds

LDAPTrustedClientCertSets the file containing a per connection client certificate

LDAPOpCacheEntriesMaximum number of entries allowed in the LDAP compare operations cache

LDAPTrustedGlobalCertSets the file containing the global trusted certificate authority or global client certificate

LDAPOpCacheTTLMaximum time that cached entries in the operations cache remain valid

LDAPTrustedModeSpecifies the SSL/TLS mode to be used when connecting to an LDAP server

LDAPVerifyServerCertForce server certificate verification

© Novell Inc, 2006

36

Enabling SSL / TLS

• The ability to establish an SSL connection to the LDAP server is supported by OpenLDAP, Novell LDAP, Microsoft and iPlanet SDK’s

• Each LDAP SDK implements the SSL connection APIs differently

• OpenLDAP– Only supports BASE64 type certificates

• Novell LDAP– Support BASE64 and DER type certificates

• iPlanet– Only supports CERT7_DB type certificates– LDAPTrustedGlobalCert must specify a cert7_db file

• Microsoft – Uses the registry certificate store and is always assumed to be available

© Novell Inc, 2006

37

Enabling SSL

LDAPTrustedGlobalCert CA_BASE64 /etc/certs/ldapcert.pemLDAPVerifyServerCert ON

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldaps://ldap-server:636/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory>

Specify “ldaps://” rather than “ldap://” to

establish an SSL connection

Can also specify the port along

with the host

© Novell Inc, 2006

38

Enabling TLS

LDAPTrustedGlobalCert CA_BASE64 /etc/certs/ldapcert.pemLDAPVerifyServerCert ONLDAPTrustedMode STARTTLS

<Directory /www/docs> AuthType Basic AuthName Secure_Alias_Test AuthBasicProvider ldap AuthLDAPURL ldap://ldap-server/o=ctx AuthzLDAPAuthoritative OFF require valid-user</Directory>

Indicate that the LDAP connections should upgrade to

a secure connections

Specify “ldap://” to initiate the connection on port 389. If “ldaps”

is used, the trusted mode will be SSL on

port 636.

© Novell Inc, 2006

39

LDAP Connection Pools

• Connections to the LDAP server are pooled from request to request

• This prevents util_ldap from having to bind-rebind/perform operation/unbind on each request

• Performance advantages are similar to HTTP keepalives

• When multiple requests are made simultaneously to the LDAP server, util_ldap will create and pool additional connections

• If a pooled connection goes bad, util_ldap will clean it up automatically but does not remove the connection data from the pool

• Connection pooling is always enabled

© Novell Inc, 2006

40

LDAP Credential and Operation Caching

• One credential cache and two types of operation caches are maintained for each LDAP URL specified in the configuration

• If the platform supports shared memory, these caches will be shared across application processes

• The shared memory caches can be disabled by setting LDAPSharedCacheSize 0

© Novell Inc, 2006

41

LDAP Credential Cache

• Caches the user name, full DN, password and the amount of time the entry has been cached

• If the user name and password match and the entry has not expired, the search/bind phase is by-passed

• Failed binds are not cached• The behavior of the credential cache can be

modified by:• LDAPCacheEntries – number of entries allowed in the cache• LDAPCacheTTL – amount of time an entry is cached (default 600

seconds)

© Novell Inc, 2006

42

LDAP Operation Caching

• Util_ldap maintains a group membership cache and a DN comparison cache

• The behavior of the two caches can be modified by:

• LDAPOpCacheEntries – number of entries allowed in the cache

• LDAPOpCacheTTL – amount of time an entry is cached (default 600 seconds)

© Novell Inc, 2006

43

Operations Cache Node Layout

Cache-Node int (*compare)() void*(*copy)() void (*free)() void (*display)() ulong (*hash)()

Cache-Node

URL-Node char *URL

Cache-Node

Cache-Node

Cache-Node

Cache-Node

Cache-Node

Cache-Node

Search-Node char*username char *dn char *bindpw

…

Compare-Node char *dn char *attrib char *value

…

DN-Compare-Node char *reqdn char *dn

© Novell Inc, 2006

44

Mod_LDAP Cache Status Monitor

• Implements a cache data display so that the different types of caches can be monitored

• Monitored attributes:• Number of entries within each cache• Number of successful hits vs accesses (fetches)• Number of inserts vs deletes• If and when a purge on the cache has been done

• Each individual cache displays its own specific information

• Enabled by setting the “ldap-status” handler

© Novell Inc, 2006

45

Cache Overview Display

© Novell Inc, 2006

46

Search Cache Display

© Novell Inc, 2006

47

Compare Cache Display

© Novell Inc, 2006

48

Summary

• Mod_Authnz_LDAP allows you to authenticate users against an LDAP directory

• No longer an experimental module• Supports complex authentication policies through the use

of LDAP filters• Conforms to the new authnz architecture in Apache 2.2• Mod_LDAP (Util_LDAP) provides common LDAP

operation services, connection and credentials caching• Provides SSL/TLS encryption capability between the

Apache server and the LDAP server• Provides cache monitoring through the “ldap-status”

handler

Questions

General Disclaimer

This document is not to be construed as a promise by any participating company to develop, deliver, or market a product. Novell, Inc., makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.