Page History
...
- Authentication by Password (class:
org.dspace.authenticate.PasswordAuthentication
) (DEFAULT) - Open ID Connect (OIDC) Authentication (class:
org.dspace.authenticate.OidcAuthentication)
- Shibboleth Authentication (class:
org.dspace.authenticate.ShibAuthentication
) - LDAP Authentication (class:
org.dspace.authenticate.LDAPAuthentication
) - ORCID Authentication (class:
org.dspace.authenticate.OrcidAuthentication
) - IP Address based Authentication (class:
org.dspace.authenticate.IPAuthentication
) - X.509 Certificate Authentication (class:
org.dspace.authenticate.X509Authentication
)
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:
- A request is received from an end-user's browser that, if fulfilled, would lead to an action requiring authorization taking place.
- 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:
- The parameters etc. of the request are stored.
- The Web UI's
startAuthentication
method is invoked. - 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. - 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 filesAuthenticationManager.java
andAuthenticationMethod.java
for more details about this mechanism.
Authentication by Password
Enabling Authentication by Password
By default, this authentication method is enabled in DSpace.
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:
Authentication by Password
Enabling Authentication by Password
By default, this authentication method is enabled in DSpace.
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 e-mail address/password-based log-in. This is achieved by 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.
A full list of all available Password Authentication Configurations:
Configuration FileConfiguration File: |
| |
---|---|---|
Property: |
| |
Example Value: |
Code Block |
---|
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.PasswordAuthentication |
Configuring 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.
A full list of all available Password Authentication Configurations:
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: |
| ||||
---|---|---|---|---|---|
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. (This setting only works when user.registration=true) | ||||
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. | ||||
Property: |
| ||||
Configuration File: |
| ||||
Property: | |||||
Example Value: |
| 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.Propertyspecifies 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:
| login.specialgroup|||
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. |
Open ID Connect (OIDC) Authentication
Info |
---|
Open ID Connect (OIDC) Authentication is only available in DSpace 7.2 or above. |
Enabling OIDC Authentication
To enable OIDC Authentication, you must ensure the org.dspace.authenticate.OidcAuthentication
class is listed as one of the AuthenticationMethods in the following configuration:
...
Configuration File:
...
[dspace]/config/modules/authentication.cfg
...
Property:
...
plugin.sequence.org.dspace.authenticate.AuthenticationMethod
...
Example Value:
|
(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.
This example requires all users to adopt a more complex password:
|
Open ID Connect (OIDC) Authentication
Info |
---|
Open ID Connect (OIDC) Authentication is only available in DSpace 7.2 or above. |
Enabling OIDC Authentication
To enable OIDC Authentication, you must ensure the org.dspace.authenticate.OidcAuthentication
class is listed as one of the AuthenticationMethods in the following configuration:
Configuration File: |
| |
---|---|---|
Property: |
| |
Example Value: |
(NOTE: This setting may be repeated to support multiple AuthenticationMethods) (WARNING: it's easy to miss, the "camel case" for |
Configuring OIDC Authentication
OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. There are many server implementations of OpenID Connect, including Keycloak and AWS Cognito.
Configuration File: |
|
---|---|
Property: |
|
Example Value: |
|
Informational Note: | (Optional) The root URL of the OpenID Connect server. This is optional, as it's only used to fill out each of the "-endpoint" configs below (see below). |
Property: | authentication-oidc.auth-server-realm |
Example Value: | authentication-oidc.auth-server-realm = dspace-realm |
Informational Note: | (Optional) The realm to authenticate against on the OpenID Connect server. This is optional, as it's only used to fill out each of the "-endpoint" configs below (see below). So, for some setups, it may be easier to configure the "-endpoint" configs directly INSTEAD OF the "auth-server-url" and "auth-server-realm" |
Property: | authentication-oidc.token-endpoint |
Example Value: | authentication-oidc.token-endpoint = ${authentication-oidc.auth-server-url}/auth/realms/${authentication-oidc.auth-server-realm}/protocol/openid-connect/token |
Informational Note: | (Required) The URL of the OIDC Token endpoint. This defaults to using the configured "auth-server-url" and "auth-server-realm" to determine the likely OIDC path for this endpoint (see example above for the default value). However, if that default path is incorrect, you may choose to hardcode the correct URL in this field. |
Property: | authentication-oidc.authorize-endpoint |
Example Value: | authentication-oidc.authorize-endpoint = ${authentication-oidc.auth-server-url}/auth/realms/${authentication-oidc.auth-server-realm}/protocol/openid-connect/auth |
Informational Note: | (Required) The URL of the OIDC Authorize endpoint. This defaults to using the configured "auth-server-url" and "auth-server-realm" to determine the likely OIDC path for this endpoint (see example above for the default value). However, if that default path is incorrect, you may choose to hardcode the correct URL in this field. |
Property: | authentication-oidc.user-info-endpoint |
Example Value: | authentication-oidc.user-info-endpoint = ${authentication-oidc.auth-server-url}/auth/realms/${authentication-oidc.auth-server-realm}/protocol/openid-connect/userinfo |
Informational Note: | (Required) The URL of the OIDC Userinfo endpoint. This defaults to using the configured |
Configuring OIDC Authentication
OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. There are many server implementations of OpenID Connect, including Keycloak and AWS Cognito.
Configuration File:
[dspace]/config/modules/authentication-oidc.cfg
Property:
authentication-oidc.auth-server-url
Example Value:
authentication-oidc.auth-server-url = https://auth.example.com
Informational Note:
So, for some setups, it may be easier to configure the "-endpoint" configs directly INSTEAD OF the
"auth-server-url" and "auth-server-realm" to determine the likely OIDC path for this endpoint (see example above for the default value). However, if that default path is incorrect, you may choose to hardcode the correct URL in this field. | |
Property: | authentication-oidc. |
client- |
id | |
Example Value: | authentication-oidc. |
client- |
id = our- |
dspace |
Informational Note: | ( |
So, for some setups, it may be easier to configure the "-endpoint" configs directly INSTEAD OF the "auth-server-url" and "auth-server-realm"
Required) The registered OIDC client id for our DSpace server's use. No default value. | |
Property: | authentication-oidc.client-secret |
Example Value: | authentication-oidc.client-secret = some-sort-of-hash |
Informational Note: | (Required) The registered OIDC client secret for our DSpace server's use. No default value. |
Property: | authentication-oidc. |
redirect- |
url | |
Example Value: | authentication-oidc. |
redirect- |
url = ${ |
dspace. |
server |
.url}/ |
api/ |
authn/oid | |
Informational Note: | The URL users will be redirected to after a successful login. The example above is the default value, and it usually does not need to be updated. |
Property: | authentication-oidc.scopes |
Example Value: | authentication-oidc. |
scopes = openid,email,profile |
Informational Note: |
The scopes to request from the OIDC server. The example above is the default value | |
Property: | authentication-oidc. |
can-self- |
register |
Example Value: |
authentication-oidc. |
can- |
self-register = true |
Informational Note: |
Specify if the user can self register using OIDC (true|false). If not specified, true is assumed. If this is set to false, then only users with an existing EPerson in DSpace will be able to authenticate through OIDC. When set to true, an EPerson will be automatically created for each person who successfully authenticates through OIDC. | |
Property: | authentication-oidc.user-info |
.email | |
Example Value: | authentication-oidc.user-info |
.email = email |
Informational Note: |
Specify the attribute present in the user info json related to the user's email. The default value is "email" | |
Property: | authentication-oidc.user-info. |
first- |
name | |
Example Value: | authentication-oidc.user-info. |
first- |
name = given_name |
Informational Note: |
Specify the attribute present in the user info json related to the user's first/given name. The default value is "given_name" | |
Property: | authentication-oidc.user-info. |
last- |
name | |
Example Value: | authentication-oidc.user-info. |
last- |
name = family_name |
Informational Note: |
authentication-oidc.redirect-url
authentication-oidc.redirect-url = ${dspace.server.url}/api/authn/oid
authentication-oidc.scopes
authentication-oidc.scopes = openid,email,profile
authentication-oidc.can-self-register
authentication-oidc.can-self-register = true
Specify if the user can self register using OIDC (true|false). If not specified, true is assumed.
If this is set to false, then only users with an existing EPerson in DSpace will be able to authenticate through OIDC. When set to true, an EPerson will be automatically created for each person who successfully authenticates through OIDC.
authentication-oidc.user-info.email
authentication-oidc.user-info.email = email
authentication-oidc.user-info.first-name
authentication-oidc.user-info.first-name = given_name
authentication-oidc.user-info.last-name
authentication-oidc.user-info.last-name = family_name
Specify the attribute present in the user info json related to the user's last/family name. The default value is "family_name" |
Sample/Test OIDC Configuration
One way to easily test OIDC Authentication is to use the PhantAuth test site at https://www.phantauth.net/. This site allows you to create a random OIDC client & a random OIDC user to authenticate as. So, it can be used to verify that DSpace's OIDC authentication is working in your system, but obviously is only meant for development/testing purposes.
To configure DSpace to use PhantAuth for authentication just requires the following updates to your local.cfg:
Code Block | ||
---|---|---|
| ||
# Enable OIDC
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.OidcAuthentication
# Settings for OIDC authentication
# Based on instructions at https://www.phantauth.net/doc/integration
authentication-oidc.authorize-endpoint = https://phantauth.net/auth/authorize
authentication-oidc.token-endpoint = https://phantauth.net/auth/token
authentication-oidc.user-info-endpoint = https://phantauth.net/auth/userinfo
# Obtain a random client-id and client-secret via https://phantauth.net/client
# Find the "client_id" and "client_secret" returned, and place those values in these next two configs.
authentication-oidc.client-id =
authentication-oidc.client-secret =
# Because PhantAuth uses random users, you MUST ensure self registration is enabled
# (This is the default setting though, which is why it's commented out)
# authentication-oidc.can-self-register = true |
Shibboleth Authentication
...
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 (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: |
| ||
Example Value: |
| ||
Informational Note: | Weather Whether to ignore the attributeroles' s scope scopes (everything after the @ sign for scoped attributes) | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Weather Whether to ignore the attributeroles' s value values (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. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | These roles are assumed if no roles were sent by Shibboleth or there was no header with name matching the value of |
LDAP Authentication
Introduction to LDAP specific terminology
...
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. "\," |
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
...