OAuth Providers
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.
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'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' devise :invitable, :database_authenticatable, :registerable, :recoverable,
:rememberable, :trackable, :validatable, :confirmable,
:omniauthable, omniauth_providers: [:orcid, :sibboleth, :facebook]You will also need to add an entry to the database.
Field descriptions:
- Name - The name of the provider (lower case!)
- Description - A helpful description for your own use ... this is not displayed to the user
-
Identifier_prefix - The URL prefix (e.g.
https://orcid.org/) for the identifier (if applicable). The identifier values should be stored in the identifiers table as the full URL (e.g.https://orcid.org/0000-0000-0000-000X). This entry is used to strip off the prefix when displaying the value on the site (e.g.0000-0000-0000-000X) - Context - A bit field value that indicates what parts of the site that the identifier scheme is applicable to.
- 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.
Context bit field options:
- for_authentication - Used to determine which schemes are used for login purposes (e.g. Shibboleth)
- for_orgs - Indicates an identifier used to identify an Org (e.g. ROR, Crossref funder id, etc.)
- for_plans - Indicates an identifier used to identify or is related to a Plan (e.g. grant_id)
- for_users - Indicates an identifier used to identify a User (e.g. ORCID, Shibboleth, etc.)
- for_contributors - Indicates an identifier used to identify a Contributor (e.g. ORCID)
We recommend using a Rake task to add entries to this table due to the bit field. For example
# lib/tasks/my_task.rake
namespace :identifier_schemes do
desc "Add some_scheme to identifier_schemes table"
task :some_scheme do
IdentifierScheme.find_or_create_by(
name: 'some_scheme',
description: 'A useful description of the scheme',
identifier_prefix: 'https://some-scheme.org/ids/',
active: true,
for_authentication: true,
for_users: true
)
end
end
In most situations you will need to add the integration to the UI.
- For login options see:
app/views/shared/_sign_in_form.html.erb - For allowing a user to link their account from the profile page:
app/views/devise/registrations/_external_identifiers.html.erb - For other contexts modify the erb files as needed.
The app/controllers/users/omniauth_callbacks_controller.rb dynamically adds a callback handler for any identifier_scheme with the 'for_authentication' context. The generic code here should properly handle most scenarios. It may be necessary to add or adjust the logic to fit your needs.
 |
 |