All Versions
DSpace Documentation
Page History
...
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 "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" |
...
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: |
| |
|---|---|---|
Property: |
| |
Example Value: |
(NOTE: This setting may be repeated to support multiple AuthenticationMethods) (WARNING: it's easy to miss, the "camel case" for |
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 configuation 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
https://github.com/DSpace/DSpace/blob/main/dspace/config/modules/authentication-saml.cfg
Configuration File: |
|
|---|---|
Property: |
|
| Example Value: |
|
| 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: |
|
Example Value: |
|
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? |
https://github.com/DSpace/DSpace/blob/main/dspace/config/modules/saml-relying-party.cfg
...
| Note |
|---|
For the |
Configuration File: |
|
|---|---|
Property: |
|
| Example Value: |
|
| |
| 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: |
|
|---|---|
Example Value: |
|
| |
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: |
|
| |
| Example Value: |
|
| Informational Note: | Can be set to sign and/or encrypt/decrypt communications. |
| Property: |
|
| |
| Example Value: |
|
| Informational Note: | Can be set to sign and/or encrypt/decrypt communications. |
| Property: |
|
| |
| Example Value: |
|
| 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 |
|
Sample/Test SAML Configuration
...
| Code Block | ||
|---|---|---|
| ||
# 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 |
...
Overview
Content Tools