feat: Linear OAuth 2.0 (#10851)

Fixes https://linear.app/chatwoot/issue/CW-3417/oauth-20-authentication
We are planning to publish the Chatwoot app in the Linear [integration
list](https://linear.app/docs/integration-directory). While we currently
use token-based authentication, Linear recommends OAuth2 authentication.
This PR implements OAuth2 support.

---------

Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>

app/controllers/api/v1/accounts/integrations/linear_controller.rb

@@ -1,5 +1,11 @@
 class Api::V1::Accounts::Integrations::LinearController < Api::V1::Accounts::BaseController
   before_action :fetch_conversation, only: [:link_issue, :linked_issues]
+  before_action :fetch_hook, only: [:destroy]
+
+  def destroy
+    @hook.destroy!
+    head :ok
+  end
 
   def teams
     teams = linear_processor_service.teams
@@ -90,4 +96,8 @@ class Api::V1::Accounts::Integrations::LinearController < Api::V1::Accounts::Bas
   def permitted_params
     params.permit(:team_id, :project_id, :conversation_id, :issue_id, :link_id, :title, :description, :assignee_id, :priority, label_ids: [])
   end
+
+  def fetch_hook
+    @hook = Integrations::Hook.where(account: Current.account).find_by(app_id: 'linear')
+  end
 end

app/controllers/linear/callbacks_controller.rb

@@ -0,0 +1,70 @@
+class Linear::CallbacksController < ApplicationController
+  include Linear::IntegrationHelper
+
+  def show
+    @response = oauth_client.auth_code.get_token(
+      params[:code],
+      redirect_uri: "#{base_url}/linear/callback"
+    )
+
+    handle_response
+  rescue StandardError => e
+    Rails.logger.error("Linear callback error: #{e.message}")
+    redirect_to linear_redirect_uri
+  end
+
+  private
+
+  def oauth_client
+    OAuth2::Client.new(
+      ENV.fetch('LINEAR_CLIENT_ID', nil),
+      ENV.fetch('LINEAR_CLIENT_SECRET', nil),
+      {
+        site: 'https://api.linear.app',
+        token_url: '/oauth/token',
+        authorize_url: '/oauth/authorize'
+      }
+    )
+  end
+
+  def handle_response
+    hook = account.hooks.new(
+      access_token: parsed_body['access_token'],
+      status: 'enabled',
+      app_id: 'linear',
+      settings: {
+        token_type: parsed_body['token_type'],
+        expires_in: parsed_body['expires_in'],
+        scope: parsed_body['scope']
+      }
+    )
+    # You may wonder why we're not handling the refresh token update, since the token will expire only after 10 years, https://github.com/linear/linear/issues/251
+    hook.save!
+    redirect_to linear_redirect_uri
+  rescue StandardError => e
+    Rails.logger.error("Linear callback error: #{e.message}")
+    redirect_to linear_redirect_uri
+  end
+
+  def account
+    @account ||= Account.find(account_id)
+  end
+
+  def account_id
+    return unless params[:state]
+
+    verify_linear_token(params[:state])
+  end
+
+  def linear_redirect_uri
+    "#{ENV.fetch('FRONTEND_URL', nil)}/app/accounts/#{account.id}/settings/integrations/linear"
+  end
+
+  def parsed_body
+    @parsed_body ||= @response.response.parsed
+  end
+
+  def base_url
+    ENV.fetch('FRONTEND_URL', 'http://localhost:3000')
+  end
+end

app/helpers/linear/integration_helper.rb

@@ -0,0 +1,47 @@
+module Linear::IntegrationHelper
+  # Generates a signed JWT token for Linear integration
+  #
+  # @param account_id [Integer] The account ID to encode in the token
+  # @return [String, nil] The encoded JWT token or nil if client secret is missing
+  def generate_linear_token(account_id)
+    return if client_secret.blank?
+
+    JWT.encode(token_payload(account_id), client_secret, 'HS256')
+  rescue StandardError => e
+    Rails.logger.error("Failed to generate Linear token: #{e.message}")
+    nil
+  end
+
+  def token_payload(account_id)
+    {
+      sub: account_id,
+      iat: Time.current.to_i
+    }
+  end
+
+  # Verifies and decodes a Linear JWT token
+  #
+  # @param token [String] The JWT token to verify
+  # @return [Integer, nil] The account ID from the token or nil if invalid
+  def verify_linear_token(token)
+    return if token.blank? || client_secret.blank?
+
+    decode_token(token, client_secret)
+  end
+
+  private
+
+  def client_secret
+    @client_secret ||= ENV.fetch('LINEAR_CLIENT_SECRET', nil)
+  end
+
+  def decode_token(token, secret)
+    JWT.decode(token, secret, true, {
+                 algorithm: 'HS256',
+                 verify_expiration: true
+               }).first['sub']
+  rescue StandardError => e
+    Rails.logger.error("Unexpected error verifying Linear token: #{e.message}")
+    nil
+  end
+end

app/javascript/dashboard/i18n/locale/en/integrations.json

@@ -297,6 +297,12 @@
         "TITLE": "Unlink",
         "SUCCESS": "Issue unlinked successfully",
         "ERROR": "There was an error unlinking the issue, please try again"
+      },
+      "DELETE": {
+        "TITLE": "Are you sure you want to delete the integration?",
+        "MESSAGE": "Are you sure you want to delete the integration?",
+        "CONFIRM": "Yes, delete",
+        "CANCEL": "Cancel"
       }
     }
   },

