Page History

...

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:	(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). 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.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 "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:	(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/oidoidc`
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:	Specify the attribute present in the user info json related to the user's last/family name. The default value is "family_name"

...

Code Block

title	local.cfg updates for PhantAuth

# 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

SAML (Security Assertion Markup Language) Authentication

Info
SAML Authentication is only available in DSpace 9.0 or above.

Enabling SAML Authentication

To enable SAML Authentication, you must ensure the org.dspace.authenticate.SamlAuthenticationclass 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:

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

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

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

Configuring SAML Authentication

SAML (Security Assertion Markup Language) is an XML based standard for transferring identity information between entities, in particular an identity provider (IdP) and a service provider (SP). The former performs authentication and transmits user identity data to the latter, the system the user is attempting to access. The SAML Authenication plugin configures DSpace to operate as a SAML service provider interacting with an external identity provider. There are many SAML IdP server implementations, including open source and enterprise options from major cloud and SAAS providers.

Note: SAML configuration can be simple, but in some cases may require a lot of configuration. In addition to the settings summarized here if you are having trouble setting up a SAML intregration it is recommended you review the documentation provided in the source code. It may also be helpful to refer to the feature submission details: https://github.com/DSpace/DSpace/pull/9470

Configuration File:	`[dspace]/config/modules/authentication-saml.cfg`
Property:	`authentication-saml.relying-party-id`
Example Value:	`authentication-saml.relying-party-id = auth0`
Informational Note:	(Required) The ID of the SAML relying party we should use for authentication. This is an internal identifier used to reference configuration in saml-relying-party.cfg.
Property:	`authentication-saml.relying-party-url`
Example Value:	`authentication-saml.relying-party-url = ${dspace.server.url}/saml2`
Informational Note:	The base URL of all SAML relying party endpoints.
Property:	`authentication-saml.authenticate-endpoint`
Example Value:	`authentication-saml.authenticate-endpoint = ${authentication-saml.relying-party-url}/authenticate/${authentication-saml.relying-party-id}`
Informational Note:	The URL of the authenticate endpoint for the SAML relying party.
Property:	`authentication-saml.autoregister`
Example Value:	`authentication-saml.autoregister = true`
Informational Note:	Should we allow new users to be registered automatically?
Property:	`authentication-saml.attribute.relying-party-id`
Example Value:	`authentication-saml.attribute.relying-party-id = org.dspace.saml.RELYING_PARTY_ID`
Informational Note:	The request attribute that contains the ID of the SAML relying party that authenticated the user.
Property:	`authentication-saml.attribute.name-id`
Example Value:	`authentication-saml.attribute.name-id = org.dspace.saml.NAME_ID`
Informational Note:	The request attribute that contains the user's SAML name ID.
Property:	`authentication-saml.attribute.email`
Example Value:	`authentication-saml.attribute.email = org.dspace.saml.EMAIL`
Informational Note:	The request attribute that contains the user's email.
Property:	`authentication-saml.attribute.first-name`
Example Value:	`authentication-saml.attribute.first-name = org.dspace.saml.GIVEN_NAME`
Informational Note:	The request attribute that contains the user's first name.
Property:	`authentication-saml.attribute.last-name`
Example Value:	`authentication-saml.attribute.last-name = org.dspace.saml.SURNAME`
Informational Note:	The request attribute that contains the user's last name.
Property:	`authentication-saml.eperson.metadata`
Example Value:	`authentication-saml.eperson.metadata = org.dspace.saml.PHONE => phone`
Informational Note:	Additional attribute mappings. Multiple attributes may be stored for each user. The left side is the request attribute, and the right side is the ePerson metadata field to map the attribute to.
Property:	`authentication-saml.eperson.metadata.autocreate`
Example Value:	`authentication-saml.eperson.metadata.autocreate = false`
Informational Note:	If the ePerson metadata field is not found, should it be created automatically?

Note
For the `saml-relying-party.cfg` settings below replace `[RELYING-PARTY-ID]` with the value of `authentication-saml.relying-party-id` from your `authentication-saml.cfg`

