Versions Compared

Old Version 14

changes.mady.by.user Hrafn Malmquist

Saved on

compared with

New Version Current

changes.mady.by.user Mark H. Wood

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed "netted" -> "NetID"

...

Existing Authentication Methods include

...

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.

...

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.

...

Configuration File:

[dspace]/config/modules/authentication-shibboleth.cfg

Property:

authentication-shibboleth.lazysession

Example Value:

authentication-shibboleth.lazysession = true

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:

authentication-shibboleth.lazysession.loginurl

Example Value:

authentication-shibboleth.lazysession.loginurl = /Shibboleth.sso/Login

Informational Note:

The url to start a shibboleth session (only for lazy sessions). Generally this setting will be "/Shibboleth.sso/Login"

Property:

authentication-shibboleth.lazysession.secure

Example Value:

authentication-shibboleth.lazysession.secure = true

Informational Note:

Force HTTPS when authenticating (only for lazy sessions). Generally this is recommended to be "true".

Property:

authentication-shibboleth.netid-header

Example Value:

authentication-shibboleth.netid-header = SHIB-NETID

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:

authentication-shibboleth.email-header

Example Value:

authentication-shibboleth.email-header = SHIB-MAIL

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:

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

Example Value:

authentication-shibboleth.email-use-tomcat-remote-user = false

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:

authentication-shibboleth.reconvert.attributes

Example Valueauthentication-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:

authentication-shibboleth.autoregister

Example Value:

authentication-shibboleth.autoregister = true

Informational Note:

Should we allow new users to be registered automatically?

Property:

authentication-shibboleth.sword.compatibility

Example Value:

authentication-shibboleth.sword.compatibility = false

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.
WARNING: If you enable this option while ALSO having "PasswordAuthentication" enabled, then you should ensure that "PasswordAuthentication" is listed prior to "ShibAuthentication" in your authentication.cfg file. Otherwise, ShibAuthentication will be used to authenticate all of your users INSTEAD OF PasswordAuthentication.

Property:

authentication-shibboleth.firstname-header

Example Value:

authentication-shibboleth.firstname-header = SHIB-GIVENNAME

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:

authentication-shibboleth.lastname-header

Example Value:

authentication-shibboleth.lastname-header = SHIB-SN

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:

authentication-shibboleth.eperson.metadata

Example Value:


Code Block
authentication-shibboleth.eperson.metadata = \
 SHIB-telephone => phone, \
 SHIB-cn => cn


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:

authentication-shibboleth.eperson.metadata.autocreate

Example Value:

authentication-shibboleth.eperson.metadata.autocreate = true

Informational Note:

If the eperson metadata field is not found, should it be automatically created?

Property:

authentication-shibboleth.role-header

Example Value:

authentication-shibboleth.role-header = SHIB-SCOPED-AFFILIATION

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:

authentication-shibboleth.role-header.ignore-scope

Example Value:

authentication-shibboleth.role-header.ignore-scope = true

Informational Note:

Weather to ignore the attribute's scope (everything after the @ sign for scoped attributes)

Property:

authentication-shibboleth.role-header.ignore-value

Example Value:

authentication-shibboleth.role-header.ignore-value = false

Informational Note:

Weather to ignore the attribute's value (everything before the @ sign for scoped attributes)

Property:

authentication-shibboleth.role.[affiliation-attribute]

Example Value:


Code Block
authentication-shibboleth.role.faculty = Faculty, Member
authentication-shibboleth.role.staff = Staff, Member
authentication-shibboleth.role.student = Students, Member


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

...

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.

...

Configuration File:

[dspace]/config/modules/authentication-ldap.cfg

Property:

authentication-ldap.enable

Example Value:

authentication-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:

authentication-ldap.autoregister

Example Value:

authentication-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.

Property:

authentication-ldap.provider_url

Example Value:

authentication-ldap.provider_url = ldap://ldap.myu.edu/o=myu.edu\,ou=mydept

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:

