decidim-api 0.30.2 → 0.31.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 603657ac1ced06c41beda6562486e56d47da7bfa48c85c84081f3e6976f07285
-  data.tar.gz: a8cdce3c7868c5731dec9cd01988297be0e1a1e79845c2a6c0f514abd4f1f08d
+  metadata.gz: ae9105250ff986390b7ea4387812c51f7f2f69cbf0b609e2146ccf64ce6b76fc
+  data.tar.gz: 47ac99a3cc8d3fefc0d1adb494f182a30c7131ccc81fdf2a8e7614fee8265062
 SHA512:
-  metadata.gz: '03355009bd2124597eb48569269dd215a419dd70fa7225c3dd90a3b31b5735134f484b3813835c1dc324de27eefd68b64f1efe47d57f2ca5e6a94076a4693f0e'
-  data.tar.gz: 8b8a797115ee099b07bdf8d91c6bd8cc41d9253d5fd6333ce869e2380d7117b8edcf0fc360eb8d402adbf62f9403e23a9b32610409134c5b076fb2c39ee74664
+  metadata.gz: ea6328163dffd2c5b6d3d2cf1025017346a2264ebac6c5179897d6857329802aa345b6bd9e67635df91320ca9daa9c65a0e29e46d81bfccd160c80101343c208
+  data.tar.gz: 65c3fab8a6a6e163dd4d4d9b40d0fc8c7e00c85abaf462e9e95b9a0d02077d381f2a35bfceb03124faa7720a5674865fce76b9e03459cd073ec9068d267988b1

data/app/controllers/decidim/api/application_controller.rb

@@ -5,6 +5,8 @@ module Decidim
     # Base controller for `decidim-api`. All other controllers inherit from this.
     class ApplicationController < ::DecidimController
       skip_before_action :verify_authenticity_token
+      before_action :ensure_api_authenticated!
+
       include NeedsOrganization
       include UseOrganizationTimeZone
       include NeedsPermission
@@ -22,6 +24,24 @@ module Decidim
       def permission_scope
         :public
       end
+
+      private
+
+      def ensure_api_authenticated!
+        return unless Decidim::Api.force_api_authentication
+        return if user_signed_in?
+
+        respond_to do |format|
+          format.html do
+            flash[:warning] = t("actions.login_before_access", scope: "decidim.core")
+            store_location_for(:user, request.path)
+            redirect_to decidim.new_user_session_path
+          end
+          format.json do
+            render json: { error: "Access denied" }, status: :unauthorized
+          end
+        end
+      end
     end
   end
 end

data/app/controllers/decidim/api/queries_controller.rb

@@ -29,10 +29,42 @@ module Decidim
       def context
         {
           current_organization:,
-          current_user:
+          current_user: api_user,
+          scopes: api_scopes
         }
       end
 
+      def api_user
+        @api_user = current_api_user || current_user
+      end
+
+      # Determines the scopes for the user for API requests.
+      #
+      # @return [Doorkeeper::OAuth::Scopes]
+      def api_scopes
+        if doorkeeper_token
+          doorkeeper_token.scopes
+        elsif api_user.present?
+          # In case a doorkeeper token is not available, we assume the user is
+          # either:
+          # - A regular authenticated user in Decidim using the API locally
+          #   from within Decidim using the system with the cookie based
+          #   authentication
+          # - A Decidim::Api::ApiUser authenticated through the `/api/sign_in`
+          #   endpoint for machine-to-machine integrations using the system with
+          #   the assigned JSON Web Token (JWT).
+          #
+          # In both of these cases we assume all scopes as the user does not
+          # request any specific scopes during the authentication process and
+          # the user would be anyways able to perform any actions they are
+          # normally allowed to perform within the regular user interface.
+          ::Doorkeeper::OAuth::Scopes.from_array(::Doorkeeper.config.scopes.all)
+        else
+          # In case no user is present, we only allow the user to read the API.
+          ::Doorkeeper::OAuth::Scopes.from_string("api:read")
+        end
+      end
+
       def prepare_variables(variables_param)
         case variables_param
         when String

