Versions Compared

Old Version 2

changes.mady.by.user Mark Cooper

Saved on

compared with

New Version 3

changes.mady.by.user Mark Cooper

Saved on

Key

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

...

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

...

https://github.com/DSpace/DSpace/blob/main/dspace/config/modules/authentication-saml.cfg

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-nameE
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?


https://github.com/DSpace/DSpace/blob/main/dspace/config/modules/saml-relying-party.cfg

Note: for the saml-relying-party.cfg settings replace RELYING-PARTY-ID with the value of authentication-saml.relying-party-id.

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.RELYING-PARTY-ID.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.RELYING-PARTY-ID.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.auth0.asserting-party.metadata-uri
Property:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-sign-on.url
Example Value:saml-relying-party.RELYING-PARTY-ID.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.auth0.asserting-party.metadata-uri
Property:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-sign-on.binding
Example Value:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-sign-on.binding = POST
Informational Note:(Optional) Only set manually if you cannot get metadata from saml-relying-party.auth0.asserting-party.metadata-uri
Property:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-sign-on.sign-request
Example Value:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-sign-on.sign-request = false
Informational Note:(Optional) Only set manually if you cannot get metadata from saml-relying-party.auth0.asserting-party.metadata-uri
Property:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-logout.url
Example Value:saml-relying-party.RELYING-PARTY-ID.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.auth0.asserting-party.metadata-uri
Property:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-logout.binding
Example Value:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-logout.binding = POST
Informational Note:(Optional) Only set manually if you cannot get metadata from saml-relying-party.auth0.asserting-party.metadata-uri
Property:saml-relying-party.RELYING-PARTY-ID.asserting-party.single-logout.response-url
Example Value:saml-relying-party.RELYING-PARTY-ID.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.RELYING-PARTY-ID.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.auth0.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.auth0.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.auth0.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.auth0.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.auth0.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

...

Code Block
titlelocal.cfg updates for PhantAuthSAML
# 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

...