Skip to content

OAuth Providers

Jump to bottom
Brian Riley edited this page Nov 29, 2016 · 9 revisions

Summary

DMPRoadmap allows you to easily add new OAuth Providers to your installation.

Once a provider has been registered, the system will automatically allow your users to link their account to that provider on their profile page. You can also instruct the system to automatically provide your users with the ability to log into the system with the new provider if you set the appropriate flag in the database.

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.

For example:

gem 'omniauth-orcid'
gem 'omniauth-shibboleth'
gem 'omniauth-facebook'

2) Run 'bundle install' to add the new gem file to your installation

3) Add the configuration information to your config/initializers/devise.rb file. See the gem's documentation for assistance with the proper configuration settings.

  config.omniauth :orcid, 'client_id', 'client_secret', {'scope': '/authenticate'}
  
  config.omniauth :shibboleth, {uid_field: 'eppn', 
                                info_fields: {email: 'mail', name: 'cn', last_name: 'sn'},
                                extra_fields: [:schacHomeOrganization]}

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 specified in the config/initializers/devise.rb file. For example config.omniauth :orcid ... must match 'orcid' in the locale files

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

identifier_schemes:
  connect_success: 'Your account has bee connected to {scheme}'
  ...
  schemes:
    orcid:
      logo: 'http://orcid.org/sites/default/files/images/orcid_16x16.png'
      user_landing_page: 'https://orcid.org/%{id}'
      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_confirmation: 'Are you sure you want to disconnect your ORCID ID?'
      disconnect_tooltip: 'Disconnect your account from ORCID. You can reconnect at any time.'

You can use the '%{id}' markup in your 'user_landing_page' line to have the system add the user's identifier for that system into the URL.

If the provider does not provide a specific landing page for the user's profile (e.g. Shibboleth), just skip that line in the yaml configuration. The system will simply display a the 'identifier_schemes.connect_success' message defined in the locale file (replacing %{scheme} with the scheme's name).

4) Add an entry to the identifier_schemes table

You will also need to add an entry to the database. The name of the scheme MUST match the one used in the locales files.

Field descriptions:

  • Name - The name of the provider (must match the one used in the locales files)
  • Description - A helpful description for your own use ... this is not displayed to the user
  • Used_for_login - If true, the system will allow the user to login with this provider
  • Active - If false, the system will no longer allow the user to login via that provider nor will it allow them to connect/disconnect their account on the profile page. The user's identifiers are NOT removed from the database when a provider has been deactivated in this way.
INSERT INTO identifier_schemes (name, description, used_for_login, active) 
VALUES ('orcid', '', false, true);

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 the configuration line from config/initializers/devise.rb
  • Remove (or comment out) the 'omniauth-[provider]' gem in your Gemfile
  • Restart the rails server

Troubleshooting

The system provides some initialization logic to help you identify configuration issues. When you start the system a comparison will be made between the providers defined in the identifier_schemes and those registered in config/initializers/devise.rb. Any issues will be written to the log.

  • ERROR "Devise was not properly initialized! Please make sure you have defined the config/initializers/devise.rb initializer."
  • WARN "Detected an Omniauth provider, PROVIDER_NAME, in config/initializers/devise.rb but it is inactive in the identifier_schemes table!"
  • INFO "Detected an unsupported identifier_scheme, PROVIDER_NAME, in the DB, deactivating the entry - if this is a mistake add it to your config/initializers/devise.rb"
  • INFO "Detected a new Omniauth provider in config/initializers/devise.rb that is not defined in the DB - adding PROVIDER_NAME to the identifier_schemes table. The new provider will only be available in the user's profile page. To enable it for login, please update the DB accordingly."

Table of Contents

Clone this wiki locally