Versions Compared

Old Version 14

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version Current

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add note on enabling ORCID auth

...

An authentication method is a class that implements the interface org.dspace.authenticate.AuthenticationMethod. It authenticates a user by evaluating the credentials (e.g. username and password) he or she presents and checking that they are valid.

The basic authentication procedure in the DSpace Web UI is this:

...

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

...

.authenticate.AuthenticationMethod. It authenticates a user by evaluating the credentials (e.g. username and password) he or she presents and checking that they are valid.

Authentication by Password

...

  • 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.sending login information to the "/api/authn/login" endpoint of the REST API, in order to obtain a JSON Web Token.  This JSON Web token must be sent on every later request which requires authentication.
  • 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.

...

Configuration File:

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

Property:

user.registration

Example Value:user.registration = false
Informational Note:This option allows you to disable all self-registration.  When set to "false", no one will be able to register new accounts with your system.  Default is "true".

Property:

authentication-password.domain.valid

Example Value:

authentication-password.domain.value = @mit.edu, .ac.uk

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. (This setting only works when user.registration=true)

Property:

authentication-password.login.specialgroup

Example Value:

authentication-password.login.specialgroup = My DSpace Group

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:

authentication-password.digestAlgorithm

Example Value:

authentication-password.digestAlgorithm = SHA-512

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.

Property:

authentication-password.regex-validation.pattern

Example Value:

authentication-password.regex-validation.pattern = ^.{8\,}$

Informational Note:

This option specifies a regular expression which all new passwords MUST validate against.  By default, DSpace just requires a new password to be 8 or more characters (see above example value). However, sites can modify this regex in order to require more robust passwords of all users.  One example of a complex rule is:

authentication-password.regex-validation.pattern = ^(?=.*?[a-z])(?=.*?[A-Z])(?=\\S*?[0-9])(?=\\S*?[!?$@#$%^&+=]).{8\,15}$

This example requires all users to adopt a more complex password:

  • (?=.*?[a-z]) - the password must contain at least one lowercase character

  • (?=.*?[A-Z]) - the password must contain at least one uppercase character

  • (?=\\S*?[0-9]) - the password must contain at least one numeric character

  • (?=\\S*?[!?$@#$%^&+=]) - the password must contain at least one of the following special character: !?$@#$%^&+=

  • .{8\,15} - the password must be at least 8 and at most 15 characters long  (NOTE: the "\," is required to escape the comma, which is a special character)

...

Configuration File:

[dspace]/config/modules/authentication.cfg

Property:

plugin.sequence.org.dspace.authenticate.AuthenticationMethod

Example Value:


plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.OidcAuthentication

(NOTE: This setting may be repeated to support multiple AuthenticationMethods)

(WARNING: it's easy to miss, the "camel case" for OidcAuthentication might catch you off guard. It's important to not use OIDCAuthentication in this line, because that class does not exist. Case matters.

...

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 (see section on roll based mapping section above)Shibboleth header holding the user's Shibboleth roles.  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 Whether to ignore the attributeroles' s scope scopes (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 Whether to ignore the attributeroles' s value values (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.

Property:

authentication-shibboleth.default-roles

Example Value:

authentication-shibboleth.default-roles = GenericUser

Informational Note:

These roles are assumed if no roles were sent by Shibboleth or there was no header with name matching the value of authentication-shibboleth.role_header.  May be repeated to provide multiple default roles.

LDAP Authentication

Introduction to LDAP specific terminology

...

Configuration File:

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

Property:

authentication-ldap.search_scope

Example Value:

authentication-ldap.search_scope = 2

Informational Note:

This is the search scope value for the LDAP search during autoregistering (autoregister=true). This will depend on your LDAP server setup, and is only really necessary if your users are spread out across a hierarchical tree on your LDAP server. This value must be one of the following integers corresponding to the following values:
 object scope : 0 
 one level scope : 1 
 subtree scope : 2

Please note that "search_context" in the LDAP configurations must also be specified.

Property:

authentication-ldap.search.anonymous

Example Value:

authentication-ldap.search.anonymous = true

Informational Note:

If true, DSpace will anonymously search LDAP (in the "search_context") for the DN of the user trying to login to DSpace. This setting is "false" by default. By default, DSpace will either use "search.user" to authenticate for the LDAP search (if search.user is specified), or will use the "object_context" value to create the user's DN.

Property:

authentication-ldap.search.user
authentication-ldap.search.password

Example Value:

authentication-ldap.search.user = cn=admin\,ou=people\,o=myu.edu
authentication-ldap.search.password = password

Informational Note:

The full DN and password of a user allowed to connect to the LDAP server and search (in the "search_context") for the DN of the user trying to login. By default, if unspecified, DSpace will either search LDAP anonymously for the user's DN (when search.anonymous=true), or will use the "object_context" value to create the user's DN.

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. "\,"

ORCID Authentication

Enabling ORCID Authentication

Note

Enabling ORCID Authentication requires also enabling Configurable Entities and Researcher Profiles

To enable ORCID Authentication, see the documentation for enabling the ORCID Integration.  You do not need to enable ORCID synchronization, but you currently must enable Researcher Profiles and Configurable Entities.

IP Authentication

Enabling IP Authentication

...