app/javascript/dashboard/routes/dashboard/settings/integrations/Linear.vue

@@ -0,0 +1,66 @@
+<script setup>
+import { ref, computed, onMounted } from 'vue';
+import {
+  useFunctionGetter,
+  useMapGetter,
+  useStore,
+} from 'dashboard/composables/store';
+
+import Integration from './Integration.vue';
+import Spinner from 'shared/components/Spinner.vue';
+
+const store = useStore();
+
+const integrationLoaded = ref(false);
+
+const integration = useFunctionGetter('integrations/getIntegration', 'linear');
+
+const uiFlags = useMapGetter('integrations/getUIFlags');
+
+const integrationAction = computed(() => {
+  if (integration.value.enabled) {
+    return 'disconnect';
+  }
+  return integration.value.action;
+});
+
+const initializeLinearIntegration = async () => {
+  await store.dispatch('integrations/get', 'linear');
+  integrationLoaded.value = true;
+};
+
+onMounted(() => {
+  initializeLinearIntegration();
+});
+</script>
+
+<template>
+  <div class="flex-grow flex-shrink p-4 overflow-auto">
+    <div class="flex flex-col">
+      <div class="flex flex-col">
+        <div>
+          <div
+            v-if="integrationLoaded && !uiFlags.isCreatingLinear"
+            class="p-4 mb-4 bg-white border border-solid rounded-sm dark:bg-slate-800 border-slate-75 dark:border-slate-700/50"
+          >
+            <Integration
+              :integration-id="integration.id"
+              :integration-logo="integration.logo"
+              :integration-name="integration.name"
+              :integration-description="integration.description"
+              :integration-enabled="integration.enabled"
+              :integration-action="integrationAction"
+              :delete-confirmation-text="{
+                title: $t('INTEGRATION_SETTINGS.LINEAR.DELETE.TITLE'),
+                message: $t('INTEGRATION_SETTINGS.LINEAR.DELETE.MESSAGE'),
+              }"
+            />
+          </div>
+          <div v-else class="flex items-center justify-center flex-1">
+            <Spinner size="" color-scheme="primary" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

app/javascript/dashboard/routes/dashboard/settings/integrations/integrations.routes.js

@@ -7,7 +7,7 @@ import Webhook from './Webhooks/Index.vue';
 import DashboardApps from './DashboardApps/Index.vue';
 import Slack from './Slack.vue';
 import SettingsContent from '../Wrapper.vue';
-
+import Linear from './Linear.vue';
 export default {
   routes: [
     {
@@ -71,6 +71,15 @@ export default {
           },
           props: route => ({ code: route.query.code }),
         },
+        {
+          path: 'linear',
+          name: 'settings_integrations_linear',
+          component: Linear,
+          meta: {
+            permissions: ['administrator'],
+          },
+          props: route => ({ code: route.query.code }),
+        },
         {
           path: ':integration_id',
           name: 'settings_applications_integration',

app/models/integrations/app.rb

@@ -1,4 +1,5 @@
 class Integrations::App
+  include Linear::IntegrationHelper
   attr_accessor :params
 
   def initialize(params)
@@ -25,10 +26,18 @@ class Integrations::App
     params[:fields]
   end
 
+  # There is no way to get the account_id from the linear callback
+  # so we are using the generate_linear_token method to generate a token and encode it in the state parameter
+  def encode_state
+    generate_linear_token(Current.account.id)
+  end
+
   def action
     case params[:id]
     when 'slack'
       "#{params[:action]}&client_id=#{ENV.fetch('SLACK_CLIENT_ID', nil)}&redirect_uri=#{self.class.slack_integration_url}"
+    when 'linear'
+      build_linear_action
     else
       params[:action]
     end
@@ -45,6 +54,17 @@ class Integrations::App
     end
   end
 
+  def build_linear_action
+    [
+      "#{params[:action]}?response_type=code",
+      "client_id=#{ENV.fetch('LINEAR_CLIENT_ID', nil)}",
+      "redirect_uri=#{self.class.linear_integration_url}",
+      "state=#{encode_state}",
+      'scope=read,write',
+      'prompt=consent'
+    ].join('&')
+  end
+
   def enabled?(account)
     case params[:id]
     when 'webhook'
@@ -64,6 +84,10 @@ class Integrations::App
     "#{ENV.fetch('FRONTEND_URL', nil)}/app/accounts/#{Current.account.id}/settings/integrations/slack"
   end
 
+  def self.linear_integration_url
+    "#{ENV.fetch('FRONTEND_URL', nil)}/linear/callback"
+  end
+
   class << self
     def apps
       Hashie::Mash.new(APPS_CONFIG)

app/views/api/v1/accounts/integrations/linear/create.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/app', formats: [:json], resource: @hook.app