decidim-mpassid 0.18.0

data/README.md

@@ -0,0 +1,207 @@
+# Decidim::Mpassid
+
+[![Build Status](https://travis-ci.com/mainio/decidim-module-mpassid.svg?branch=master)](https://travis-ci.com/mainio/decidim-module-mpassid)
+[![codecov](https://codecov.io/gh/mainio/decidim-module-mpassid/branch/master/graph/badge.svg)](https://codecov.io/gh/mainio/decidim-module-mpassid)
+
+A [Decidim](https://github.com/decidim/decidim) module to add MPASSid
+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 MPASSid service is owned by the Ministry of the Education and Culture and
+operated by CSC - Tieteen tietotekniikan keskus Oy. Neither of these parties or
+the MPASSid maintainers are 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-mpassid`](https://github.com/mainio/omniauth-mpassid) documentation
+in order to learn more about the preparation and getting started with MPASSid.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "decidim-mpassid"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+After installation, you can add the initializer running the following command:
+
+```bash
+$ bundle exec rails generate decidim:mpassid:install
+```
+
+You need to set the following configuration options inside the initializer:
+
+- `:sp_entity_id` - The service provider entity ID, i.e. your applications
+  entity ID used to identify the service at the MPASSid SAML identity provider.
+  * Default: depends on the application's URL, e.g.
+    `https://www.example.org/users/auth/mpassid/metadata`
+- `:auto_email_domain` - Defines the auto-email domain for automatically
+  verified email addresses for the identified users. This makes it easier for
+  the users to use the system as they don't have to go through any extra steps
+  verifying their email addresses, as they have already verified their identity.
+  * The auto-generated email format is similar to the following string:
+    `mpassid-756be91097ac490961fd04f121cb9550@example.org`. The email will
+    always have the `mpassid-` 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-mpassid`](https://github.com/mainio/omniauth-mpassid)
+documentation.
+
+The install generator will also enable the MPASSid authentication method for
+OmniAuth by default by adding these lines your `config/secrets.yml`:
+
+```yml
+default: &default
+  # ...
+  omniauth:
+    # ...
+    mpassid:
+      enabled: false
+      icon: account-login
+development:
+  # ...
+  omniauth:
+    # ...
+    mpassid:
+      enabled: true
+      mode: test
+      icon: account-login
+```
+
+This will enable the MPASSid 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 MPASSid 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 MPASSid
+production environment, you can omit this configuration option completely.
+
+The example configuration will set the `account-login` 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 MPASSid authorization
+from Decidim's system management panel. After enabled, you can start using it.
+
+This gem also provides a MPASSid 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 MPASSid authorization.
+
+## Customization
+
+For some specific needs, you may need to store extra metadata for the MPASSid
+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/mpassid.rb
+
+Decidim::Mpassid.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 = "CustomMpassidActionAuthorizer"
+    workflow.options do |options|
+      options.attribute :custom_option, type: :string, required: false
+    end
+  end
+  config.metadata_collector_class = CustomMpassidMetadataCollector
+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 CustomMpassidMetadataCollector < Decidim::Mpassid::Verification::MetadataCollector
+  def metadata
+    super.tap do |data|
+      # You can access the SAML attributes using the `saml_attributes` accessor:
+      school_codes = saml_attributes[:school_code]
+      unless school_codes.blank?
+        extra = school_codes.map do |school_code|
+          "Extra data for: #{school_code}"
+        end
+
+        # This will actually add the data to the user's authorization metadata
+        # hash.
+        data[:extra] = extra.join(",")
+      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-mpassid
+
+## 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:mpassid: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:mpassid:install")
+  end
+end

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

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Mpassid
+    class OmniauthCallbacksController < ::Decidim::Devise::OmniauthRegistrationsController
+      # Make the view helpers available needed in the views
+      helper Decidim::Mpassid::Engine.routes.url_helpers
+      helper_method :omniauth_registrations_path
+
+      skip_before_action :verify_authenticity_token, only: [:mpassid, :failure]
+      skip_after_action :verify_same_origin_request, only: [:mpassid, :failure]
+
+      # This is called always after the user returns from the authentication
+      # flow from the MPASSid identity provider.
+      def mpassid
+        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
+          # MPASSid 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.mpassid.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 MPASSid 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: "mpassid_nids",
+          unique_id: user_signature
+        )
+        if authorization
+          return nil if authorization.user != user
+        else
+          authorization = Decidim::Authorization.find_or_initialize_by(
+            name: "mpassid_nids",
+            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.mpassid.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
+
+      def metadata_collector
+        @metadata_collector ||= Decidim::Mpassid::Verification::Manager.metadata_collector_for(
+          saml_attributes
+        )
+      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: oauth_data[:info][:name],
+          # The nickname is automatically "parametrized" by Decidim core from
+          # the name string, i.e. it will be in correct format.
+          nickname: oauth_data[:info][:name],
+          oauth_signature: user_signature,
+          avatar_url: oauth_data[:info][:image],
+          raw_data: oauth_hash
+        }
+      end
+
+      def user_signature
+        @user_signature ||= OmniauthRegistrationForm.create_signature(
+          oauth_data[:provider],
+          user_identifier
+        )
+      end
+
+      # The MPASSid's assigned UID for the person. Note that this may change in
+      # case the user moves to another "registry". Not sure what they mean with
+      # "registry" in this context, but could be e.g. to another school or
+      # municipality.
+      def user_identifier
+        @user_identifier ||= oauth_data[:uid]
+      end
+
+      # Digested format of the person's identifier to be used in the
+      # auto-generated emails. This is used so that the actual identifier is not
+      # revealed directly to the end user.
+      def person_identifier_digest
+        @person_identifier_digest ||= Digest::MD5.hexdigest(
+          "MPASSID:#{user_identifier}:#{Rails.application.secrets.secret_key_base}"
+        )
+      end
+
+      def verified_email
+        @verified_email ||= begin
+          if Decidim::Mpassid.auto_email_domain
+            domain = Decidim::Mpassid.auto_email_domain
+            "mpassid-#{person_identifier_digest}@#{domain}"
+          end
+        end
+      end
+
+      def saml_attributes
+        @saml_attributes ||= oauth_hash[:extra][:saml_attributes]
+      end
+    end
+  end
+end