Section 3.47. <AuthBy LDAP2>

3.47. <AuthBy LDAP2>

<AuthBy LDAP2> module authenticates by issuing requests to an LDAP server. When the LDAP server replies, Radiator fetches a number of attributes and looks in them for the password, check items and reply items in order to authenticate the user. It does not log (but does reply to) accounting requests. You need to have a basic understanding of LDAP servers and databases in order to configure <AuthBy LDAP2>.

When an <AuthBy LDAP2> module receives its first authentication request, it attempts to connect to the LDAP server specified by Host. Optionally you can authenticate Radiator as a valid user of the LDAP server by specifying AuthDN and AuthPassword. This is not the same thing as authenticating a user. It happens before authenticating a user, and proves that this radiusd is allowed to talk to the LDAP database.

The <AuthBy LDAP2> module tries then to fetch some attributes for the user. Specify the base DN to start looking in, and the attribute name with which to filter. Also specify the attributes that contain the password, and (optionally) the names of the attributes containing an encrypted password, RADIUS check items and RADIUS reply items. This scheme allows you to work with almost any LDAP schema. All you have to do is identify the right LDAP attribute names.

If all the check items are satisfied by the attributes in the request, the <AuthBy LDAP2> module replies with an Access-Accept message containing all the attributes in the reply items attribute (if any). If the user does not appear in the LDAP database, or if any check attribute does not match, an Access-Reject message is sent to the client.

At present, <AuthBy LDAP2> modules do synchronous connections and searches. This can mean significant delays if your LDAP server is reached by a slow network connection, or your LDAP server is slow. In this case, consider putting the

<AuthBy
                  LDAP2>

realm in a sub-server, and having your main Radiator forward requests for that realm to the RADIUS sub-server.

This clause supports all the common LDAP configuration parameters. For more information about the LDAP configuration parameters, see Section 3.9. LDAP configuration.

<AuthBy LDAP2> understands also the same parameters as <AuthBy xxxxxx>. For more information, see Section 3.32. <AuthBy xxxxxx>.

3.47.1. Using <AuthBy LDAP2> with Microsoft Active Directory

When using <AuthBy LDAP2> together with Microsoft Active Directory (AD), you may need to try the following:

Use ServerChecksPassword when the user must be authenticated. AD does not provide password to LDAP. In this case, do not use HoldserverConnection. For more information, see Section 3.47.10. ServerChecksPassword.
Leave BaseDN empty if you use Global Catalog. For more information, see Global Catalog and LDAP Searches .
Global Catalog contains all users but not necessarily not all the attributes. Use port 3268 for LDAP and port 3269 for LDAPS to access to Global Catalog.
Use AttrsWithBaseScope if you need to get a constructed attribute, such as tokenGroups, for a certain user. For more information, see Section 3.47.8. AttrsWithBaseScope.

3.47.2. BaseDN

This is the base DN, where searches are made. It is used in similar way as with all LDAP modules. For more information, see Section 3.9.1. BaseDN.

Special formatting characters are permitted. When using

<AuthBy
                     LDAP2>

, %0 is replaced by UsernameAttr and %1 by the user name.

Tip

On some LDAP servers, you can get a significant performance increase by narrowing the search to the exact entry you are interested in. With AuthBy LDAP2 default settings, this example restricts the search to uid=username,ou=foo,o=bar,c=au:

BaseDN      %0=%1,ou=foo,o=bar,c=au
Scope       base

3.47.3. SearchFilter

This is the LDAP filter to use when searching for the user. It is used in similar way as with all LDAP modules. For more information, see Section 3.9.2. SearchFilter.

Usually, the search filter that is used to find a matching user name is

(uid=name)

uid is the name of the LDAP attribute defined by the UsernameAttr parameter, and name is the name of the user currently being authenticated. For advanced applications, you can completely alter the search filter that Radiator uses by using the optional SearchFilter parameter. It allows you to use arbitrarily complicated LDAP search filters to select or exclude users based on attributes other than their user name. Special formatting characters are permitted, %0 is replaced by UsernameAttr and %1 by the user name. For example, this SearchFilter matches only users with the appropriate setting of their ‘current’ attribute:

SearchFilter (&(current=1)(uid=%1))

