References

• Fixes Add support for SAML authentication #9438
• Related to Add support for SAML authentication. dspace-angular#2937

Description

This adds support for SAML authentication.

Instructions for Reviewers

List of changes in this PR:

• Add VS Code project files to .gitignore, so I can use it for development.
• Amend the ConfigurationService API to allow working with configuration properties as hierarchies. This makes it much easier to deal with deeply nested properties required to fully configure SAML relying parties.
• Implement a SAML relying party service at /server/saml2.
• Implement a SAML authentication endpoint at /server/api/authn/saml.

See #9438 for details about the SAML relying party service and authentication endpoint.

This needs to be tested in conjunction with the UI changes in DSpace/dspace-angular#2937.

To test this, you'll need a SAML IdP. I've been developing against a personal auth0 instance, which you're welcome to use.

This is the minimal configuration that you'll need to add to your local.cfg to use my auth0 instance as the IdP:

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

Also enable SAML authentication, and set it to use the above relying party:

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

authentication-saml.relying-party-id = auth0

rest.cors.allowed-origins = ${dspace.ui.url},null

To use a different IdP, see the configuration example for details about the available configuration options for a relying party. Consult with the administrator of your IdP to determine how to make the connection. Typically, the process is something like:

1. The administrator of the IdP provides a URL to the metadata for the IdP.
2. Configure a new relying party in DSpace, setting asserting-party.metadata-uri to the IdP's metadata URL.
3. If encryption and/or signing are desired/required by the IdP, configure private keys and certificates into the relying party.
4. 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, as in the above example.
5. 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.
6. The administrator of the IdP says that the configuration is complete. Testing can commence.

Testing

1. Run DSpace from this branch with a SAML relying party and SAML authentication configured, as described above.
2. Run the UI from Add support for SAML authentication. dspace-angular#2937.

To test SAML login as an existing DSpace user:

1. Log in as an Administrator using email/password authentication.
2. Create a new user, noting the email address you use. (If using the auth0 service, an email will actually be sent to this address.)
3. Log out.
4. Log in again, this time clicking the "Log in with SAML" button.
5. The login screen from the IdP should appear. If using the auth0 service, this will have a "sign up" link that you can use to create a user. Use the email address of the user you just added to DSpace.
6. After registration/login with the IdP, you should be redirected back to DSpace, and should be logged in as the user you created in step 2.
7. Log out. This should log you out of DSpace, but not out of the IdP.
8. Log in again. This should log you into DSpace as the same user, without showing the login screen from the IdP, since the login with the IdP is still active.
9. Log out again.
10. Log out of the IdP. If using the auth0 service, go to https://dev-vynkcnqhac3c0s10.us.auth0.com/v2/logout. If using another IdP, visit its logout page.
11. Log in using SAML again. You should see the login screen from the IdP this time, since you logged out of the IdP.
12. Log out of both DSpace and the IdP.

To test SAML login as a new, auto-registered DSpace user:

1. If using the auth0 service: You can't self-register a new auth0 user for this test, because they don't let you set a first and last name when registering, and a first and last name are required to auto-register a DSpace user. Contact me for the login information for an auth0 user that has the first and last name set.

   If using your own IdP, identify a user on the IdP that does not have an existing DSpace account, and that does have the email, first name, and last name set.

2. Log in to DSpace using SAML. When the log in screen from the IdP appears, use the credentials of the user from step 1.

3. You should be redirected back to DSpace, and the End User Agreement should appear.

4. Accept the End User Agreement.

5. You should be logged in as a newly created DSpace user, with the email address, first name, and last name from the IdP.

Checklist

This checklist provides a reminder of what we are going to look for when reviewing your PR. You need not complete this checklist prior to creating your PR (draft PRs are always welcome). If you are unsure about an item in the checklist, don't hesitate to ask. We're here to help!

• My PR is small in size (e.g. less than 1,000 lines of code, not including comments & integration tests). Exceptions may be made if previously agreed upon.
  Sorry, this is about as small as I can make it, and have it be functional.
• My PR passes Checkstyle validation based on the Code Style Guide.
• My PR includes Javadoc for all new (or modified) public methods and classes. It also includes Javadoc for large or complex private methods.
• My PR passes all tests and includes new/updated Unit or Integration Tests based on the Code Testing Guide.
• If my PR includes new libraries/dependencies (in any pom.xml), I've made sure their licenses align with the DSpace BSD License based on the Licensing of Contributions documentation.
• If my PR modifies REST API endpoints, I've opened a separate REST Contract PR related to this change.
  I'm not sure if this is necessary for these changes.
• If my PR includes new configurations, I've provided basic technical documentation in the PR itself.
• If my PR fixes an issue ticket, I've linked them together.