Setting up SSO for your instance of the DMPTool

Note this documentation is for people who are running their own instance of the DMPTool system! If you want information on how to allow your users to sign into dmptool.org, then please see Enabling Single Sign On (SSO) for your institution

Service Provider Setup

To support SSO for your instance of the DMPTool system, you will need to install a service provider that can handle communications with the Identity provider(s) you want to work with.

We use a service provider from Shibboleth and have it running on the same server as the Rails application. There are other Service Provider options out there like CAS but Shibboleth seems to be very popular in the academic community. We are also members of the InCommon federation and we recommend that you join that or a similar one that can provide you with Identity Provider metadata. Joining a federation prevents you and the Identity Providers from having to manually add each others metadata.

We highly recommend that you contact your institution’s team that manages your SSO login to help you get this all set up! They will be a big help since they should be familiar with these federations, how Service Provider (SP) and Identity Provider (IdP) and SAML work together.

The general workflow seems simple on the surface but it’s a fairly complicated process. Here is how it works:

• User enters their email address on your website
• If their email matches them to an Org record that has an entityID then they a presented with an SSO sign in button
• Use clicks the button on your website to sign in to SSO
• Your website’s omniauth_passthrus_controller.rb contacts your SP with the entityId and a callback URL
• Your SP looks up the entityID in its metadata (the metadata is provided by your federation) to find the address of the IdP. If it finds a record, it sends the user to the IdP login page
• The user signs into the IdP
• The IdP redirects the user back to your SP with SAML data (usually containing email, first name, last name, and a unique id called an eppn)
• Your SP verifies the SAML information. If it looks good, it redirects to your website’s omniauth_callbacks_controller.rb
• The omniauth_callbacks_controller.rb checks to see if the user exists. If they do, it logs them in. If not, it sends them to the create account form with prepopulated information that was received in the SAML.

DMPTool Configuration

Note that you MUST register your service provider with your federation (or both you and the IdP manually add each other's metadata) for this to work. The Service Provider <-> Identity Provider exchange requires SSL certs and other information.

Once you have the service provider installed and registered with your federation, you can:

• Update the ‘Shibboleth configuration’ section of the config/dmproadmap.yml file with the URLs for your service provider.
• Check the config/initializers/devise.rb file which has information about all of the SAML attributes you want to work with from the IdP(s). Since users were already signing into my DMPTool system successfully with, you will probably not need to make changes here.
• Check the app/controllers/users/omniauth_passthrus_controller.rb you can add some debug here to help verify that things are working
• Check the app/controllers/users/omniauth_callbacks_controller.rb you can add some debug here to help verify that things are working

Here are a few other things to consider:

• If you decide to install the service provider on the same server as your application, make sure you enable ‘sticky’ sessions if you have a load balancer. If you do not, then sometimes you can have issues if the SSO handshake begins on one server and ends on another.
• The omniauth_callbacks_controller.rb has some logic that references the Oauth2 API. That is for OAuth2 workflows that happen via the API.