In SearchFilter, you an use any special formatting character. For backwards compatibility, Perl variables used to be interpolated, but this has been removed. The default setting for SearchFilter is (%0=%1), which matches the user name against the LDAP attribute defined by the UsernameAttr parameter (usually uid). Therefore, the default search string is (uid=name).

3.47.4. EncryptedPasswordAttr

This is the optional name of the LDAP attribute that contains a Unix crypt(3) encrypted password for the user. If you specify EncryptedPasswordAttr, it will be used instead of PasswordAttr, and PasswordAttr will not be fetched. You must specify either PasswordAttr or EncryptedPasswordAttr. There is no default.

Tip

If your passwords are in the form

{crypt}1xMKc0GIVUNbE,
                        {SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc=

or {SSHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc= you should be using PasswordAttr, not EncryptedPasswordAttr. Only use EncryptedPasswordAttr if the your password are plain old Unix crypt format, like: 1xMKc0GIVUNbE.

# Get the encrypted password from cryptpw
EncryptedPasswordAttr cryptpw

3.47.5. PasswordAttr

This is the name of the LDAP attribute that contains the password for the user. The password may be in any of the formats supported by User-Password. For more information, see Section 7.1.1. User-Password, Password. Most LDAP servers will only have a plaintext password if they are secured in another way, and probably not even then. You must specify either PasswordAttr or EncryptedPasswordAttr. There is no default.

Note

OpenLDAP's userPassword is (a) encrypted and (b) only retrievable via an appropriately authenticated binding to the slapd.

# Plaintext passwords. Gasp
PasswordAttr passwd

Tip

If there is no password to be checked (e.g. Wireless MAC Addresses) you should specify PasswordAttr without a value, otherwise you will get a warning log message.

CAUTION

The value of currently configured PasswordAttr is printed as **obscured** when the attributes received from the LDAP server are logged. If the PasswordAttr is not present, nothing is logged for it. That is, only the value is obscured not the information about the presence of the attribute in the reply. To debug the password, use the Debug configuration parameter and see the console output. Another option is to configure “PasswordLogFileName” for the enclosing Handler. For more information, see Section 9.6. Password log file.

3.47.6. UsernameAttr

This is the name of the LDAP attribute that is required to match the user name in the authentication request (possibly after user name rewriting by RewriteUsername). Defaults to “uid”. The LDAP search filter is constructed from UsernameAttr and the name of the user in the Access-Request like this: “(UsernameAttr = user name)” For example, if you UsernameAttr is “uid”, and user “mikem” tries to log in, Radiator will use the LDAP filter “(uid=mikem)”. This behaviour can be customised with the Search-Filter parameter.

# Use the uid attribute to match usernames
UsernameAttr uid

3.47.7. AuthAttrDef

This optional parameter allows you to specify LDAP attributes to use as general check and reply items during authentication. AuthAttrDef is more general and useful than CheckAttr and ReplyAttr, and should be used in preference to them.

Using AuthAttrDef you can specify multiple LDAP attributes and tell Radiator to use them as check or reply items during authentication.

You can specify any number of AuthAttrDef parameters, one for each check or reply attribute in your LDAP database. The general format is:

AuthAttrDef ldapattributename[, radiusattributename, type[, formatted]]

ldapattributename is the name of the LDAP attribute to be used as the check or reply item. If it is multi-valued, and this is a check item, then Radiator will permit a match with any one of the values.
radiusattributename is the name of the RADIUS attribute that wall be used as the check or reply item. The special radiusattributename ‘GENERIC’ indicates that it is a list of comma separated attribute=value pairs, similar to ReplyAttr or CheckAttr.
type indicates whether it is a check or reply item. It consists of the word “check” or the word “reply”. If type is “request” the value is saved in the current request, from where it can be later collected with a special formatting macro like: %{attributename}.
formatted indicates that the LDAP attributes are to be subject to special character processing before being used.

Tip

The radiusattributename and type fields are optional. If they are not specified, then the ldapattributename attribute will be fetched from LDAP, but the fetched value of that attribute will not be used. This can be helpful for some types of LDAP query.

Example

Fetch the LDAP attribute called calledstationid, and use it as a check item against the RADIUS Called-Station-Id

AuthAttrDef       calledstationid,Called-Station-Id,check

Example

Check the RADIUS Service-Type matches the LDAP attribute called servicetype, and return the LDAP attribute called address as a static IP address (after special character replacements):

AuthAttrDef       servicetype,Service-Type,check
AuthAttrDef       address,Framed-IP-Address,reply,formatted

Example

During LDAP authentication, save 2 LDAP attributes into the current request:

# Put poolhint attribute into the request:
AuthAttrDef radiusUserPoolHint, X-userPoolHint, request
# Put Group Name attribute into the Request:
AuthAttrDef radiusSimultaneousUseGroupName,X-GroupName, request

Then use those attributes in a later AuthBy FILE:

fred        Group=%{X-GroupName}
            PoolHint=%{X-userPoolHint}

Example

Check items handle multi-valued LDAP attributes in a special way: by permitting a match with any one of the multiple values. For example, suppose you had callingstation LDAP attribute that could be multi-valued, and into which you put all the numbers the user was permitted to call from (as a separate value for each number), then you would use:

AuthAttrDef callingstation,Calling-Station-Id,check

3.47.8. AttrsWithBaseScope

Tells Radiator to search first for the user DN then do a search with scope base to fetch the attributes. Required, for example, to get access to Windows AD constructed attributes, such as tokenGroups, which are only returned when the search scope is set to base. Defaults to off.

3.47.9. PostSearchHook

This optional parameter allows you to define a Perl function that is run during the authentication process. The hook is called after the LDAP search results have been received, and after Radiator has processed the attributes it is interested in. Hook authors can use LDAP library routines to extract other attributes and process them in any way. PostSearchHook is called once for each LDAP result, as governed by MaxRecords parameter. If there are no results, the hook is not run. See Section 3.47.13. MaxRecords.

PostSearchHook has the following arguments:

Handle to the current AuthBy object
User name
Pointer to the current request
Pointer to the User object being constructed to hold the check and reply items for the user being authenticated
Search result entry
Pointer to the reply packet currently being constructed

Here is an example of PostSearchHook:

# this example for LDAP2 gets an additional attribute,
# multiplies it by 60 and uses it for Session-Timeout
# as a reply attribute for the user
PostSearchHook sub {my $attr = $_[4]->get('someldapattr');\
            $_[3]->get_reply->add_attr('Session-Timeout',\
            $attr * 60);}

Tip

In order to get any attributes you may want to access in the PostSearchHook, you also need to add this to the <AuthBy LDAP> clause:

AuthAttrDef someldapattr

someldapattr is the name of the LDAP attribute you are going to access in the PostSearchHook.

3.47.10. ServerChecksPassword

Normally, Radiator fetches the user's password attribute from the LDAP server using the PasswordAttr parameter and checks the password internally. This optional parameter causes the LDAP server to check the password instead. This is useful with LDAP servers that implement proprietary encryption algorithms in their passwords, or do not provide access to password attribute. For example, Microsoft Active Directory does not provide read access to password information over LDAP.

When ServerChecksPassword is specified, the password checking is performed using an LDAP bind operation.

Here is an example of using ServerChecksPassword:

# We are using Active Directory
ServerChecksPassword

CAUTION

ServerChecksPassword is compatible with PAP, EAP-TTLS/PAP, and other authentication methods that provide a plain text password. ServerChecksPassword does not work with CHAP, MSCHAP, and most EAP methods since these do not provide a password Radiator can use with an LDAP bind operation.

Note

In some cases, using ServerChecksPassword with HoldServerConnection may cause failure situations. This is due to some LDAP servers' behaviour when the password check fails but the connection is not closed. A failure situation may also occur when the password check succeeds but the user is not allowed to perform searches in the server. If your users experience unexpected authentication failures, try testing your system without using these 2 parameters together.

3.47.11. UnbindAfterServerChecksPassword

This optional parameter works around problems with some LDAP servers. Normally, when ServerChecksPassword is set, after Radiator checks a users password the LDAP connection is not unbound. This can cause problems with some LDAP servers (notably Oracle ID and Novell eDirectory), where they unexpectedly cause the following LDAP query to fail with LDAP_INAPPROPRIATE_AUTH. Setting this flag causes an unbind after each ServerChecksPassword bind.

3.47.12. AuthCheckDN

This optional parameter allows you to specify an alternate DN to use to check a user's password, instead of the one returned by the search result. Special formatting characters are permitted, and %0 is replaced by the DN returned by the search.

Note

This is an advanced parameter. Most installations will not need to use it. Available in AuthBy LDAP2 only.

3.47.13. MaxRecords

This optional parameter specifies the maximum number of matching LDAP records to use for check and reply items. Default is 1 to be backwards compatible with earlier versions of AuthBy LDAP2. Only the first match (if any) is used for ServerChecksPassword. This parameter can be used to extract additional check and reply items from LDAP records that define user roles.

3.47.14. GetNovellUP

This optional parameter can be used with the Novell eDirectory LDAP server to fetch the user's Universal Password and use it to authenticate the user. The eDirectory Universal Password is a single password for each user that can be used to authenticate a range of Unix and Windows services. Normally it is not possible to fetch the users password from eDirectory, but GetNovellUP uses a special Novell API to fetch the users plaintext password.

GetNovellUP will fetch the password if ServerChecksPassword is not set, and if PasswordAttr and EncryptedPasswordAttr are either not set or are not present in the user's LDAP record.

Passwords retrieved with GetNovellUP are in plaintext and are compatible with PAP, CHAP, MSCHAP, MSCHAPV2, TLS, TTLS-*, PEAP-MSCHAPV2, EAP-MD5 etc.

The eDirectory server must be configured correctly before it will supply Universal Passwords to Radiator. The following conditions must be met.

eDirectory Password Policy must be created and assigned to the group, organisational unit or organisation that holds the users to be authenticated.
Password Policy must have Universal Passwords enabled.
Password Policy must have ‘Allow password retrieval by admin’ enabled.

See goodies/edirectory.txt for more details about how to install and configure eDirectory so that Radiator can use GetNovellUP successfully.

3.47.15. GroupSearchFilter

For advanced applications, you can specify a search filter that Radiator will use to find which user groups a user belongs to by using the optional GroupSearchFilter parameter. It allows you to use arbitrarily complicated LDAP search filters to find the names of user groups the user belongs to. Special formatting characters are permitted, and %0 is replaced by UsernameAttr and %1 by the user name.

3.47.16. GroupNameCN

When GroupSearchFilter is specified and Radiator looks for the user groups the user is a member of, this parameter specifies the name of the Group name attribute in the LDAP records. Defaults to "cn".

3.47.17. GroupBaseDN

When GroupSearchFilter is specified and Radiator looks for the user groups the user is a member of, this parameter specifies an alternate LDAP base DN for the group search. Defaults to the value of BaseDN.

3.47.18. CheckAttr

This is the optional name of the LDAP attribute that contains the RADIUS check items for the user. During authentication, all the check items in this LDAP attribute (if specified) will be matched against the RADIUS attributes in the authentication request in the same was as for AuthBy FILE and AuthBy SQL, including Expiration in the format “Dec 08 1998”. Defaults to undefined. For more information, see Section 7.1. Check items.

Tip

If there are multiple instances of the LDAP attribute for the user, they are concatenated together with commas. This means that you can have each RADIUS check attribute in its own LDAP attribute for easy reading and maintenance.

Tip

AuthAttrDef is a more general and easy to use method of defining check and reply items. Support for CheckAttr will be discontinued sometime in the future.

# Check the radius items in checkitems
CheckAttr checkitems

3.47.19. ReplyAttr

This is the optional name of the LDAP attribute that contains the RADIUS reply items for the user. If the user authenticates successfully, all the RADIUS attributes named in this LDAP attribute will be returned to the user in the Access-Accept message. Defaults to undefined. For more information, see Section 7.2. Reply items.

Tip

If there are multiple instances of the LDAP attribute for the user, they are concatenated together with commas. This means that you can have each RADIUS reply attribute in its own LDAP attribute for easy reading and maintenance.

Tip

AuthAttrDef is a more general and easy to use method of defining check and reply items. Support for ReplyAttr will be discontinued sometime in the future.

# Reply with all the items in replyitems
ReplyAttr replyitems