All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
Configuration File: |
| ||||||
---|---|---|---|---|---|---|---|
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This setting will enable or disable LDAP authentication in DSpace. With the setting off, users will be required to register and login with their email address. With this setting on, users will be able to login and register with their LDAP user ids and passwords. | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This will turn LDAP autoregistration on or off. With this on, a new EPerson object will be created for any user who successfully authenticates against the LDAP server when they first login. With this setting off, the user must first register to get an EPerson object by entering their ldap username and password and filling out the forms. | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This is the url to your institution's LDAP server. You may or may not need the /o=myu.edu part at the end. Your server may also require the ldaps:// protocol. (This field has no default value) NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. Therefore, be careful to escape any required commas in this configuration by adding a backslash (\) before each comma, e.g. "\," | ||||||
Property: |
| ||||||
Example Value: | authentication-ldap.starttls = false | ||||||
Informational Note: | Should we issue StartTLS after establishing TCP connection in order to initiate an encrypted connection?
| ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Explanation: | This is the unique identifier field in the LDAP directory where the username is stored. (This field has no default value) | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This is the LDAP object context to use when authenticating the user. By default, DSpace will use this value to create the user's DN in order to attempt to authenticate them. It is appended to the id_field and username. For example If your users do NOT all exist under a single "object_context" in LDAP, then you should ignore this setting and INSTEAD use the Hierarchical LDAP Authentication settings below (especially see " NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. Therefore, be careful to escape any required commas in this configuration by adding a backslash (\) before each comma, e.g. "\," | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This is the search context used when looking up a user's LDAP object to retrieve their data for autoregistering. With NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. Therefore, be careful to escape any required commas in this configuration by adding a backslash (\) before each comma, e.g. "\," | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This is the LDAP object field where the user's email address is stored. "mail" is the most common for LDAP servers. (This field has no default value) If the "email_field" is unspecified, or the user has no email address in LDAP, his/her username (id_field value) will be saved as the email in DSpace (or appended to | ||||||
Property: | authentication-ldap.netid_email_domain | ||||||
Example Value: | authentication-ldap.netid_email_domain = @example.com | ||||||
Informational Note: | If your LDAP server does not hold an email address for a user (i.e. no Please note: this field will only be used if " | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This is the LDAP object field where the user's last name is stored. " | ||||||
Property: | authentication-ldap.givenname_field | ||||||
Example Value: |
| ||||||
Informational Note: | This is the LDAP object field where the user's given names are stored. I'm not sure how common the givenName field is in different LDAP instances. If the field is not found the field will be left blank in the new eperson object. (This field has no default value) | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | This is the field where the user's phone number is stored in the LDAP directory. If the field is not found the field will be left blank in the new eperson object. (This field has no default value) | ||||||
Property: |
| ||||||
Example Value: |
| ||||||
Informational Note: | If specified, all user sessions successfully logged in via LDAP will automatically become members of this DSpace Group (for the remainder of their current, logged in session). This DSpace Group must already exist (it will not be automatically created). | ||||||
Property: |
login.groupmap.* | ||||||
Example Value: | authentication-ldap.login.groupmap.1 = ou=Students:ALL_STUDENTS authentication-ldap.login.groupmap.2 = ou=Employees:ALL_EMPLOYEES authentication-ldap.login.groupmap.3 = ou=Faculty:ALL_FACULTY | ||||||
Informational Note: | The left part of the value (before the ":") must correspond to a portion of a user's DN (unless " For example, if the authenticated user's DN in LDAP is in the following form:
that user would get assigned to the ALL_STUDENTS DSpace group for the remainder of their current session. However, if that same user later graduates and is employed by the university, their DN in LDAP may change to:
Upon logging into DSpace after that DN change, the authenticated user would now be assigned to the ALL_EMPLOYEES DSpace group for the remainder of their current session. Note: This option can be used independently from the login.specialgroup option, which will put all LDAP users into a single DSpace group. Both options may be used together. | ||||||
Property: | authentication-ldap.login.groupmap.attribute | ||||||
Example Value: | authentication-ldap.login.groupmap.attribute = group | ||||||
Informational Note: | The value of the "
For example:
The above would ensure that any authenticated users where their LDAP "group" attribute equals "mathematics" would be added to the DSpace Group named "Mathematics_Group" for the remainder of their current session. However, if that same user logged in later with a new LDAP "group" value of "computer science", he/she would no longer be a member of the "Mathematics_Group" in DSpace. |
As every LDAP is different, configuring your DSpace to communicate with your LDAP can sometimes be a challenge. We recommend using third-party LDAP tools to test your LDAP connection / username / password, and perform sample searches to better understand what information is being returned from your local LDAP. This will help ensure that LDAP configuration goes more smoothly.
One example of such an LDAP tool is the ldapsearch
commandline tool available in most Linux operating systems (e.g. in Debian / Ubuntu it's available in the "ldap-utils" package). Below are some example ldapsearch commands that can be used to determine (and/or debug) specific configurations in your authentication-ldap.cfg
. In the below examples, we've used the names of specific DSpace configurations as placeholders (in square brackets).
Code Block |
---|
# Basic anonymous connection (for VERBOSE, add -v)
ldapsearch -x -H [provider_url]
# Debug a connection error (add -d-1)
# If you are connecting to an LDAPS URL and see connection errors (e.g. "peer cert untrusted or revoked")
# then see below note about "SSL Connection Errors"
ldapsearch -x -H [provider_url] -d-1
# Attempt to connect to [provider_url] as [search.user] (will prompt for search.user's password)
# This doesn't actually perform a query, just ensures that authentication is working
# NOTE: "search.user" is USUALLY either the full user DN (e.g. "cn=dspaceadmin,ou=people,o=myu.edu")
# or "DOMAIN\USERNAME" (e.g. "MYU\DSpaceUser"). The latter is more likely with Windows Active Directory
ldapsearch -x -H [provider_url] -D [search.user] -W
# Attempt to list the first 100 users in a given [search_context], returning the "cn", "mail" and "sn" fields for each
ldapsearch -x -H [provider_url] -D [search.user] -W -b [search_context] -z 100 cn mail sn
# Attempt to find the first 100 users whose [id_field] starts with the letter "t", returning the [id_field], "cn", "mail" and "sn" fields for each
ldapsearch -x -H [provider_url] -D [search.user] -W -b [search_context] -z 100 -s sub "([id_field]=t*)" [id_field] cn mail sn |
SSL Connection Errors: If you are using ldapsearch with an LDAPS connection (secure connection), you may receive "peer cert untrusted or revoked" errors if the LDAP SSL certificate is self-signed. You can temporarily tell LDAP to accept any security certificate by setting TLS_REQCERT allow
in your ldapsearch's ldap.conf
file. Be sure to remove this setting however after you are done testing!
Code Block |
---|
# FOR TESTING ONLY! This setting disables the check for a valid LDAP Server security certificate,
# which is considered a security issue for production LDAP setups. Setting this to "allow" tells
# the LDAP client to accept any security certificates that it cannot verify or validate.
TLS_REQCERT allow |
More information on this SSL workaround can be found at:
...