doc/rlm_ldap

   1 1.   INSTALATION
   2
   3 This module depends on OpenLDAP v2.x SDK libraries.  For details on obtaining
   4 source of OpenLDAP look at <http://www.openldap.org>.  OpenLDAP SDK in turn
   5 depends on OpenSSL crypto libraries and (optionaly) on Cyrus-SASL libraries.
   6
   7 2. LDAP ATTRIBUTES
   8
   9 The mapping between radius and ldap attributes is in raddb/ldap.attrmap. You
  10 should edit the file and add any new mapping which you need. The schema files
  11 is located in doc/RADIUS-LDAPv3.schema. Before adding any radius attributes
  12 the ldap server schema should be updated.  All ldap entries containing radius
  13 attributes should contain at least "objectclass: radiusprofile"
  14
  15 radiusCheckItem and radiusReplyItem are special. They allow the administrator
  16 to add any check or reply item respectively without adding it in the ldap
  17 schema. The format should be <ldap-attribute>: <radius-attribute> <operator>
  18 <value>
  19
  20 ie radiusReplyItem: Cisco-AVPair := "ip:addr-pool=dialin_pool"
  21
  22 3. CONFIGURATION
  23
  24 Add following subsection to the modules{} section of radiusd.conf to control
  25 the rlm_ldap module:
  26
  27   modules { ...
  28
  29         ldap {
  30
  31 #       server: LDAP server hostname/ip address
  32 #
  33 #       Optionaly could contain space separated list of host[:port], but
  34 #       redundancy/resiliency is better acheived configuring multiple rlm_ldap
  35 #       module instances and invocing them in   redundand/failover
  36 #       configuration in authorize/authenticate sections
  37 #
  38 #       You can also pass an ldap url like ldap://localhost
  39 #       That way you can also specify alternative ldap schemas like
  40 #       ldaps:// or ldapi://
  41 #       The port directive will be ignored in that case
  42 #
  43 #       default: settings for your system, as set in etc/openldap/ldap.conf
  44 #
  45                 server   = localhost
  46
  47 #       port: LDAP server port
  48 #
  49 #       If LDAP server port is set to 636 (ldaps), SSL connection is enforced.
  50 #       This feature is useful for LDAP servers which support SSL, but don't
  51 #       do TLS negotiation (like Novell eDirectory).
  52 #
  53 #       default: 389 (ldap)
  54 #
  55                 port = 636
  56
  57 #       net_timeout: # of seconds to wait for response of the server (network
  58 #       failures) default: 10
  59 #
  60                 net_timeout = 1
  61
  62 #       timeout: # seconds to wait for LDAP query to finish default: 20
  63 #
  64                 timeout = 2
  65
  66 #       timelimit: # of seconds server has to process the query (server-side
  67 #       time limit) default: 20
  68 #
  69                 timelimit = 5
  70
  71 #       ldap_debug: debug flag for LDAP SDK (see OpenLDAP documentation)
  72 #       default: 0x0000 (no debugging messages)
  73 #       Example:(LDAP_DEBUG_FILTER+LDAP_DEBUG_CONNS)
  74                 ldap_debug = 0x0028
  75
  76 #       identity: DN under which LDAP searches are done password: pasword
  77 #       which authenticate this DN default: anonymous bind, no password
  78 #       required NOTE: searches are done now over unencrypted connection!
  79 #
  80 #       identity = "cn=admin,o=My Org,c=UA" password = mypass
  81
  82
  83 #       ldap_connections_number: The number of ldap connections that the
  84 #       module will keep open to use in requests. Usually it will not need to
  85 #       be larger than 5-10 connections default: 5
  86
  87         ldap_connections_number = 5
  88
  89 #       basedn = <Base of LDAP searches>
  90 #
  91                 basedn   = "o=My Org,c=UA"
  92
  93 #       filter: LDAP search filter, to locate user object using name supplied
  94 #       by client during Radius authentication
  95 #
  96 #       default: filter   = "(uid=%u)"
  97
  98 #       base_filter: The LDAP search filter used for base scope searches, like
  99 #       when searching for the default or regular profiles
 100 #
 101 #       deafault: base_filter = "(objectclass=radiusprofile)"
 102
 103                 filter   = "(uid=%u)"
 104
 105 #       start_tls: When set to "yes" the StartTLS extended operation is used to
 106 #       start TLS transport encryption.
 107                 start_tls = no
 108
 109 #       tls_mode: When set to "yes" OR the server port is 636 we try to connect with TLS
 110 #       Start TLS should be prefered, tls_mode is provided only for ldap servers
 111 #       like Active Directory which do not support it.
 112 #       default: no
 113
 114                 tls_mode = no
 115
 116 #       tls_cacertfile: A PEM-encoded file that contains the CA Certificates that
 117 #       you trust
 118                 tls_cacertfile = /path/to/cacert.pem
 119
 120 #       tls_cacertdir: Path the a directory of CA Certificates that you trust, the
 121 #       directory must be in "hash format" (see openssl verify)
 122                 tls_cacertdir = /path/to/ca/dir/
 123
 124 #       tls_certfile: The PEM Encoded certificate file that we should present to
 125 #       clients connecting
 126                 tls_certfile = /path/to/radius.crt
 127
 128 #       tls_keyfile: The PEM Encoded private key that we should use to encrypt the
 129 #       session
 130                 tls_keyfile = /path/to/radius.key
 131
 132 #       tls_randfile: A file containing random data to seed the OpenSSL PRNG.  Not
 133 #       needed if your OpenSSL is already properly random.
 134                 tls_randfile = /path/to/rnd
 135
 136 #       tls_require_cert: Certificate Verification requirements.  Can be "never"
 137 #       (don't even bother trying), "allow" (try, but don't fail if the cerificate
 138 #       can't be verified), or "demand" (fail if the certificate doesn't verify.)
 139 #       The default is "allow"
 140                 tls_require_cert = "allow"
 141
 142 #       default_profile: DN of a LDAP object, which contains default RADIUS
 143 #       attributes.  default: NULL - use only user specific attributes or
 144 #       attributes, supplied by other modules.
 145 #
 146         default_profile = "cn=RadProfile,o=My Org,c=UA"
 147
 148 #       profile_attribute: user object attribute, which contains DN of
 149 #       radiusProfile object for this user.  default: NULL - use only user
 150 #       specific attributes or attributes, supplied by other modules.
 151 #
 152 #       profile_attribute = "radiusProfileDn"
 153
 154 #       access_attr_used_for_allow: Define if the access attribute (described
 155 #       below) will be used to allow access (meaning if it exists then user
 156 #       remote access will be allowed) or to deny access.  default: yes - used
 157 #       to allow access
 158
 159 #       access_attr: if attribute is specified, module checks for its
 160 #       existance in user object.  If access_attr_used_for_allow is set to
 161 #       yes: If it exists the user is allowed to get remote access.  If it
 162 #       exists and is set to FALSE the user is denied remote access.  If it
 163 #       does not exist user is denied remote access by default if
 164 #       access_attr_used_for_allow is set to no: If it exists the user is
 165 #       denied remote access.  If it does not exist user is allowed remote
 166 #       access.
 167 #
 168 #       default: NULL - don't check for the attribute
 169
 170         access_attr = "dialupAccess"
 171
 172 #       password_header: If the user password is available we add it to the
 173 #       check items (to assist in CHAP ie) striping any headers first.
 174 #       NOTE: The password_header directive is NOT case insensitive
 175 #       default: NULL
 176 #
 177 #       password_header = "{clear}"
 178
 179 #       password_attribute: Define the attribute which contains the user
 180 #       password.
 181 #
 182 #       default: NULL - don't add password
 183 #
 184 #       password_attribute = "userPassword"
 185
 186 #       groupname_attribute: The attribute containing group name in the LDAP
 187 #       server. It is used to search group by name.
 188 #
 189 #       default: cn - Search filter is "(cn=%GroupName)"
 190 #
 191 #       groupname_attribute = "cn"
 192
 193 #       compare_check_items: Specifies if the module will do a comparison on
 194 #       the check items extracted from the ldap with the corresponding items
 195 #       present in the incoming request.
 196 #
 197 #       default: no - don't do any comparisons
 198 #
 199 #       compare_check_items = yes
 200
 201 #       do_xlat: Specifies if the module will do an xlat on the radius attributes
 202 #       extracted from the ldap database. Also the attribute operators will be
 203 #       honored. If the directive is set to 'no' then we will fall back to the
 204 #       pairadd() function which will just add the attributes at the end of the
 205 #       corresponding attribute list (check or reply items). This can be used to
 206 #       fall back to 0.8.1 behaviour without changing the ldap data or to gain a
 207 #       little performance if the ldap data is rather simple (no special operators)
 208 #
 209 #       default: yes - do an xlat and honor operators
 210 #
 211 #       do_xlat = yes
 212
 213
 214 #       groupmembership_filter: The filter to search for group membership of a
 215 #       particular user after we have found the DN for the group.
 216 #
 217 #       default: (|(&(objectClass=GroupOfNames)(member=%{Ldap-UserDn}))(&(objectClass=GroupOfUniqueNames)(uniquemember=%{Ldap-UserDn})))
 218 #
 219 #       groupmembership_filter = "(|(&(objectClass=GroupOfNames)(member=%{Ldap-UserDn}))(&(objectClass=GroupOfUniqueNames)(uniquemember=%{Ldap-UserDn})))"
 220
 221
 222 #       groupmembership_attribute: The attribute in the user entry that states
 223 #       the group the user belongs to.  The attribute can either contain the
 224 #       group name or the group DN. If it contains the group DN
 225 #       groupmembership_attribute will also be used to find the group's name.
 226 #       The attribute will be used after a search based on the
 227 #       groupname_attribute and groupmembership_filter has failed.  default:
 228 #       NULL - don't search for a group based on attributes in the user entry.
 229 #
 230 #       groupmembership_attribute = "radiusGroupName"
 231
 232         } }
 233
 234 NOTE: As LDAP is case insensitive, you should probably also set "lower_user =
 235 yes" and "lower_time = before" in main section of radiusd.conf, to get limits
 236 on simultaneous logins working correctly. Otherwise, users will be able get
 237 large number of sessions, capitalizing parts of their login names.
 238
 239 MODULE MESSAGES: On user rejection rlm_ldap will return the following module
 240 messages:
 241
 242 "rlm_ldap: User not found" "rlm_ldap: Access Attribute denies access"
 243 "rlm_ldap: Bind as user failed"
 244
 245 These messages will be visible in radius.log as aditional information in
 246 "Login incorrect" and "Invalid user" log messages.
 247
 248 LDAP XLAT: The ldap module now supports LDAP URLs in xlat strings. That is you
 249 can now add LDAP URLs in the configuration options and hopefully shortly also
 250 in the users file. The strings will be of the following form:
 251
 252 %{ldap:ldap:///dc=company,dc=com?uid?sub?uid=%u}
 253
 254 The requested attributes list MUST contain only ONE attribute. In case this
 255 attribute is multi valued which value is returned is considered UNDEFINED.
 256 Also, adding the host:port information SHOULD be avoided unless there are more
 257 than one ldap module instances in which case the host,port information can be
 258 used to distinguish which module will actually return the information (the
 259 xlat function will return NULL if the host,port information does not
 260 correspond to the configured attributes).  If there are more than one
 261 instances the module instance name can be used instead of the string 'ldap'
 262 before the ldap url to decide which instance will return the information.
 263 That is the xlat string will be of the form:
 264
 265 %{$instance_name:ldap:///dc=comapny,dc=com?uid?sub?uid=%u}
 266
 267 i.e.: ${ldap_company1:ldap:///dc=company1,dc=com?uid?sub?uid=%u}
 268
 269
 270 USER PROFILE ATTRIBUTE: The module can use the User-Profile attribute. If it
 271 is set, it will assume that it contains the DN of a profile entry containing
 272 radius attributes. This entry will _replace_ the default profile directive.
 273 That way we can use different profiles based on checks on the radius
 274 attributes contained in the Access-Request packets. For example (users file):
 275
 276 DEFAULT Service-Type == Outbound-User, User-Profile := "uid=outbound-dialup,dc=company,dc=com"
 277
 278
 279 GROUP SUPPORT: The module supports searching for ldap groups by use of the
 280 Ldap-Group attribute. As long as the module has been instanciated it can be
 281 used to do group membership checks through other modules. For example in the
 282 users file:
 283
 284 DEFAULT Ldap-Group == "disabled", Auth-Type := Reject
 285         Reply-Message = "Sorry, you are not allowed to have dialup access"
 286
 287 DNs are also accepted as Ldap-Group values, i.e.:
 288
 289 DEFAULT Ldap-Group == "cn=disabled,dc=company,dc=com", Auth-Type := Reject
 290         Reply-Message = "Sorry, you are not allowed to have dialup access"
 291
 292
 293 USERDN Attribute:
 294 When rlm_ldap has found the DN corresponding to the username provided in the access-request
 295 (all this happens in the authorize section) it will add an Ldap-UserDN attribute in the check
 296 items list containing that DN. The attribute will be searched for in the authenticate section
 297 and if present will be used for authentication (ldap bind with the user DN/password). Otherwise
 298 a search will be performed to find the user dn. If the administrator wishes to use rlm_ldap only
 299 for authentication or does not wish to populate the identity,password configuration attributes
 300 he can set this attribute by other means and avoid the ldap search completely. For instance it can
 301 be set through the users file in the authorize section:
 302
 303 DEFAULT Ldap-UserDN := `uid=%{User-Name},ou=people,dc=company,dc=com`
 304
 305
 306 DIRECTORY COMPATIBILITY NOTE: If you use LDAP only for authorization and
 307 authentication (e.g. you can not afford schema extention), I propose to set
 308 all necessary attributes in raddb/users file with following authorize section
 309 of radiusd.conf :
 310
 311 authorize { ldap { notfound = return } files  }