Page History
...
Since many institutions and organizations have existing authentication systems, DSpace has been designed to allow these to be easily integrated into an existing authentication infrastructure. It keeps a series, or "stack", of authentication methods, so each one can be tried in turn. This makes it easy to add new authentication methods or rearrange the order without changing any existing code. You can also share authentication code with other sites.
Configuration File: |
| ||
---|---|---|---|
Property: |
| ||
Example Value: |
|
The configuration property plugin.sequence.org.dspace.authenticate.AuthenticationMethod
defines the authentication stack. It is a comma-separated list of class names. Each of these classes implements a different authentication method
, or way of determining the identity of the user. They are invoked in the order specified until one succeeds.
...
However, to enable Authentication by Password, you must ensure the org.dspace.authenticate.PasswordAuthentication
class is listed as one of the AuthenticationMethods in the following configuration:
Configuration File: |
| ||
---|---|---|---|
Property: |
| ||
Example Value: |
|
Configuring Authentication by Password
The default method org.dspace.authenticate.PasswordAuthentication
has the following properties:
- Use of inbuilt built-in e-mail address/password-based log-in. This is achieved by forwarding a request that is attempting an action requiring authorization to the password log-in servlet,
/password-login
. The password log-in servlet (org.dspace.app.webui.servlet.PasswordServlet
) contains code that will resume the original request if authentication is successful, as per step 3. described above. - Users can register themselves (i.e. add themselves as e-people without needing approval from the administrators), and can set their own passwords when they do this
- Users are not members of any special (dynamic) e-person groups
- You can restrict the domains from which new users are able to register. To enable this feature, uncomment the following line from dspace.cfg:
authentication.password.domain.valid = example.com
Example options might be '@example.com
' to restrict registration to users with addresses ending in @example.com, or '@example.com, .ac.uk
' to restrict registration to users with addresses ending in @example.com or with addresses in the .ac.uk domain.
A full list of all available Password Authentication Configurations:
Configuration File: |
|
---|---|
Property: |
|
Example Value: |
|
Informational Note: | This option allows you to limit self-registration to email addresses ending in a particular domain value. The above example would limit self-registration to individuals with "@mit.edu" email addresses and all ".ac.uk" email addresses. |
Property: |
|
Example Value: |
|
Informational Note: | This option allows you to automatically add all password authenticated user sessions to a specific DSpace Group (the group must exist in DSpace) for the remainder of their logged in session. |
Property: |
|
Example Value: |
|
Informational Note: | This option specifies the hashing algorithm to be used in converting plain-text passwords to more secure password digests. The example value is the default. You may select any digest algorithm available through java.security.MessageDigest on your system. At least MD2, MD5, SHA-1, SHA-256, SHA-384, and SHA-512 should be available, but you may have installed others. Most sites will not need to adjust this. |
Shibboleth Authentication
...
To enable Shibboleth Authentication, you must ensure the org.dspace.authenticate.ShibAuthentication
class is listed as one of the AuthenticationMethods in the following configuration:
Configuration File: |
| ||
---|---|---|---|
Property: |
| ||
Example Value: |
|
Configuring Shibboleth Authentication
...
Code Block |
---|
#### SAMPLE MOD_SHIB CONFIGURATION FOR APACHE2 (it may require local modifications based on your Apache setup) #### # While this sample VirtualHost is for HTTPS requests (recommended for Shibboleth, obviously), # you may also need/want to create one for HTTP (*:80) <VirtualHost *:443> ... # PLEASE NOTE: We have omitted many Apache settings (ServerName, LogLevel, SSLCertificateFile, etc) # which you may need/want to add to your VirtualHost # As long as Shibboleth module is installed, enable all Shibboleth/mod_shib related settings <IfModule mod_shib> # Shibboleth recommends turning on UseCanonicalName # See "Prepping Apache" in https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig UseCanonicalName On # Most DSpace instances will want to use Shibboleth "Lazy Session", which ensures that users # can access DSpace without first authenticating via Shibboleth. # This section turns on Shibboleth "Lazy Session". Also ensures that once they have authenticated # (by accessing /Shibboleth.sso/Login path), then their Shib session is kept alive <Location /> AuthType shibboleth ShibRequireSession Off require shibboleth # If your "shibboleth2.xml" file specifies an <ApplicationOverride> setting for your # DSpace Service Provider, then you may need to tell Apache which "id" to redirect Shib requests to. # Just uncomment this and change the value "my-dspace-id" to the associated @id attribute value. #ShibRequestSetting applicationId my-dspace-id </Location> # If a user attempts to access the DSpace shibboleth login page, force them to authenticate via Shib <Location "/shibboleth-login"> AuthType shibboleth ShibRequireSession On # Please note that setting ShibUseHeaders to "On" is a potential security risk. # You may wish to set it to "Off". See the mod_shib docs for details about this setting: # https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions # Here's a good guide to configuring Apache + Tomcat when this setting is "Off": # https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications ShibUseHeaders On require valid-user </Location> # Ensure /Shibboleth.sso path (in Apache) can be accessed # By default it may be inaccessible if your Apache security is tight. <Location "/Shibboleth.sso"> Order deny,allow Allow from all # Also ensure Shibboleth/mod_shib responds to this path SetHandler shib </Location> # Finally, you may need to ensure requests to /Shibboleth.sso are NOT redirected # to Tomcat (as they need to be handled by mod_shib instead). # NOTE: THIS SETTING IS LIKELY ONLY NEEDED IF YOU ARE USING mod_proxy TO REDIRECT # ALL REQUESTS TO TOMCAT (e.g. ProxyPass / ajp://localhost:8009/) # ProxyPass /Shibboleth.sso ! </IfModule> ... </VirtualHost> |
Sample shibboleth2.xml Configuration
...
Code Block |
---|
<!-- *** Sample Shibboleth Settings for http://www.testshib.org/ *** --> <!-- This provides a simple sample of how you could configure --> <!-- shibboleth2.xml for DSpace sites. --> <!-- TO ENABLE: You'd need to specify "applicationId" as "testshib" in --> <!-- your mod_shib settings, e.g. --> <!-- <Location /> --> <!-- ... --> <!-- ShibRequestSetting applicationId testshib --> <!-- </Location> --> <ApplicationOverride id="testshib" entityID="http://mydspace.edu/shibboleth" REMOTE_USER="principal-id"> <!-- We'll use a TEST IdP, hosted by the awesome http://www.testshib.org/ testing service. --> <!-- See also: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO --> <Sessions lifetime="28800" timeout="3600" checkAddress="false" relayState="ss:mem" handlerSSL="true"> <SSO entityID="https://idp.testshib.org/idp/shibboleth"> SAML2 SAML1 </SSO> </Sessions> <!-- Loads and trusts a metadata file that describes the IdP and how to communicate with it. --> <!-- By default, metadata is retrieved from the TEST IdP at http://www.testshib.org --> <!-- and is cached in a local file named "testshib-idp-metadata.xml". --> <!-- See also: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider --> <MetadataProvider type="XML" uri="http://www.testshib.org/metadata/testshib-providers.xml" backingFilePath="testshib-idp-metadata.xml" reloadInterval="180000"/> </ApplicationOverride> |
...
DSpace Shibboleth Configuration Options
...
If you are currently using Email based authentication (either 1 or 2) and want to upgrade to NetID based authentication then there is an easy path. Simply enable shibboleth to pass the NetID attribute and set the netid-header below to the correct value. When a user attempts to log in to DSpace first DSpace will look for an EPerson with the passed NetID, however when this fails DSpace will fall back to email based authentication. Then DSpace will update the user's EPerson account record to set their netted NetID so all future authentications for this user will be based upon nettedNetID. One thing to note is that DSpace will prevent an account from switching NetIDs. If an account all ready already has a NetID set and then they try and authenticate with a different NetID the authentication will fail.
...
The values extracted (a user may have multiple roles) will be used to look up which groups to place the user into. The groups are defined as "authentication-shibboleth.role.<role-name>" which is a comma separated list of DSpace groups.
Configuration File: |
|
---|---|
Property: |
|
Example Value: |
|
Informational Note: | Whether to use lazy sessions or active sessions. For more DSpace instances, you will likely want to use lazy sessions. Active sessions will force every user to authenticate via Shibboleth before they can access your DSpace (essentially resulting in a "dark archive"). |
Property: |
|
Example Value: | authentication-shibboleth. |
Informational Note: | The url to start a shibboleth session (only for lazy sessions). Generally this setting will be "/Shibboleth.sso/Login" |
Property: |
|
Example Value: |
|
Informational Note: | Force HTTPS when authenticating (only for lazy sessions). Generally this is recommended to be "true". |
Property: |
|
Example Value: |
|
Informational Note: | The HTTP header where shibboleth will supply a user's NetID. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file. |
Property: |
|
Example Value: |
|
Informational Note: | The HTTP header where the shibboleth will supply a user's email address. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file. |
Property: |
|
Example Value: |
|
Informational Note: | Used when a netid or email headers are not available should Shibboleth authentication fall back to using Tomcat's remote user feature? Generally this is not recommended. See the "Authentication Methods" section above. |
Property: |
|
Example Value | authentication-shibboleth.reconvert.attributes = false |
Informational Note: | Shibboleth attributes are by default UTF-8 encoded. Some servlet container automatically converts the attributes from ISO-8859-1 (latin-1) to UTF-8. As the attributes already were UTF-8 encoded it may be necessary to reconvert them. If you set this property true, DSpace converts all shibboleth attributes retrieved from the servlet container from UTF-8 to ISO-8859-1 and uses the result as if it were UTF-8. This procedure restores the shibboleth attributes if the servlet container wrongly converted them from ISO-8859-1 to UTF-8. Set this true, if you notice character encoding problems within shibboleth attributes. |
Property: |
|
Example Value: |
|
Informational Note: | Should we allow new users to be registered automatically? |
Property: |
|
Example Value: |
|
Informational Note: | SWORD compatibility will allow this authentication method to work when using SWORD. SWORD relies on username and password based authentication and is entirely incapable of supporting shibboleth. This option allows you to authenticate username and passwords for SWORD sessions with out adding another authentication method onto the stack. You will need to ensure that a user has a password. One way to do that is to create the user via the create-administrator command line command and then edit their permissions. |
Property: |
|
Example Value: |
|
| |
Informational Note: | The HTTP header where the shibboleth will supply a user's given name. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file. |
Property: |
|
---|---|
Example Value: |
|
| |||
Informational Note: | The HTTP header where the shibboleth will supply a user's surname. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file. | ||
Property: |
| ||
---|---|---|---|
Example Value: |
| ||
Informational Note: | Additional user attributes mapping, multiple attributes may be stored for each user. The left side is the Shibboleth-based metadata Header and the right side is the eperson metadata field to map the attribute to. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | If the eperson metadata field is not found, should it be automatically created? | ||
Property: |
| ||
Example Value: |
|
|
| |
Informational Note: | The shibboleth header to do role-based mappings |
. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file. See the Role-based Groups section above for more info. | |||
Property: |
| ||
---|---|---|---|
Example Value: |
| ||
Informational Note: | Weather to ignore the attribute's scope (everything after the @ sign for scoped attributes) | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Weather to ignore the attribute's value (everything before the @ sign for scoped attributes) | ||
Property: |
| ||
Example Value: |
|
|
| |
Informational Note: | Mapping of affiliation values to DSpace groups. See the |
Role-based Groups |
section above for more info. |
LDAP Authentication
...
Introduction to LDAP
...
specific terminology
If you are unfamiliar with LDAP, the following introduction to some of its terminology might come in handy:
https://stackoverflow.com/questions/18756688/what-are-cn-ou-dc-in-an-ldap-search
Enabling LDAP Authentication
To enable LDAP Authentication, you To enable LDAP Authentication, you must ensure the org.dspace.authenticate.LDAPAuthentication
class is listed as one of the AuthenticationMethods in the following configuration:
Configuration File: |
| ||
---|---|---|---|
Property: |
| ||
Example Value: |
|
Configuring LDAP Authentication
...
If you want to give any special privileges to LDAP users, create a stackable authentication method to automatically put people who have a netid into a special group. You might also want to give certain email addresses special privileges. Refer to the Custom Authentication Code section below for more information about how to do this.
Here is an explanation of each of the different LDAP configuration parameters:
Note | ||
---|---|---|
| ||
NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. As some LDAP configuration may contain commas, you must be careful to escape any required commas by adding a backslash (\) before each comma, e.g. "\,". The configuration reference for authentication-ldap.cfg has been updated below with additional examples. |
Here is an explanation of each of the different LDAP configuration parameters:
Configuration File:
[dspace]/config/modules/authentication-ldap.cfg
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) |
Property:
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 |
Property:
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: |
authentication-ldap.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. |
Debugging LDAP connection and configuration
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:
- http://www.bind9.net/manual/openldap/2.3/tls.html
- http://muzso.hu/2012/03/29/how-to-configure-ssl-aka.-ldaps-for-libnss-ldap-auth-client-config-in-ubuntu
Enabling Hierarchical LDAP Authentication
...
You can optionally specify the search scope. If anonymous access is not enabled on your LDAP server, you will need to specify the full DN and password of a user that is allowed to bind in order to search for the users.
Configuration File: |
|
---|---|
Property: |
|
Example Value: |
|
Informational Note: | This is the search scope value for the LDAP search during autoregistering ( Please note that " |
Property: |
|
Example Value: |
|
Informational Note: | If true, DSpace will anonymously search LDAP (in the " |
Property: |
|
Example Value: |
|
Informational Note: | The full DN and password of a user allowed to connect to the LDAP server and search (in the " 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. "\," |
IP Authentication
Enabling IP Authentication
To enable IP Authentication, you must ensure the org.dspace.authenticate.IPAuthentication
class is listed as one of the AuthenticationMethods in the following configuration:
Configuration File: |
| ||
---|---|---|---|
Property: |
| ||
Example Value: |
|
Configuring IP Authentication
Configuration File: |
|
---|
Once enabled, you are then able to map DSpace groups to IP addresses in authentication-ip.cfg
by setting ip.GROUPNAME = iprange[, iprange ...]
, e.g:
...
- See the HTTPS installation instructions to configure your Web server. If you are using HTTPS with Tomcat, note that the
<Connector>
tag must include the attributeclientAuth="true"
so the server requests a personal Web certificate from the client. Add the
org.dspace.authenticate.X509Authentication
pluginfirst
to the list of stackable authentication methods in the value of the configuration keyplugin.sequence.org.dspace.authenticate.AuthenticationMethod
Configuration File:
[dspace]/config/modules/authentication.cfg
Property:
plugin.sequence.org.dspace.authenticate.AuthenticationMethod
Example Value:
Code Block plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.X509Authentication plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.PasswordAuthentication
Configuring X.509 Certificate Authentication
Configuration File: |
|
---|
You must also configure DSpace with the same CA certificates as the web server, so it can accept and interpret the clients' certificates. It can share the same keystore file as the web server, or a separate one, or a CA certificate in a file by itself. Configure it by oneof these methods, either the Java keystore
Code Block authentication-x509.keystore.path = path to Java keystore file authentication-x509.keystore.password = password to access the keystore
...or the separate CA certificate file (in PEM or DER format):
Code Block authentication-x509.ca.cert = path to certificate file for CA whose client certs to accept.
- Choose whether to enable auto-registration: If you want users who authenticate successfully to be automatically registered as new E-Persons if they are not already, set the
autoregister
configuration property totrue
. This lets you automatically accept all users with valid personal certificates. The default isfalse
.
...