Configuration File:	`[dspace]/config/modules/saml-relying-party.cfg`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Example Value:	`saml-relying-party.auth0.asserting-party.metadata-uri = https://dev-vynkcnqhac3c0s10.us.auth0.com/samlp/metadata/Vn8jWX0iFHtepmXi7rjZa9h5M1kqXNWY`
Informational Note:	The URI where metadata for the asserting party (IdP) can be retrieved. Ideally, this is the only asserting party configuration that is needed, because all of the other asserting party configuration properties will be set automatically from the metadata.
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.entity-id`
Example Value:	`saml-relying-party.auth0.asserting-party.entity-id = urn:dev-vynkcnqhac3c0s10.us.auth0.com`
Informational Note:	(Optional) Only set manually if you cannot get metadata from `saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.single-sign-on.url`
Example Value:	`saml-relying-party.auth0.asserting-party.single-sign-on.url = https://dev-vynkcnqhac3c0s10.us.auth0.com/samlp/Vn8jWX0iFHtepmXi7rjZa9h5M1kqXNWY`
Informational Note:	(Optional) Only set manually if you cannot get metadata from `saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.single-sign-on.binding`
Example Value:	`saml-relying-party.auth0.asserting-party.single-sign-on.binding = POST`
Informational Note:	(Optional) Only set manually if you cannot get metadata from `saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.single-sign-on.sign-request`
Example Value:	`saml-relying-party.auth0.asserting-party.single-sign-on.sign-request = false`
Informational Note:	(Optional) Only set manually if you cannot get metadata from `saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.single-logout.url`
Example Value:	`saml-relying-party.auth0.asserting-party.single-logout.url = https://dev-vynkcnqhac3c0s10.us.auth0.com/samlp/Vn8jWX0iFHtepmXi7rjZa9h5M1kqXNWY/logout`
Informational Note:	(Optional) Only set manually if you cannot get metadata from `saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.single-logout.binding`
Example Value:	`saml-relying-party.auth0.asserting-party.single-logout.binding = POST`
Informational Note:	(Optional) Only set manually if you cannot get metadata from `saml-relying-party.[RELYING-PARTY-ID].asserting-party.metadata-uri`
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.single-logout.response-url`
Example Value:	`saml-relying-party.auth0.asserting-party.single-logout.response-url =`
Informational Note:	Note that single logout information can be configured for the asserting party, but SAML single logout is not currently supported by DSpace.
Property:	`saml-relying-party.[RELYING-PARTY-ID].asserting-party.verification.credentials.0.certificate-location`
Example Value:	`saml-relying-party.auth0.asserting-party.verification.credentials.0.certificate-location = file:///opt/dspace/cert/auth0-ap-certificate.crt`
Informational Note:	(Optional) If a verification certificate is configured, the certificate-location should contain the URL of an X509 certificate. This can be a file, http(s), or classpath URL.
Property:	`saml-relying-party.[RELYING-PARTY-ID].signing.credentials.0.private-key-location`
Example Value:	`saml-relying-party.auth0.signing.credentials.0.private-key-location = file:///opt/dspace/secrets/rp-private.key`
Informational Note:	Can be set to sign and/or encrypt/decrypt communications.
Property:	`saml-relying-party.[RELYING-PARTY-ID].signing.credentials.0.certificate-location`
Example Value:	`saml-relying-party.auth0.signing.credentials.0.certificate-location = file:///opt/dspace/cert/rp-certificate.crt`
Informational Note:	Can be set to sign and/or encrypt/decrypt communications.
Property:	`saml-relying-party.[RELYING-PARTY-ID].decryption.credentials.0.private-key-location`
Example Value:	`saml-relying-party.auth0.decryption.credentials.0.private-key-location = file:///opt/dspace/secrets/rp-private.key`
Informational Note:	Can be set to sign and/or encrypt/decrypt communications.
Property:	`saml-relying-party.[RELYING-PARTY-ID].decryption.credentials.0.private-key-location`
Example Value:	`saml-relying-party.auth0.decryption.credentials.0.private-key-location = file:///opt/dspace/secrets/rp-private.key`
Informational Note:	Can be set to sign and/or encrypt/decrypt communications.
Property:	`saml-relying-party.[RELYING-PARTY-ID].attributes`
Example Value:	`saml-relying-party.auth0.attributes = \` `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress => org.dspace.saml.EMAIL, \` `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname => org.dspace.saml.GIVEN_NAME, \` `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname => org.dspace.saml.SURNAME`
Informational Note:	Mapping of SAML assertion attributes to request attributes. The left side is the name of an attribute in the assertion received from the IdP. The right side is the name of the request attribute to map the SAML attribute to, before forwarding the request to the authentication endpoint. A mapping to `org.dspace.saml.EMAIL` must be supplied in order for the authentication endpoint to associate a SAML user to a DSpace user. Mappings for `org.dspace.saml.GIVEN_NAME` and `org.dspace.saml.SURNAME` are required for new users to be registered automatically.

Sample/Test SAML Configuration

One way to test SAML authentication is to sign up for a free account with a service like Auth0. They provide documentation on how to create a SAML Identity Provider. However, you can use any SAML IdP and there are many available.

To configure DSpace to use SAML for authentication (with auth0 as an example) requires this minimal configuration:

Code Block

title	local.cfg updates for SAML

# Enable SAML
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.SAMLAuthentication
authentication-saml.relying-party-id = auth0 # refer to our IdP as "auth0" in our configuration

# Settings for SAML authentication (note the use of "auth0" in the replying-party configuation properties)
saml-relying-party.auth0.asserting-party.metadata-uri = https://dev-vynkcnqhac3c0s10.us.auth0.com/samlp/metadata/Vn8jWX0iFHtepmXi7rjZa9h5M1kqXNWY

saml-relying-party.auth0.attributes = \
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress => org.dspace.saml.EMAIL, \
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname => org.dspace.saml.GIVEN_NAME, \
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname => org.dspace.saml.SURNAME

# Add the IdP url to the list of allowed origins
rest.cors.allowed-origins = ${dspace.ui.url},https://dev-vynkcnqhac3c0s10.us.auth0.com

In general when setting up a SAML integration the flow will go something like:

The administrator of the IdP provides a URL to the metadata for the IdP.
Configure a new relying party in DSpace, setting asserting-party.metadata-uri to the IdP's metadata URL.
If encryption and/or signing are desired/required by the IdP, configure private keys and certificates into the relying party.
Ask the administrator of the IdP to release the user's email, first name, and last name as attributes, and ask what the names of those attributes will be. Configure the relying party's attributes property, to map those attribute names to org.dspace.saml.EMAIL, org.dspace.saml.GIVEN_NAME, and org.dspace.saml.SURNAME.
Start DSpace, and provide the relying party's metadata URL (/server/saml2/service-provider-metadata/{id}) to the administrator of the IdP, so they can use it to configure their side. Alternatively, retrieve the metadata, and provide it to the administrator of the IdP through another channel.
The administrator of the IdP says that the configuration is complete. Testing can commence.

Shibboleth Authentication

...

All Versions

DSpace Documentation

Page tree

Versions Compared

Old Version 1

New Version Current

Key

SAML (Security Assertion Markup Language) Authentication

Enabling SAML Authentication

Configuring SAML Authentication

Sample/Test SAML Configuration

Shibboleth Authentication