authentication-ldap.starttls

Example Value:authentication-ldap.starttls = false
Informational Note:

Should we issue StartTLS after establishing TCP connection in order to initiate an encrypted connection?
Note: This (TLS) is different from LDAPS:

  • TLS is a tunnel for plain LDAP and is typically recognized on the same port (standard LDAP port: 389)
  • LDAPS is a separate protocol, deprecated in favor of the standard TLS method. (standard LDAPS port: 636)

Property:

authentication-ldap.id_field

Example Value:

authentication-ldap.id_field = uid

Explanation:

This is the unique identifier field in the LDAP directory where the username is stored. (This field has no default value)

Property:

authentication-ldap.object_context

Example Value:

authentication-ldap.object_context = ou=people\,o=myu.edu

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 uid=username\,ou=people\,o=myu.edu. You will need to modify this to match your LDAP configuration. (This field has no default value)

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 "search.user" or "search.anonymous")

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:

authentication-ldap.search_context

Example Value:

authentication-ldap.search_context = ou=people

Informational Note:

This is the search context used when looking up a user's LDAP object to retrieve their data for autoregistering. With autoregister=true, when a user authenticates without an EPerson object we search the LDAP directory to get their name (id_field) and email address (email_field) 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 search_context is the same as the object_context parameter. But again this depends on your LDAP server configuration. (This field has no default value, and it MUST be specified when either search.anonymous=true or search.user is specified)

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:

authentication-ldap.email_field

Example Value:

authentication-ldap.email_field = mail

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 netid_email_domain, when specified)

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 email_field), you can use the following field to specify your email domain. This value is appended to the netid (id_field) in order to make an email address (which is then stored in the DSpace EPerson). For example, a netid of 'user' and netid_email_domain as @example.com would set the email of the user to be user@example.com

Please note: this field will only be used if "email_field" is unspecified OR the user in question has no email address stored in LDAP. If both "email_field" and "netid_email_domain" are unspecified, then the "id_field" will be used as the email address.

Property:

authentication-ldap.surname_field

Example Value:

authentication-ldap.surname_field = sn

Informational Note:

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

Property:

authentication-ldap.givenname_field

Example Value:

authentication-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. (This field has no default value)

Property:

authentication-ldap.phone_field

Example Value:

authentication-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. (This field has no default value)

Property:

authentication-ldap.login.specialgroup

Example Value:

authentication-ldap.login.specialgroup = group-name

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).
This is useful if you want a DSpace Group made up of all internal authenticated users. This DSpace Group can then be used to bestow special permissions on any users who have authenticated via LDAP (e.g. you could allow anyone authenticated via LDAP to view special, on campus only collections or similar)

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 "login.group.attribute" is specified..please see below). The right part of the value corresponds to the name of an existing DSpace group.

For example, if the authenticated user's DN in LDAP is in the following form:

cn=jdoe,OU=Students,OU=Users,dc=example,dc=edu

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:

cn=jdoe,OU=Employees,OU=Users,dc=example,dc=edu

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 "authentication-ldap.login.groupmap.attribute" should specify the name of a single LDAP attribute. If this property is uncommented, it changes the meaning of the left part of "authentication-ldap.login.groupmap.*" (see above) as follows:

  • If the authenticated user has this LDAP attribute, look up the value of this LDAP attribute in the left part (before the ":") of the authentication-ldap.login.groupmap.* value
  • If that LDAP value is found in any "authentication-ldap.login.groupmap.*" field, assign this authenticated user to the DSpace Group specified by the right part (after the ":") of the authentication-ldap.login.groupmap.* value.

For example:

  • authentication-ldap.login.groupmap.attribute = group
  • authentication-ldap.login.groupmap.1 = mathematics:Mathematics_Group

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.

...

Hierarchical LDAP Authentication shares all the above standard LDAP configurations, but has some additional settings.

...