decidim-suomifi 0.18.0

data/README.md

@@ -0,0 +1,236 @@
+# Decidim::Suomifi
+
+[![Build Status](https://travis-ci.com/mainio/decidim-module-suomifi.svg?branch=master)](https://travis-ci.com/mainio/decidim-module-suomifi)
+[![codecov](https://codecov.io/gh/mainio/decidim-module-suomifi/branch/master/graph/badge.svg)](https://codecov.io/gh/mainio/decidim-module-suomifi)
+
+A [Decidim](https://github.com/decidim/decidim) module to add Suomi.fi
+strong authentication to Decidim as a way to authenticate and authorize the
+users.
+
+The gem has been developed by [Mainio Tech](https://www.mainiotech.fi/).
+
+The development has been sponsored by the
+[City of Helsinki](https://www.hel.fi/).
+
+The Population Register Centre (VRK) or the Suomi.fi maintainers are not related
+to this gem in any way, nor do they provide technical support for it. Please
+contact the gem maintainers in case you find any issues with it.
+
+## Preparation
+
+Please refer to the
+[`omniauth-suomifi`](https://github.com/mainio/omniauth-suomifi) documentation
+in order to learn more about the preparation and getting started with Suomi.fi.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "decidim-suomifi"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+After installation, you can add the initializer running the following command:
+
+```bash
+$ bundle exec rails generate decidim:suomifi:install
+```
+
+You need to set the following configuration options inside the initializer:
+
+- `:scope_of_data` - The scope of data for Suomi.fi
+  * Default: `:medium_extensive`
+  * `:limited` - Limited scope (name and personal identity number)
+  * `:medium_extensive` - Medium extensive scope (limted + address information)
+  * `:extensive` - Extensive scope (medium extensive + Finnish citizenship
+    information)
+- `:sp_entity_id` - The service provider entity ID, i.e. your applications
+  entity ID used to identify the service at the Suomi.fi SAML identity provider.
+  * Set this to the same ID that you use for the metadata sent to Suomi.fi.
+  * Default: depends on the application's URL, e.g.
+    `https://www.example.org/users/auth/suomifi/metadata`
+- `:certificate_file` - Path to the local certificate included in the metadata
+  sent to Suomi.fi.
+- `:private_key_file` - Path to the local private key (corresponding to the
+  certificate). Will be used to decrypt messages coming from Suomi.fi.
+- `:auto_email_domain` - Defines the auto-email domain in case the user's domain
+  is not stored at Suomi.fi. In case this is not set (default), emails will not
+  be auto-generated and users will need to enter them manually in case Suomi.fi
+  does not report them.
+  * The auto-generated email format is similar to the following string:
+    `suomifi-756be91097ac490961fd04f121cb9550@example.org`. The email will
+    always have the `suomifi-` prefix and the domain part is defined by the
+    configuration option.
+
+For more information about these options and possible other options, please
+refer to the [`omniauth-suomifi`](https://github.com/mainio/omniauth-suomifi)
+documentation.
+
+Note that you will also need to generate a private key and a corresponding
+certificate and configure them inside the generated initializer. For the testing
+environment you can create a self signed certificate e.g. with the following
+command:
+
+```bash
+$ mkdir config/cert
+$ cd config/cert
+$ openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:2048 \
+  -keyout suomifi.key -out suomifi.crt
+```
+
+For the production environment you will need an actual certificate signed by
+a trusted CA. The self signed certificate can be used for the Suomi.fi test
+environment.
+
+The install generator will also enable the Suomi.fi authentication method for
+OmniAuth by default by adding these lines your `config/secrets.yml`:
+
+```yml
+default: &default
+  # ...
+  omniauth:
+    # ...
+    suomifi:
+      enabled: false
+      icon: globe
+development:
+  # ...
+  omniauth:
+    # ...
+    suomifi:
+      enabled: true
+      mode: test
+      icon: globe
+```
+
+This will enable the Suomi.fi authentication for the development environment
+only. In case you want to enable it for other environments as well, apply the
+OmniAuth configuration keys accordingly to other environments as well.
+
+The development environment is hooking into the Suomi.fi testing endpoints by
+default which is defined by the `mode: test` option in the OmniAuth
+configuration. For environments that you want to hook into the Suomi.fi
+production environment, you can omit this configuration option completely.
+
+The example configuration will set the `globe` icon for the the authentication
+button from the Decidim's own iconset. In case you want to have a better and
+more formal styling for the sign in button, you will need to customize the sign
+in / sign up views.
+
+## Usage
+
+After the installation steps, you will need to enable the Suomi.fi authorization
+from Decidim's system management panel. After enabled, you can start using it.
+
+This gem also provides a Suomi.fi sign in method which will automatically
+authorize the user accounts. In case the users already have an account, they
+can still authorize themselves using the Suomi.fi authorization.
+
+## Customization
+
+For some specific needs, you may need to store extra metadata for the Suomi.fi
+authorization or add new authorization configuration options for the
+authorization.
+
+This can be achieved by applying the following configuration to the module
+inside the initializer described above:
+
+```ruby
+# config/initializers/suomifi.rb
+
+Decidim::Suomifi.configure do |config|
+  # ... keep the default configuration as is ...
+  # Add this extra configuration:
+  config.workflow_configurator = lambda do |workflow|
+    # When expiration is set to 0 minutes, it will never expire.
+    workflow.expires_in = 0.minutes
+    workflow.action_authorizer = "CustomSuomifiActionAuthorizer"
+    workflow.options do |options|
+      options.attribute :custom_option, type: :string, required: false
+    end
+  end
+  config.metadata_collector_class = CustomSuomifiMetadataCollector
+end
+```
+
+For the workflow configuration options, please refer to the
+[decidim-verifications documentation](https://github.com/decidim/decidim/tree/master/decidim-verifications).
+
+For the custom metadata collector, please extend the default class as follows:
+
+```ruby
+# frozen_string_literal: true
+
+class CustomSuomifiMetadataCollector < Decidim::Suomifi::Verification::MetadataCollector
+  def metadata
+    base = super
+
+    base.tap do |data|
+      # You can access the SAML attributes using the `saml_attributes` accessor:
+      postal_code = saml_attributes[:permanent_domestic_address_postal_code]
+
+      # Or you can access the base attributes already defined through the
+      # default metadata collector:
+      postal_code = base[:postal_code]
+
+      unless postal_code.blank?
+        # This will actually add the data to the user's authorization metadata
+        # hash.
+        data[:extra] = "Custom data for: #{postal_code}"
+      end
+    end
+  end
+end
+```
+
+## Contributing
+
+See [Decidim](https://github.com/decidim/decidim).
+
+### Testing
+
+To run the tests run the following in the gem development path:
+
+```bash
+$ bundle
+$ DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rake test_app
+$ DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rspec
+```
+
+Note that the database user has to have rights to create and drop a database in
+order to create the dummy test app database.
+
+In case you are using [rbenv](https://github.com/rbenv/rbenv) and have the
+[rbenv-vars](https://github.com/rbenv/rbenv-vars) plugin installed for it, you
+can add these environment variables to the root directory of the project in a
+file named `.rbenv-vars`. In this case, you can omit defining these in the
+commands shown above.
+
+### Test code coverage
+
+If you want to generate the code coverage report for the tests, you can use
+the `SIMPLECOV=1` environment variable in the rspec command as follows:
+
+```bash
+$ SIMPLECOV=1 bundle exec rspec
+```
+
+This will generate a folder named `coverage` in the project root which contains
+the code coverage report.
+
+### Localization
+
+If you would like to see this module in your own language, you can help with its
+translation at Crowdin:
+
+https://crowdin.com/project/decidim-suomifi
+
+## License
+
+See [LICENSE-AGPLv3.txt](LICENSE-AGPLv3.txt).

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "decidim/dev/common_rake"
+
+desc "Generates a dummy app for testing"
+task test_app: "decidim:generate_external_test_app" do
+  Dir.chdir("spec/decidim_dummy_app") do
+    system("bundle exec rails generate decidim:suomifi:install --test-initializer true")
+  end
+end
+
+desc "Generates a development app."
+task development_app: "decidim:generate_external_development_app" do
+  Dir.chdir("development_app") do
+    system("bundle exec rails generate decidim:suomifi:install --dummy-cert true")
+  end
+end

data/app/controllers/decidim/suomifi/omniauth_callbacks_controller.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Suomifi
+    class OmniauthCallbacksController < ::Decidim::Devise::OmniauthRegistrationsController
+      # Make the view helpers available needed in the views
+      helper Decidim::Suomifi::Engine.routes.url_helpers
+      helper_method :omniauth_registrations_path
+
+      skip_before_action :verify_authenticity_token, only: [:suomifi, :failure]
+      skip_after_action :verify_same_origin_request, only: [:suomifi, :failure]
+
+      # This is called always after the user returns from the authentication
+      # flow from the Suomi.fi identity provider.
+      def suomifi
+        if user_signed_in?
+          # The user is most likely returning from an authorization request
+          # because they are already signed in. In this case, add the
+          # authorization and redirect the user back to the authorizations view.
+
+          # Make sure the user has an identity created in order to aid future
+          # Suomi.fi sign ins.
+          identity = current_user.identities.find_by(
+            organization: current_organization,
+            provider: oauth_data[:provider],
+            uid: user_identifier
+          )
+          unless identity
+            # Check that the identity is not already bound to another user.
+            id = Decidim::Identity.find_by(
+              organization: current_organization,
+              provider: oauth_data[:provider],
+              uid: user_identifier
+            )
+            return fail_authorize(:identity_bound_to_other_user) if id
+
+            current_user.identities.create!(
+              organization: current_organization,
+              provider: oauth_data[:provider],
+              uid: user_identifier
+            )
+          end
+
+          # Add the authorization for the user
+          return fail_authorize unless authorize_user(current_user)
+
+          # Show the success message and redirect back to the authorizations
+          flash[:notice] = t(
+            "authorizations.create.success",
+            scope: "decidim.suomifi.verification"
+          )
+          return redirect_to(
+            stored_location_for(resource || :user) ||
+            decidim_verifications.authorizations_path
+          )
+        end
+
+        # Normal authentication request, proceed with Decidim's internal logic.
+        send(:create)
+      end
+
+      def failure
+        strategy = failed_strategy
+        saml_response = strategy.response_object if strategy
+        return super unless saml_response
+
+        # In case we want more info about the returned status codes, use the
+        # code below.
+        #
+        # Status codes:
+        #   Requester = A problem with the request OR the user cancelled the
+        #               request at the identity provider.
+        #   Responder = The handling of the request failed.
+        #   VersionMismatch = Wrong version in the request.
+        #
+        # Additional state codes:
+        #   AuthnFailed = The authentication failed OR the user cancelled
+        #                 the process at the identity provider.
+        #   RequestDenied = The authenticating endpoint (which the
+        #                   identity provider redirects to) rejected the
+        #                   authentication.
+        # if !saml_response.send(:validate_success_status) && !saml_response.status_code.nil?
+        #   codes = saml_response.status_code.split(" | ").map do |full_code|
+        #     full_code.split(":").last
+        #   end
+        # end
+
+        # Some extra validation checks
+        validations = [
+          # The success status validation fails in case the response status
+          # code is something else than "Success". This is most likely because
+          # of one the reasons explained above. In general there are few
+          # possible explanations for this:
+          # 1. The user cancelled the request and returned to the service.
+          # 2. The underlying identity service the IdP redirects to rejected
+          #    the request for one reason or another. E.g. the user cancelled
+          #    the request at the identity service.
+          # 3. There is some technical problem with the identity provider
+          #    service or the XML request sent to there is malformed.
+          :success_status,
+          # Checks if the local session should be expired, i.e. if the user
+          # took too long time to go through the authorization endpoint.
+          :session_expiration,
+          # The NotBefore and NotOnOrAfter conditions failed, i.e. whether the
+          # request is handled within the allowed timeframe by the IdP.
+          :conditions
+        ]
+        validations.each do |key|
+          next if saml_response.send("validate_#{key}")
+
+          flash[:alert] = t(".#{key}")
+          return redirect_to after_omniauth_failure_path_for(resource_name)
+        end
+
+        super
+      end
+
+      # This is overridden method from the Devise controller helpers
+      # This is called when the user is successfully authenticated which means
+      # that we also need to add the authorization for the user automatically
+      # because a succesful Suomi.fi authentication means the user has been
+      # successfully authorized as well.
+      def sign_in_and_redirect(resource_or_scope, *args)
+        # Add authorization for the user
+        if resource_or_scope.is_a?(::Decidim::User)
+          return fail_authorize unless authorize_user(resource_or_scope)
+        end
+
+        super
+      end
+
+      private
+
+      def authorize_user(user)
+        authorization = Decidim::Authorization.find_by(
+          name: "suomifi_eid",
+          unique_id: user_signature
+        )
+        if authorization
+          return nil if authorization.user != user
+        else
+          authorization = Decidim::Authorization.find_or_initialize_by(
+            name: "suomifi_eid",
+            user: user
+          )
+        end
+
+        authorization.attributes = {
+          unique_id: user_signature,
+          metadata: authorization_metadata
+        }
+        authorization.save!
+
+        # This will update the "granted_at" timestamp of the authorization which
+        # will postpone expiration on re-authorizations in case the
+        # authorization is set to expire (by default it will not expire).
+        authorization.grant!
+
+        authorization
+      end
+
+      def fail_authorize(failure_message_key = :already_authorized)
+        flash[:alert] = t(
+          "failure.#{failure_message_key}",
+          scope: "decidim.suomifi.omniauth_callbacks"
+        )
+        redirect_to stored_location_for(resource || :user) || decidim.root_path
+      end
+
+      # Data that is stored against the authorization "permanently" (i.e. as
+      # long as the authorization is valid).
+      def authorization_metadata
+        metadata_collector.metadata
+      end
+
+      # Needs to be specifically defined because the core engine routes are not
+      # all properly loaded for the view and this helper method is needed for
+      # defining the omniauth registration form's submit path.
+      def omniauth_registrations_path(resource)
+        Decidim::Core::Engine.routes.url_helpers.omniauth_registrations_path(resource)
+      end
+
+      # Private: Create form params from omniauth hash
+      # Since we are using trusted omniauth data we are generating a valid signature.
+      def user_params_from_oauth_hash
+        return nil if oauth_data.empty?
+        return nil if saml_attributes.empty?
+        return nil if user_identifier.blank?
+
+        {
+          provider: oauth_data[:provider],
+          uid: user_identifier,
+          name: user_full_name,
+          # The nickname is automatically "parametrized" by Decidim core from
+          # the name string, i.e. it will be in correct format.
+          nickname: user_full_name,
+          oauth_signature: user_signature,
+          avatar_url: oauth_data[:info][:image],
+          raw_data: oauth_hash
+        }
+      end
+
+      def user_full_name
+        return oauth_data[:info][:name] if oauth_data[:info][:name]
+
+        @user_full_name ||= begin
+          first_name = begin
+            saml_attributes[:given_name] ||
+              saml_attributes[:first_names] ||
+              saml_attributes[:eidas_first_names]
+          end
+          last_name = begin
+            saml_attributes[:last_name] ||
+              saml_attributes[:eidas_family_name]
+          end
+
+          "#{first_name} #{last_name}"
+        end
+      end
+
+      def user_signature
+        @user_signature ||= OmniauthRegistrationForm.create_signature(
+          oauth_data[:provider],
+          user_identifier
+        )
+      end
+
+      # See the omniauth-suomi gem's notes about the UID. It should be always
+      # unique per person as long as it can be determined from the user's data.
+      # This consists of one of the following in this order:
+      # - The person's electronic identifier (SATU ID, sähköinen asiointitunnus)
+      # - The person's personal identifier (HETU ID, henkilötunnus) in hashed
+      #   format
+      # - The person's eIDAS personal identifier (eIDAS PID) in hashed format
+      # - The SAML NameID in the SAML response in case no unique personal data
+      #   is available as defined above
+      def user_identifier
+        @user_identifier ||= oauth_data[:uid]
+      end
+
+      def person_identifier_digest
+        metadata_collector.person_identifier_digest
+      end
+
+      def metadata_collector
+        @metadata_collector ||= Decidim::Suomifi::Verification::Manager.metadata_collector_for(
+          saml_attributes
+        )
+      end
+
+      def verified_email
+        @verified_email ||= begin
+          if saml_attributes[:email]
+            saml_attributes[:email]
+          elsif Decidim::Suomifi.auto_email_domain
+            domain = Decidim::Suomifi.auto_email_domain
+            "suomifi-#{person_identifier_digest}@#{domain}"
+          end
+        end
+      end
+
+      def saml_attributes
+        @saml_attributes ||= oauth_hash[:extra][:saml_attributes]
+      end
+    end
+  end
+end