Improve setup documentation. Add ENV vars for easier configuration

README.md

@@ -7,7 +7,7 @@ Decidim CiviCRM integration module
 
 This module provides certain integrations in order to use [CiviCRM](https://civicrm.org/) with Decidim.
 
-Currently, the implementation supported is using CiviCRM 5.3 with Drupal 7.8.
+Currently, the implementation supported is using CiviCRM 5.x with Drupal 7.x.
 
 Features:
 --------
@@ -20,6 +20,14 @@ Features:
 - Ability to sincronize users from groups in CiviCRM automatically with private participatory space members
 - Ability to redirect users to external url after joining a meeting (admin configurable)
 
+Requirements
+------------ 
+
+- The OAuth2 integration requires that Drupal has installed the module https://www.drupal.org/project/oauth2_server. Create a new Oauth Server and then a client with a CLIENT_ID and  CLIENT_SECRET. Add to the callback redirect urls your site: https://YOURDOMAIN.TLD/users/auth/civicrm/callback
+- The CiViCRM API integration requires to generate an API key for a user, follow the instructions in https://docs.civicrm.org/sysadmin/en/latest/setup/api-keys/. Use the generated secret for a particular user for the CIVICRM_API_SECRET. Extract from your `civicrm.settings.php` the CIVICRM_SITE_KEY.
+
+![OAuth2 Login](features/login.png)
+
 Install
 -------
 
@@ -47,37 +55,55 @@ bundle exec rails db:migrate
 
 ## Configuration
 
+By default, you can just get by using ENV vars to automatically configure the API and the OAuth2 integration.
+
+| ENV | Description | Example |
+|---|---|---|
+| CIVICRM_API_KEY | You user API key, [see how to generate one here](https://docs.civicrm.org/sysadmin/en/latest/setup/api-keys/).  | `XXXXXXXX` |
+| CIVICRM_SITE_KEY | Your CiViCRM installation key. Find it in your `civicrm.setttings.php` | `XXXXXXXX` |
+| CIVICRM_API_URL |  The URL for your CiViCRM v3 API. Go to https://YOURCIVICRM.SITE/en/civicrm/api3#explorer, run an example and you'll see the URL there. | `https://YOURCIVICRM.SITE/sites/all/modules/civicrm/extern/rest.php` |
+| CIVICRM_CLIENT_ID | In your Drupal, under the OAuth2 module administrator (https://YOURCIVICRM.SITE/en/admin/structure/oauth2-servers), create a new server and a new client. Define the client id and the client secret there | `some_id_you_created` |
+| CIVICRM_CLIENT_SECRET | Same as the previous one. | `XXXXXXXX` |
+| CIVICRM_SITE | Just the main URL of your Drupal/CiViCRM site | https://YOURCIVICRM.SITE |
+| CIVICRM_ICON | **Optional**, defaults to the original CiViCRM logo. If you want to override it, place the image under your `app/packs/images/my-icon.png` and reference it here as `media/images/my-icon.png` | `media/images/civicrm-icon.png` |
+
+
+### Alternate method
+
+There's more configuration options on this module (see [lib/decidim/civicrm.rb](lib/decidim/civicrm.rb)). 
 
-Customize your integration by creating an initializer (ie: `config/initializes/decidim_civicrm.rb`) and set some of the variables:
+In order to further customize your integration, you can create an initializer (ie: `config/initializes/decidim_civicrm.rb`) and set some of the variables:
 
 ```ruby
 # config/initializers/decidim_civicrm.rb
 
 Decidim::Civicrm.configure do |config|
   # Configure api credentials
   config.api =   {
-    key: Rails.application.secrets.dig(:civicrm, :api, :key),
-    secret: Rails.application.secrets.dig(:civicrm, :api, :secret),
+    api_key: Rails.application.secrets.dig(:civicrm, :api, :api_key),
+    site_key: Rails.application.secrets.dig(:civicrm, :api, :site_key),
     url: Rails.application.secrets.dig(:civicrm, :api, :url)
   }
 
   # Configure omniauth secrets
   config.omniauth =   {
+    enabled: Rails.application.secrets.dig(:omniauth, :civicrm, :enabled),
     client_id: Rails.application.secrets.dig(:omniauth, :civicrm, :client_id),
     client_secret: Rails.application.secrets.dig(:omniauth, :civicrm, :client_secret),
+    icon_path: "media/images/icon.png", # be sure to place the file under app/packs/images/icon.png
     site: Rails.application.secrets.dig(:omniauth, :civicrm, :site)
   }
 
   # whether to send notifications to user when they auto-verified or not:
   config.send_verification_notifications = false
 
   # Optional: enable or disable verification methods (all enableD by default)
-  config.authorizations = [:civicrm, :civicrm_groups]
+  config.authorizations = [:civicrm, :civicrm_groups, :civicrm_membership_types]
 end
 
 ```
 
-> **IMPORTANT**: Remember to activate the verification methods (civicrm and civicrm_groups) in the Decidim `/system` admin page
+> **IMPORTANT**: Remember to activate the verification methods (civicrm, civicrm_groups and civicrm_membership_types) in the Decidim `/system` admin page
 
 
 ## Contributing

Rakefile

@@ -48,7 +48,6 @@ task :development_app do
     )
   end
 
-  install_initializer("development_app", "development")
   install_module("development_app")
   seed_db("development_app")
 end

app/controllers/concerns/decidim/civicrm/needs_civicrm_snippets.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Decidim
+  module Civicrm
+    module NeedsCivicrmSnippets
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :snippets
+      end
+
+      def snippets
+        @snippets ||= Decidim::Snippets.new
+
+        unless @snippets.any?(:oauth2_civicrm)
+          @snippets.add(:oauth2_civicrm, ActionController::Base.helpers.javascript_pack_tag("decidim_civicrm"))
+          @snippets.add(:oauth2_civicrm, ActionController::Base.helpers.stylesheet_pack_tag("decidim_civicrm"))
+          @snippets.add(:head, @snippets.for(:oauth2_civicrm))
+        end
+
+        @snippets
+      end
+    end
+  end
+end

app/packs/entrypoints/decidim_civicrm.js

@@ -0,0 +1,3 @@
+import "stylesheets/decidim/civicrm/oauth_login.scss";
+// Load images
+require.context("../images", true)

app/packs/stylesheets/decidim/civicrm/oauth_login.scss

@@ -0,0 +1,17 @@
+.social-register,
+.button--social.button--social--mini {
+  &.button--civicrm {
+    .button--social__icon {
+      padding: 4px;
+
+      .icon {
+        display: inline-block !important;
+        background: white;
+        width: 36px;
+        height: auto;
+        padding: 2px;
+        border-radius: 3px;
+      }
+    }
+  }
+}

config/assets.rb

@@ -19,5 +19,6 @@
 # SCSS files within the entrypoints, they become available for inclusion using
 # `stylesheet_pack_tag`.
 Decidim::Webpacker.register_entrypoints(
+  decidim_civicrm: "#{base_path}/app/packs/entrypoints/decidim_civicrm.js",
   decidim_admin_civicrm_selects: "#{base_path}/app/packs/entrypoints/decidim_admin_civicrm_selects.js"
 )

config/locales/en.yml

@@ -123,6 +123,13 @@ en:
       contact:
         errors:
           not_unique: Contact is already taken
+    system:
+      organizations:
+        omniauth_settings:
+          civicrm:
+            client_id: Client ID
+            client_secret: Client secret
+            site: Site
   layouts:
     decidim:
       admin:

lib/decidim/civicrm.rb

@@ -18,18 +18,20 @@ module Civicrm
     # setup API credentials
     config_accessor :api do
       {
-        key: nil,
-        secret: nil,
-        url: nil
+        api_key: ENV["CIVICRM_API_KEY"].presence,
+        site_key: ENV["CIVICRM_SITE_KEY"].presence,
+        url: ENV["CIVICRM_API_URL"].presence
       }
     end
 
     # setup a hash with :client_id, :client_secret and :site to enable omniauth authentication
     config_accessor :omniauth do
       {
-        client_id: nil,
-        client_secret: nil,
-        site: nil
+        enabled: ENV["CIVICRM_CLIENT_ID"].present?,
+        client_id: ENV["CIVICRM_CLIENT_ID"].presence,
+        client_secret: ENV["CIVICRM_CLIENT_SECRET"].presence,
+        site: ENV["CIVICRM_SITE"].presence,
+        icon_path: ENV["CIVICRM_ICON"].presence || "media/images/civicrm-icon.png"
       }
     end
 

lib/decidim/civicrm/api.rb

@@ -26,8 +26,8 @@ def self.config
 
       def self.credentials
         {
-          api_key: config[:key],
-          key: config[:secret]
+          api_key: config[:api_key],
+          key: config[:site_key]
         }
       end
 

lib/decidim/civicrm/engine.rb

@@ -16,6 +16,8 @@ class Engine < ::Rails::Engine
         # omniauth only trigger notifications when a new user is registered
         # this adds a notification too when user logs in
         Decidim::CreateOmniauthRegistration.include(Decidim::Civicrm::CreateOmniauthRegistrationOverride)
+        Decidim::Devise::SessionsController.include(Decidim::Civicrm::NeedsCivicrmSnippets)
+        Decidim::ApplicationController.include(Decidim::Civicrm::NeedsCivicrmSnippets)
         Decidim::Admin::ResourcePermissionsController.include(Decidim::Civicrm::Admin::NeedsMultiselectSnippets)
         Decidim::Meetings::RegistrationsController.include(Decidim::Civicrm::MeetingsRegistrationsControllerOverride)
         Decidim::Meetings::JoinMeeting.include(Decidim::Civicrm::JoinMeetingOverride)
@@ -26,13 +28,17 @@ class Engine < ::Rails::Engine
       end
 
       initializer "decidim_civicrm.omniauth" do
-        next unless Decidim::Civicrm.omniauth && Decidim::Civicrm.omniauth[:client_id]
+        next unless Decidim::Civicrm.omniauth && Decidim::Civicrm.omniauth[:enabled].present?
+
+        # Decidim use the secrets configuration to decide whether to show the omniauth provider
+        Rails.application.secrets[:omniauth][Decidim::Civicrm::OMNIAUTH_PROVIDER_NAME.to_sym] = Decidim::Civicrm.omniauth
 
         Rails.application.config.middleware.use OmniAuth::Builder do
           provider Decidim::Civicrm::OMNIAUTH_PROVIDER_NAME,
                    client_id: Decidim::Civicrm.omniauth[:client_id],
                    client_secret: Decidim::Civicrm.omniauth[:client_secret],
                    site: Decidim::Civicrm.omniauth[:site],
+                   icon_path: Decidim::Civicrm.omniauth[:icon_path],
                    scope: "openid profile email"
         end
       end

lib/decidim/civicrm/version.rb

@@ -5,6 +5,6 @@ module Decidim
   module Civicrm
     DECIDIM_VERSION = "0.26.1"
     COMPAT_DECIDIM_VERSION = ">= 0.25.0, < 0.27"
-    VERSION = "0.4"
+    VERSION = "0.5"
   end
 end

lib/generators/decidim/civicrm/templates/civicrm_config.rb

@@ -3,16 +3,17 @@
 Decidim::Civicrm.configure do |config|
   # Configure api credentials
   config.api = {
-    key: Rails.application.secrets.dig(:civicrm, :api, :key),
-    secret: Rails.application.secrets.dig(:civicrm, :api, :secret),
+    api_key: Rails.application.secrets.dig(:civicrm, :api, :api_key),
+    site_key: Rails.application.secrets.dig(:civicrm, :api, :site_key),
     url: Rails.application.secrets.dig(:civicrm, :api, :url)
   }
 
   # Configure omniauth secrets
   config.omniauth = {
     client_id: Rails.application.secrets.dig(:omniauth, :civicrm, :client_id),
     client_secret: Rails.application.secrets.dig(:omniauth, :civicrm, :client_secret),
-    site: Rails.application.secrets.dig(:omniauth, :civicrm, :site)
+    site: Rails.application.secrets.dig(:omniauth, :civicrm, :site),
+    icon_path: Rails.application.secrets.dig(:omniauth, :civicrm, :icon_path)
   }
 
   # whether to send notifications to user when they auto-verified or not:

lib/generators/decidim/civicrm/templates/test_civicrm_config.rb

@@ -4,8 +4,8 @@
 Decidim::Civicrm.configure do |config|
   # Configure api credentials
   config.api = {
-    key: "test-api-key",
-    secret: "test-api-secret",
+    api_key: "test-api-key",
+    site_key: "test-site-key",
     url: "http://test.api.example.org"
   }
 

lib/omniauth/strategies/civicrm.rb

@@ -21,7 +21,7 @@ class Civicrm < OmniAuth::Strategies::OAuth2
       info do
         {
           name: extra[:contact][:display_name],
-          nickname: raw_info["preferred_username"],
+          nickname: sanitized_nickname,
           email: raw_info["email"],
           image: raw_info["picture"]
         }
@@ -45,7 +45,7 @@ def client
       end
 
       def callback_url
-        full_host + script_name + callback_path
+        full_host + callback_path
       end
 
       def raw_info
@@ -55,6 +55,11 @@ def raw_info
       def civicrm_info
         @civicrm_info ||= ::Decidim::Civicrm::Api::FindUser.new(uid).result
       end
+
+      def sanitized_nickname
+        # TODO: restrict nicknamize to the current organization
+        Decidim::UserBaseEntity.nicknamize(raw_info["preferred_username"] || raw_info["email"])
+      end
     end
   end
 end