data/app/controllers/decidim/api/sessions_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Api
+    class SessionsController < ::Devise::SessionsController
+      skip_before_action :verify_authenticity_token
+
+      respond_to :json
+
+      def failure
+        render json: resource_attributes(anonymous_user).merge(
+          "jwt_token" => nil,
+          "avatar" => nil
+        ), status: :unauthorized
+      end
+
+      private
+
+      def auth_options
+        { scope: resource_name, recall: "#{controller_path}#failure" }
+      end
+
+      def after_sign_in_path_for(_resource_or_scope)
+        nil
+      end
+
+      def respond_with(resource, _opts = {})
+        serialized_user = resource_attributes(resource)
+
+        if request.env[::Warden::JWTAuth::Middleware::TokenDispatcher::ENV_KEY]
+          jwt_token = request.env[::Warden::JWTAuth::Hooks::PREPARED_TOKEN_ENV_KEY]
+          return failure if jwt_token.blank?
+
+          # Some systems (that is you Microsoft Power Automate (Flow)) may be
+          # parsing off the headers which makes it difficult for the API users
+          # to get the bearer token. This allows them to get it from the request
+          # body instead.
+          return render json: serialized_user.merge(
+            "jwt_token" => jwt_token,
+            "avatar" => nil
+          ), status: :ok
+        end
+
+        # Since avatar can be ActiveStorage object now, it can cause infinite loops
+        render json: serialized_user.merge("avatar" => nil)
+      end
+
+      def respond_to_on_destroy
+        head :ok
+      end
+
+      def resource_attributes(resource)
+        resource.attributes.slice("id", "name", "nickname")
+      end
+
+      def anonymous_user
+        Decidim::Api::ApiUser.new(api_key: params.dig("api_user", "key"))
+      end
+    end
+  end
+end

data/app/models/decidim/api/api_user.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Api
+    class ApiUser < UserBaseEntity
+      include Decidim::Traceable
+
+      attribute :tos_agreement, :boolean, default: true
+
+      devise :api_authenticatable, :jwt_authenticatable, jwt_revocation_strategy: JwtDenylist
+
+      validates :api_key, :name, uniqueness: { case_sensitive: true, scope: :organization }
+
+      def presenter
+        Decidim::Api::ApiUserPresenter.new(self)
+      end
+
+      def self.log_presenter_class_for(_log)
+        Decidim::AdminLog::UserPresenter
+      end
+
+      # Checks if the user has the given `role` or not.
+      #
+      # role - a String or a Symbol that represents the role that is being
+      #   checked
+      #
+      # Returns a boolean.
+      def role?(role)
+        roles.include?(role.to_s)
+      end
+
+      # Public: Returns the active role of the user
+      def active_role
+        admin ? "admin" : roles.first
+      end
+
+      # Public: returns the user's name or the default one
+      def name
+        super || I18n.t("decidim.anonymous_user")
+      end
+
+      # Check if the user account has been deleted or not
+      def deleted?
+        deleted_at.present?
+      end
+
+      # Public: whether the user has been officialized or not
+      def officialized?
+        !officialized_at.nil?
+      end
+
+      def confirmed?
+        true
+      end
+
+      def follows?(followable)
+        Decidim::Follow.where(user: self, followable: followable).any?
+      end
+
+      # Public: whether the user accepts direct messages from another
+      def accepts_conversation?(_user)
+        false
+      end
+
+      def unread_conversations
+        Decidim::Messaging::Conversation.unread_by(self)
+      end
+
+      def tos_accepted?
+        true
+      end
+
+      def admin_terms_accepted?
+        true
+      end
+
+      def needs_password_update?
+        false
+      end
+    end
+  end
+end

data/app/models/decidim/api/jwt_denylist.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Api
+    class JwtDenylist < ApplicationRecord
+      include ::Devise::JWT::RevocationStrategies::Denylist
+
+      self.table_name = :decidim_api_jwt_denylists
+    end
+  end
+end

data/app/packs/entrypoints/decidim_api_graphiql.js

@@ -9,7 +9,7 @@ import React from "react";
 import { createRoot } from "react-dom/client";
 
 import { GraphiQL } from "graphiql"; // eslint-disable-line no-unused-vars
-import Configuration from "src/decidim/configuration";
+import Configuration from "src/decidim/refactor/implementation/configuration"
 
 window.Decidim = window.Decidim || {};
 window.Decidim.config = new Configuration();
@@ -89,6 +89,7 @@ const graphQLFetcher = function (graphQLParams) {
   });
 };
 
