Versions Compared

Old Version 3

changes.mady.by.user Robin Taylor

Saved on

compared with

New Version 4

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Authentication Plugins

Table of Contents
minLevel2
outlinetrue
stylenone

Stackable Authentication Method(s

...

)

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.

...

  1. A request is received from an end-user's browser that, if fulfilled, would lead to an action requiring authorization taking place.
  2. If the end-user is already authenticated:
    • If the end-user is allowed to perform the action, the action proceeds
    • If the end-user is NOT allowed to perform the action, an authorization error is displayed.
    • If the end-user is NOT authenticated, i.e. is accessing DSpace anonymously:
  3. The parameters etc. of the request are stored.
  4. The Web UI's startAuthentication method is invoked.
  5. First it tries all the authentication methods which do implicit authentication (i.e. they work with just the information already in the Web request, such as an X.509 client certificate). If one of these succeeds, it proceeds from Step 2 above.
  6. If none of the implicit methods succeed, the UI responds by putting up a "login" page to collect credentials for one of the explicit authentication methods in the stack. The servlet processing that page then gives the proffered credentials to each authentication method in turn until one succeeds, at which point it retries the original operation from Step 2 above.
    Please see the source files AuthenticationManager.java and AuthenticationMethod.java for more details about this mechanism.

Shibboleth Authentication Configuration Settings

Detailed instructions for installing Shibboleth on DSpace may be found at https://mams.melcoe.mq.edu.au/zope/mams/pubs/Installation/dspace15.

...

  1. By explicitly specifying to the user which attribute (header) carries the email address.
  2. By turning on the user-email-using-tomcat=true which means the software will attempt to acquire the user's email from Tomcat.
    The first option takes Precedence when specified. both options can be enabled to allow for fallback.

    Property:

    authentication.shib.email-header

    Example Value:

    authentication.shib.email-header = MAIL

    Informational Note:

    The option specifies that the email comes from the mentioned header. This value is CASE-Sensitive.

    Property:

    authentication.shib.firstname-header

    Example Value:

    authentication.shib.firstname-header = SHIB-EP-GIVENNAME

    Informational Note:

    Optional. Specify the header that carries the user's first name. This is going to be used for the creation of new-user.

    Property:

    authentication.shib.lastname-header

    Example Value:

    authentication.shib.lastname-header = SHIB-EP-SURNAME

    Informational Note:

    Optional. Specify the header that carries user's last name. This is used for creation of new user.

    Property:

    authentication.shib.email-use-tomcat-remote-user

    Example Value:

    authentication.shib.email-use-tomcat-remote-user = true

    Informational Note:

    This option forces the software to acquire the email from Tomcat.

    Property:

    authentication.shib.autoregister

    Example Value:

    authentication.shib.autoregister = true

    Informational Note:

    Option will allow new users to be registered automatically if the IdP provides sufficient information (and the user does not exist in DSpace).

    Property:

    Code Block
    authentication.shib.role-header
authentication.shib-role.header.ignore-scope

    Example Value:

    Code Block
    authentication.shib.role-header = Shib-EP-ScopedAffiliation
authentication.shib-role.header.ignore-scope = true

    or

    Code Block
    authentication.shib.role-header = Shib-EP-UnscopedAffiliation
 authentication.shib-role.header.ignore-scope = false

    Informational Note:

    These two options specify which attribute that is responsible for providing user's roles to DSpace and unscope the attributes if needed. When not specified, it is defaulted to 'Shib-EP-UnscopedAffiliation', and ignore-scope is defaulted to 'false'. The value is specified in AAP.xml (Shib 1.3.x) or attribute-filter.xml (Shib 2.x). The value is CASE-Sensitive. The values provided in this header are separated by semi-colon or comma. If your service provider (SP) only provides scoped role header, you need to set authentication.shib.role-header.ignore-Scope as 'true'. For example if you only get Shib-EP-ScopedAffiliation instead of Shib-EP-ScopedAffiliation, you name to make your settings as in the example value above.

    Property:

    authentication.shib.default-roles

    Example Value:

    authentication.shib.default-roles = Staff, Walk-ins

    Informational Note:

    When user is fully authN or IdP but would not like to release his/her roles to DSpace (for privacy reasons?), what should the default roles be given to such user. The values are separated by semi-colon or comma.

    Property:

    Code Block
    authentication.shib.role.Senior\ Researcher
authentication.shib.role.Librarian

    Example Value:

    Code Block
    authentication.shib.role.Senior\ Researcher = Researcher, Staff
