Identity Brokering — Auth Flow

┌──────────────┐        ┌──────────────┐        ┌────────────┐
│  AI Client   │        │   LockMCP    │        │  LockMCP   │
│ (Claude etc) │        │   Identity   │        │ Data Plane │
└──────────────┘        └──────────────┘        └────────────┘
       │                       │                      │
       │  1. Tool request, no credentials             │
       │ ────────────────────────────────────────────►│
       │                       │                      │
       │  2. 401 + where to authenticate              │
       │  ◄────────────────────────────────────────── │
       │                       │                      │
       │  3. Open browser, start OAuth                │
       │ ─────────────────────►│                      │
       │                       │                      │
       │  4. User signs in to LockMCP                 │
       │                       │                      │
       │  5. Token issued (roles, tenant, permissions)│
       │  ◄─────────────────── │                      │
       │                       │                      │
       │  6. Tool request, Bearer <token>             │
       │ ────────────────────────────────────────────►│
       │                       │                      │
       │           7. Verify signature (RS256)        │
       │           8. Resolve user from `sub`         │
       │           9. Load roles → permitted tools    │
       │                       │                      │
       │  10. Tool result (or 403 if not permitted)   │
       │  ◄────────────────────────────────────────── │

Authentication failed: user not found — please log in to the Dashboard first

I'm integrating my API with LockMCP, an MCP connector hub, using its "Identity Brokering"
identity model. LockMCP forwards my authenticated users' own token to my API as a standard
bearer credential on every request:

  Authorization: Bearer <token>

No other header identifies the caller or connection — everything needed is in the token's own
claims. Please inspect my existing codebase (its auth middleware, ORM/database layer, and
conventions) and implement the following, adapting the matching-language reference code below
to fit my actual stack rather than pasting it in verbatim:

=== 0. ENVIRONMENT SETUP ===

Add one environment variable my code will read the issuer from:

  LOCKMCP_ISSUER=<YOUR_ISSUER_URL>

Add it to my .env / .env.example, and tell me explicitly to also set it as a real environment
variable on whatever platform actually hosts this API (Render, Vercel, Fly, etc.) — adding it
to a local .env file alone does nothing for the deployed app.

=== 1. TOKEN VERIFICATION ===

Add real JWT verification to every endpoint any of my API's tools call (audit all of them, not
just the first one):
  - Read the bearer token from the standard Authorization header.
  - Verify the RS256 signature against the JWKS at `<YOUR_ISSUER_URL>/protocol/openid-connect/certs`.
  - Require the token's `iss` claim to equal `<YOUR_ISSUER_URL>` exactly (string match).
  - Require `exp` and `sub` to be present; reject an expired token.
  - Do NOT require or check the `aud` claim — the hub itself does not enforce it, so requiring
    it here would reject valid tokens.
  - On success, treat `sub` as the caller's LockMCP user id.

Reference implementation — pick whichever matches my stack, or adapt the pattern if none do:

--- Node.js (TypeScript) ---
```typescript
// middleware/verifyLockMcpToken.ts
import jwt, { type JwtPayload } from "jsonwebtoken";
import jwksClient from "jwks-rsa";
import type { Request, Response, NextFunction } from "express";

const EXPECTED_ISSUER = process.env.LOCKMCP_ISSUER ?? "";

const jwks = jwksClient({
  jwksUri: `${EXPECTED_ISSUER}/protocol/openid-connect/certs`,
  cache: true,
  cacheMaxAge: 10 * 60 * 1000,
});

function getKey(header: jwt.JwtHeader, callback: jwt.SigningKeyCallback) {
  jwks.getSigningKey(header.kid, (err, key) => {
    callback(err, key?.getPublicKey());
  });
}

export function verifyLockMcpToken(req: Request, res: Response, next: NextFunction) {
  const auth = req.headers.authorization ?? "";
  const [scheme, token] = auth.split(" ");
  if (scheme !== "Bearer" || !token) {
    return res.status(401).json({ success: false, message: "Missing bearer token" });
  }

  jwt.verify(
    token,
    getKey,
    { algorithms: ["RS256"], issuer: EXPECTED_ISSUER },
    (err, decoded) => {
      if (err || !decoded || typeof decoded === "string") {
        return res.status(401).json({ success: false, message: "Invalid or expired token" });
      }
      const claims = decoded as JwtPayload;
      if (!claims.sub || !claims.exp) {
        return res.status(401).json({ success: false, message: "Invalid or expired token" });
      }
      (req as any).lockMcpUserId = claims.sub;
      next();
    },
  );
}
```

