fix(integrations): configure Jira OAuth per-integration via admin UI (#462)

Jira OAuth previously relied on global JIRA_CLIENT_ID/SECRET/REDIRECT_URI
env vars and Jira-specific auth/callback routes, which prevented each
instance from registering its own Atlassian OAuth app from the admin UI.

- JiraAdapter now prefers per-integration credentials (clientId/secret/
  redirectUri) decrypted by IntegrationManager, falling back to the legacy
  JIRA_* env vars only when an integration provides none.
- Remove the Jira-specific /api/integrations/jira/auth and /callback routes
  in favor of the generic /api/integrations/oauth/<provider>/* flow.
- test-connection: the OAuth2 path no longer attempts a non-existent
  client-credentials probe; it confirms client config is present and returns
  requiresUserAuth so the integration is not prematurely marked ACTIVE.
- Admin UI: surface the canonical callback URL (with copy), add Authorize/
  Reauthorize actions and an "Awaiting authorization" status for OAuth
  integrations not yet connected.
- Document the per-integration setup and legacy env fallback; add i18n keys.

Author: therealbrad

docs/docs/user-guide/integrations.md

@@ -221,22 +221,19 @@ When using API key authentication, and assuming the account has the required per
 
 #### Jira with OAuth 2.0
 
-OAuth 2.0 is Atlassian's preferred authentication path for Jira Cloud and is recommended for any team where the per-user reporter attribution and granular scoping matter.
+OAuth 2.0 is Atlassian's preferred authentication path for Jira Cloud and is recommended for any team where per-user reporter attribution and granular scoping matter. Each user authorizes individually and issues are created as that user.
 
-1. Create OAuth app in [Atlassian Developer Console](https://developer.atlassian.com/console)
-2. Set redirect URL: `https://your-testplanit-domain/api/auth/jira/callback`
-3. Configure in TestPlanIt:
-
-```text
-Client ID: [from-atlassian]
-Client Secret: [from-atlassian]
-```
+1. Create an OAuth 2.0 (3LO) integration in the [Atlassian Developer Console](https://developer.atlassian.com/console).
+2. Under **Permissions**, add the **Jira API** and select these scopes: `read:jira-work`, `write:jira-work`, and `read:jira-user`. (TestPlanIt also requests `offline_access` during authorization so it can refresh tokens — you don't add that one in the console.)
+3. Under **Authorization**, set the **Callback URL** to:
 
-Benefits:
+   ```text
+   <your-testplanit-url>/api/integrations/oauth/jira/callback
+   ```
 
-- Provides user-specific authentication
-- Each user authorizes their own Jira access
-- Issues created with the actual user as reporter
+   TestPlanIt shows this exact URL (with a copy button) in the integration dialog when you choose OAuth 2.0, so you don't have to construct it by hand.
+4. In TestPlanIt, add a Jira integration, choose **OAuth 2.0**, and enter the **Client ID** and **Client Secret** from the app, plus your Jira site URL (e.g. `https://your-domain.atlassian.net`).
+5. Finish the shared steps in [Completing the OAuth setup](#completing-the-oauth-setup-all-providers) — the integration must be authorized, activated, assigned to a project, and have a linked project before issues can be created.
 
 #### GitHub with Personal Access Token
 
@@ -336,10 +333,10 @@ OAuth 2.0 gives **per-user attribution**: each user authorizes individually and
 
 Creating the OAuth app and entering the Client ID/Secret is only half the setup. Issue creation stays blocked until an administrator (or project manager) finishes these steps **in order**:
 
-1. **Activate the integration.** In **Administration → Issue Integrations**, click **Test Connection** on the new integration. This validates the configuration and marks it **Active**. An inactive integration does not appear when assigning to a project.
+1. **Activate the integration by authorizing it.** A new OAuth 2.0 integration shows **Awaiting authorization** — this is expected, not an error. (Running **Test Connection** only confirms the Client ID/Secret are well-formed; OAuth has no client-credentials grant, so it cannot mark the integration Active on its own.) In **Administration → Issue Integrations**, click **Authorize** on the integration row, and grant access on the provider's consent screen. This connects your account and flips the integration to **Active**. An integration that is not yet Active does not appear when assigning to a project.
 2. **Assign it to a project.** In **Project Settings → Issue Integrations**, click **Assign** on the integration.
 3. **Link an external project (repository).** In the integration's settings panel, use **Linked External Projects → Add Projects**, select the target repository (e.g. `owner/repo`), click **Add Selected**, then **Save Settings**. This step is required — without a linked external project the Create Issue dialog reports **"Integration Not Configured"** and the **Create** button stays disabled.
-4. **Authorize — once per user.** Each person who will create issues opens **Project → Integrations**, clicks **Authorize**, and grants access on the provider's consent screen. Because authorization is per-user, every issue is attributed to the individual who created it.
+4. **Authorize the remaining users — once per user.** Authorization is per-user, so each *additional* person who will create issues opens **Project → Integrations**, clicks **Authorize**, and grants access on the provider's consent screen. (The admin who activated the integration in step 1 is already authorized.) Every issue is then attributed to the individual who created it.
 
 #### Azure DevOps
 

testplanit/.env.example

@@ -28,11 +28,26 @@ DATABASE_URL="postgresql://user:password@postgres:5432/testplanit?schema=public"
 # POSTGRES_PORT=5432
 
 # Next.js Configuration
+# NEXTAUTH_URL must be the app's public URL. It also forms the OAuth callback
+# (redirect) URI that issue-tracker integrations register with their providers:
+#   ${NEXTAUTH_URL}/api/integrations/oauth/<provider>/callback
+# (e.g. .../api/integrations/oauth/jira/callback). OAuth client credentials
+# for Jira/GitHub/GitLab/Gitea are entered per-integration in
+# Administration → Issue Integrations — not via environment variables.
 NEXTAUTH_URL="http://localhost:3000"
 
 # Generate a secure secret for NextAuth (e.g., using `openssl rand -base64 32`)
 NEXTAUTH_SECRET=$(openssl rand -base64 32)
 
+# Legacy Jira OAuth fallback (optional, deprecated):
+# Older single-app deployments configured Jira OAuth globally via these vars.
+# New installs should leave them unset and configure the Client ID/Secret
+# per-integration in the admin UI instead; they are only consulted when an
+# integration does not provide its own credentials.
+# JIRA_CLIENT_ID=
+# JIRA_CLIENT_SECRET=
+# JIRA_REDIRECT_URI=
+
 # Public API URL (optional)
 # NEXT_PUBLIC_API_URL="http://localhost:3000/api"
 

testplanit/app/[locale]/admin/integrations/AuthorizeIntegrationButton.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { Integration } from "@prisma/client";
+import { ShieldCheck } from "lucide-react";
+import { useTranslations } from "next-intl";
+
+interface AuthorizeIntegrationButtonProps {
+  integration: Integration;
+}
+
+/**
+ * Row action that starts the per-user OAuth (3LO) authorization for an
+ * integration that is configured but not yet connected. It uses the generic
+ * OAuth route, which only needs an integrationId (no project assignment); the
+ * callback stores the user's token and flips the integration to ACTIVE.
+ */
+export function AuthorizeIntegrationButton({
+  integration,
+}: AuthorizeIntegrationButtonProps) {
+  const t = useTranslations("admin.integrations");
+
+  const handleAuthorize = () => {
+    const params = new URLSearchParams({
+      integrationId: integration.id.toString(),
+    });
+    window.location.href = `/api/integrations/oauth/${integration.provider.toLowerCase()}/auth?${params.toString()}`;
+  };
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          onClick={handleAuthorize}
+          className="px-2 py-1 h-auto text-warning-foreground"
+        >
+          <ShieldCheck className="h-4 w-4" />
+          <span className="sr-only">{t("authorize")}</span>
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        <p>{t("authorizeHint")}</p>
+      </TooltipContent>
+    </Tooltip>
+  );
+}

