SSO Integration Guide

CLIENT ID:      bg_client_a1b2c3d4e5f6g7h8i9j0k1l
CLIENT SECRET:  bg_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X POST https://buildgara.com/api/oauth/clients \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Analytics App",
    "redirectUris": ["https://myapp.com/callback", "https://dev.myapp.com/callback"],
    "description": "Charts and dashboards",
    "logoUrl": "https://myapp.com/logo.png"
  }'

{
  "success": true,
  "client": {
    "id": 12,
    "name": "My Analytics App",
    "clientId": "bg_client_a1b2c3d4e5f6g7h8i9j0k1l",
    "clientSecret": "bg_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "redirectUris": ["https://myapp.com/callback", "https://dev.myapp.com/callback"],
    "description": "Charts and dashboards",
    "isTrusted": false,
    "createdAt": "2026-09-03T10:00:00.000Z"
  }
}

https://buildgara.com/oauth/authorize?client_id=bg_client_a1b2c3d4e5f6g7h8i9j0k1l&redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback&response_type=code&scope=openid%20profile%20email%20role&state=9f8f0f2e3c4b5a6d&code_challenge=YJk8fVkn9yFhQm2cR8gD4sW6xZ0bL3tN7pQ1uV5yA9c&code_challenge_method=S256

https://myapp.com/callback?code=bg_code_1a2b3c…&state=9f8f0f2e3c4b5a6d

https://myapp.com/callback?error=access_denied&error_description=User%20denied%20access&state=9f8f0f2e3c4b5a6d

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "bg_code_1a2b3c…",
  "client_id": "bg_client_a1b2c3d4e5f6g7h8i9j0k1l",
  "client_secret": "bg_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "redirect_uri": "https://myapp.com/callback",
  "code_verifier": "the-exact-verifier-you-generated-at-login-start"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIs…",
  "scope": "openid profile email role"
}

GET /api/oauth/userinfo
Authorization: Bearer <access_token>

{
  "sub": "42",
  "name": "Anisha Sharma",
  "preferred_username": "anisha",
  "email": "anisha@example.com",
  "email_verified": true,
  "role": "founder",
  "avatar": "https://…/avatar.jpg",
  "country": "Nepal",
  "city": "Kathmandu",
  "is_founder": true,
  "is_investor": false,
  "is_provider": false
}

# 1. Open this URL in a browser (manual step) — copy the code from the redirect
https://buildgara.com/oauth/authorize?client_id=bg_client_xxx&redirect_uri=https://myapp.com/callback&response_type=code&scope=openid%20profile%20email%20role&state=abc123

# 2. Exchange the code (against the production API)
curl -X POST https://api.buildgara.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "bg_code_...",
    "client_id": "bg_client_xxx",
    "client_secret": "bg_sec_...",
    "redirect_uri": "https://myapp.com/callback"
  }'

# 3. Fetch the profile
curl https://api.buildgara.com/api/oauth/userinfo \
  -H "Authorization: Bearer <access_token_from_step_2>"

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json());

const CLIENT_ID = process.env.BG_CLIENT_ID;              // bg_client_…
const CLIENT_SECRET = process.env.BG_CLIENT_SECRET;      // bg_sec_… (server only!)
const REDIRECT_URI = process.env.BG_REDIRECT_URI;        // https://myapp.com/callback

const WEB_BASE = process.env.BG_WEB_BASE || "https://buildgara.com";
const API_BASE = process.env.BG_API_BASE || "https://api.buildgara.com";

const b64url = (buf) => Buffer.from(buf).toString("base64url");

// 1. "Login with BuildGara" button -> /login/buildgara
app.get("/login/buildgara", (_req, res) => {
  const state = b64url(crypto.randomBytes(16));                 // CSRF token
  const codeVerifier = b64url(crypto.randomBytes(48));          // PKCE verifier (43-128 chars)
  const codeChallenge = b64url(
    crypto.createHash("sha256").update(codeVerifier).digest()
  );

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    response_type: "code",
    scope: "openid profile email role",
    state,
    code_challenge: codeChallenge,
    code_challenge_method: "S256",
  });
  res.cookie("bg_oauth_state", state, { httpOnly: true, sameSite: "lax", secure: process.env.NODE_ENV === "production" });
  res.cookie("bg_oauth_verifier", codeVerifier, { httpOnly: true, sameSite: "lax", secure: process.env.NODE_ENV === "production" });
  res.redirect(`${WEB_BASE}/oauth/authorize?${params}`);
});

