OAuth Providers

Summary

DMPRoadmap allows you to easily add new OAuth Providers to your installation. Simply update the locale files with the appropriate messaging and logo and then add the configuration keys to the database.

Once you've added the appropriate gem, updated the locales files and added an entry to the database, the system will automatically register the callback handler for you and will update the User Profile page so that your users can begin linking their account to the new service.

Adding a new Provider

1) Add the appropriate gem to the Gemfile

DMPRoadmap uses the Devise gem to manage user login/logout, registration, password management, and OAuth handling. You must locate and add an appropriate gem for your provider to the Gemfile so that Devise can call out to the provider for authentication purposes.

An overview of Devise's Omniauth handler can be found here. Typically a Github or Google search for 'devise omniauth [provider]' will find the gem you're looking for.

gem 'omniauth-orcid'

2) Run 'bundle install'

3) Add an entry to each of the /config/locales/*.yml files.

You must add an entry into each of the locales files for your new provider. This should be added to the 'identifier_schemes:' section at the bottom of the file.

Note: The name of the provider you enter here MUST match the name of the provider you enter into the identifier_schemes table in the database (e.g. ORCID in the examples here)

It is recommended that you review their guidelines for displaying their logo and any associated messaging.

    ORCID:
      logo: 'http://orcid.org/sites/default/files/images/orcid_16x16.png'
      connect: 'Create or Connect your ORCID ID'
      connect_tooltip: 'ORCID provides a persistent digital identifier that distinguishes you from other researchers. Learn more at orcid.org'
      disconnect_tooltip: 'Disconnect your ORCID ID'
      disconnect_confirmation: 'Are you sure you want to disconnect your ORCID ID?'

4) Add an entry to the identifier_schemes table

You will also need to add an entry to the database that includes your unique API keys for the provider.

Note: The name of the provider you enter here MUST match the name of the provider you used in the locales files above! (e.g. ORCID in the examples here)

Field descriptions:

• Name - The name of the provider (must match the one used in the locales files)
• Landing Page URI - A link to the user's main landing page on the provider's site. For example, this is the user's public page in the ORCID system. The system will replace the '{id}' placeholder with the user's identifier for that provider ... leave blank for providers that do not offer this service (e.g. Shibboleth)
• API Key - Your API key for the provider
• API Secret - Your API secret for the provider
• Params - Any query string parameters that should be passed along to the provider when they are called for authentication purposes (see the providers documentation for more details)

INSERT INTO identifier_schemes (name, landing_page_uri, api_key, api_secret, params) 
VALUES ('ORCID', 'https://orcid.org/{id}', 'ABCD1234', 'secret', '{"scope": "/authenticate"}');

5) Restart the rails server

Removing a Provider

• Remove the entry from the identifier_schemes table
• Remove the entries for the provider from the config/locales/*.yml files If you are only temporarily removing the provider, you can leave these entries in the locale files. The site's pages use the entry in the database to determine what providers to present to the user
• Remove (or comment out) the 'omniauth-[provider]' fem in your Gemfile
• Restart the rails server

Troubleshooting