--- Node.js (JavaScript) ---
```javascript
// middleware/verifyLockMcpToken.js
const jwt = require("jsonwebtoken");
const jwksClient = require("jwks-rsa");

const EXPECTED_ISSUER = process.env.LOCKMCP_ISSUER ?? "";

const jwks = jwksClient({
  jwksUri: `${EXPECTED_ISSUER}/protocol/openid-connect/certs`,
  cache: true,
  cacheMaxAge: 10 * 60 * 1000,
});

function getKey(header, callback) {
  jwks.getSigningKey(header.kid, (err, key) => {
    callback(err, key && key.getPublicKey());
  });
}

function verifyLockMcpToken(req, res, next) {
  const auth = req.headers.authorization ?? "";
  const [scheme, token] = auth.split(" ");
  if (scheme !== "Bearer" || !token) {
    return res.status(401).json({ success: false, message: "Missing bearer token" });
  }

  jwt.verify(
    token,
    getKey,
    { algorithms: ["RS256"], issuer: EXPECTED_ISSUER },
    (err, decoded) => {
      if (err || !decoded || !decoded.sub || !decoded.exp) {
        return res.status(401).json({ success: false, message: "Invalid or expired token" });
      }
      req.lockMcpUserId = decoded.sub;
      next();
    },
  );
}

module.exports = { verifyLockMcpToken };
```

--- Python ---
```python
# middleware/verify_lockmcp_token.py
import os
from functools import wraps

import jwt
from flask import request, jsonify
from jwt import PyJWKClient

EXPECTED_ISSUER = os.environ.get("LOCKMCP_ISSUER", "")
_jwks_client = PyJWKClient(f"{EXPECTED_ISSUER}/protocol/openid-connect/certs")


def verify_lockmcp_token(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        auth = request.headers.get("Authorization", "")
        scheme, _, token = auth.partition(" ")
        if scheme != "Bearer" or not token:
            return jsonify(success=False, message="Missing bearer token"), 401
        try:
            signing_key = _jwks_client.get_signing_key_from_jwt(token)
            claims = jwt.decode(
                token,
                signing_key.key,
                algorithms=["RS256"],
                issuer=EXPECTED_ISSUER,
                options={"require": ["exp", "iss", "sub"], "verify_aud": False},
            )
        except jwt.PyJWTError:
            return jsonify(success=False, message="Invalid or expired token"), 401

        request.lockmcp_user_id = claims["sub"]
        return fn(*args, **kwargs)

    return wrapper
```

--- Java ---
```java
// LockMcpTokenVerifier.java
import com.auth0.jwk.Jwk;
import com.auth0.jwk.JwkProvider;
import com.auth0.jwk.JwkProviderBuilder;
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.interfaces.DecodedJWT;

import java.security.interfaces.RSAPublicKey;
import java.util.concurrent.TimeUnit;

public class LockMcpTokenVerifier {
    private final String expectedIssuer;
    private final JwkProvider jwkProvider;

    public LockMcpTokenVerifier(String expectedIssuer) {
        this.expectedIssuer = expectedIssuer;
        this.jwkProvider = new JwkProviderBuilder(expectedIssuer + "/protocol/openid-connect/certs")
            .cached(10, 10, TimeUnit.MINUTES)
            .build();
    }

    /** Returns the verified token's `sub` claim (the caller's LockMCP user id), or throws if invalid. */
    public String verify(String bearerToken) throws Exception {
        DecodedJWT unverified = JWT.decode(bearerToken);
        Jwk jwk = jwkProvider.get(unverified.getKeyId());
        Algorithm algorithm = Algorithm.RSA256((RSAPublicKey) jwk.getPublicKey(), null);

        DecodedJWT verified = JWT.require(algorithm)
            .withIssuer(expectedIssuer)
            .build()
            .verify(bearerToken);

        if (verified.getSubject() == null || verified.getExpiresAt() == null) {
            throw new IllegalArgumentException("Missing sub/exp claim");
        }
        return verified.getSubject();
    }
}
```

=== 2. AUTHORIZATION ===

Do NOT gate access on the token's role claim (`realm_access.roles` or a custom `roles` claim).
That claim is empty for real users today — a current platform limitation, not something my code
is doing wrong. Instead: if a request reaches my API at all, LockMCP has already authorized this
specific user to call this specific tool under its own access control, before my API was ever
called — treat a verified token as sufficient authorization for whatever this endpoint does.
This is guidance, not something to write code for — the fix is to NOT add a role check here.
Only add an independent role/permission check on my side if I explicitly need defense-in-depth
beyond what LockMCP already enforces, and if so, key it off the token's `sub` claim (the one
stable identifier always present), using a mapping I maintain myself.

=== 3. USER MAPPING ===

