Skip to content

OAuth Providers

Jump to bottom
Brian Riley edited this page Feb 3, 2017 · 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]}

  config.omniauth :facebook, 'client_id', 'client_secret'

4) Add the provider to the User model's devise section

  devise :invitable, :database_authenticatable, :registerable, :recoverable, 
         :rememberable, :trackable, :validatable, :confirmable, 
         :omniauthable, omniauth_providers: [:orcid, :sibboleth, :facebook]

5) 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).

6) 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);

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

Table of Contents

Clone this wiki locally