testplanit/app/[locale]/admin/integrations/columns.tsx

@@ -9,6 +9,7 @@ import { Link, Plug } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { useMemo } from "react";
 import { siGithub, siGitlab, siJira, siRedmine } from "simple-icons";
+import { AuthorizeIntegrationButton } from "./AuthorizeIntegrationButton";
 import { DeleteIntegrationButton } from "./DeleteIntegrationButton";
 import { EditIntegrationButton } from "./EditIntegrationButton";
 import { SyncIntegrationButton } from "./SyncIntegrationButton";
@@ -127,6 +128,26 @@ export const useColumns = (
             ERROR: "destructive",
           };
 
+          // An OAuth 2.0 (3LO) integration that isn't yet connected is in a
+          // valid, expected mid-setup state — not a misconfiguration. Show
+          // "Awaiting authorization" instead of a bare "Inactive" so the
+          // admin understands the next step is to authorize, not that they
+          // did something wrong.
+          const awaitingAuthorization =
+            row.original.authType === "OAUTH2" &&
+            row.original.status === "INACTIVE";
+
+          if (awaitingAuthorization) {
+            return (
+              <Badge
+                variant="outline"
+                className="border-warning text-warning-foreground"
+              >
+                {t("status.awaitingAuthorization")}
+              </Badge>
+            );
+          }
+
           return (
             <Badge variant={statusColors[row.original.status] as any}>
               {t(`status.${row.original.status.toLowerCase()}` as any)}
@@ -228,6 +249,13 @@ export const useColumns = (
         meta: { isPinned: "right" },
         cell: ({ row }) => (
           <div className="bg-primary-foreground whitespace-nowrap flex justify-center gap-1">
+            {row.original.authType === "OAUTH2" &&
+              row.original.status === "INACTIVE" && (
+                <AuthorizeIntegrationButton
+                  key={`authorize-${row.original.id}`}
+                  integration={row.original}
+                />
+              )}
             <SyncIntegrationButton
               key={`sync-${row.original.id}`}
               integration={row.original}