If any endpoint these tools call writes a foreign key referencing "the acting user" (e.g. a
column like agentId, createdBy, ownerId, userId on a row being created), find or create a local
user row for this LockMCP identity right after verification succeeds, and use that row's local
id for the foreign key — never the raw `sub`. Key the lookup on the token's `email` claim
against whatever column my existing user table already treats as unique (usually `email`) — do
not add a new column or migration unless my schema genuinely has no unique user-identifying
column already. If `email` is absent from the token, fall back to a stable placeholder derived
from `sub` (e.g. `${sub}@lockmcp.local`). Give any newly-created row a random/placeholder
password — it must never be a real, login-capable local account.

Reference implementation — pick whichever matches my stack, or adapt the pattern if none do:

--- Node.js (TypeScript) ---
```typescript
// Run this inside your token-verification middleware, after the JWT is verified,
// using whatever ORM/query layer your app already has (this example uses Prisma).
interface LockMcpClaims {
  sub: string;
  email?: string;
  preferred_username?: string;
  given_name?: string;
  family_name?: string;
}

async function resolveLocalUser(decoded: LockMcpClaims) {
  const lockMcpEmail = decoded.email || decoded.preferred_username || `${decoded.sub}@lockmcp.local`;

  const localUser = await prisma.user.upsert({
    where: { email: lockMcpEmail },
    update: {},
    create: {
      email: lockMcpEmail,
      password: crypto.randomUUID(), // placeholder — never used to log in locally
      firstName: decoded.given_name ?? 'LockMCP',
      lastName: decoded.family_name ?? 'User',
      role: 'AGENT', // or whatever your default role should be
    },
  });

  return { id: localUser.id, email: localUser.email, lockMcpUserId: decoded.sub };
}
```

--- Node.js (JavaScript) ---
```javascript
// Run this inside your token-verification middleware, after the JWT is verified,
// using whatever ORM/query layer your app already has (this example uses Prisma).
const lockMcpEmail = decoded.email || decoded.preferred_username || `${decoded.sub}@lockmcp.local`;

const localUser = await prisma.user.upsert({
  where: { email: lockMcpEmail },
  update: {},
  create: {
    email: lockMcpEmail,
    password: crypto.randomUUID(), // placeholder — never used to log in locally
    firstName: decoded.given_name || 'LockMCP',
    lastName: decoded.family_name || 'User',
    role: 'AGENT', // or whatever your default role should be
  },
});

req.user = { id: localUser.id, email: localUser.email, lockMcpUserId: decoded.sub };
```

--- Python ---
```python
# Run this right after JWT verification succeeds, using whatever ORM your app has
# (this example uses SQLAlchemy-style get-or-create; adapt to your own layer).
lock_mcp_email = claims.get("email") or claims.get("preferred_username") or f"{claims['sub']}@lockmcp.local"

local_user = get_user_by_email(lock_mcp_email)
if local_user is None:
    local_user = create_user(
        email=lock_mcp_email,
        password=secrets.token_urlsafe(32),  # placeholder — never used to log in locally
        first_name=claims.get("given_name", "LockMCP"),
        last_name=claims.get("family_name", "User"),
        role="AGENT",  # or whatever your default role should be
    )

request.state.user = {"id": local_user.id, "email": local_user.email, "lock_mcp_user_id": claims["sub"]}
```

--- Java ---
```java
// Run this right after JWT verification succeeds, using whatever persistence layer
// your app has (this example uses JPA/Hibernate).
public class LockMcpUserResolver {
    private final EntityManager entityManager;

    public LockMcpUserResolver(EntityManager entityManager) {
        this.entityManager = entityManager;
    }

    @Transactional
    public LocalUser resolve(DecodedJWT verified) {
        String email = verified.getClaim("email").asString();
        if (email == null) email = verified.getClaim("preferred_username").asString();
        if (email == null) email = verified.getSubject() + "@lockmcp.local";

        LocalUser existing = entityManager
            .createQuery("SELECT u FROM LocalUser u WHERE u.email = :email", LocalUser.class)
            .setParameter("email", email)
            .getResultStream()
            .findFirst()
            .orElse(null);
        if (existing != null) return existing;

        LocalUser created = new LocalUser();
        created.setEmail(email);
        created.setPassword(java.util.UUID.randomUUID().toString());
        created.setFirstName(java.util.Optional.ofNullable(verified.getClaim("given_name").asString()).orElse("LockMCP"));
        created.setLastName(java.util.Optional.ofNullable(verified.getClaim("family_name").asString()).orElse("User"));
        created.setRole("AGENT");
        entityManager.persist(created);
        return created;
    }
}
```

=== FINALLY ===

Look at how my project currently structures auth/middleware and database access, and implement
all of the above following those existing patterns rather than pasting the reference code in
verbatim. Remind me explicitly that none of this takes effect until actually deployed — a
local-only change has no effect on what LockMCP calls until it's pushed and deployed.

(For full context, this prompt is generated from the "Identity Brokering — Auth Flow" page
under Docs in the LockMCP dashboard.)

Authorization: Bearer <token>