diff --git a/docs/source/simplesamlphp-idp.xml b/docs/source/simplesamlphp-idp.xml index 34bff2640a95c1f620af508570f99cbdc9dbc0bc..2469347cf5ab78449be0d1a2430b3040c3fa640a 100644 --- a/docs/source/simplesamlphp-idp.xml +++ b/docs/source/simplesamlphp-idp.xml @@ -165,6 +165,75 @@ LDAP server.</para> </listitem> </itemizedlist> + + <section> + <title>Searching for the user's DN</title> + + <para>It is possible to search for the DN of the user by matching the + username provided by the user against one or more attributes. This + feature is configured by the following options in + <filename>config/ldap.php</filename>:</para> + + <itemizedlist> + <listitem> + <para><literal>auth.ldap.search.enable</literal>: Whether + searching for the user's DN should be enabled. Set this to + <literal>TRUE</literal> to enable searching.</para> + </listitem> + + <listitem> + <para><literal>auth.ldap.search.base</literal>: The DN we should + search for the user in.</para> + </listitem> + + <listitem> + <para><literal>auth.ldap.search.attributes</literal>: The + attributes we shoule match the username against. This can be a + single attribute, in which case it should be a string, or multiple + attributes, in which case it should be an array of strings.</para> + + <para>If this is multiple attributes, they will be joined into a + search query with the following form: + <literal>(|(<attr1>=<username>)(<attr2>=<username>)...)</literal> + </para> + </listitem> + + <listitem> + <para><literal>auth.ldap.search.username</literal>: The user we + should authenticate to the LDAP server as before searching. + Leave this as <literal>NULL</literal> if it isn't necessary to + authenticate to the server before searching.</para> + </listitem> + + <listitem> + <para><literal>auth.ldap.search.password</literal>: The password + for the user selected with the + <literal>auth.ldap.search.username</literal> option.</para> + </listitem> + </itemizedlist> + + <example> + <title>Configuring LDAP for searching</title> + + <programlisting>$config = array ( + 'auth.ldap.hostname' => 'ldap.example.org', + 'auth.ldap.attributes' => NULL, + 'auth.ldap.enable_tls' => FALSE, + + /* Enable searching. */ + 'auth.ldap.search.enable' => TRUE, + + /* The base DN for the search. */ + 'auth.ldap.search.base' => 'cn=users,dc=example,dc=org', + + /* The user can authenticate using the uid or the email address. */ + 'auth.ldap.search.attributes' => array('uid', 'mail'), + + 'auth.ldap.search.username' => 'uid=authsearch,cn=server,dc=example,dc=org', + 'auth.ldap.search.password' => 'secret', +);</programlisting> + </example> + </section> </section> <section>