The Complete Guide to Implementing OAuth with Claude Code

OAuth Authentication and Claude Code

OAuth 2.0 is the authentication standard for modern web applications. Claude Code can efficiently implement complex OAuth flows while understanding your project structure. For basic usage, see the Claude Code Getting Started Guide.

Implementing Authorization Code Flow

Here’s the most common OAuth flow implemented with Node.js + Express.

import express from "express";
import crypto from "crypto";

const app = express();

const OAUTH_CONFIG = {
  clientId: process.env.OAUTH_CLIENT_ID!,
  clientSecret: process.env.OAUTH_CLIENT_SECRET!,
  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
  tokenEndpoint: "https://provider.example.com/oauth/token",
  redirectUri: "http://localhost:3000/callback",
  scopes: ["openid", "profile", "email"],
};

// Authorization initiation endpoint
app.get("/auth/login", (req, res) => {
  const state = crypto.randomBytes(32).toString("hex");
  req.session.oauthState = state;

  const params = new URLSearchParams({
    response_type: "code",
    client_id: OAUTH_CONFIG.clientId,
    redirect_uri: OAUTH_CONFIG.redirectUri,
    scope: OAUTH_CONFIG.scopes.join(" "),
    state,
  });

  res.redirect(
    `${OAUTH_CONFIG.authorizationEndpoint}?${params.toString()}`
  );
});

PKCE Support

PKCE (Proof Key for Code Exchange) is required for SPAs and mobile apps.

function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto
    .createHash("sha256")
    .update(verifier)
    .digest("base64url");

  return { verifier, challenge };
}

app.get("/auth/login-pkce", (req, res) => {
  const { verifier, challenge } = generatePKCE();
  const state = crypto.randomBytes(32).toString("hex");

  req.session.codeVerifier = verifier;
  req.session.oauthState = state;

  const params = new URLSearchParams({
    response_type: "code",
    client_id: OAUTH_CONFIG.clientId,
    redirect_uri: OAUTH_CONFIG.redirectUri,
    scope: OAUTH_CONFIG.scopes.join(" "),
    state,
    code_challenge: challenge,
    code_challenge_method: "S256",
  });

  res.redirect(
    `${OAUTH_CONFIG.authorizationEndpoint}?${params.toString()}`
  );
});

Callback Handling and Token Retrieval

app.get("/callback", async (req, res) => {
  const { code, state } = req.query;

  // CSRF protection: validate state
  if (state !== req.session.oauthState) {
    return res.status(403).json({ error: "Invalid state parameter" });
  }

  try {
    const tokenResponse = await fetch(OAUTH_CONFIG.tokenEndpoint, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "authorization_code",
        code: code as string,
        redirect_uri: OAUTH_CONFIG.redirectUri,
        client_id: OAUTH_CONFIG.clientId,
        client_secret: OAUTH_CONFIG.clientSecret,
        // When using PKCE
        ...(req.session.codeVerifier && {
          code_verifier: req.session.codeVerifier,
        }),
      }),
    });

    const tokens = await tokenResponse.json();

    // Store tokens in session
    req.session.accessToken = tokens.access_token;
    req.session.refreshToken = tokens.refresh_token;
    req.session.tokenExpiry = Date.now() + tokens.expires_in * 1000;

    res.redirect("/dashboard");
  } catch (error) {
    console.error("Token exchange failed:", error);
    res.status(500).json({ error: "Authentication failed" });
  }
});

Token Refresh

Implement middleware to handle access token expiration.

async function refreshTokenMiddleware(
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
) {
  if (!req.session.accessToken) {
    return res.redirect("/auth/login");
  }

  // Refresh 5 minutes before expiration
  if (Date.now() > req.session.tokenExpiry - 5 * 60 * 1000) {
    try {
      const response = await fetch(OAUTH_CONFIG.tokenEndpoint, {
        method: "POST",
        headers: { "Content-Type": "application/x-www-form-urlencoded" },
        body: new URLSearchParams({
          grant_type: "refresh_token",
          refresh_token: req.session.refreshToken,
          client_id: OAUTH_CONFIG.clientId,
          client_secret: OAUTH_CONFIG.clientSecret,
        }),
      });

      const tokens = await response.json();
      req.session.accessToken = tokens.access_token;
      req.session.refreshToken = tokens.refresh_token ?? req.session.refreshToken;
      req.session.tokenExpiry = Date.now() + tokens.expires_in * 1000;
    } catch {
      return res.redirect("/auth/login");
    }
  }

  next();
}

app.use("/api/*", refreshTokenMiddleware);

Effective Prompts for Claude Code

Here are effective prompts for implementing OAuth with Claude Code. For more on prompt writing, see 5 Tips for Better Prompts.

Implement OAuth 2.0 Authorization Code Flow with PKCE.
- Provider: Google
- Framework: Express + TypeScript
- Session management: express-session + Redis
- Include automatic token refresh
- Implement CSRF and replay attack protections

Security Checklist

Make sure to verify the following points in your OAuth implementation.

• state parameter to prevent CSRF attacks
• PKCE to prevent authorization code interception attacks
• Store tokens in HttpOnly Cookies or secure server-side sessions
• Strictly validate redirect_uri with a whitelist
• Token expiration management and automatic refresh

For detailed specifications, refer to OAuth 2.0 RFC 6749. For the latest Claude Code features, check the official documentation.

Summary

With Claude Code, you can implement complex OAuth 2.0 flows consistently while understanding your project’s context. It enables you to build authentication infrastructure quickly while following security best practices.