539 lines
16 KiB
Plaintext
539 lines
16 KiB
Plaintext
LDAP module
|
|
===========
|
|
|
|
The LDAP module provides a method for authenticating users against an
|
|
LDAP server. There are two separate authentication modules and two
|
|
authentication processing filters:
|
|
|
|
|
|
`ldap:LDAP`
|
|
: Authenticate the user against a single LDAP server.
|
|
|
|
`ldap:LDAPMulti`
|
|
: Allow the user to chose one LDAP server to authenticate against.
|
|
|
|
`ldap:AttributeAddFromLDAP`
|
|
: Adds an attribute value from LDAP to the request
|
|
|
|
`ldap:AttributeAddUsersGroups`
|
|
: Add an attribute to the request with all the user's group memberships
|
|
|
|
`ldap:LDAP`
|
|
-----------
|
|
|
|
This module is used when you have an organization with a single LDAP
|
|
server with all the users. To create an LDAP authentication source, open
|
|
`config/authsources.php` in a text editor, and add an entry for the
|
|
authentication source:
|
|
|
|
'example-ldap' => array(
|
|
'ldap:LDAP',
|
|
|
|
/* The hostname of the LDAP server. */
|
|
'hostname' => 'ldap.example.org',
|
|
|
|
/* Whether SSL/TLS should be used when contacting the LDAP server. */
|
|
'enable_tls' => FALSE,
|
|
|
|
/*
|
|
* Which attributes should be retrieved from the LDAP server.
|
|
* This can be an array of attribute names, or NULL, in which case
|
|
* all attributes are fetched.
|
|
*/
|
|
'attributes' => NULL,
|
|
|
|
/*
|
|
* The pattern which should be used to create the user's DN given the username.
|
|
* %username% in this pattern will be replaced with the user's username.
|
|
*
|
|
* This option is not used if the search.enable option is set to TRUE.
|
|
*/
|
|
'dnpattern' => 'uid=%username%,ou=people,dc=example,dc=org',
|
|
|
|
/*
|
|
* As an alternative to specifying a pattern for the users DN, it is possible to
|
|
* search for the username in a set of attributes. This is enabled by this option.
|
|
*/
|
|
'search.enable' => FALSE,
|
|
|
|
/*
|
|
* The DN which will be used as a base for the search.
|
|
* This can be a single string, in which case only that DN is searched, or an
|
|
* array of strings, in which case they will be searched in the order given.
|
|
*/
|
|
'search.base' => 'ou=people,dc=example,dc=org',
|
|
|
|
/*
|
|
* The attribute(s) the username should match against.
|
|
*
|
|
* This is an array with one or more attribute names. Any of the attributes in
|
|
* the array may match the value the username.
|
|
*/
|
|
'search.attributes' => array('uid', 'mail'),
|
|
|
|
/*
|
|
* The username & password where simpleSAMLphp should bind to before searching. If
|
|
* this is left NULL, no bind will be performed before searching.
|
|
*/
|
|
'search.username' => NULL,
|
|
'search.password' => NULL,
|
|
),
|
|
|
|
|
|
You should update the name of this authentication source
|
|
(`example-ldap`) to have a name which makes sense to your organization.
|
|
You also need to update the `hostname` and `dnpattern` options. The
|
|
`hostname` should be the hostname of your LDAP server, and the
|
|
`dnpattern` should be a pattern which can be used to generate the `dn`
|
|
of a user with a given username.
|
|
|
|
All other options have default values, and are not required.
|
|
|
|
### Searching for a user ###
|
|
|
|
Sometimes you cannot generate the user's `dn` from the username, or you
|
|
may want to allow the user to authenticate with for example their email
|
|
address as the username. In this case, you can configure the LDAP
|
|
module to search for the users `dn` by searching for the username in
|
|
one or more attributes.
|
|
|
|
To enable searching, you must set the `search.enable` option to `TRUE`.
|
|
You must then configure the `search.base` and the `search.attributes`
|
|
options. The `search.base`-option must be the `dn` which should be used
|
|
as the base/root of the search. The `search.attributes`-option is an
|
|
array with attributes the username should be matched against.
|
|
|
|
The `dnpattern` option will not be used if searching is enabled.
|
|
|
|
Some LDAP servers may require authentication before a search can be
|
|
performed. In this case, you should configure the `search.username`
|
|
and `search.password` options. The `search.username` option is a `dn`
|
|
which can be used to perform a search, and the `search.password` option
|
|
is the password for that `dn`.
|
|
|
|
### Configuring failover ###
|
|
|
|
You can configure multiple LDAP servers in the hostname option by separating the individual hosts with a space.
|
|
This enables the builtin LDAP failover in OpenLDAP.
|
|
|
|
Note that OpenLDAP waits for a timeout from the first server before attempting to connect to the other.
|
|
To avoid a very long wait, it is recommended to change the timeouts.
|
|
This can be done in the system-wide ldap configuration file.
|
|
|
|
NETWORK_TIMEOUT 10
|
|
TIMELIMIT 15
|
|
TIMEOUT 20
|
|
|
|
In this case, if we are unable to connect to the first LDAP server within 10 seconds, we will attempt the next.
|
|
(Note: the NETWORK_TIMEOUT option was introduced with OpenLDAP version 2.4.)
|
|
|
|
#### Example ####
|
|
|
|
/* Configuration that uses two ldap servers. */
|
|
'example-ldap' => array(
|
|
'ldap:LDAP',
|
|
/* The hostname of the LDAP server. */
|
|
'hostname' => 'ldaps://ldap1.example.org ldaps://ldap2.example.org',
|
|
'dnpattern' => 'uid=%username%,ou=people,dc=example,dc=org',
|
|
),
|
|
|
|
|
|
`ldap:LDAPMulti`
|
|
----------------
|
|
|
|
This module can be used if your organization has separate groups with
|
|
separate LDAP servers or separate LDAP configurations. To use this
|
|
authentication module, open `config/authsources.php` in a text editor,
|
|
and add an entry which uses this module:
|
|
|
|
'example-ldapmulti' => array(
|
|
'ldap:LDAPMulti',
|
|
|
|
/*
|
|
* The way the organization as part of the username should be handled.
|
|
* Three possible values:
|
|
* - 'none': No handling of the organization. Allows '@' to be part
|
|
* of the username.
|
|
* - 'allow': Will allow users to type 'username@organization'.
|
|
* - 'force': Force users to type 'username@organization'. The dropdown
|
|
* list will be hidden.
|
|
*
|
|
* The default is 'none'.
|
|
*/
|
|
'username_organization_method' => 'none',
|
|
|
|
/*
|
|
* Whether the organization should be included as part of the username
|
|
* when authenticating. If this is set to TRUE, the username will be on
|
|
* the form <username>@<organization identifier>. If this is FALSE, the
|
|
* username will be used as the user enters it.
|
|
*
|
|
* The default is FALSE.
|
|
*/
|
|
'include_organization_in_username' => FALSE,
|
|
|
|
/*
|
|
* A list of available LDAP servers.
|
|
*
|
|
* The index is an identifier for the organization/group. When
|
|
* 'username_organization_method' is set to something other than 'none',
|
|
* the organization-part of the username is matched against the index.
|
|
*
|
|
* The value of each element is an array in the same format as an LDAP
|
|
* authentication source.
|
|
*/
|
|
'employees' => array(
|
|
/*
|
|
* A short name/description for this group. Will be shown in a dropdown list
|
|
* when the user logs on.
|
|
*
|
|
* This option can be a string or an array with language => text mappings.
|
|
*/
|
|
'description' => 'Employees',
|
|
|
|
/*
|
|
* The rest of the options are the same as those available for
|
|
* the LDAP authentication source.
|
|
*/
|
|
'hostname' => 'ldap.employees.example.org',
|
|
'dnpattern' => 'uid=%username%,ou=employees,dc=example,dc=org',
|
|
),
|
|
|
|
'students' => array(
|
|
'description' => 'Students',
|
|
|
|
'hostname' => 'ldap.students.example.org',
|
|
'dnpattern' => 'uid=%username%,ou=students,dc=example,dc=org',
|
|
),
|
|
|
|
),
|
|
|
|
The name of the authentication source (`example-ldapmulti`) should be
|
|
changed to something that makes sense for your organization. Each entry
|
|
in the configuration represents the configuration for one group of
|
|
users. The `description`-option in each group is the name of the group,
|
|
and will be shown to the user in a dropdown list on the login page.
|
|
|
|
The `description`-option can also be an array with descriptions in
|
|
different languages:
|
|
|
|
'description' => array(
|
|
'en' => 'Employees',
|
|
'no' => 'Ansatte',
|
|
),
|
|
|
|
All options from the `ldap:LDAP` configuration can be used in each
|
|
group, and you should refer to the documentation for that module for
|
|
more information about available options.
|
|
|
|
|
|
`ldap:AttributeAddFromLDAP`
|
|
---------------------------
|
|
|
|
Filter to add attributes to the identity by executing a query against
|
|
an LDAP directory. In addition to all the configuration options available
|
|
in the ldap:AttributeAddUsersGroups filter (below), these are the filter
|
|
specific configuration options:
|
|
|
|
|
|
50 = array(
|
|
'class' => 'ldap:AttributeAddFromLDAP',
|
|
|
|
/**
|
|
* The attributes to search for and their mappings. This must be an array,
|
|
* and keys can be skipped. If you skip a key, then the attribute will be
|
|
* exported with the same name as the LDAP attribute.
|
|
*
|
|
* Default: NULL
|
|
* Required: Yes
|
|
*/
|
|
'attributes' => array('mail', 'jpegPhoto' => 'jpegphoto'),
|
|
|
|
/**
|
|
* The attribute policy that defines what to do with attributes that are
|
|
* already part of the attributes of the user. Can be one of:
|
|
*
|
|
* - add: blindly add the values. If the attribute already exists and has
|
|
* the same value, the result of the filter will be two equal values.
|
|
*
|
|
* - merge: carefully merge the values. If a value is already part of
|
|
* the attribute, do not add a duplicate.
|
|
*
|
|
* - replace: if the attribute is present before running the filter,
|
|
* replace its values with the ones obtained at this point.
|
|
*
|
|
* Default: merge
|
|
* Required: No
|
|
*/
|
|
'attribute.policy' => 'merge',
|
|
|
|
/**
|
|
* The search filter to find the user in LDAP.
|
|
*
|
|
* Note: Variable substitution will be performed on this option.
|
|
* Any attribute in the identity can be substituted by surrounding
|
|
* it with percent symbols (%). For instance %cn% would be replaced
|
|
* with the CN of the user.
|
|
*
|
|
* Default: NULL
|
|
* Required: Yes
|
|
*/
|
|
'search.filter' => '(uid=%uid%)',
|
|
);
|
|
|
|
|
|
### Backwards Compatibility ###
|
|
|
|
Previous versions of this filter allowed just one attribute to be fetched from the
|
|
LDAP at a time. The options 'attribute.new' and 'search.attribute' were used instead
|
|
of the new option 'attributes'. Fortunately, the filter is backwards compatible, so
|
|
your old configuration will still work, but keep in mind that the old configuration
|
|
style is deprecated now and will be removed in 2.0.
|
|
|
|
|
|
### Example ###
|
|
|
|
This is the most basic configuration possible. It will look at the
|
|
authsource for all LDAP connection information and queries LDAP for
|
|
the specific attributes requested.
|
|
|
|
50 => array(
|
|
'class' => 'ldap:AttributeAddFromLDAP',
|
|
'authsource' => 'example-ldap',
|
|
'attributes' => array('displayName' => 'cn', 'jpegPhoto'),
|
|
'search.filter' => '(uid=%uid%)',
|
|
)
|
|
|
|
If no authsource is available then you can specify the connection info
|
|
using the filter configuration. Note: Not all of the options below are
|
|
required, see the config options for ldap:AttributeAddFromLDAP above.
|
|
|
|
50 => array(
|
|
'class' => 'ldap:AttributeAddFromLDAP',
|
|
'ldap.hostname' => 'ldap.example.org',
|
|
'ldap.username' => 'CN=LDAP User,CN=Users,DC=example,DC=org',
|
|
'ldap.password' => 'Abc123',
|
|
'ldap.basedn' => 'DC=example,DC=org',
|
|
'attributes' => array('displayName' => 'cn', 'jpegPhoto'),
|
|
'search.filter' => '(uid=%uid%)',
|
|
)
|
|
|
|
|
|
|
|
|
|
`ldap:AttributeAddUsersGroups`
|
|
------------------------------
|
|
|
|
This filter will add the logged in user's LDAP group memberships to
|
|
a specified request attribute. Although most LDAP products have a
|
|
memberOf attribute which only lists the direct membership relations,
|
|
this filter checks those relation for "sub" groups, recursively
|
|
checking the hierarchy for all groups the user would technically be
|
|
a member of. This can be helpful for other filters to know. Below is
|
|
a listing of all configuration options and their details.
|
|
|
|
|
|
50 => array(
|
|
'class' => 'ldap:AttributeAddUsersGroups',
|
|
|
|
|
|
/**
|
|
* LDAP connection settings can be retrieved from an ldap:LDAP
|
|
* authsource. Specify the authsource name here to pull that
|
|
* data from the authsources.php file in the config folder.
|
|
*
|
|
* Note: ldap:LDAPMulti is not supported as the SimpleSAMLphp
|
|
* framework does not pass any information about which
|
|
* LDAP source the user selected.
|
|
*
|
|
* Default: NULL
|
|
* Require: No
|
|
*/
|
|
'authsource' => NULL,
|
|
'authsource' => 'example-ldap',
|
|
|
|
|
|
/**
|
|
* This is the attribute name which the users groups will be
|
|
* added to. If the attribute exists in the request then the
|
|
* filter will attempt to add them.
|
|
*
|
|
* Default: 'groups'
|
|
* Required: No
|
|
*/
|
|
'attribute.groups' => 'groups',
|
|
|
|
|
|
/**
|
|
* The base DN used to search LDAP. May not be needed if searching
|
|
* LDAP using the standard method, meaning that no Product is specified.
|
|
* Can be listed as a single string for one base, else an array of
|
|
* strings for multiple bases.
|
|
*
|
|
* Default: ''
|
|
* Required: No
|
|
* AuthSource: search.base
|
|
*/
|
|
'ldap.basedn' => '',
|
|
'ldap.basedn' => 'DC=example,DC=org',
|
|
'ldap.basedn' => array(
|
|
'OU=Staff,DC=example,DC=org',
|
|
'OU=Students,DC=example,DC=org'
|
|
),
|
|
|
|
|
|
/**
|
|
* Set to TRUE to enable LDAP debug level. Passed to
|
|
* the LDAP connection class.
|
|
*
|
|
* Default: FALSE
|
|
* Required: No
|
|
* AuthSource: debug
|
|
*/
|
|
'ldap.debug' => FALSE,
|
|
'ldap.debug' => TRUE,
|
|
|
|
|
|
/**
|
|
* Set to TRUE to force the LDAP connection to use TLS.
|
|
*
|
|
* Note: If ldaps:// is specified in the hostname then it
|
|
* will automatically use TLS.
|
|
*
|
|
* Default: FALSE
|
|
* Required: No
|
|
* AuthSource: enable_tls
|
|
*/
|
|
'ldap.enable_tls' => FALSE,
|
|
'ldap.enable_tls' => TRUE,
|
|
|
|
|
|
/**
|
|
* This is the hostname string of LDAP server(s) to try
|
|
* and connect to. It should be the same format as the
|
|
* LDAP authsource hostname as it is passed to that class.
|
|
*
|
|
* Note: Multiple servers are separated by a space.
|
|
*
|
|
* Default: NULL
|
|
* Required: Yes, unless authsource is used
|
|
* AuthSource: hostname
|
|
*/
|
|
'ldap.hostname' => 'ldap.example.org',
|
|
'ldap.hostname' => 'ad1.example.org ad2.example.org',
|
|
|
|
|
|
/**
|
|
* This is the password used to bind to LDAP.
|
|
*
|
|
* Default: NULL
|
|
* Required: No, only if required for binding.
|
|
* AuthSource: search.password OR priv.password
|
|
*/
|
|
'ldap.password' => 'Abc123',
|
|
|
|
|
|
/**
|
|
* By specifying the directory service product name, the number
|
|
* of LDAP queries can be dramatically reduced. The reason is
|
|
* that most products have a special query to recursively search
|
|
* group membership.
|
|
*
|
|
* Note: Only ActiveDirectory is currently supported.
|
|
*
|
|
* Default: ''
|
|
* Required: No
|
|
*/
|
|
'ldap.product' => '',
|
|
'ldap.product' => 'ActiveDirectory',
|
|
|
|
|
|
/**
|
|
* The LDAP timeout value passed to the LDAP connection class.
|
|
*
|
|
* Default: 0
|
|
* Required: No
|
|
* AuthSource: timeout
|
|
*/
|
|
'ldap.timeout' => 0,
|
|
'ldap.timeout' => 30,
|
|
|
|
|
|
/**
|
|
* This is the username used to bind to LDAP with.
|
|
* More than likely will need to be in the DN of
|
|
* user binding to LDAP.
|
|
*
|
|
* Default: NULL
|
|
* Required: No, only if required for binding.
|
|
* AuthSource: search.username OR priv.username
|
|
*/
|
|
'ldap.username' => 'CN=LDAP User,CN=Users,DC=example,DC=org',
|
|
|
|
|
|
/**
|
|
* The following attribute.* and type.* configuration options
|
|
* define the LDAP schema and should only be defined/modified
|
|
* if the schema has been modified or the LDAP product used
|
|
* uses other attribute names. By default, the schema is setup
|
|
* for ActiveDirectory.
|
|
*
|
|
* Defaults: Listed Below
|
|
* Required: No
|
|
*/
|
|
'attribute.dn' => 'distinguishedName',
|
|
'attribute.groups' => 'groups', // Also noted above
|
|
'attribute.member' => 'member',
|
|
'attribute.memberof' => 'memberOf',
|
|
'attribute.groupname' => 'name',
|
|
'attribute.type' => 'objectClass',
|
|
'attribute.username' => 'sAMAccountName',
|
|
|
|
|
|
/**
|
|
* As mentioned above, these can be changed if the LDAP schema
|
|
* has been modified. These list the Object/Entry Type for a given
|
|
* DN, in relation to the 'attribute.type' config option above.
|
|
* These are used to determine the type of entry.
|
|
*
|
|
* Defaults: Listed Below
|
|
* Required: No
|
|
*/
|
|
'type.group' => 'group',
|
|
'type.user' => 'user',
|
|
)
|
|
|
|
|
|
### Example ###
|
|
|
|
This is the most basic configuration possible. It will look at the
|
|
authsource for all LDAP connection information and manually search
|
|
the hierarchy for the users group memberships.
|
|
|
|
50 => array(
|
|
'class' => 'ldap:AttributeAddUsersGroups',
|
|
'authsource' => 'example-ldap'
|
|
)
|
|
|
|
By making one small change we can optimize the filter to use better
|
|
group search methods and eliminate un-needed LDAP queries.
|
|
|
|
50 => array(
|
|
'class' => 'ldap:AttributeAddUsersGroups',
|
|
'authsource' => 'example-ldap',
|
|
'ldap.product' => 'ActiveDirectory'
|
|
)
|
|
|
|
If no authsource is available then you can specify the connection info
|
|
using the filter configuration. Note: Not all of the options below are
|
|
required, see the config info above for details.
|
|
|
|
50 => array(
|
|
'class' => 'ldap:AttributeAddUsersGroups',
|
|
'ldap.hostname' => 'ldap.example.org',
|
|
'ldap.username' => 'CN=LDAP User,CN=Users,DC=example,DC=org',
|
|
'ldap.password' => 'Abc123',
|
|
'ldap.basedn' => 'DC=example,DC=org'
|
|
)
|
|
|