Skip to content

Latest commit

 

History

History
110 lines (78 loc) · 5.11 KB

CONTRIBUTING.md

File metadata and controls

110 lines (78 loc) · 5.11 KB
Raw

Contributing to this module

Please read the README "Usage" to understand how this module can be configured via ENV vars.

Bug reports and pull requests are welcome on GitHub at https://github.com/ConsorciAOC-PRJ/decidim-module-trusted-ids.

Adding additional OmniAuth providers

We accept OmniAuth providers to be added to this module. However, only strong authentication providers will be accepted. That is, providers that provide a strong authentication mechanism providing a unique identifier for each user. Preferably from official entities.

To add a new OmniAuth provider, you must:

  1. Create a new OmniAuth provider in the OmniAuth_providers directory. You can copy the valid.rb file and adapt it to your needs. Note that the name of the file must be the same as the name of the provider. For instance, if the provider is called valid, the file must be called valid.rb. The name of the provider must be unique. The OmniAuth method must return the uid property with an unique identifier for the user that will be used to connect and extract additional information from the census API.

  2. Add the class to the autoloader section in strategies.rb, with the name of your OmniAuth class provider.

module OmniAuth
  module Strategies
    autoload :Valid, "omniauth/strategies/valid"
    autoload :FooBar, "omniauth/strategies/foo_bar"
  end
end
  1. Add the name and description that will be used to present the authorization button in the locales file.
en:
  decidim:
    trusted_ids:
      providers:
        valid:
          name: VÀLid
          description: VÀLid is the digital identity service of the Government of Catalonia.
        foo_bar:
          name: "Foo Bar"
          description: "Foo Bar description"

Note that the name of the authorization method associated with the OmniAuth method will be dynamically calculated according to the name property. This is done in the file zz_fallbacks.rb.

  1. In your application, use the ENV OMNIAUTH_PROVIDER=foo_bar or create an initializer to specify the default OmniAuth provider:
Decidim::TrustedIds.configure do |config|
  config.omniauth_provider = :foo_bar
end

Saving metadata extracted from the OAuth provider

Saving metadata extracted from the OAuth provider is optional. But you can use this module to use some of this data to authorize users without relaying on them introducing data.

This process is described in the README "Workflow" and "Usage" sections.

Creating and additional census authorization handler

This module comes with a default census authorization handler that can be used to authorize users called "Via Oberta" that uses the AOC census API, Via Oberta.

This authorization method uses the data extracted from the Valid OAuth provider and send it to the Via Oberta API to authorize users.

However, you can create your own census authorization handler to authorize users using additional data extracted from any OAuth provider capable of giving the information required by your census API.

The best way to start if you want to create a new census authorization handler, is to look at the implementation of the Via Oberta handler and use it as a template to create your own handler.

This authorization method is implemented in the following files:

Using additional configuration metadata for each organization (tenant)

You might want to configure some variables per/tenant. For instance, the identifier of the organization or the city using it.

This module can add fields in the System Decidim Settings administrator (/system), in the "Advanced" section. You simply must define a list of fields using the ENV var CENSUS_AUTHORIZATION_SYSTEM_ATTRIBUTES or directly in a initializer:

# `config/initializers/decidim_trusted_ids.rb`
Decidim::TrustedIds.configure do |config|
  config.census_authorization = {
      handler: :my_authorization_handler,
      form: "Decidim::MyNameSpace::MyAuthorizationHandler"),
      #...any_other_thing..,
      system_attributes: "municipal_code province_code organization_name"
    }
end

This will create the fields to fill in the System Settings page, see the README "Screenshots" section.

Localizing fields

You can localize the fields using the config/locales/en.yml attribute names under the activemodel.attributes.trusted_ids_census_config.settings key. For instance:

en:
  activemodel:
    attributes:
      trusted_ids_census_config:
        settings:
          municipal_code: Municipal code
          province_code: Province code
          organization_name: Organization name