authentication.shib.role.Librarian = Administrator

    Informational Note:

    The following mappings specify role mapping between IdP and Dspace. The left side of the entry is IdP's role (prefixed with 'authentication.shib.role.') which will be mapped to the right entry from DSpace. DSpace's group as indicated on the right entry has to EXIST in DSpace, otherwise user will be identified as 'anonymous'. Multiple values on the right entry should be separated by comma. The values are CASE-Sensitive. Heuristic one-to-one mapping will be done when the IdP groups entry are not listed below (i.e. if 'X' group in IdP is not specified here, then it will be mapped to 'X' group in DSpace if it exists, otherwise it will be mapped to simply 'anonymous'). Given sufficient demand, future release could support regex for the mapping special characters need to be escaped by '\'

Authentication by Password

The default method org.dspace.authenticate.PasswordAuthentication has the following properties:

  • Use of inbuilt 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.

X.509 Certificate Authentication

The X.509 authentication method uses an X.509 certificate sent by the client to establish his/her identity. It requires the client to have a personal Web certificate installed on their browser (or other client software) which is issued by a Certifying Authority (CA) recognized by the web server.

...

  1. 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 one of 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.
  2. 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 authentication.x509.autoregister configuration property to true. This lets you automatically accept all users with valid personal certificates. The default is false.

Example of a Custom Authentication Method

Also included in the source is an implementation of an authentication method used at MIT, edu.mit.dspace.MITSpecialGroup. This does not actually authenticate a user, it only adds the current user to a special (dynamic) group called 'MIT Users' (which must be present in the system!). This allows us to create authorization policies for MIT users without having to manually maintain membership of the MIT users group.

...

You can create your own custom authentication method and add it to the stack. Use the most similar existing method as a model, e.g. org.dspace.authenticate.PasswordAuthentication for an "explicit" method (with credentials entered interactively) or org.dspace.authenticate.X509Authentication for an implicit method.

Configuring IP Authentication

You can enable IP authentication by adding its method to the stack in the DSpace configuration, e.g.:

...

  • If the Groupname contains blanks you must escape the, e.g. Department\ of\ Statistics
  • If your DSpace installation is hidden behind a web proxy, remember to set the 'useProxies' configuration option within the 'Logging' section of dspace.cfg to use the IP address of the user rather than the IP address of the proxy server.

Configuring LDAP Authentication

You can enable LDAP authentication by adding its method to the stack in the DSpace configuration, e.g.

...

Standard LDAP Configuration

Property:

ldap.enable

Example Value:

ldap.enable = false

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:

ldap.provider_url

Example Value:

ldap.provider_url = ldap://ldap.myu.edu/o=myu.edu

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.

Property:

ldap.id_field

Example Value:

ldap.id_field = uid

Explanation:

This is the unique identifier field in the LDAP directory where the username is stored.

Property:

ldap.object_context

Example Value:

ldap.object_context = ou=people, o=myu.edu

Informational Note:

This is the object context used when authenticating the user. It is appended to the ldap.id_field and username. For example uid=username,ou=people,o=myu.edu. You will need to modify this to match your LDAP configuration.

Property:

ldap.search_context

Example Value:

ldap.search_context = ou=people

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c6fc8afaa9dc9143-fcabbc52-46174edd-a3089886-dc2278bacd7618fa4a111c71"><ac:plain-text-body><![CDATA[

Informational Note:

This is the search context used when looking up a user's LDAP object to retrieve their data for autoregistering. With ldap.autoregister turned on, when a user authenticates without an EPerson object we search the LDAP directory to get their name and email address so that we can create one for them. So after we have authenticated against uid=username,ou=people,o=byu.edu we now search in ou=people for filtering on [uid=username]. Often the ldap.search_context is the same as the ldap.object_context parameter. But again this depends on your LDAP server configuration.

]]></ac:plain-text-body></ac:structured-macro>

Property:

ldap.email_field

Example Value:

ldap.email_field = mail

Informational Note:

This is the LDAP object field where the user's email address is stored. "mail" is the default and the most common for LDAP servers. If the mail field is not found the username will be used as the email address when creating the eperson object.

Property:

ldap.surname_field

Example Value:

ldap.surname_field = sn

Informational Note:

This is the LDAP object field where the user's last name is stored. "sn" is the default and is the most common for LDAP servers. If the field is not found the field will be left blank in the new eperson object.

Property:

ldap.givenname_field

Example Value:

ldap.givenname_field = givenName

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.

Property:

ldap.phone_field

Example Value:

ldap.phone_field = telephoneNumber

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.

Property:

webui.ldap.autoregister

Example Value:

webui.ldap.autoregister = true

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.

LDAP Users Group

Property:

ldap.login.specialgroup

Example Value:

ldap.login.specialgroup = group-name

Informational Note:

If required, a group name can be given here, and all users who log into LDAP will automatically become members of this group. This is useful if you want a group made up of all internal authenticated users. (Remember to log on as the administrator, add this to the "Groups" with read rights).

...