// 2. BuildGara redirects the browser here with ?code=...&state=...
app.get("/api/auth/buildgara/callback", async (req, res) => {
  const { code, state, error } = req.query;

  if (error) return res.status(400).send(`Login failed/cancelled: ${error}`);
  if (!code || state !== req.cookies.bg_oauth_state) {
    return res.status(400).send("Invalid or expired state — possible CSRF. Try logging in again.");
  }
  const codeVerifier = req.cookies.bg_oauth_verifier;

  // 3. Server-to-server token exchange
  const tokenRes = await fetch(`${API_BASE}/api/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
      code_verifier: codeVerifier,
    }),
  });
  const token = await tokenRes.json();
  if (!tokenRes.ok) return res.status(502).send(`Token exchange failed: ${token.error_description || token.error}`);

  // 4. Fetch the canonical profile
  const userRes = await fetch(`${API_BASE}/api/oauth/userinfo`, {
    headers: { Authorization: `Bearer ${token.access_token}` },
  });
  if (!userRes.ok) return res.status(502).send("Could not fetch profile");
  const profile = await userRes.json();

  // 5. Upsert a local user keyed on profile.sub, then start your session
  const localUser = await upsertUserBySub(profile.sub, profile);

  res.clearCookie("bg_oauth_state");
  res.clearCookie("bg_oauth_verifier");
  req.session.userId = localUser.id;      // your session mechanism
  res.redirect("/dashboard");
});

import hashlib, secrets, base64, httpx
from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse

app = FastAPI()

CLIENT_ID = "bg_client_..."
CLIENT_SECRET = "bg_sec_..."          # server only
REDIRECT_URI = "https://myapp.com/callback"
WEB_BASE = "https://buildgara.com"
API_BASE = "https://api.buildgara.com"

def b64url(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

@app.get("/login/buildgara")
def start(request: Request):
    state = b64url(secrets.token_bytes(16))
    verifier = b64url(secrets.token_bytes(48))
    challenge = b64url(hashlib.sha256(verifier.encode()).digest())

    # store state + verifier in your session (here: signed cookie)
    request.session["sso_state"] = state
    request.session["sso_verifier"] = verifier

    params = {
        "client_id": CLIENT_ID, "redirect_uri": REDIRECT_URI,
        "response_type": "code", "scope": "openid profile email role",
        "state": state, "code_challenge": challenge,
        "code_challenge_method": "S256",
    }
    qs = "&".join(f"{k}={v}" for k, v in params.items())
    return RedirectResponse(f"{WEB_BASE}/oauth/authorize?{qs}")

@app.get("/api/auth/buildgara/callback")
async def callback(request: Request, code: str, state: str, error: str | None = None):
    if error:
        return {"error": error}
    if state != request.session.pop("sso_state", None):
        return {"error": "state mismatch — CSRF suspected"}

    async with httpx.AsyncClient() as client:
        token = await client.post(f"{API_BASE}/api/oauth/token", json={
            "grant_type": "authorization_code", "code": code,
            "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET,
            "redirect_uri": REDIRECT_URI,
            "code_verifier": request.session.pop("sso_verifier"),
        })
        data = token.json()
        me = await client.get(f"{API_BASE}/api/oauth/userinfo",
                              headers={"Authorization": f"Bearer {data['access_token']}"})

    profile = me.json()
    user = upsert_user_by_sub(profile["sub"], profile)   # your DB logic
    return {"user": user.id, "profile": profile}

BUILDGARA_CLIENT_ID=bg_client_xxxxxxxxxxxxxxxxxxxxxxxx
BUILDGARA_CLIENT_SECRET=bg_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BUILDGARA_REDIRECT_URI=https://myapp.com/auth/buildgara-callback.php
BUILDGARA_AUTHORIZE_URL=https://buildgara.com/oauth/authorize
BUILDGARA_TOKEN_URL=https://api.buildgara.com/api/oauth/token
BUILDGARA_USERINFO_URL=https://api.buildgara.com/api/oauth/userinfo
BUILDGARA_SSO_SCOPE=openid profile email role

<?php
session_start();

$cfg = [
    'client_id'     => getenv('BUILDGARA_CLIENT_ID'),
    'redirect_uri'  => getenv('BUILDGARA_REDIRECT_URI'),
    'authorize_url' => getenv('BUILDGARA_AUTHORIZE_URL') ?: 'https://buildgara.com/oauth/authorize',
    'scope'         => getenv('BUILDGARA_SSO_SCOPE') ?: 'openid profile email role',
];

// state: single-use, session-bound CSRF token
$_SESSION['bg_oauth_state'] = bin2hex(random_bytes(16));

$params = http_build_query([
    'client_id'     => $cfg['client_id'],
    'redirect_uri'  => $cfg['redirect_uri'],
    'response_type' => 'code',
    'scope'         => $cfg['scope'],
    'state'         => $_SESSION['bg_oauth_state'],
    // Trusted first-party client only: silently approves users who are
    // already signed in to BuildGara. Omit for non-trusted apps.
    'prompt'        => 'none',
]);

header('Location: ' . $cfg['authorize_url'] . '?' . $params);
exit;

<?php
session_start();

$cfg = [
    'client_id'     => getenv('BUILDGARA_CLIENT_ID'),
    'client_secret' => getenv('BUILDGARA_CLIENT_SECRET'), // server-side only!
    'redirect_uri'  => getenv('BUILDGARA_REDIRECT_URI'),
    'token_url'     => getenv('BUILDGARA_TOKEN_URL')     ?: 'https://api.buildgara.com/api/oauth/token',
    'userinfo_url'  => getenv('BUILDGARA_USERINFO_URL')  ?: 'https://api.buildgara.com/api/oauth/userinfo',
];

$fail = function (string $msg): void {
    $_SESSION['sso_error'] = $msg;
    header('Location: /login.php');   // your login page
    exit;
};

if (!empty($_GET['error'])) {
    $fail('BuildGara sign-in was cancelled or failed. Please try again.');
}
$code  = $_GET['code']  ?? '';
$state = $_GET['state'] ?? '';
if ($code === '' || $state === '') {
    $fail('Invalid sign-in response. Please try again.');
}

// Verify state (single-use). For a *dashboard-initiated* flow (the user
// launched your app from a card on the BuildGara dashboard) there is no
// stored state — a confidential client may proceed, because the code can
// only be redeemed with your server-side client_secret.
if (!empty($_SESSION['bg_oauth_state'])) {
    $expected = $_SESSION['bg_oauth_state'];
    unset($_SESSION['bg_oauth_state']); // consume: single-use
    if (!hash_equals($expected, $state)) {
        $fail('Your sign-in session expired. Please try again.');
    }
}

// ── 1. Exchange the code (server-to-server) ────────────────────────────
function bg_post_json(string $url, array $body): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'Accept: application/json'],
        CURLOPT_POSTFIELDS     => json_encode($body),
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_CONNECTTIMEOUT => 10,
    ]);
    $resp   = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    return [$status, is_string($resp) ? (json_decode($resp, true) ?: []) : []];
}

[$tokenStatus, $tokens] = bg_post_json($cfg['token_url'], [
    'grant_type'    => 'authorization_code',
    'code'          => $code,
    'client_id'     => $cfg['client_id'],
    'client_secret' => $cfg['client_secret'],
    'redirect_uri'  => $cfg['redirect_uri'],
]);
if ($tokenStatus < 200 || $tokenStatus >= 300 || empty($tokens['access_token'])) {
    error_log('[BuildGara SSO] token exchange failed: HTTP ' . $tokenStatus
        . ' ' . json_encode($tokens));
    $fail('Sign-in failed. Please try again.');
}

// ── 2. Fetch the verified profile ──────────────────────────────────────
$ch = curl_init($cfg['userinfo_url']);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $tokens['access_token']],
    CURLOPT_TIMEOUT        => 30,
]);
$profile = json_decode((string) curl_exec($ch), true) ?: [];
curl_close($ch);
if (empty($profile['sub']) || empty($profile['email'])) {
    $fail('Could not verify your BuildGara account. Please try again.');
}

// ── 3. Match or create your local user (keyed on `sub`) ────────────────
$pdo = db(); // your PDO handle
$stmt = $pdo->prepare('SELECT id FROM users WHERE buildgara_sub = ? LIMIT 1');
$stmt->execute([(string) $profile['sub']]);
$userId = $stmt->fetchColumn();

if (!$userId) {
    // First login from this BuildGara account: create the local user.
    $stmt = $pdo->prepare(
        'INSERT INTO users (buildgara_sub, name, email, role) VALUES (?, ?, ?, ?)'
    );
    $stmt->execute([
        (string) $profile['sub'],
        (string) ($profile['name'] ?? ''),
        (string) $profile['email'],
        (string) ($profile['role'] ?? ''),
    ]);
    $userId = (int) $pdo->lastInsertId();
}

// ── 4. Start the session ───────────────────────────────────────────────
session_regenerate_id(true);          // prevent session fixation
$_SESSION['user_id'] = (int) $userId;
header('Location: /dashboard.php');
exit;

ALTER TABLE users ADD COLUMN buildgara_sub VARCHAR(64) NULL DEFAULT NULL;
ALTER TABLE users ADD UNIQUE KEY uq_users_buildgara_sub (buildgara_sub);

<a href="/auth/buildgara-login.php">Continue with BuildGara</a>

npm install buildgara-oauth-sdk

# Backend .env
BUILDGARA_CLIENT_ID=bg_client_xxxxxxxxxxxxxxxxxxxxxxxx
BUILDGARA_CLIENT_SECRET=bg_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BUILDGARA_REDIRECT_URI=https://myapp.com/callback

// src/lib/sso.ts
import { buildGara } from "buildgara-oauth-sdk";

export const ssoClient = buildGara({
  clientId: import.meta.env.VITE_BUILDGARA_CLIENT_ID,
  // Production: https://myapp.com/callback (registered in Developer Apps).
  redirectUri: import.meta.env.VITE_BUILDGARA_REDIRECT_URI,
});

// src/components/LoginButton.tsx
import { useState } from "react";
import { ssoClient } from "../lib/sso";

export function LoginButton() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSSOLogin = async () => {
    setLoading(true);
    setError(null);
    try {
      await ssoClient.startLoginPopup({ width: 450, height: 600 });
      const { profile } = await ssoClient.waitForPopupResult();
      window.location.reload(); // your app is now logged in server-side
    } catch (err: any) {
      setError(err.message || "SSO Login failed");
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleSSOLogin} disabled={loading}>
      {loading ? "Signing in…" : "Login with BuildGara"}
    </button>
  );
}

// server/auth.ts
import { buildGaraServer } from "buildgara-oauth-sdk";

const bgServer = buildGaraServer({
  clientId: process.env.BUILDGARA_CLIENT_ID!,
  clientSecret: process.env.BUILDGARA_CLIENT_SECRET!, // server-side only
  redirectUri: process.env.BUILDGARA_REDIRECT_URI!,   // https://myapp.com/callback
});

export async function ssoExchange(req: any, res: any) {
  try {
    const { code, code_verifier, redirect_uri } = req.body;

    // One call: token exchange + UserInfo. Throws typed SsoError subclasses.
    const { profile, accessToken } = await bgServer.exchangeCode(
      code,
      code_verifier || "",
      redirect_uri || undefined, // per-call override wins; otherwise configured value
    );

    // Key your accounts on profile.sub — never on email (checklist #6).
    const user = await upsertUserBySub(profile.sub, profile);
    req.session.userId = user.id;
    return res.json({ success: true, user: { id: user.id, name: profile.name } });
  } catch (err: any) {
    return res.status(400).json({ error: err.message || "SSO exchange failed" });
  }
}

// server.ts
app.get("/callback", bgServer.callbackHandler({
  onProfile: async ({ profile, accessToken }) => {
    const user = await upsertUserBySub(profile.sub, profile);
    return { ok: true, userId: user.id };
  },
}));