+// We do not have turbo or decidim_core when this file is loaded, and we need to leave it with old "DOMContentLoaded"
 window.addEventListener("DOMContentLoaded", () => {
   const container = document.getElementById("graphiql-container");
 

data/app/presenters/decidim/api/api_user_presenter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Api
+    class ApiUserPresenter < Decidim::UserPresenter
+      def deleted?
+        false
+      end
+
+      def badge
+        "verified-badge"
+      end
+
+      def can_be_contacted?
+        false
+      end
+
+      def can_follow?
+        false
+      end
+    end
+  end
+end

data/config/assets.rb

@@ -2,8 +2,8 @@
 
 base_path = File.expand_path("..", __dir__)
 
-Decidim::Webpacker.register_path("#{base_path}/app/packs")
-Decidim::Webpacker.register_entrypoints(
+Decidim::Shakapacker.register_path("#{base_path}/app/packs")
+Decidim::Shakapacker.register_entrypoints(
   decidim_api_docs: "#{base_path}/app/packs/entrypoints/decidim_api_docs.js",
   decidim_api_graphiql: "#{base_path}/app/packs/entrypoints/decidim_api_graphiql.js"
 )

data/config/initializers/devise.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+Devise.jwt do |jwt|
+  # In order to be compatible with the JWT authentication, we need to set these
+  # configurations. JWT secret is being used by the devise-jwt to sign the
+  # tokens, once the user authenticated. The token signature ensures the
+  # validity of the token and that the user has not tampered with it. If the
+  # secret is not set correctly, the API authentication does not work.
+  #
+  # Note that the `dispatch_requests` and `revocation_requests` paths are the
+  # full paths because we do not want the JWT tokens to be dispatched or revoked
+  # during normal Decidim user sign ins or sign outs. This also requires a small
+  # override to `Warden::JWTAuth` which is defined at
+  # `decidim-api/lib/warden/jwt_auth/decidim_overrides.rb`.
+  jwt.secret = Decidim::Env.new("DECIDIM_API_JWT_SECRET").value
+  next unless jwt.secret
+
+  jwt.dispatch_requests = [
+    ["POST", %r{^/api/sign_in$}]
+  ]
+  jwt.revocation_requests = [
+    ["DELETE", %r{^/api/sign_out$}]
+  ]
+  jwt.expiration_time = Decidim::Api.jwt_expires_in.minutes.to_i
+  jwt.aud_header = "X_JWT_AUD"
+end

data/config/routes.rb

@@ -6,4 +6,12 @@ Decidim::Api::Engine.routes.draw do
   get "/docs/*path", to: "documentation#show"
   get "/", to: redirect("/api/docs")
   post "/" => "queries#create", :as => :root
+
+  devise_for :api_users,
+             class_name: "Decidim::Api::ApiUser",
+             module: "decidim/api",
+             path: "/",
+             router_name: :decidim_api,
+             controllers: { sessions: "decidim/api/sessions" },
+             only: :sessions
 end

data/decidim-api.gemspec

@@ -33,7 +33,8 @@ Gem::Specification.new do |s|
   end
 
   s.add_dependency "decidim-core", Decidim::Api.version
-  s.add_dependency "graphql", "~> 2.4.0"
+  s.add_dependency "devise-jwt", "~> 0.12.1"
+  s.add_dependency "graphql", "~> 2.4.0", ">= 2.4.17"
   s.add_dependency "graphql-docs", "~> 5.0"
   s.add_dependency "rack-cors", "~> 1.0"
 

data/docs/usage.md

@@ -12,7 +12,7 @@ Typically (although some particular installations may change that) you will find
 * `URL/api/docs` This documentation, every Decidim site should provide one.
 * `URL/api/graphiql` [GraphiQL](https://github.com/graphql/graphiql) is a in-browser IDE for exploring GraphQL APIs. Some Decidim installations may choose to remove access to this tool. In that case you can use a [standalone version](https://electronjs.org/apps/graphiql) and use any `URL/api` as the endpoint
 
-### Using the GraphQL APi
+### Using the GraphQL API
 
 The GraphQL format is a JSON formatted text that is specified in a query. Response is a JSON object as well. For details about specification check the official [GraphQL site](https://graphql.org/learn/).
 
@@ -54,6 +54,96 @@ The most practical way to experiment with GraphQL, however, is just to use the i
 
 From now on, we will skip the "query" keyword for the purpose of readability. You can skip it too if you are using GraphiQL, if you are querying directly (by using CURL for instance) you will need to include it.
 
+### Signing in to the API
+
+In case you want to use the API as a sign in user to perform mutations representing a user in Decidim, you have two available options for such integrations through the system administration panel:
+
+1. Creating an OAuth application and implementing the OAuth authentication flow for the users of your application. Use this option for participant-facing applications where the participants represent themselves in Decidim through the API.
+2. Creating API credentials and signing in to the API with these credentials to perform the operations as a signed in machine user. Use this option for machine-to-machine automations where there is no real end user interacting with Decidim.
+
+If you only want to test the GraphQL queries as a signed in user, you can use the normal Decidim authentication functionality to sign in and then use the GraphiQL IDE to perform these queries as a signed in user.
+
+#### OAuth flow for participant-facing applications
+
+Participant-facing applications where the participants need to interact with Decidim through GraphQL mutations can be integrated using OAuth applications. In order to configure such integration capability from the system administration panel, create a new OAuth application and provide the necessary details for your integration. Note that the "application type" for such applications would typically be "Public". For more information regarding the application types, refer to [RFC 6749 Section 2.1. (OAuth client types)](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
+
+In order to use the OAuth access tokens to represent the user through the API, please select the following scopes as "Available" scopes for the application:
+
+* `user` - Authenticated users have the ability to represent a logged in user in Decidim
+* `api:read` - Authenticated users have the ability to read data from the API
+* `api:write` - Authenticated users have the ability to write data through the API (in case your external application needs to perform mutations over the API on behalf of the user)
+
+Once configured, you can now use any OAuth authentication library to perform the OAuth authentication flow with your application users and receive an access token to utilize the Decidim API representing the signed in user. Please note that with public OAuth clients especially (and recommended also for confidential clients), you have to use [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) with the authorization flow.
+
+Once the OAuth application is created, you can authenticate against it with the following steps:
+
+1. Send the user to perform an OAuth authorization request at Decidim with the required API scopes (`user`, `api:read` and `api:write` if you want to perform mutations over the API). Along with the authorization request, also send the additional parameters required by PKCE (`code_challenge` and `code_challenge_method`).
+2. Receive an OAuth authorization code back to your application's configured redirect URI.
+3. Utilizing the received authorization code, request an OAuth access token from the OAuth token endpoint. Along with the token request, also send the additional parameter required by PKCE `code_verifier`.
+4. The issued token is a JSON Web Token (JWT) when the authorization request contains the defined scopes. This token can be now used to represent the user in further calls to the API by passing the token with its type (`Bearer`) within the HTTP Authorization header with the request to the API.
+
+When doing the requests to the API, you also need to pass the OAuth client ID within the `X-Jwt-Aud` header of the requests in order for the token to be recognized as a valid token for the issued client. Passing the bearer token to the `Authorization` header and the OAuth client ID to the `X-Jwt-Aud` header, you can send the following HTTP request to the API to validate that the token works and the user is recognized as signed in:
+
+```http
+POST /api HTTP/1.1
+Accept: application/json
+Authorization: Bearer token
+Content-Length: 53
+Content-Type: application/json
+Host: DOMAIN
+X-Jwt-Aud: OAUTH_CLIENT_ID
+
+{"query":"{ session { user { id name nickname } } }"}
+```
+
+You should see the user details in the response in case the token is valid and you have configured the API correctly. If the response does not contain the user details, please refer to the Decidim configuration documentation.
+
+Once the interaction with the API is completed, it is recommended to revoke the tokens, which is similar to the user signing out of the application. This can be done utilizing the OAuth revocation endpoint provided by Decidim. After the token is revoked, it is no longer valid and the user has to perform a re-authorization the next time they want to utilize the API.
+
+In case you need tokens with a longer life span, you can either look into the Decidim documentation to extend the validity period of the access tokens or enable refresh tokens for the OAuth application when configuring it. However, note that tokens with longer lifespan can weaken the security of your system and make your application users vulnerable to security threats. Such use cases should be carefully planned and the security concerns should be addressed seriously.
+
+#### API credentials flow for machine-to-machine automations
+
+The API credentials represent an administrative user in Decidim that performs administrative tasks on behalf of the end users. This type of integration flows should never live on devices that the participants have access to. These types of integrations are meant for different types of automations, such as transferring proposal answers or meeting reports back to Decidim from an external system automatically, e.g. once a day.
+
+Note that these credentials are highly sensitive and have elevated permissions, so take good care of the system security where you are planning to store these credentials. If these credentials end up in participants' hands, the whole system is compromised and no longer secure. You should always primarily create OAuth integrations where the end users will manually perform the authorization for the application to perform actions on behalf of them.
+
+Once you have validated that this is the correct way for your integration to operate, you can create the API credentials from the system administration panel. You will receive an API key and API secret after creating the credentials. These credentials should be also manually rotated on a regular basis to prevent unauthorized access to the system with these credentials in case they are leaked. The credentials have to be manually rotated in order to prevent external applications breaking because they cannot rotate the credentials themselves and they are typically statically configured for these applications.
+
+Given you have issued the API key and API secret, you can now send a sign in request to the API using these credentials as follows:
+
+```bash
+curl -s -i -H "Content-type: application/x-www-form-urlencoded" \
+  -d "api_user[key]=PASTE_API_KEY_HERE" \
+  -d "api_user[secret]=PASTE_API_SECRET_HERE" \
+  -X POST https://DOMAIN/api/sign_in | grep 'Authorization' | cut -d ' ' -f2-
+```
+
+After running this command, you should see the following string in the console, where `token` is replaced with the access token:
+
+```bash
+Bearer token
+```
+
+This string is passed to the following requests within the HTTP `Authorization` header to represent the user during API calls. You can use the following example query to test it out and confirm that signing in works as expected:
+
+```bash
+curl -w "\n" -H "Content-Type: application/json" \
+  -H "Authorization: Bearer token" \
+  -d '{"query":"{ session { user { id name nickname } } }"}' \
+  -X POST https://DOMAIN/api
+```
+
+You should see the user details in the response in case the token is valid and you have configured the API correctly. If the response does not contain the user details, please refer to the Decidim configuration documentation.
+
+Once the API interaction is done, you should always make an HTTP DELETE request to `/api/sign_out` with the same token in order to revoke the token from further access as follows:
+
+```bash
+curl -s -o /dev/null -w "HTTP %{http_code}\n" \
+  -H "Authorization: Bearer token" \
+  -X DELETE http://DOMAIN/api/sign_out
+```
+
 ### Usage limits
 
 Decidim is just a Rails application, meaning that any particular installation may implement custom limits in order to access the API (and the application in general).
@@ -404,11 +494,11 @@ Consider this query:
         translation(locale: "en")
       }
       ... on Proposals {
-        proposals(order: {endorsementCount: "desc"}, first: 2) {
+        proposals(order: {likeCount: "desc"}, first: 2) {
           edges {
             node {
               id
-              endorsements {
+              likes {
                 name
               }
             }
@@ -437,7 +527,7 @@ The response:
               {
                 "node": {
                   "id": "35",
-                  "endorsements": [
+                  "likes": [
                     {
                       "name": "Ms. Johnathon Schaefer"
                     },
@@ -468,7 +558,7 @@ The response:
               {
                 "node": {
                   "id": "33",
-                  "endorsements": [
+                  "likes": [
                     {
                       "name": "Spring Brakus"
                     },
@@ -529,7 +619,7 @@ Example:
           edges {
             node {
               id
-              endorsements {
+              likes {
                 name
               }
             }
@@ -564,13 +654,13 @@ Being the response:
               {
                 "node": {
                   "id": "32",
-                  "endorsements": []
+                  "likes": []
                 }
               },
               {
                 "node": {
                   "id": "31",
-                  "endorsements": [
+                  "likes": [
                     {
                       "name": "Mr. Nicolas Raynor"
                     },

data/lib/decidim/api/component_mutation_type.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Api
+    class ComponentMutationType < GraphQL::Schema::Union
+      description "A component mutation."
+
+      possible_types(*Decidim::MutationRegistry.instance.mutation_types)
+
+      def self.resolve_type(obj, _ctx)
+        mod = obj.manifest_name.camelize
+        "Decidim::#{mod}::#{mod}MutationType".constantize
+      rescue NameError
+        Rails.logger.warn("Mutation type not found for #{mod}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/decidim/api/devise.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "devise/models/api_authenticatable"
+require "devise/strategies/api_authenticatable"
+
+Devise.add_module(
+  :api_authenticatable,
+  model: true,
+  strategy: true,
+  controller: :sessions,
+  route: { session: [nil, :destroy] }
+)

data/lib/decidim/api/engine.rb

@@ -27,7 +27,7 @@ module Decidim
         app.config.middleware.insert_before 0, Rack::Cors do
           allow do
             origins "*"
-            resource "/api", headers: :any, methods: [:post, :options]
+            resource "/api/*", headers: :any, methods: [:post, :options]
           end
         end
       end
@@ -41,7 +41,7 @@ module Decidim
         end
       end
 
-      initializer "decidim_api.webpacker.assets_path" do
+      initializer "decidim_api.shakapacker.assets_path" do
         Decidim.register_assets_path File.expand_path("app/packs", root)
       end
     end