` — the **exact** origin, never `*` when
credentials are used.
- `Access-Control-Allow-Credentials: true`
- `Access-Control-Allow-Headers: Content-Type`
- `Vary: Origin`
- Answer `OPTIONS` preflight with `204`.
### Session & cookie
A server-side session holds `codeVerifier`, `accessToken`, `instanceUrl`, and `refreshToken`
(the last stored at callback and used for the 401/403 auto-refresh above). The session
cookie must be **`HttpOnly`** and **`SameSite=Lax`**. On localhost, `:8700 → :8500` is
same-*site*, so the Lax cookie is still sent; CORS only governs whether the browser may
*read* the response. (Cross-*site* production needs `SameSite=None; Secure` over HTTPS.)
### Security invariants (non-negotiable)
- `CLIENT_SECRET` and the raw `access_token` **never** leave the server. The browser only
ever receives the FrontDoor URL.
- PKCE uses **`S256`**, never `plain`.
- The OAuth `state` is a **random per-session** value, stored server-side and **validated on
the callback** (single-use). PKCE + `state` are separate defenses — both are implemented.
- OAuth-error responses on `/getAccessToken` are served as **`text/plain`**, so a reflected
`error_description` can't execute as HTML.
- Do not log secrets or tokens.
> **If you deploy this beyond localhost, add two more.** These are deliberately left out of the
> localhost reference (they'd add framework-specific machinery without changing the demo), but
> they matter once the broker is internet-facing — apply them in **every** port you ship, not
> just one, so the ports stay behavior-identical:
> - **Rotate the session id after authentication** (e.g. Express `req.session.regenerate`,
> PHP `session_regenerate_id`, Spring `changeSessionId`) to close session-fixation. The random
> `state` above already blocks the login-CSRF path; rotation hardens the fixation variant.
> - **Serve over HTTPS with `SameSite=None; Secure` cookies**, and back the in-memory session
> store with a shared store (Redis, a DB) so sessions survive restarts and work across workers.
>
> One intentional cross-port difference to know about: on a **transport-level** failure reaching
> Salesforce (DNS/connect/timeout), the Java port returns **502** while the other six return
> **500**; and a non-GET request to a known path returns **405** on the Go/Java/.NET ports vs
> **404** on Node/PHP/Ruby. Both are outside the documented GET-only, happy-path contract and
> don't affect the SPA.
---
## Node.js (Express)
> Execution-verified reference implementation, distilled from the repo's production
> `authRouter.ts`. The six ports that follow mirror it exactly.
**Run it.** From `token-broker/`: install, copy `.env.example` to `.env` and fill in your
org + ECA values, load `.env` into the environment, then start. The broker listens on
**http://localhost:8500**.
```bash
cd token-broker
npm install
cp .env.example .env
set -a; source .env; set +a
npm start
```
> **Loading `.env` (applies to every port below).** The broker reads its config from the
> environment, so you must load `.env` **before** starting it — the start command alone does
> **not** read the file. `set -a; source .env; set +a` exports every line for the launched
> process. The `source` path is **relative to your current directory**, so it points at
> wherever `.env` actually lives: it's `.env` from `token-broker/`, `../.env` from a port
> subdirectory like `token-broker/java/`, `../../.env` if your broker sits a level deeper.
> After sourcing, confirm it worked with `echo "ORG_URL=$ORG_URL"` — a blank value means the
> path is wrong. If a secret contains shell-special characters, keep it quoted in `.env`.
> (Node-only shortcut: `node --env-file=.env server.js`, supported natively on Node 20.6+.)
>
> **zsh footgun — keep pasted commands comment-free.** Don't paste a command line with a
> trailing `# comment`. The default macOS interactive shell (zsh, without
> `interactive_comments` set) does **not** strip `#…` — it passes it on as a literal
> argument, which breaks the command (e.g. `go run . # …` fails with a bogus-path error).
> Every run-block below is comment-free for exactly this reason; explanatory text sits in
> prose above the block instead.
Then open **http://localhost:8500/login** once to authenticate. After login you're
redirected back, and your SPA can call `GET /getFrontdoorURL` to get
`{ frontdoorUrl, orgUrl }`.
**`token-broker/package.json`:**
```json
{
"name": "tableau-next-token-broker",
"version": "1.0.0",
"private": true,
"type": "module",
"description": "Server-side OAuth token broker that mints a Salesforce FrontDoor URL for the Analytics Embedding SDK",
"scripts": {
"start": "node server.js",
"dev": "node --watch server.js"
},
"engines": {
"node": ">=18"
},
"dependencies": {
"express": "^4.19.2",
"express-session": "^1.18.0"
}
}
```
**`token-broker/.env.example`** (copy to `.env`, never commit the real one):
```properties
# Copy to .env and fill in. Never commit the real .env.
# Port the broker listens on (defaults to 8500)
PORT=8500
# Your org's OAuth login host (My Domain login URL or login.salesforce.com)
LOGIN_URL=https://yourorg.my.salesforce.com
# Your org's Lightning My Domain host — this is the SDK `orgUrl`
ORG_URL=https://yourorg.lightning.force.com
# ECA Consumer Key
CLIENT_ID=your_consumer_key_here
# ECA Consumer Secret. The reference ECA in this repo requires it
# (isSecretRequiredForTokenExchange: true), so set it. Leave blank ONLY if your ECA was
# provisioned PKCE-only. An invalid_client error on token exchange means it's required.
CLIENT_SECRET=
# Must EXACTLY match a Callback URL on the ECA (this is the broker's own callback, port 8500)
REDIRECT_URI=http://localhost:8500/getAccessToken
# Your SPA's origin. Two jobs: (1) where the browser is sent after login, and (2) the exact
# origin the broker allows via CORS for /getFrontdoorURL. The samples all run on port 8700,
# so this must match wherever you serve the frontend.
APP_ORIGIN=http://localhost:8700
# Session cookie signing secret — set a strong random value in production
SESSION_SECRET=change-me-in-production
```
**`token-broker/server.js`:**
```js
/**
* Tableau Next embedding — server-side token broker.
*
* Runs the OAuth Authorization Code + PKCE flow and mints a FrontDoor URL that the
* frontend passes to the SDK as `authCredential`. Keep this on the server: it holds the
* client secret (if any) and the raw access token; the browser only ever sees the
* short-lived FrontDoor URL.
*
* Distilled from packages/playground/sdk_test/routers/authRouter.ts.
*
* Endpoints:
* GET /login → starts OAuth (redirects to Salesforce)
* GET /getAccessToken → OAuth callback; exchanges code → access token (stored in session)
* GET /getFrontdoorURL → exchanges access token → { frontdoorUrl } (call this from the SPA)
* GET /health → { ok: true }
*/
import express from 'express';
import session from 'express-session';
import crypto from 'node:crypto';
// ---- Config (from environment) -------------------------------------------------------
const {
PORT = 8500,
// Your org's login host, e.g. https://yourorg.my.salesforce.com or https://login.salesforce.com
LOGIN_URL,
// Your org's Lightning My Domain host, e.g. https://yourorg.lightning.force.com
ORG_URL,
// ECA Consumer Key
CLIENT_ID,
// ECA Consumer Secret. The reference ECA requires it (isSecretRequiredForTokenExchange: true);
// set it. Leave unset only for an ECA provisioned PKCE-only. invalid_client => it's required.
CLIENT_SECRET,
// Must exactly match a Callback URL registered on the ECA.
REDIRECT_URI = `http://localhost:${PORT}/getAccessToken`,
// Where to send the user back after a successful login (the SPA's origin, port 8700 —
// NOT the broker's PORT). Also the exact origin allowed for the credentialed CORS fetch.
APP_ORIGIN = 'http://localhost:8700',
SESSION_SECRET = 'change-me-in-production',
} = process.env;
for (const [k, v] of Object.entries({ LOGIN_URL, ORG_URL, CLIENT_ID })) {
if (!v) {
console.error(`Missing required env var: ${k}. See .env.example.`);
process.exit(1);
}
}
// ---- PKCE helpers --------------------------------------------------------------------
const base64url = (buf) =>
buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
function generatePkce() {
const verifier = base64url(crypto.randomBytes(64));
const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());
return { verifier, challenge };
}
// ---- App -----------------------------------------------------------------------------
const app = express();
// CORS: the SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this
// broker (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these
// headers or the browser drops the response. Allow-Origin must name the exact origin (not '*')
// when credentials are involved. On localhost, :8700 and :8500 are the same *site*, so the
// SameSite=Lax session cookie is still sent — CORS just permits reading the response.
// (Dependency-free; for many origins or production, use the `cors` package + HTTPS + SameSite=None.)
app.use((req, res, next) => {
res.header('Access-Control-Allow-Origin', APP_ORIGIN);
res.header('Access-Control-Allow-Credentials', 'true');
res.header('Access-Control-Allow-Headers', 'Content-Type');
res.header('Vary', 'Origin');
if (req.method === 'OPTIONS') return res.sendStatus(204);
next();
});
app.use(
session({
secret: SESSION_SECRET,
resave: false,
saveUninitialized: true,
cookie: { httpOnly: true, sameSite: 'lax' },
}),
);
// 1) Kick off OAuth with PKCE.
app.get('/login', (req, res) => {
const { verifier, challenge } = generatePkce();
req.session.codeVerifier = verifier;
// Random per-session `state` for CSRF / login-mix-up protection: it's echoed back on the
// callback and must match. PKCE defends against code interception; `state` is the separate
// login-CSRF defense — you want both. (A fixed constant here would leave the callback forgeable.)
const state = base64url(crypto.randomBytes(32));
req.session.oauthState = state;
const params = new URLSearchParams({
response_type: 'code',
client_id: CLIENT_ID,
redirect_uri: REDIRECT_URI,
scope: 'api refresh_token lightning web',
code_challenge: challenge,
code_challenge_method: 'S256',
state,
});
res.redirect(`${LOGIN_URL}/services/oauth2/authorize?${params}`);
});
// 2) OAuth callback → exchange the code for an access token.
app.get('/getAccessToken', async (req, res) => {
const { code, state, error, error_description } = req.query;
if (error) return res.type('text/plain').status(400).send(`OAuth error: ${error_description || error}`);
// Reject the callback unless `state` matches the value we stored at /login (CSRF defense).
const expectedState = req.session.oauthState;
if (!state || !expectedState || state !== expectedState) {
return res.type('text/plain').status(400).send('Invalid or missing OAuth state');
}
delete req.session.oauthState; // single-use
const codeVerifier = req.session.codeVerifier;
if (!code || !codeVerifier) return res.type('text/plain').status(400).send('Missing code or PKCE verifier');
const params = new URLSearchParams({
grant_type: 'authorization_code',
client_id: CLIENT_ID,
redirect_uri: REDIRECT_URI,
code: String(code),
code_verifier: String(codeVerifier),
});
// Sent when configured. The reference ECA requires it; a PKCE-only ECA omits it.
if (CLIENT_SECRET) params.append('client_secret', CLIENT_SECRET);
try {
const resp = await fetch(`${LOGIN_URL}/services/oauth2/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString(),
});
const data = await resp.json();
if (!resp.ok || data.error) {
return res
.type('text/plain')
.status(resp.status || 500)
.send(`Token exchange failed: ${data.error_description || data.error || 'unknown'}`);
}
req.session.accessToken = data.access_token;
req.session.instanceUrl = data.instance_url;
// Stored so we can silently re-mint after the ~2h access-token TTL elapses. Present only
// if the ECA granted the `refresh_token` scope (it's requested in /login); if the org
// withholds it, refreshAccessToken() is a no-op and the user re-runs /login by hand.
req.session.refreshToken = data.refresh_token;
res.redirect(APP_ORIGIN); // back to the SPA; it will call /getFrontdoorURL
} catch (e) {
res.type('text/plain').status(500).send(`Token exchange error: ${e.message}`);
}
});
// Exchange the stored refresh token for a fresh access token. Returns true on success and
// updates the session in place; false if there's no refresh token or the refresh fails
// (e.g. the org withheld the scope, or the refresh token itself was revoked/expired).
async function refreshAccessToken(req) {
const { refreshToken } = req.session;
if (!refreshToken) return false;
const params = new URLSearchParams({
grant_type: 'refresh_token',
client_id: CLIENT_ID,
refresh_token: refreshToken,
});
if (CLIENT_SECRET) params.append('client_secret', CLIENT_SECRET);
try {
const resp = await fetch(`${LOGIN_URL}/services/oauth2/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString(),
});
const data = await resp.json();
if (!resp.ok || data.error || !data.access_token) return false;
req.session.accessToken = data.access_token;
// A refresh_token grant returns instance_url; keep it in sync. It does NOT return a new
// refresh_token, so leave the stored one as-is.
if (data.instance_url) req.session.instanceUrl = data.instance_url;
return true;
} catch {
return false;
}
}
// POST the stored access token to the singleaccess endpoint to mint a FrontDoor URL.
async function mintFrontdoor(instanceUrl, accessToken) {
return fetch(`${instanceUrl}/services/oauth2/singleaccess`, {
method: 'POST',
headers: {
accept: 'application/json',
authorization: `Bearer ${accessToken}`,
'content-type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams(),
});
}
// 3) Exchange the stored access token for a FrontDoor URL. The SPA fetches this.
app.get('/getFrontdoorURL', async (req, res) => {
if (!req.session.accessToken || !req.session.instanceUrl) {
return res.status(401).json({ error: 'Not authenticated. Visit /login first.' });
}
try {
let resp = await mintFrontdoor(req.session.instanceUrl, req.session.accessToken);
// The access token expires (~2h on sandbox). On 401/403, refresh once and retry so the
// SPA keeps working without bouncing the user back through /login.
if ((resp.status === 401 || resp.status === 403) && (await refreshAccessToken(req))) {
resp = await mintFrontdoor(req.session.instanceUrl, req.session.accessToken);
}
if (!resp.ok) {
// Still failing after the refresh attempt — the session is stale; the SPA should /login.
// Surface Salesforce's own reason: the body carries {"error","error_description"} that
// distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
// it's safe to forward; truncate defensively.
const body = (await resp.text().catch(() => '')).trim();
const detail = body ? `: ${body.length > 500 ? `${body.slice(0, 500)}…` : body}` : '';
return res.status(resp.status).json({
error: `Salesforce responded ${resp.status}${detail}. Re-authenticate at /login.`,
});
}
const data = await resp.json();
res.json({ frontdoorUrl: data.frontdoor_uri, orgUrl: ORG_URL });
} catch (e) {
res.status(500).json({ error: e.message || 'Failed to generate FrontDoor URL' });
}
});
app.get('/health', (_req, res) => res.json({ ok: true }));
app.listen(PORT, () => {
console.log(`Token broker on http://localhost:${PORT}`);
console.log(` Log in: http://localhost:${PORT}/login`);
});
```
**Production notes:** cross-*site* cookies need `SameSite=None; Secure` over HTTPS; use
durable session storage and a real `SESSION_SECRET`; for many origins swap the hand-rolled
CORS header for the `cors` package.
---
## JWT Bearer broker (Node.js)
> **Alternative flow — verified end-to-end on a real org.** This is the server-to-server
> [JWT Bearer flow](#auth-alternative-the-jwt-bearer-flow), not the interactive Auth Code + PKCE
> flow the seven brokers above use. It has been run against a live org (token minted via JWT →
> FrontDoor URL → dashboard rendered); the one caveat is that it's **not part of the official
> SDK guide**, which documents Auth Code + PKCE. This Node.js broker is the verified reference;
> faithful ports follow it in [Java](#java-spring-boot--jwt-bearer),
> [Python](#python-fastapi--jwt-bearer), [Go](#go-nethttp--jwt-bearer),
> [C#](#c-aspnet-core--jwt-bearer), [Ruby](#ruby-sinatra--jwt-bearer), and
> [PHP](#php-built-in-server--jwt-bearer) — only the JWT-signing library changes per language; the
> two Salesforce calls are identical. For any other language, port the same way.
Before using this, complete the one-time
[certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time): generate `private.key` + `public.crt`,
upload `public.crt` to the ECA, and enable the JWT Bearer flow on it. This broker signs with
the private key — **there is no `CLIENT_SECRET`** in this flow.
**`token-broker-jwt/package.json`:**
```json
{
"name": "tableau-next-token-broker-jwt",
"version": "1.0.0",
"private": true,
"type": "module",
"description": "Server-side OAuth JWT Bearer broker that mints a Salesforce FrontDoor URL for the Analytics Embedding SDK",
"scripts": {
"start": "node server.js",
"dev": "node --watch server.js"
},
"engines": {
"node": ">=18"
},
"dependencies": {
"express": "^4.19.2",
"express-session": "^1.18.0",
"jsonwebtoken": "^9.0.2"
}
}
```
**`token-broker-jwt/.env.example`** (copy to `.env`, never commit the real one; and never
commit `private.key`):
```properties
# Copy to .env and fill in. Never commit the real .env or the private key.
# Port the broker listens on (defaults to 8500)
PORT=8500
# The org's OAuth login host — this is BOTH where we POST the token request and the JWT `aud`.
# Prod: https://login.salesforce.com | Sandbox: https://test.salesforce.com | or your My Domain login host.
LOGIN_URL=https://login.salesforce.com
# Your org's Lightning My Domain host — this is the SDK `orgUrl`
ORG_URL=https://yourorg.lightning.force.com
# ECA Consumer Key — becomes the JWT `iss` claim
CLIENT_ID=your_consumer_key_here
# The Salesforce username to impersonate — becomes the JWT `sub` claim. This user must be
# pre-authorized for the ECA and hold a Tableau+/Tableau Next license.
SF_USERNAME=user@yourorg.com
# Path to the RSA private key whose public cert is uploaded to the ECA. Keep it server-side.
# (Alternatively set PRIVATE_KEY to the PEM contents directly, with \n for newlines.)
PRIVATE_KEY_PATH=./private.key
# Your SPA's origin — where the browser is sent and the CORS-allowed origin for /getFrontdoorURL.
APP_ORIGIN=http://localhost:8700
# Session cookie signing secret — set a strong random value in production
SESSION_SECRET=change-me-in-production
```
**`token-broker-jwt/server.js`:**
```js
/**
* Tableau Next embedding — server-side token broker (JWT Bearer flow).
*
* ALTERNATIVE to the Authorization Code + PKCE broker (server.js). Instead of an interactive
* login, the server signs a JWT with its private key and exchanges it for an access token,
* impersonating SF_USERNAME. It then mints the SAME FrontDoor URL the SDK consumes.
*
* Keep this on the server: it holds the private key and the raw access token; the browser
* only ever sees the short-lived FrontDoor URL. There is NO client secret in this flow —
* the RS256 signature authenticates the client.
*
* Endpoints:
* GET /login → runs the JWT Bearer exchange, stores the session, redirects to the SPA
* GET /getFrontdoorURL → mints { frontdoorUrl, orgUrl } from the stored token (call this from the SPA)
* GET /health → { ok: true }
*/
import express from 'express';
import session from 'express-session';
import fs from 'node:fs';
import jwt from 'jsonwebtoken';
const {
PORT = 8500,
LOGIN_URL,
ORG_URL,
CLIENT_ID,
SF_USERNAME,
PRIVATE_KEY,
PRIVATE_KEY_PATH = './private.key',
APP_ORIGIN = 'http://localhost:8700',
SESSION_SECRET = 'change-me-in-production',
} = process.env;
for (const [k, v] of Object.entries({ LOGIN_URL, ORG_URL, CLIENT_ID, SF_USERNAME })) {
if (!v) {
console.error(`Missing required env var: ${k}. See .env.example.`);
process.exit(1);
}
}
// Read the signing key once, from PRIVATE_KEY (PEM inline, \n-escaped) or PRIVATE_KEY_PATH.
// Fail fast with a clear message if it's missing — otherwise fs throws a raw ENOENT stack.
// Note: PRIVATE_KEY_PATH is resolved relative to the CURRENT WORKING DIRECTORY, not this file —
// run the broker from token-broker-jwt/, or set an absolute path. The key must be UNENCRYPTED
// (the openssl -nodes command in the cert setup produces one); an encrypted key needs a passphrase.
let privateKey;
try {
privateKey = PRIVATE_KEY
? PRIVATE_KEY.replace(/\\n/g, '\n')
: fs.readFileSync(PRIVATE_KEY_PATH, 'utf8');
} catch {
console.error(
`Cannot read private key at ${PRIVATE_KEY_PATH}. Copy private.key into this directory ` +
`(or set PRIVATE_KEY_PATH to an absolute path). See the certificate & ECA setup section.`,
);
process.exit(1);
}
const app = express();
app.use((req, res, next) => {
res.header('Access-Control-Allow-Origin', APP_ORIGIN);
res.header('Access-Control-Allow-Credentials', 'true');
res.header('Access-Control-Allow-Headers', 'Content-Type');
res.header('Vary', 'Origin');
if (req.method === 'OPTIONS') return res.sendStatus(204);
next();
});
app.use(
session({
secret: SESSION_SECRET,
resave: false,
saveUninitialized: true,
cookie: { httpOnly: true, sameSite: 'lax' },
}),
);
// Sign the JWT assertion. Claims: iss=client_id, sub=user to impersonate, aud=login host,
// exp≤5min. jsonwebtoken sets iat and the RS256 header; we set expiresIn to bound exp.
function createAssertion() {
return jwt.sign({ iss: CLIENT_ID, sub: SF_USERNAME, aud: LOGIN_URL }, privateKey, {
algorithm: 'RS256',
expiresIn: '3m',
});
}
// Exchange the signed JWT for an access token. No client_secret — the signature is the auth.
// On a Salesforce-side rejection (e.g. invalid_grant) we throw an error carrying the upstream
// HTTP status so callers can forward it — a config error is NOT a 5xx (see /login).
async function getAccessTokenViaJwt() {
const params = new URLSearchParams({
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion: createAssertion(),
});
const resp = await fetch(`${LOGIN_URL}/services/oauth2/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString(),
});
const data = await resp.json().catch(() => ({}));
if (!resp.ok || !data.access_token) {
// Salesforce returns {error, error_description}; forward it (no secret/token in the body).
const reason = data.error_description || data.error || `HTTP ${resp.status}`;
const err = new Error(`JWT token exchange failed: ${reason}`);
err.upstreamStatus = resp.status; // e.g. 400 for invalid_grant — an expected config error
throw err;
}
return { accessToken: data.access_token, instanceUrl: data.instance_url };
}
// POST the access token to singleaccess to mint a FrontDoor URL (identical to the PKCE broker).
async function mintFrontdoor(instanceUrl, accessToken) {
return fetch(`${instanceUrl}/services/oauth2/singleaccess`, {
method: 'POST',
headers: {
accept: 'application/json',
authorization: `Bearer ${accessToken}`,
'content-type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams(),
});
}
// 1) Run the JWT Bearer exchange and stash the token server-side, then bounce to the SPA.
// There's no interactive redirect to Salesforce — the exchange happens entirely server-side.
app.get('/login', async (req, res) => {
try {
const { accessToken, instanceUrl } = await getAccessTokenViaJwt();
req.session.accessToken = accessToken;
req.session.instanceUrl = instanceUrl;
res.redirect(APP_ORIGIN);
} catch (e) {
// A Salesforce rejection (invalid_grant etc.) is an expected CONFIG error — forward its
// status (a 4xx). Reserve 502 for genuine transport faults (no upstreamStatus = fetch failed).
const status = e.upstreamStatus || 502;
res.type('text/plain').status(status).send(e.message || 'JWT authentication failed');
}
});
// 2) Mint a FrontDoor URL from the stored token. The SPA fetches this.
// On 401/403 (token expired), just re-run the exchange — a JWT Bearer client can silently
// re-mint with no user interaction, so there's no refresh-token dance here.
app.get('/getFrontdoorURL', async (req, res) => {
try {
if (!req.session.accessToken || !req.session.instanceUrl) {
const t = await getAccessTokenViaJwt();
req.session.accessToken = t.accessToken;
req.session.instanceUrl = t.instanceUrl;
}
let resp = await mintFrontdoor(req.session.instanceUrl, req.session.accessToken);
if (resp.status === 401 || resp.status === 403) {
const t = await getAccessTokenViaJwt();
req.session.accessToken = t.accessToken;
req.session.instanceUrl = t.instanceUrl;
resp = await mintFrontdoor(t.instanceUrl, t.accessToken);
}
if (!resp.ok) {
const body = (await resp.text().catch(() => '')).trim();
const detail = body ? `: ${body.length > 500 ? `${body.slice(0, 500)}…` : body}` : '';
return res.status(resp.status).json({ error: `Salesforce responded ${resp.status}${detail}.` });
}
const data = await resp.json();
res.json({ frontdoorUrl: data.frontdoor_uri, orgUrl: ORG_URL });
} catch (e) {
// Same as /login: a Salesforce config rejection carries upstreamStatus (a 4xx); forward it.
// A genuine transport fault (no upstreamStatus = the token/instance host was unreachable) is
// a 502 — an upstream we depend on failed, not a bug in this broker.
const status = e.upstreamStatus || 502;
res.status(status).json({ error: e.message || 'Failed to generate FrontDoor URL' });
}
});
app.get('/health', (_req, res) => res.json({ ok: true }));
app.listen(PORT, () => {
console.log(`JWT Bearer token broker on http://localhost:${PORT}`);
console.log(` Authenticate: http://localhost:${PORT}/login`);
});
```
**Run it.** From `token-broker-jwt/`, with `.env` filled in. First get the private key into
place — `PRIVATE_KEY_PATH` is resolved **relative to the directory you run from**, not to
`server.js`, so the key must sit in `token-broker-jwt/` (or use an absolute path):
```bash
cp /path/to/private.key token-broker-jwt/private.key # only public.crt was uploaded to the ECA; keep this local
cd token-broker-jwt
ls -la private.key # confirm it's actually here before you start
npm install
set -a; source .env; set +a # re-run this after ANY edit to .env — a running
node server.js # process keeps the OLD values until you re-source + restart
```
Then open **http://localhost:8500/login** once — it runs the exchange server-side (no
Salesforce login screen) and redirects to your SPA, which calls `GET /getFrontdoorURL`.
> **Troubleshooting the exchange:** if `/login` returns a `400` with `invalid_grant`, that's an
> expected config error (the broker forwards Salesforce's status, not a 502) — the usual causes
> are the `sub` user not being pre-authorized on the ECA, an `aud` that doesn't match `LOGIN_URL`,
> a clock skew pushing `exp`, or the uploaded public cert not matching `private.key`. A `502`
> means the token host was unreachable (wrong `LOGIN_URL`, network). A successful
> `/getFrontdoorURL` returning a `frontdoorUrl` that renders in the SDK is the confirmation.
---
## Java (Spring Boot) — JWT Bearer
> **Alternative flow — the [JWT Bearer broker](#jwt-bearer-broker-nodejs) above was verified end-to-end on a real org; this is its faithful Java port** (static-reviewed here — no offline Maven build toolchain — not separately run on an org), **not part of the official SDK guide**. Server-to-server, **no interactive login screen**. Same Spring Boot shape as the Auth Code + PKCE broker above — an env-bound `@ConfigurationProperties`, a `@RestController` with the endpoints, a `OncePerRequestFilter` for CORS, and `java.net.http.HttpClient` for the POSTs — but instead of redirecting a user to log in, the server signs a JWT with its private key and exchanges it for an access token, impersonating `SF_USERNAME`. Session state lives in the servlet `HttpSession` (server-side; the cookie is only the opaque `JSESSIONID`). There is **no `CLIENT_SECRET`** and **no `REDIRECT_URI`** in this flow — the RS256 signature is the client authentication. The private key and the raw access token stay server-side; the browser only ever sees the short-lived FrontDoor URL.
Before using this, complete the one-time [certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time): generate `private.key` + `public.crt`, upload `public.crt` to the ECA, and enable the JWT Bearer flow on it. This broker signs with the private key.
**Run it.** From `token-broker-jwt/java/`. Get the signing key into place **first** — `PRIVATE_KEY_PATH` (default `./private.key`) is resolved **relative to the directory you run from**, not to the source tree, so the key must sit in `token-broker-jwt/java/` (or use an absolute path). Then load the shared `.env` (see the Node section for how `.env` loading and the `source` path work), confirm it loaded, and start. The broker listens on **http://localhost:8500**.
```bash
cp /path/to/private.key token-broker-jwt/java/private.key # only public.crt went to the ECA; keep this local
cd token-broker-jwt/java
ls -la private.key # confirm it's actually here before you start
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
mvn spring-boot:run
```
Then open **http://localhost:8500/login** once. Unlike the PKCE broker there is **no Salesforce login screen** — the exchange runs entirely server-side and `/login` bounces straight to your SPA, which calls `GET /getFrontdoorURL`.
Requires **JDK 21 (LTS)** and **Maven 3.9+**. Env vars are the same set as the Node JWT `.env.example` above (`PORT`, `LOGIN_URL`, `ORG_URL`, `CLIENT_ID`, `SF_USERNAME`, `PRIVATE_KEY_PATH` / optional inline `PRIVATE_KEY`, `APP_ORIGIN`, `SESSION_SECRET`) — no `CLIENT_SECRET`, no `REDIRECT_URI`. Pin JDK **21**, not "21+": the pinned Spring Boot 3.3.4 does **not** support the newest JDKs (e.g. 26) — running Maven under one fails to build with obscure compiler/bytecode errors. Install Zulu 21 (or any LTS 21 build) and point Maven at it. On a corporate/proxied Maven setup (Salesforce-internal especially) the same **two-layer TLS wall** described in the [PKCE Java section](#java-spring-boot) applies — import the Salesforce Internal Root CA into the JDK's `cacerts` and force `JAVA_HOME` onto that JDK; on a clean, non-proxied setup none of it applies.
> **Troubleshooting the exchange:** if `/login` returns a `400` with `invalid_grant`, that's an expected config error — the broker forwards Salesforce's status, not a 502. Usual causes: the `sub` user (`SF_USERNAME`) not pre-authorized on the ECA, an `aud` that doesn't match `LOGIN_URL`, a clock skew pushing `exp`, or the uploaded `public.crt` not matching `private.key`. A `502` means the token host was unreachable (wrong `LOGIN_URL`, network). If the app fails to *start* with "Cannot read private key at …", the key isn't in the working directory (see the `cp`/`ls` step above). A successful `/getFrontdoorURL` returning a `frontdoorUrl` that renders in the SDK is the confirmation.
**`token-broker-jwt/java/pom.xml`:**
```xml
4.0.0
org.springframework.boot
spring-boot-starter-parent
3.3.4
com.example
token-broker-jwt
1.0.0
jar
token-broker-jwt
Salesforce OAuth JWT Bearer token broker for the Analytics Embedding SDK
21
21
21
UTF-8
org.springframework.boot
spring-boot-starter-web
com.auth0
java-jwt
4.4.0
org.springframework.boot
spring-boot-starter-test
test
token-broker-jwt
org.springframework.boot
spring-boot-maven-plugin
```
**`token-broker-jwt/java/src/main/resources/application.properties`:**
```properties
# Port the broker listens on. Same env var / default as the Node reference (PORT=8500).
server.port=${PORT:8500}
# Keep Spring's banner/log noise down; the broker never logs secrets, keys, or tokens.
logging.level.root=INFO
logging.level.com.example.broker=INFO
# Session cookie: HttpOnly + SameSite=Lax, matching the Node reference.
# (:8700 -> :8500 on localhost is same-site, so the Lax cookie is still sent cross-port.)
server.servlet.session.cookie.http-only=true
server.servlet.session.cookie.same-site=lax
```
**`token-broker-jwt/java/src/main/java/com/example/broker/BrokerApplication.java`:**
```java
package com.example.broker;
import com.example.broker.config.BrokerProperties;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* Bootstraps the Salesforce OAuth token broker (JWT Bearer flow).
*
* Instead of an interactive login, the server signs a JWT with its private key and exchanges
* it for an access token — impersonating {@code SF_USERNAME} — then mints the same FrontDoor URL
* the Analytics Embedding SDK uses as {@code authCredential}. There is no client secret in this
* flow; the RS256 signature is the authentication. The private key and the raw access token never
* leave this process; the browser only ever receives the short-lived FrontDoor URL.
*
*
See {@link com.example.broker.api.TokenBrokerController} for the endpoints this exposes, and
* {@link BrokerProperties} for how configuration is read (and validated) from the environment.
*/
@SpringBootApplication
public class BrokerApplication {
public static void main(String[] args) {
SpringApplication.run(BrokerApplication.class, args);
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/config/BrokerProperties.java`:**
```java
package com.example.broker.config;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.stereotype.Component;
/**
* Broker configuration, read straight from the environment (not Spring {@code @Value}/
* {@code application.properties}) so the env var names and defaults line up exactly with the Node
* JWT Bearer reference implementation.
*
*
{@code LOGIN_URL}, {@code ORG_URL}, {@code CLIENT_ID} and {@code SF_USERNAME} are required; a
* missing one fails application startup immediately (mirrors the Node reference's {@code
* process.exit(1)}). There is deliberately no {@code CLIENT_SECRET} and no {@code REDIRECT_URI} in
* this flow. The signing key comes from {@code PRIVATE_KEY} (inline PEM) or {@code
* PRIVATE_KEY_PATH} (default {@code ./private.key}); see {@link
* com.example.broker.oauth.PrivateKeyLoader}.
*/
@Component
public class BrokerProperties {
private final String port;
private final String loginUrl;
private final String orgUrl;
private final String clientId;
private final String username;
private final String privateKeyInline;
private final String privateKeyPath;
private final String appOrigin;
private final String sessionSecret;
public BrokerProperties() {
this.port = env("PORT", "8500");
this.loginUrl = requireEnv("LOGIN_URL");
this.orgUrl = requireEnv("ORG_URL");
this.clientId = requireEnv("CLIENT_ID");
this.username = requireEnv("SF_USERNAME");
this.privateKeyInline = env("PRIVATE_KEY", null);
this.privateKeyPath = env("PRIVATE_KEY_PATH", "./private.key");
this.appOrigin = env("APP_ORIGIN", "http://localhost:8700");
this.sessionSecret = env("SESSION_SECRET", "change-me-in-production");
}
private static String env(String name, String defaultValue) {
String value = System.getenv(name);
return (value == null || value.isBlank()) ? defaultValue : value;
}
/** Fails fast (mirrors the Node reference's {@code process.exit(1)} on a missing var). */
private static String requireEnv(String name) {
String value = System.getenv(name);
if (value == null || value.isBlank()) {
throw new IllegalStateException("Missing required env var: " + name + ". See .env.example.");
}
return value;
}
public String getPort() {
return port;
}
public String getLoginUrl() {
return loginUrl;
}
public String getOrgUrl() {
return orgUrl;
}
/** The JWT {@code iss} claim (the ECA Consumer Key). */
public String getClientId() {
return clientId;
}
/** The JWT {@code sub} claim — the Salesforce user to impersonate. */
public String getUsername() {
return username;
}
/** Inline PEM ({@code \n}-escaped), or {@code null} to read {@link #getPrivateKeyPath()}. */
public String getPrivateKeyInline() {
return privateKeyInline;
}
public String getPrivateKeyPath() {
return privateKeyPath;
}
public String getAppOrigin() {
return appOrigin;
}
/**
* Read for parity with the Node reference's env var contract. Unlike Express's signed-cookie
* session store, the embedded Tomcat session used here (cookie settings in {@code
* application.properties}) identifies sessions by an opaque, server-generated ID rather than a
* value derived from this secret, so it's not wired into the session mechanism itself. Swap in
* a signed/distributed session store (e.g. Spring Session) for production and use this value
* there.
*/
public String getSessionSecret() {
return sessionSecret;
}
/** Non-secret snapshot, safe to log at startup (never the key or username's credentials). */
public Map describeNonSecret() {
Map summary = new LinkedHashMap<>();
summary.put("port", port);
summary.put("loginUrl", loginUrl);
summary.put("orgUrl", orgUrl);
summary.put("username", username);
summary.put("privateKeyPath", privateKeyInline != null ? "(inline PRIVATE_KEY)" : privateKeyPath);
summary.put("appOrigin", appOrigin);
return summary;
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/config/CorsFilter.java`:**
```java
package com.example.broker.config;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
/**
* CORS for the SPA on {@code APP_ORIGIN}: a different origin than this broker, so its
* credentialed {@code fetch('/getFrontdoorURL')} needs these headers or the browser drops the
* response. {@code Access-Control-Allow-Origin} must name the exact origin (never {@code *})
* because credentials are involved; on localhost, {@code :8700 -> :8500} is the same *site*, so
* the {@code SameSite=Lax} session cookie is still sent regardless — CORS just lets the browser
* read the response.
*
* Runs ahead of every other filter ({@link Ordered#HIGHEST_PRECEDENCE}) so every response —
* including the OPTIONS preflight, which never reaches a controller — carries these headers.
* Mirrors the Node reference's hand-rolled middleware; for many origins or production, reach for
* {@code WebMvcConfigurer#addCorsMappings} instead.
*/
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class CorsFilter extends OncePerRequestFilter {
private final BrokerProperties properties;
public CorsFilter(BrokerProperties properties) {
this.properties = properties;
}
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN, properties.getAppOrigin());
response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_CREDENTIALS, "true");
response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_HEADERS, "Content-Type");
response.setHeader(HttpHeaders.VARY, "Origin");
if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
response.setStatus(HttpStatus.NO_CONTENT.value());
return;
}
chain.doFilter(request, response);
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/config/StartupLogger.java`:**
```java
package com.example.broker.config;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
/**
* Logs the broker's URL and a non-secret config summary once the embedded server is actually
* listening — mirrors the Node reference's post-{@code app.listen} console output.
*/
@Component
public class StartupLogger {
private static final Logger log = LoggerFactory.getLogger(StartupLogger.class);
private final BrokerProperties properties;
public StartupLogger(BrokerProperties properties) {
this.properties = properties;
}
@EventListener(ApplicationReadyEvent.class)
void logStartup() {
log.info("JWT Bearer token broker on http://localhost:{}", properties.getPort());
log.info(" Authenticate: http://localhost:{}/login", properties.getPort());
log.info("Config: {}", properties.describeNonSecret());
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/PrivateKeyLoader.java`:**
```java
package com.example.broker.oauth;
import com.example.broker.config.BrokerProperties;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.GeneralSecurityException;
import java.security.KeyFactory;
import java.security.interfaces.RSAPrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import org.springframework.stereotype.Component;
/**
* Loads the RSA signing key once, at startup, from {@code PRIVATE_KEY} (inline PEM, {@code
* \n}-escaped) or {@code PRIVATE_KEY_PATH} (default {@code ./private.key}). The key must be
* unencrypted — the {@code openssl … -nodes} command in the certificate & ECA
* setup produces one; an encrypted key would need a passphrase this broker never prompts for.
*
*
The JDK's {@link KeyFactory} natively parses PKCS#8 ({@code -----BEGIN PRIVATE KEY-----}),
* which is exactly what that openssl command emits. A legacy PKCS#1 key ({@code -----BEGIN RSA
* PRIVATE KEY-----}) is wrapped into PKCS#8 here so it works too, with no BouncyCastle dependency.
*
*
{@code PRIVATE_KEY_PATH} is resolved relative to the current working directory,
* not this class — run the broker from {@code token-broker-jwt/java/}, or set an absolute path. A
* missing/unreadable key fails startup fast with a clean message, not a raw stack trace.
*/
@Component
public class PrivateKeyLoader {
private final RSAPrivateKey privateKey;
public PrivateKeyLoader(BrokerProperties properties) {
this.privateKey = load(properties);
}
public RSAPrivateKey getPrivateKey() {
return privateKey;
}
private static RSAPrivateKey load(BrokerProperties properties) {
String pem = readPem(properties);
if (pem.contains("ENCRYPTED")) {
throw new IllegalStateException(
"Private key is encrypted. This broker needs an unencrypted key (regenerate with "
+ "openssl … -nodes). See the certificate & ECA setup section.");
}
boolean pkcs1 = pem.contains("BEGIN RSA PRIVATE KEY");
byte[] der = Base64.getDecoder().decode(stripPem(pem));
try {
byte[] pkcs8 = pkcs1 ? wrapPkcs1AsPkcs8(der) : der;
return (RSAPrivateKey) KeyFactory.getInstance("RSA").generatePrivate(new PKCS8EncodedKeySpec(pkcs8));
} catch (GeneralSecurityException e) {
throw new IllegalStateException(
"Could not parse the RSA private key. Ensure it is an unencrypted PEM (PKCS#8 or "
+ "PKCS#1). See the certificate & ECA setup section.",
e);
}
}
private static String readPem(BrokerProperties properties) {
String inline = properties.getPrivateKeyInline();
if (inline != null && !inline.isBlank()) {
return inline.replace("\\n", "\n");
}
try {
return Files.readString(Path.of(properties.getPrivateKeyPath()), StandardCharsets.UTF_8);
} catch (IOException e) {
// Match the Node reference's fail-fast message — no raw ENOENT stack trace.
throw new IllegalStateException("Cannot read private key at " + properties.getPrivateKeyPath()
+ ". Copy private.key into this directory (or set PRIVATE_KEY_PATH to an absolute path). "
+ "See the certificate & ECA setup section.");
}
}
private static String stripPem(String pem) {
return pem.replaceAll("-----BEGIN [^-]+-----", "")
.replaceAll("-----END [^-]+-----", "")
.replaceAll("\\s", "");
}
/**
* Wraps a PKCS#1 {@code RSAPrivateKey} DER blob in a PKCS#8 {@code PrivateKeyInfo} so the JDK's
* {@link KeyFactory} (which reads only PKCS#8) can parse it — {@code SEQUENCE { version 0,
* AlgorithmIdentifier(rsaEncryption, NULL), OCTET STRING(pkcs1) }}.
*/
private static byte[] wrapPkcs1AsPkcs8(byte[] pkcs1) {
byte[] version = {0x02, 0x01, 0x00};
byte[] rsaAlgorithmId = {
0x30, 0x0D, 0x06, 0x09, 0x2A, (byte) 0x86, 0x48, (byte) 0x86,
(byte) 0xF7, 0x0D, 0x01, 0x01, 0x01, 0x05, 0x00
};
byte[] privateKeyOctet = derElement((byte) 0x04, pkcs1);
byte[] body = concat(version, rsaAlgorithmId, privateKeyOctet);
return derElement((byte) 0x30, body); // SEQUENCE
}
private static byte[] derElement(byte tag, byte[] content) {
byte[] length = derLength(content.length);
byte[] out = new byte[1 + length.length + content.length];
out[0] = tag;
System.arraycopy(length, 0, out, 1, length.length);
System.arraycopy(content, 0, out, 1 + length.length, content.length);
return out;
}
private static byte[] derLength(int length) {
if (length < 0x80) {
return new byte[] {(byte) length};
}
ByteArrayOutputStream valueBytes = new ByteArrayOutputStream();
for (int shift = 24; shift >= 0; shift -= 8) {
int b = (length >>> shift) & 0xFF;
if (b != 0 || valueBytes.size() > 0) {
valueBytes.write(b);
}
}
byte[] value = valueBytes.toByteArray();
byte[] out = new byte[1 + value.length];
out[0] = (byte) (0x80 | value.length);
System.arraycopy(value, 0, out, 1, value.length);
return out;
}
private static byte[] concat(byte[]... arrays) {
ByteArrayOutputStream out = new ByteArrayOutputStream();
for (byte[] array : arrays) {
out.write(array, 0, array.length);
}
return out.toByteArray();
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/JwtAssertionFactory.java`:**
```java
package com.example.broker.oauth;
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import com.example.broker.config.BrokerProperties;
import java.time.Duration;
import java.time.Instant;
import org.springframework.stereotype.Component;
/**
* Signs the JWT client assertion — the heart of the JWT Bearer flow. RS256 over the claims
* {@code iss=CLIENT_ID}, {@code sub=SF_USERNAME}, {@code aud=LOGIN_URL}, with {@code exp} bounded
* to ~3 minutes (Salesforce rejects an assertion whose lifetime exceeds 5). The RS256 signature
* is the client authentication; there is no client secret in this flow.
*/
@Component
public class JwtAssertionFactory {
// Salesforce caps the assertion lifetime at 5 minutes; stay well under it.
private static final Duration LIFETIME = Duration.ofMinutes(3);
private final BrokerProperties properties;
private final Algorithm algorithm;
public JwtAssertionFactory(BrokerProperties properties, PrivateKeyLoader keyLoader) {
this.properties = properties;
// Signing only: java-jwt's RSA256 takes (publicKey, privateKey); the public key is unused here.
this.algorithm = Algorithm.RSA256(null, keyLoader.getPrivateKey());
}
public String createAssertion() {
Instant now = Instant.now();
return JWT.create()
.withIssuer(properties.getClientId())
.withSubject(properties.getUsername())
.withAudience(properties.getLoginUrl())
.withIssuedAt(now)
.withExpiresAt(now.plus(LIFETIME))
.sign(algorithm);
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/FormEncoding.java`:**
```java
package com.example.broker.oauth;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.StringJoiner;
/**
* Encodes a map of parameters as {@code application/x-www-form-urlencoded}. Shared by the outbound
* token-exchange and single-access POST bodies ({@link SalesforceOAuthClient}), so the encoding
* rules live in exactly one place.
*/
public final class FormEncoding {
private FormEncoding() {}
public static String encode(Map params) {
StringJoiner joiner = new StringJoiner("&");
params.forEach((key, value) -> joiner.add(urlEncode(key) + "=" + urlEncode(value)));
return joiner.toString();
}
private static String urlEncode(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8);
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/TokenResponse.java`:**
```java
package com.example.broker.oauth;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Subset of the Salesforce {@code /services/oauth2/token} response we care about. The JWT Bearer
* grant issues no refresh token, so there's none here. Unknown fields (e.g. {@code id}, {@code
* scope}, {@code issued_at}) are ignored.
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public record TokenResponse(
@JsonProperty("access_token") String accessToken,
@JsonProperty("instance_url") String instanceUrl,
@JsonProperty("error") String error,
@JsonProperty("error_description") String errorDescription) {}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/SingleAccessResponse.java`:**
```java
package com.example.broker.oauth;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/** Subset of the Salesforce {@code /services/oauth2/singleaccess} response we care about. */
@JsonIgnoreProperties(ignoreUnknown = true)
public record SingleAccessResponse(@JsonProperty("frontdoor_uri") String frontdoorUri) {}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/UpstreamException.java`:**
```java
package com.example.broker.oauth;
/**
* Raised when Salesforce responds to the token exchange or the FrontDoor (single-access) request
* with a non-2xx status, or the call itself fails (network error, timeout). Carries the HTTP
* status to propagate back to our own caller: a Salesforce config rejection (e.g. {@code
* invalid_grant}) keeps its 4xx; a genuine transport fault is a 502. This is what keeps an
* expected config error from being collapsed into a generic 5xx.
*/
public class UpstreamException extends RuntimeException {
private final int statusCode;
public UpstreamException(int statusCode, String message) {
super(message);
this.statusCode = statusCode;
}
public UpstreamException(int statusCode, String message, Throwable cause) {
super(message, cause);
this.statusCode = statusCode;
}
public int getStatusCode() {
return statusCode;
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/BrokerSession.java`:**
```java
package com.example.broker.oauth;
import jakarta.servlet.http.HttpSession;
/**
* Thin, typed wrapper over {@link HttpSession} for the values this broker stashes there: the
* access token + instance URL from the JWT Bearer exchange. There's no PKCE verifier or OAuth
* state to keep (no browser round-trip), and no refresh token (the grant issues none) — on
* expiry the broker simply re-runs the exchange. Keeps the raw attribute-name strings in one
* place instead of scattered across the controller.
*/
public final class BrokerSession {
private static final String ACCESS_TOKEN = "accessToken";
private static final String INSTANCE_URL = "instanceUrl";
private final HttpSession session;
public BrokerSession(HttpSession session) {
this.session = session;
}
public void storeTokens(String accessToken, String instanceUrl) {
session.setAttribute(ACCESS_TOKEN, accessToken);
session.setAttribute(INSTANCE_URL, instanceUrl);
}
public String getAccessToken() {
return (String) session.getAttribute(ACCESS_TOKEN);
}
public String getInstanceUrl() {
return (String) session.getAttribute(INSTANCE_URL);
}
public boolean isAuthenticated() {
return getAccessToken() != null && getInstanceUrl() != null;
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/oauth/SalesforceOAuthClient.java`:**
```java
package com.example.broker.oauth;
import com.example.broker.config.BrokerProperties;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.stereotype.Component;
/**
* The two server-to-server calls this broker makes to Salesforce: the JWT Bearer token exchange,
* and the FrontDoor (single-access) mint. Both are plain {@code application/x-www-form-urlencoded}
* POSTs over {@link HttpClient} — no need for a heavier REST client here, and
* no client secret anywhere: the JWT's RS256 signature is the authentication.
*/
@Component
public class SalesforceOAuthClient {
private static final Duration REQUEST_TIMEOUT = Duration.ofSeconds(15);
private final HttpClient httpClient;
private final ObjectMapper objectMapper;
private final BrokerProperties properties;
private final JwtAssertionFactory assertionFactory;
public SalesforceOAuthClient(BrokerProperties properties, JwtAssertionFactory assertionFactory) {
this.properties = properties;
this.assertionFactory = assertionFactory;
this.httpClient = HttpClient.newBuilder().connectTimeout(REQUEST_TIMEOUT).build();
this.objectMapper = new ObjectMapper();
}
/**
* Signs a fresh assertion and POSTs it to {@code /services/oauth2/token} with
* {@code grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer}. No {@code client_secret} —
* the signature is the auth. A Salesforce rejection (e.g. {@code invalid_grant}: the {@code
* sub} user not pre-authorized, an {@code aud} mismatch, clock skew, or a cert/key mismatch)
* becomes an {@link UpstreamException} carrying its HTTP status (e.g. 400), so the caller can
* forward it as a 4xx rather than collapse it to a 5xx.
*/
public TokenResponse getAccessTokenViaJwt() {
Map form = new LinkedHashMap<>();
form.put("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer");
form.put("assertion", assertionFactory.createAssertion());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(properties.getLoginUrl() + "/services/oauth2/token"))
.timeout(REQUEST_TIMEOUT)
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(FormEncoding.encode(form)))
.build();
HttpResponse response = send(request, "JWT token exchange");
TokenResponse token = parse(response.body(), TokenResponse.class, "token response");
if (response.statusCode() / 100 != 2 || token.accessToken() == null) {
// Salesforce returns {error, error_description}; forward it (no secret/token in the body).
String reason = token.errorDescription() != null ? token.errorDescription() : token.error();
int status = response.statusCode() >= 400 ? response.statusCode() : 500;
throw new UpstreamException(status, "JWT token exchange failed" + (reason != null ? ": " + reason : ""));
}
return token;
}
/**
* POSTs (empty body) to {@code /services/oauth2/singleaccess} with the session's
* bearer token, to mint a short-lived FrontDoor URL.
*/
public SingleAccessResponse mintFrontdoorUrl(String instanceUrl, String accessToken) {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(instanceUrl + "/services/oauth2/singleaccess"))
.timeout(REQUEST_TIMEOUT)
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(""))
.build();
HttpResponse response = send(request, "FrontDoor request");
if (response.statusCode() / 100 != 2) {
// Surface Salesforce's own reason: the body carries {"error","error_description"} that
// distinguishes e.g. an expired token (401/403 -> re-mint in the controller) from a missing
// scope. No token/secret is in it, so it's safe to forward; truncate defensively.
String body = response.body() == null ? "" : response.body().strip();
String detail = body.isEmpty() ? "" : ": " + (body.length() > 500 ? body.substring(0, 500) + "…" : body);
throw new UpstreamException(response.statusCode(), "Salesforce responded " + response.statusCode() + detail);
}
return parse(response.body(), SingleAccessResponse.class, "single-access response");
}
private HttpResponse send(HttpRequest request, String label) {
try {
return httpClient.send(request, HttpResponse.BodyHandlers.ofString());
} catch (IOException e) {
throw new UpstreamException(502, label + " failed: " + e.getMessage(), e);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new UpstreamException(502, label + " interrupted", e);
}
}
private T parse(String body, Class type, String label) {
try {
return objectMapper.readValue(body, type);
} catch (IOException e) {
throw new UpstreamException(502, "Malformed " + label + " from Salesforce", e);
}
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/api/TokenBrokerController.java`:**
```java
package com.example.broker.api;
import com.example.broker.config.BrokerProperties;
import com.example.broker.oauth.BrokerSession;
import com.example.broker.oauth.SalesforceOAuthClient;
import com.example.broker.oauth.SingleAccessResponse;
import com.example.broker.oauth.TokenResponse;
import com.example.broker.oauth.UpstreamException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpSession;
import java.net.URI;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* The endpoints of the Salesforce OAuth token broker (JWT Bearer flow). Unlike the Auth Code +
* PKCE broker there is no {@code /getAccessToken} callback and no Salesforce login screen: {@code
* /login} runs the exchange server-side and redirects straight to the SPA, {@code
* /getFrontdoorURL} trades the session's access token for a short-lived FrontDoor URL the SPA can
* use as the SDK's {@code authCredential}, and {@code /health} is a liveness check.
*
* Status codes mirror the Node JWT reference: an expected Salesforce config rejection keeps its
* 4xx (it is not collapsed to a 5xx), a transport fault is a 502, and only an unexpected
* server fault is a 500.
*/
@RestController
public class TokenBrokerController {
private final BrokerProperties properties;
private final SalesforceOAuthClient oauthClient;
public TokenBrokerController(BrokerProperties properties, SalesforceOAuthClient oauthClient) {
this.properties = properties;
this.oauthClient = oauthClient;
}
/**
* Runs the JWT Bearer exchange server-side, stashes the token in the session, then bounces to
* the SPA. There is no interactive redirect to Salesforce — no login screen.
*/
@GetMapping("/login")
public ResponseEntity login(HttpServletRequest request) {
BrokerSession session = new BrokerSession(request.getSession(true));
try {
storeFreshToken(session);
} catch (UpstreamException e) {
// A Salesforce rejection (invalid_grant etc.) is an expected CONFIG error — forward its
// 4xx status. Reserve 502 for genuine transport faults (token host unreachable), which
// getAccessTokenViaJwt already tags.
return ResponseEntity.status(e.getStatusCode()).contentType(MediaType.TEXT_PLAIN).body(e.getMessage());
}
return ResponseEntity.status(HttpStatus.FOUND).location(URI.create(properties.getAppOrigin())).build();
}
/**
* Mints a FrontDoor URL from the session's token; the SPA calls this. If nothing is stored yet
* (or the token has expired, surfacing as 401/403 from single-access), the broker silently
* re-runs the JWT exchange and retries once — a JWT Bearer client re-mints with no user
* interaction, so there is no refresh-token dance here.
*/
@GetMapping("/getFrontdoorURL")
public ResponseEntity getFrontdoorUrl(HttpSession httpSession) {
BrokerSession session = new BrokerSession(httpSession);
try {
if (!session.isAuthenticated()) {
storeFreshToken(session);
}
SingleAccessResponse singleAccess;
try {
singleAccess = oauthClient.mintFrontdoorUrl(session.getInstanceUrl(), session.getAccessToken());
} catch (UpstreamException e) {
// Only an expired/invalid token (401/403) is retryable by re-minting; anything else
// propagates to the outer handler with its own status.
if (e.getStatusCode() != 401 && e.getStatusCode() != 403) {
throw e;
}
storeFreshToken(session);
singleAccess = oauthClient.mintFrontdoorUrl(session.getInstanceUrl(), session.getAccessToken());
}
return ResponseEntity.ok(new FrontdoorResponse(singleAccess.frontdoorUri(), properties.getOrgUrl()));
} catch (UpstreamException e) {
// A Salesforce config rejection carries its 4xx; a transport fault is a 502. Forward it —
// never collapse a config error to a 5xx. (No "re-authenticate" hint: a JWT client re-mints
// silently, there's no login screen to send anyone to.)
return ResponseEntity.status(e.getStatusCode()).body(new ErrorResponse(e.getMessage()));
}
}
@GetMapping("/health")
public HealthResponse health() {
return new HealthResponse(true);
}
/** Runs the JWT Bearer exchange and stores the fresh access token + instance URL in the session. */
private void storeFreshToken(BrokerSession session) {
TokenResponse token = oauthClient.getAccessTokenViaJwt();
session.storeTokens(token.accessToken(), token.instanceUrl());
}
}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/api/FrontdoorResponse.java`:**
```java
package com.example.broker.api;
import com.fasterxml.jackson.annotation.JsonInclude;
/** JSON body returned by {@code GET /getFrontdoorURL}: {@code {"frontdoorUrl", "orgUrl"}}. */
@JsonInclude(JsonInclude.Include.NON_NULL)
public record FrontdoorResponse(String frontdoorUrl, String orgUrl) {}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/api/ErrorResponse.java`:**
```java
package com.example.broker.api;
/** JSON error body returned by the broker's endpoints: {@code {"error": "..."}}. */
public record ErrorResponse(String error) {}
```
**`token-broker-jwt/java/src/main/java/com/example/broker/api/HealthResponse.java`:**
```java
package com.example.broker.api;
/** JSON body returned by {@code GET /health}: {@code {"ok": true}}. */
public record HealthResponse(boolean ok) {}
```
---
## Python (FastAPI) — JWT Bearer
> **Alternative flow — the [JWT Bearer broker (Node.js)](#jwt-bearer-broker-nodejs) above was verified end-to-end on a real org; this is its faithful Python port** (byte-compiles clean via `py_compile` here, not separately run on an org). FastAPI + `httpx`, signing the assertion with **PyJWT** (RS256). There's no interactive login and **no Salesforce login screen** — the server signs a JWT with its private key and exchanges it for a token, impersonating a fixed user, so there's **no `CLIENT_SECRET` and no `REDIRECT_URI`** (the RS256 signature is the auth). Verified via that Node reference (JWT → FrontDoor URL → dashboard rendered); the one caveat is that it's **not part of the official SDK guide**, which documents Auth Code + PKCE. Complete the one-time [certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time) first: generate `private.key` + `public.crt`, upload `public.crt` to the ECA, and enable the JWT Bearer flow on it.
**Run it.** From `token-broker-jwt/python/`, create a venv and install deps, then get the private key into place — `PRIVATE_KEY_PATH` is resolved **relative to the directory you launch from**, not to `main.py`, so the key must sit in `token-broker-jwt/python/` (or use an absolute path). Load the shared `.env` (the JWT broker's `.env`, one dir up — see the Node section for how `.env` loading and the `source` path work), confirm it loaded, then start. The broker listens on **http://localhost:8500**.
```bash
cd token-broker-jwt/python
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp /path/to/private.key ./private.key # only public.crt was uploaded to the ECA; keep this one local
ls -la private.key # PRIVATE_KEY_PATH is relative to THIS dir -- confirm it's here first
set -a; source ../.env; set +a # re-source after ANY .env edit, then restart -- a running
echo "ORG_URL=$ORG_URL" # process keeps the OLD values until you re-source + restart
uvicorn main:app --port 8500
```
Then open **http://localhost:8500/login** once. Unlike the PKCE broker there is **no Salesforce login screen** — it runs the exchange entirely server-side and redirects straight to your SPA, which calls `GET /getFrontdoorURL`.
Requires **Python 3.9+**. Uses **PyJWT** (with the `cryptography` extra) to sign the RS256 assertion; the private key must be **unencrypted** — the `openssl ... -nodes` command in the cert setup produces one, and an encrypted key would need a passphrase. (Note: Starlette's `CORSMiddleware` answers preflight with `200`, not the contract's literal `204`; browsers treat any 2xx preflight identically.)
**`token-broker-jwt/python/requirements.txt`:**
```text
fastapi==0.141.1
uvicorn[standard]==0.52.1
httpx==0.28.1
pyjwt[crypto]==2.10.1
```
**Config.** Reads the same environment as the [JWT Bearer broker (Node.js)](#jwt-bearer-broker-nodejs) — the same `.env`, minus `CLIENT_SECRET` and `REDIRECT_URI` (neither exists in this flow): `PORT`, `LOGIN_URL` (also the JWT `aud`), `ORG_URL` (the SDK `orgUrl`), `CLIENT_ID` (the JWT `iss`), `SF_USERNAME` (the JWT `sub`), `PRIVATE_KEY_PATH` (default `./private.key`, cwd-relative) or `PRIVATE_KEY` (inline PEM, `\n`-escaped), `APP_ORIGIN`, and `SESSION_SECRET`.
**`token-broker-jwt/python/main.py`:**
```python
"""Tableau Next embedding -- server-side token broker (Python / FastAPI, JWT Bearer flow).
ALTERNATIVE to the Authorization Code + PKCE broker (main.py). Instead of an interactive login,
the server signs a JWT with its private key and exchanges it for an access token, impersonating
SF_USERNAME, then mints the SAME FrontDoor URL the SDK consumes as ``authCredential``.
Port of the Node/Express JWT Bearer broker (``token-broker-jwt/server.js``). Keep this on the
server: it holds the private key and the raw access token; the browser only ever sees the
short-lived FrontDoor URL. There is NO client secret in this flow -- the RS256 signature is the auth.
Endpoints:
GET /login -> runs the JWT Bearer exchange server-side, stores the session, redirects to the SPA
GET /getFrontdoorURL -> mints {frontdoorUrl, orgUrl} from the stored token (call this from the SPA)
GET /health -> {"ok": true}
"""
import os
import secrets
import sys
import threading
from datetime import datetime, timedelta, timezone
from typing import Optional
import httpx
import jwt
from fastapi import FastAPI, Request, Response
from fastapi.responses import JSONResponse, PlainTextResponse, RedirectResponse
from starlette.middleware.cors import CORSMiddleware
# ---- Config (from environment) -----------------------------------------------------
PORT = int(os.environ.get("PORT", "8500"))
# The org's OAuth login host -- BOTH where we POST the token request and the JWT `aud` claim.
LOGIN_URL = os.environ.get("LOGIN_URL")
# The org's Lightning My Domain host -- the SDK `orgUrl`.
ORG_URL = os.environ.get("ORG_URL")
# ECA Consumer Key -- the JWT `iss` claim.
CLIENT_ID = os.environ.get("CLIENT_ID")
# Salesforce username to impersonate -- the JWT `sub` claim. Must be pre-authorized on the ECA
# and hold a Tableau+/Tableau Next license.
SF_USERNAME = os.environ.get("SF_USERNAME")
# RSA private key whose public cert is uploaded to the ECA: either a path (default ./private.key)
# or the PEM contents inline (PRIVATE_KEY, with \n for newlines). There is NO CLIENT_SECRET here.
PRIVATE_KEY = os.environ.get("PRIVATE_KEY")
PRIVATE_KEY_PATH = os.environ.get("PRIVATE_KEY_PATH", "./private.key")
# The SPA's origin -- where the browser is sent and the CORS-allowed origin for /getFrontdoorURL.
APP_ORIGIN = os.environ.get("APP_ORIGIN", "http://localhost:8700")
SESSION_SECRET = os.environ.get("SESSION_SECRET", "change-me-in-production")
for name, value in {
"LOGIN_URL": LOGIN_URL,
"ORG_URL": ORG_URL,
"CLIENT_ID": CLIENT_ID,
"SF_USERNAME": SF_USERNAME,
}.items():
if not value:
print(f"Missing required env var: {name}. See .env.example.", file=sys.stderr)
sys.exit(1)
# ---- Signing key ---------------------------------------------------------------------
# Load the signing key once, from PRIVATE_KEY (inline PEM, \n-escaped) or PRIVATE_KEY_PATH.
# Fail fast with a clean message if it's missing -- otherwise open() throws a raw traceback.
# PRIVATE_KEY_PATH is resolved relative to the CURRENT WORKING DIRECTORY, not this file -- run
# from token-broker-jwt/python/, or set an absolute path. The key must be UNENCRYPTED (the
# `openssl ... -nodes` command in the cert setup produces one); an encrypted key needs a passphrase.
if PRIVATE_KEY:
PRIVATE_KEY_PEM = PRIVATE_KEY.replace("\\n", "\n")
else:
try:
with open(PRIVATE_KEY_PATH, "r", encoding="utf-8") as fh:
PRIVATE_KEY_PEM = fh.read()
except OSError:
print(
f"Cannot read private key at {PRIVATE_KEY_PATH}. Copy private.key into this directory "
f"(or set PRIVATE_KEY_PATH to an absolute path). See the certificate & ECA setup section.",
file=sys.stderr,
)
sys.exit(1)
# ---- JWT Bearer exchange -------------------------------------------------------------
class TokenExchangeError(Exception):
"""A JWT Bearer exchange failed. ``upstream_status`` carries Salesforce's HTTP status for an
expected config rejection (e.g. 400 invalid_grant) so endpoints can forward it as a 4xx; it's
None for a genuine transport fault (token host unreachable), which callers map to a 502."""
def __init__(self, message: str, upstream_status: Optional[int] = None):
super().__init__(message)
self.upstream_status = upstream_status
def create_assertion() -> str:
"""Sign the JWT assertion with RS256. Claims: iss=client_id, sub=user to impersonate,
aud=login host, exp bounded to 3 min. (iat mirrors what jsonwebtoken sets automatically;
Salesforce only requires exp.)"""
now = datetime.now(timezone.utc)
claims = {
"iss": CLIENT_ID,
"sub": SF_USERNAME,
"aud": LOGIN_URL,
"iat": now,
"exp": now + timedelta(minutes=3),
}
return jwt.encode(claims, PRIVATE_KEY_PEM, algorithm="RS256")
async def get_access_token_via_jwt() -> tuple[str, str]:
"""Exchange the signed JWT for an access token. No client_secret -- the RS256 signature is the
auth. Returns (access_token, instance_url). On a Salesforce rejection (e.g. invalid_grant) we
raise TokenExchangeError carrying the upstream 4xx status so callers can forward it -- a config
error is NOT a 5xx. A transport fault raises with upstream_status=None (a 502 for callers)."""
data = {
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": create_assertion(),
}
try:
async with httpx.AsyncClient() as client:
resp = await client.post(f"{LOGIN_URL}/services/oauth2/token", data=data)
except httpx.HTTPError as exc:
raise TokenExchangeError(f"JWT token exchange failed: {exc}") from exc
try:
token_data = resp.json()
except ValueError:
token_data = {}
if resp.is_error or not token_data.get("access_token"):
# Salesforce returns {error, error_description}; forward it (no secret/token in the body).
reason = token_data.get("error_description") or token_data.get("error") or f"HTTP {resp.status_code}"
raise TokenExchangeError(f"JWT token exchange failed: {reason}", upstream_status=resp.status_code)
return token_data["access_token"], token_data["instance_url"]
async def _mint_frontdoor(client: httpx.AsyncClient, instance_url: str, access_token: str) -> httpx.Response:
"""POST the access token to singleaccess to mint a FrontDoor URL (identical to the PKCE broker)."""
return await client.post(
f"{instance_url}/services/oauth2/singleaccess",
headers={
"accept": "application/json",
"authorization": f"Bearer {access_token}",
"content-type": "application/x-www-form-urlencoded",
},
content=b"",
)
# ---- App -----------------------------------------------------------------------------
app = FastAPI(title="Tableau Next Token Broker (JWT Bearer)")
# CORS: the SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this broker
# (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these headers or the
# browser drops the response. Allow-Origin must name the exact origin (not '*') when credentials are
# involved. On localhost, :8700 and :8500 are the same *site*, so the SameSite=Lax session cookie is
# still sent -- CORS just permits reading the response.
app.add_middleware(
CORSMiddleware,
allow_origins=[APP_ORIGIN],
allow_credentials=True,
allow_methods=["GET", "OPTIONS"],
allow_headers=["Content-Type"],
)
# ---- Server-side session store -------------------------------------------------------
# CRITICAL: session state (accessToken, instanceUrl) must stay SERVER-SIDE, exactly like the Node
# reference's express-session MemoryStore. The cookie carries ONLY an opaque, unguessable session
# id -- never the token, and never the private key. (Starlette's SessionMiddleware is a *signed
# cookie* store, which would serialize the raw access_token into the browser cookie; that violates
# the "token never leaves the server" invariant, so we don't use it.)
#
# This in-memory dict is fine for local dev / a single process. For production or multiple workers,
# back it with a shared store (Redis, a database, etc.) so sessions survive restarts.
SESSION_COOKIE = "token_broker_session"
_sessions: dict[str, dict] = {}
_sessions_lock = threading.Lock()
def _get_session(request: Request) -> dict:
"""Return the server-side session dict for this request (empty if none yet)."""
sid = request.cookies.get(SESSION_COOKIE)
if not sid:
return {}
with _sessions_lock:
return _sessions.get(sid, {})
def _save_session(response: Response, request: Request, data: dict) -> None:
"""Persist the session dict server-side and set the opaque-id cookie if new."""
sid = request.cookies.get(SESSION_COOKIE)
with _sessions_lock:
if not sid or sid not in _sessions:
sid = secrets.token_urlsafe(32)
_sessions[sid] = data
# HttpOnly + SameSite=Lax; the value is only the opaque id, never the token.
response.set_cookie(SESSION_COOKIE, sid, httponly=True, samesite="lax", secure=False, path="/")
@app.get("/login")
async def login(request: Request) -> Response:
"""Run the JWT Bearer exchange entirely server-side, stash the token, then bounce to the SPA.
There is NO interactive redirect to Salesforce -- no login screen, no user prompt."""
try:
access_token, instance_url = await get_access_token_via_jwt()
except TokenExchangeError as exc:
# A Salesforce rejection (invalid_grant etc.) is an expected CONFIG error -- forward its
# 4xx status. A transport fault (upstream_status=None, token host unreachable) is a 502.
status = exc.upstream_status or 502
return PlainTextResponse(str(exc) or "JWT authentication failed", status_code=status)
response = RedirectResponse(url=APP_ORIGIN, status_code=302) # straight to the SPA, no SF screen
session = _get_session(request)
session["accessToken"] = access_token
session["instanceUrl"] = instance_url
_save_session(response, request, session)
return response
@app.get("/getFrontdoorURL")
async def get_frontdoor_url(request: Request) -> JSONResponse:
"""Mint a FrontDoor URL from the session's token. The SPA calls this. If there's no stored
token yet, run the exchange first; on a 401/403 (expired token) re-run it once and retry -- a
JWT Bearer client re-mints silently with no user interaction, so there's no refresh-token dance."""
session = _get_session(request)
try:
if not session.get("accessToken") or not session.get("instanceUrl"):
session["accessToken"], session["instanceUrl"] = await get_access_token_via_jwt()
async with httpx.AsyncClient() as client:
resp = await _mint_frontdoor(client, session["instanceUrl"], session["accessToken"])
if resp.status_code in (401, 403):
session["accessToken"], session["instanceUrl"] = await get_access_token_via_jwt()
resp = await _mint_frontdoor(client, session["instanceUrl"], session["accessToken"])
except TokenExchangeError as exc:
# A Salesforce config rejection carries the upstream 4xx status -- forward it. A transport
# fault (upstream_status=None, token host unreachable) is a 502, not a 500.
status = exc.upstream_status or 502
return JSONResponse({"error": str(exc) or "Failed to generate FrontDoor URL"}, status_code=status)
except httpx.HTTPError as exc:
# Transport fault talking to singleaccess -- the instance host was unreachable.
return JSONResponse({"error": str(exc) or "Failed to generate FrontDoor URL"}, status_code=502)
if resp.is_error:
# Still failing after the retry -- surface Salesforce's own reason (the body carries
# {"error","error_description"}). No token/secret is in it, so it's safe to forward;
# truncate defensively.
body = (resp.text or "").strip()
detail = f": {body[:500]}…" if len(body) > 500 else (f": {body}" if body else "")
return JSONResponse(
{"error": f"Salesforce responded {resp.status_code}{detail}."},
status_code=resp.status_code,
)
data = resp.json()
result = JSONResponse({"frontdoorUrl": data.get("frontdoor_uri"), "orgUrl": ORG_URL})
_save_session(result, request, session) # persist token + set the opaque-id cookie if new
return result
@app.get("/health")
async def health() -> JSONResponse:
return JSONResponse({"ok": True})
if __name__ == "__main__":
import uvicorn
print(f"JWT Bearer token broker on http://localhost:{PORT}")
print(f" Authenticate: http://localhost:{PORT}/login (no login screen -- bounces to the SPA)")
uvicorn.run(app, host="0.0.0.0", port=PORT)
```
---
## Go (net/http) — JWT Bearer
> **Alternative flow — the [JWT Bearer broker](#jwt-bearer-broker-nodejs) above was verified end-to-end on a real org; this is its faithful Go port** (`go vet` + `go build` clean here, not separately run on an org). Server-to-server, so there's **no login screen** —
> the broker signs a JWT with its private key and exchanges it for an access token (impersonating
> `SF_USERNAME`), then mints the SAME FrontDoor URL the SDK consumes. Like the PKCE Go port it's
> **standard-library only** (`go run .`, no deps): the RS256 assertion is built and signed with
> `crypto/rsa` in a small `signJWT` helper — no JWT library. There is **no `CLIENT_SECRET` and no
> `REDIRECT_URI`** here; the signature is the auth. Session state is the same in-memory map keyed by a
> `crypto/rand` opaque id (server-side; the cookie carries only that id, `HttpOnly` + `SameSite=Lax`).
> Complete the one-time [certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time)
> first. Caveat: this is **not part of the official SDK guide**, which documents Auth Code + PKCE.
**Run it.** From `token-broker-jwt/go/`, with the JWT Bearer broker's `.env` filled in. First get the
private key into place — `PRIVATE_KEY_PATH` is resolved **relative to the directory you run from**,
not to `main.go`, so the key must sit in `token-broker-jwt/go/` (or set an absolute path). There's no
dependency-install step — this port is **standard-library only**, so `go run .` compiles and starts it
directly:
```bash
cd token-broker-jwt/go
cp /path/to/private.key ./private.key && ls -la private.key # only public.crt went to the ECA; keep this local
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
go run .
```
Then open **http://localhost:8500/login** once — it runs the exchange server-side (**no Salesforce
login screen**) and bounces straight to your SPA, which calls `GET /getFrontdoorURL`.
Requires **Go 1.22+** (method-qualified `ServeMux` routes). Reads config directly from `os.Getenv` (no
`.env` loader) — export the same vars the JWT Bearer broker (Node.js) section documents.
**`token-broker-jwt/go/go.mod`:**
```text
module tableau-next-token-broker-jwt
go 1.22
```
**`token-broker-jwt/go/main.go`:**
```go
// Command tableau-next-token-broker-jwt runs the Salesforce OAuth JWT Bearer flow and mints a
// FrontDoor URL for the Analytics Embedding SDK.
//
// ALTERNATIVE to the Authorization Code + PKCE broker. Instead of an interactive login, the
// server signs a JWT with its private key and exchanges it for an access token, impersonating
// SF_USERNAME, then mints the SAME FrontDoor URL the SDK consumes.
//
// Keep this server-side: it holds the private key and the raw access token. The browser only
// ever receives the short-lived FrontDoor URL. There is NO client secret in this flow -- the
// RS256 signature authenticates the client.
//
// Endpoints:
//
// GET /login runs the JWT Bearer exchange server-side, stores the session, redirects to the SPA
// GET /getFrontdoorURL exchanges the stored token -> {frontdoorUrl, orgUrl} (call from the SPA)
// GET /health liveness check
package main
import (
"crypto"
"crypto/rand"
"crypto/rsa"
"crypto/sha256"
"crypto/x509"
"encoding/base64"
"encoding/json"
"encoding/pem"
"errors"
"fmt"
"io"
"log"
"net/http"
"net/url"
"os"
"strings"
"sync"
"time"
)
// config holds the broker's settings, all sourced from the environment. Note the absence of a
// client secret and redirect URI -- neither exists in the JWT Bearer flow.
type config struct {
port string
loginURL string // also the JWT `aud` claim
orgURL string
clientID string // the JWT `iss` claim
sfUsername string // the JWT `sub` claim -- the user to impersonate
privateKeyPath string
appOrigin string
// sessionSecret is read for parity with the other broker ports' env surface (SESSION_SECRET
// is documented everywhere), but this broker's in-memory session store keys sessions by an
// unguessable server-side id rather than a signed cookie, so it isn't consumed today.
sessionSecret string
}
// loadConfig reads configuration from the environment and fails fast if a required value is
// missing, mirroring the Node reference implementation.
func loadConfig() config {
cfg := config{
port: getEnv("PORT", "8500"),
loginURL: os.Getenv("LOGIN_URL"),
orgURL: os.Getenv("ORG_URL"),
clientID: os.Getenv("CLIENT_ID"),
sfUsername: os.Getenv("SF_USERNAME"),
privateKeyPath: getEnv("PRIVATE_KEY_PATH", "./private.key"),
appOrigin: getEnv("APP_ORIGIN", "http://localhost:8700"),
sessionSecret: getEnv("SESSION_SECRET", "change-me-in-production"),
}
required := map[string]string{
"LOGIN_URL": cfg.loginURL,
"ORG_URL": cfg.orgURL,
"CLIENT_ID": cfg.clientID,
"SF_USERNAME": cfg.sfUsername,
}
for _, name := range []string{"LOGIN_URL", "ORG_URL", "CLIENT_ID", "SF_USERNAME"} {
if required[name] == "" {
log.Fatalf("Missing required env var: %s. See .env.example.", name)
}
}
return cfg
}
func getEnv(name, fallback string) string {
if v := os.Getenv(name); v != "" {
return v
}
return fallback
}
// loadPrivateKey reads the RSA signing key once at startup: it prefers the inline PRIVATE_KEY
// (PEM with \n-escaped newlines) and otherwise reads PRIVATE_KEY_PATH. It fails fast with a clean
// message rather than a raw file-read panic. Note PRIVATE_KEY_PATH is resolved relative to the
// CURRENT WORKING DIRECTORY, not this file -- run the broker from token-broker-jwt/go, or set an
// absolute path.
func loadPrivateKey(cfg config) *rsa.PrivateKey {
var pemBytes []byte
if inline := os.Getenv("PRIVATE_KEY"); inline != "" {
pemBytes = []byte(strings.ReplaceAll(inline, `\n`, "\n"))
} else {
b, err := os.ReadFile(cfg.privateKeyPath)
if err != nil {
log.Fatalf("Cannot read private key at %s. Copy private.key into this directory or set an absolute path. See the certificate & ECA setup section.", cfg.privateKeyPath)
}
pemBytes = b
}
key, err := parsePrivateKey(pemBytes)
if err != nil {
log.Fatalf("Cannot parse private key: %v. It must be an UNENCRYPTED RSA key (the openssl -nodes command produces one). See the certificate & ECA setup section.", err)
}
return key
}
// parsePrivateKey decodes an unencrypted RSA private key from PEM. It accepts both encodings
// openssl emits: PKCS#8 ("BEGIN PRIVATE KEY", via x509.ParsePKCS8PrivateKey) and PKCS#1
// ("BEGIN RSA PRIVATE KEY", via x509.ParsePKCS1PrivateKey). An encrypted key
// ("BEGIN ENCRYPTED PRIVATE KEY") is rejected -- the key must be unencrypted.
func parsePrivateKey(pemBytes []byte) (*rsa.PrivateKey, error) {
block, _ := pem.Decode(pemBytes)
if block == nil {
return nil, errors.New("no PEM block found (expected BEGIN PRIVATE KEY or BEGIN RSA PRIVATE KEY)")
}
switch block.Type {
case "PRIVATE KEY": // PKCS#8
key, err := x509.ParsePKCS8PrivateKey(block.Bytes)
if err != nil {
return nil, err
}
rsaKey, ok := key.(*rsa.PrivateKey)
if !ok {
return nil, errors.New("private key is not RSA (RS256 requires an RSA key)")
}
return rsaKey, nil
case "RSA PRIVATE KEY": // PKCS#1
return x509.ParsePKCS1PrivateKey(block.Bytes)
default:
return nil, fmt.Errorf("unsupported PEM block %q; expected an unencrypted RSA private key", block.Type)
}
}
// signJWT builds a compact RS256 JWS -- base64url(header).base64url(claims).base64url(signature)
// -- with the standard library, so this port stays dependency-free. RS256 is "sign the SHA-256
// digest of the signing input with RSASSA-PKCS1-v1_5", which is exactly rsa.SignPKCS1v15 over a
// crypto.SHA256 hash. All three segments use base64url with no padding, per the JWT spec.
func signJWT(claims map[string]any, key *rsa.PrivateKey) (string, error) {
headerJSON, err := json.Marshal(map[string]string{"alg": "RS256", "typ": "JWT"})
if err != nil {
return "", err
}
claimsJSON, err := json.Marshal(claims)
if err != nil {
return "", err
}
signingInput := base64.RawURLEncoding.EncodeToString(headerJSON) + "." +
base64.RawURLEncoding.EncodeToString(claimsJSON)
digest := sha256.Sum256([]byte(signingInput))
sig, err := rsa.SignPKCS1v15(rand.Reader, key, crypto.SHA256, digest[:])
if err != nil {
return "", err
}
return signingInput + "." + base64.RawURLEncoding.EncodeToString(sig), nil
}
// broker holds everything a request handler needs: config, an HTTP client for the
// server-to-server calls to Salesforce, the parsed signing key, and the session store.
type broker struct {
cfg config
sessions *sessionStore
client *http.Client
privateKey *rsa.PrivateKey
}
const sessionCookieName = "token-broker-jwt-session"
// sessionData is the state the broker stashes across requests: the access token + instance URL
// obtained from the JWT exchange. It lives only server-side -- never in the cookie. There's no
// PKCE verifier or refresh token here: a JWT Bearer client silently re-mints by re-signing.
type sessionData struct {
accessToken string
instanceUrl string
}
// sessionStore is a minimal, single-process, in-memory session store: state lives in this map,
// keyed by a crypto/rand opaque id, and the browser's cookie carries only that id -- never the
// session payload. This is the Go analog of express-session's default MemoryStore. A real
// deployment (multi-process, or one that must survive restarts) should back this with a shared
// store instead (e.g. Redis); see the README.
type sessionStore struct {
mu sync.Mutex
data map[string]*sessionData
}
func newSessionStore() *sessionStore {
return &sessionStore{data: make(map[string]*sessionData)}
}
// newSessionID returns a high-entropy, unguessable id (32 random bytes, base64url-encoded)
// suitable for use as an opaque session-cookie value.
func newSessionID() (string, error) {
raw := make([]byte, 32)
if _, err := rand.Read(raw); err != nil {
return "", err
}
return base64.RawURLEncoding.EncodeToString(raw), nil
}
// load returns the session named by the request's cookie, or nil if there isn't one --
// e.g. no cookie yet, or a stale id (this store doesn't survive restarts).
func (s *sessionStore) load(r *http.Request) *sessionData {
cookie, err := r.Cookie(sessionCookieName)
if err != nil {
return nil
}
s.mu.Lock()
defer s.mu.Unlock()
return s.data[cookie.Value]
}
// create allocates a new session under a fresh opaque id, sets that id as an HttpOnly+SameSite=Lax
// cookie on the response, and returns the (empty) session for the caller to populate.
func (s *sessionStore) create(w http.ResponseWriter) (*sessionData, error) {
id, err := newSessionID()
if err != nil {
return nil, err
}
sess := &sessionData{}
s.mu.Lock()
s.data[id] = sess
s.mu.Unlock()
http.SetCookie(w, &http.Cookie{
Name: sessionCookieName,
Value: id,
Path: "/",
HttpOnly: true,
SameSite: http.SameSiteLaxMode,
})
return sess, nil
}
// getOrCreate returns the request's existing session, or creates (and cookies) a fresh one if the
// request has none. A tampered or stale cookie shouldn't block the flow, so this never errors on a
// bad incoming cookie -- it just starts over.
func (s *sessionStore) getOrCreate(r *http.Request, w http.ResponseWriter) (*sessionData, error) {
if sess := s.load(r); sess != nil {
return sess, nil
}
return s.create(w)
}
// tokenError carries the upstream HTTP status from a token-endpoint failure so handlers can decide
// what to return. A completed Salesforce rejection (e.g. 400 invalid_grant) sets StatusCode; a
// request that never reached Salesforce sets transport=true (-> 502). A server-side fault (signing,
// undecodable response) leaves both zero/false (-> 500).
type tokenError struct {
StatusCode int
transport bool
msg string
}
func (e *tokenError) Error() string { return e.msg }
// statusForTokenError maps a token-exchange failure to the HTTP status the broker returns: a
// transport fault (token host unreachable) becomes 502; an expected Salesforce config rejection (a
// 4xx like invalid_grant) is forwarded as-is; anything else -- a signing fault, an undecodable
// body, an upstream 5xx -- is an unexpected server fault and becomes 500.
func statusForTokenError(err error) int {
var te *tokenError
if errors.As(err, &te) {
if te.transport {
return http.StatusBadGateway
}
if te.StatusCode >= 400 && te.StatusCode < 500 {
return te.StatusCode
}
}
return http.StatusInternalServerError
}
// createAssertion builds and signs the RS256 JWT bearer assertion. Claims: iss=CLIENT_ID,
// sub=SF_USERNAME (the user to impersonate), aud=LOGIN_URL (the token host), plus iat and an exp
// bounded to 3 minutes out (Salesforce requires exp within 5 minutes).
func (b *broker) createAssertion() (string, error) {
now := time.Now()
claims := map[string]any{
"iss": b.cfg.clientID,
"sub": b.cfg.sfUsername,
"aud": b.cfg.loginURL,
"iat": now.Unix(),
"exp": now.Add(3 * time.Minute).Unix(),
}
return signJWT(claims, b.privateKey)
}
// tokenResponse is the subset of Salesforce's /services/oauth2/token response we need.
type tokenResponse struct {
AccessToken string `json:"access_token"`
InstanceURL string `json:"instance_url"`
Error string `json:"error"`
ErrorDescription string `json:"error_description"`
}
// getAccessTokenViaJwt signs a JWT assertion and exchanges it for an access token. There is NO
// client_secret -- the RS256 signature is the auth. On a Salesforce-side rejection it returns a
// *tokenError carrying the upstream status (e.g. 400 for invalid_grant) so callers can forward a
// 4xx rather than a 5xx; a request that never reached Salesforce yields a transport *tokenError.
func (b *broker) getAccessTokenViaJwt() (accessToken, instanceURL string, err error) {
assertion, serr := b.createAssertion()
if serr != nil {
return "", "", &tokenError{msg: "Failed to sign JWT assertion: " + serr.Error()}
}
form := url.Values{
"grant_type": {"urn:ietf:params:oauth:grant-type:jwt-bearer"},
"assertion": {assertion},
}
resp, perr := b.client.Post(
b.cfg.loginURL+"/services/oauth2/token",
"application/x-www-form-urlencoded",
strings.NewReader(form.Encode()),
)
if perr != nil {
// The request never reached Salesforce -- a transport fault, not a config error.
return "", "", &tokenError{transport: true, msg: "JWT token exchange error: " + perr.Error()}
}
defer resp.Body.Close()
var data tokenResponse
if derr := json.NewDecoder(resp.Body).Decode(&data); derr != nil {
return "", "", &tokenError{StatusCode: resp.StatusCode, msg: "JWT token exchange: invalid response from Salesforce"}
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 || data.AccessToken == "" {
// Salesforce returns {error, error_description}; forward it (no secret/token in the body).
reason := data.ErrorDescription
if reason == "" {
reason = data.Error
}
if reason == "" {
reason = fmt.Sprintf("HTTP %d", resp.StatusCode)
}
return "", "", &tokenError{StatusCode: resp.StatusCode, msg: "JWT token exchange failed: " + reason}
}
return data.AccessToken, data.InstanceURL, nil
}
// mintFrontdoor POSTs the access token to the singleaccess endpoint to mint a FrontDoor URL
// (identical to the PKCE broker).
func (b *broker) mintFrontdoor(instanceURL, accessToken string) (*http.Response, error) {
req, err := http.NewRequest(http.MethodPost, instanceURL+"/services/oauth2/singleaccess", strings.NewReader(""))
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
return b.client.Do(req)
}
// frontdoorResponse is the JSON shape returned to the SPA by handleGetFrontdoorURL.
type frontdoorResponse struct {
FrontdoorURL string `json:"frontdoorUrl,omitempty"`
OrgURL string `json:"orgUrl,omitempty"`
Error string `json:"error,omitempty"`
}
// singleAccessResponse is the subset of /services/oauth2/singleaccess we need.
type singleAccessResponse struct {
FrontdoorURI string `json:"frontdoor_uri"`
}
// handleLogin runs the JWT Bearer exchange entirely server-side, stashes the token, and bounces the
// browser to the SPA. There's NO interactive redirect to Salesforce -- no login screen.
func (b *broker) handleLogin(w http.ResponseWriter, r *http.Request) {
accessToken, instanceURL, err := b.getAccessTokenViaJwt()
if err != nil {
// A Salesforce rejection (invalid_grant etc.) is an expected CONFIG error -- forward its
// 4xx. Reserve 502 for a transport fault (token host unreachable), 500 for anything else.
http.Error(w, err.Error(), statusForTokenError(err))
return
}
sess, serr := b.sessions.getOrCreate(r, w)
if serr != nil {
http.Error(w, "Failed to persist session", http.StatusInternalServerError)
return
}
sess.accessToken = accessToken
sess.instanceUrl = instanceURL
http.Redirect(w, r, b.cfg.appOrigin, http.StatusFound)
}
// handleGetFrontdoorURL exchanges the session's access token for a FrontDoor URL. If there's no
// stored token yet it runs the JWT exchange on the spot (a JWT Bearer client needs no user
// interaction), so the SPA can call this directly. The raw access token never leaves the server.
func (b *broker) handleGetFrontdoorURL(w http.ResponseWriter, r *http.Request) {
sess, serr := b.sessions.getOrCreate(r, w)
if serr != nil {
writeJSON(w, http.StatusInternalServerError, frontdoorResponse{Error: "Failed to persist session"})
return
}
// No stored token? Mint one now instead of bouncing the browser to /login.
if sess.accessToken == "" || sess.instanceUrl == "" {
accessToken, instanceURL, err := b.getAccessTokenViaJwt()
if err != nil {
writeJSON(w, statusForTokenError(err), frontdoorResponse{Error: err.Error()})
return
}
sess.accessToken = accessToken
sess.instanceUrl = instanceURL
}
resp, err := b.mintFrontdoor(sess.instanceUrl, sess.accessToken)
if err != nil {
// Couldn't reach Salesforce at all -- a transport fault, not a server bug.
writeJSON(w, http.StatusBadGateway, frontdoorResponse{Error: "Failed to generate FrontDoor URL"})
return
}
defer resp.Body.Close()
// The access token expires. On 401/403, re-run the JWT exchange once and retry -- no refresh
// token needed, since a JWT Bearer client silently re-mints with no user interaction.
if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
accessToken, instanceURL, rerr := b.getAccessTokenViaJwt()
if rerr != nil {
writeJSON(w, statusForTokenError(rerr), frontdoorResponse{Error: rerr.Error()})
return
}
sess.accessToken = accessToken
sess.instanceUrl = instanceURL
resp.Body.Close()
resp, err = b.mintFrontdoor(sess.instanceUrl, sess.accessToken)
if err != nil {
writeJSON(w, http.StatusBadGateway, frontdoorResponse{Error: "Failed to generate FrontDoor URL"})
return
}
defer resp.Body.Close()
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
// Still failing after the retry. Surface Salesforce's own reason: the body carries
// {"error","error_description"} with no token/secret in it, so it's safe to forward;
// truncate defensively.
raw, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
detail := strings.TrimSpace(string(raw))
if len(detail) > 500 {
detail = detail[:500] + "…"
}
if detail != "" {
detail = ": " + detail
}
writeJSON(w, resp.StatusCode, frontdoorResponse{Error: fmt.Sprintf("Salesforce responded %d%s.", resp.StatusCode, detail)})
return
}
var data singleAccessResponse
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
writeJSON(w, http.StatusInternalServerError, frontdoorResponse{Error: "Invalid response from Salesforce"})
return
}
writeJSON(w, http.StatusOK, frontdoorResponse{FrontdoorURL: data.FrontdoorURI, OrgURL: b.cfg.orgURL})
}
func handleHealth(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, http.StatusOK, map[string]bool{"ok": true})
}
func writeJSON(w http.ResponseWriter, status int, body any) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(body)
}
// withCORS answers preflight requests and adds the CORS headers every response needs so the SPA on
// appOrigin can read a credentialed response. Access-Control-Allow-Origin must name the exact
// origin (never "*") because credentials are involved.
func withCORS(appOrigin string, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", appOrigin)
w.Header().Set("Access-Control-Allow-Credentials", "true")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
w.Header().Set("Vary", "Origin")
if r.Method == http.MethodOptions {
w.WriteHeader(http.StatusNoContent)
return
}
next.ServeHTTP(w, r)
})
}
func main() {
cfg := loadConfig()
privateKey := loadPrivateKey(cfg) // fail fast before we bind a port
b := &broker{
cfg: cfg,
sessions: newSessionStore(),
client: &http.Client{},
privateKey: privateKey,
}
// Method-qualified patterns (Go 1.22+) so each path responds only to GET, matching the golden
// Express reference's app.get(...). A non-GET request to a known path gets a 405 from the mux
// rather than falling through to a handler. There's no /getAccessToken -- the JWT flow has no
// browser callback.
mux := http.NewServeMux()
mux.HandleFunc("GET /login", b.handleLogin)
mux.HandleFunc("GET /getFrontdoorURL", b.handleGetFrontdoorURL)
mux.HandleFunc("GET /health", handleHealth)
addr := ":" + cfg.port
log.Printf("JWT Bearer token broker on http://localhost:%s", cfg.port)
log.Printf(" Authenticate: http://localhost:%s/login", cfg.port)
if err := http.ListenAndServe(addr, withCORS(cfg.appOrigin, mux)); err != nil {
log.Fatal(err)
}
}
```
> **Troubleshooting the exchange:** if `/login` returns a `400` with `invalid_grant`, that's an
> expected config error (the broker forwards Salesforce's status, not a 502) — the usual causes are
> the `sub` user not being pre-authorized on the ECA, an `aud` that doesn't match `LOGIN_URL`, clock
> skew pushing `exp`, or the uploaded public cert not matching `private.key`. A `502` means the token
> host was unreachable (wrong `LOGIN_URL`, network). A `500` at startup that reads `Cannot read/parse
> private key` means the key isn't in `token-broker-jwt/go/` or isn't an unencrypted RSA key. A
> successful `/getFrontdoorURL` returning a `frontdoorUrl` that renders in the SDK is the confirmation.
---
## C# (ASP.NET Core) — JWT Bearer
> **Alternative flow — the [JWT Bearer broker](#jwt-bearer-broker-nodejs) above was verified
> end-to-end on a real org; this is its faithful C# port** (static-reviewed here — no offline
> .NET build toolchain — not separately run on an org). Instead of the interactive
> Authorization Code + PKCE flow, the server signs a JWT with its private key and exchanges it for
> an access token, impersonating `SF_USERNAME` — so there is **no interactive login screen** and
> **no `CLIENT_SECRET`** (the RS256 signature is the auth). This is the server-to-server
> [JWT Bearer flow](#auth-alternative-the-jwt-bearer-flow). Same caveat as the Node version: it's **not part
> of the official SDK guide**, which documents Auth Code + PKCE. Complete the one-time
> [certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time) first (generate
> `private.key` + `public.crt`, upload `public.crt` to the ECA, enable the JWT Bearer flow). Same
> ASP.NET Core 8 minimal API and server-side `HttpContext.Session` as the PKCE port; the one
> difference is a single first-party NuGet package (`System.IdentityModel.Tokens.Jwt`) for RS256
> signing. The private key and raw token stay server-side — the browser only ever sees the FrontDoor URL.
**Run it.** From `token-broker-jwt/dotnet/`. First get the private key into place — `PRIVATE_KEY_PATH`
is resolved **relative to the directory you run from**, not to `Program.cs`, so the key must sit in
`token-broker-jwt/dotnet/` (or set an absolute path). Then load the shared `.env`, confirm it loaded,
and run. The broker listens on **http://localhost:8500**.
```bash
cp /path/to/private.key token-broker-jwt/dotnet/private.key # only public.crt was uploaded to the ECA; keep this local
cd token-broker-jwt/dotnet
ls -la private.key # confirm it's actually here before you start
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
dotnet restore
dotnet run
```
Requires the **.NET 8 SDK**. Env vars are the JWT set from the Node `.env.example` above (`PORT`,
`LOGIN_URL` — also the JWT `aud`, `ORG_URL`, `CLIENT_ID` — the JWT `iss`, `SF_USERNAME` — the JWT
`sub`, `PRIVATE_KEY_PATH` — default `./private.key`, optionally `PRIVATE_KEY` inline PEM, `APP_ORIGIN`,
`SESSION_SECRET`). There is **no login screen**: hitting **http://localhost:8500/login** runs the
exchange server-side and bounces straight to the SPA, which then calls `GET /getFrontdoorURL`.
**`token-broker-jwt/dotnet/broker.csproj`:**
```xml
net8.0
enable
enable
TokenBroker
token-broker-jwt
true
```
**`token-broker-jwt/dotnet/Program.cs`:**
```csharp
// Tableau Next embedding — server-side token broker (C# / ASP.NET Core 8, minimal API).
//
// ALTERNATIVE to the Authorization Code + PKCE broker (see the C# section above). Instead of an
// interactive login, the server signs a JWT with its private key and exchanges it for an access
// token, impersonating SF_USERNAME. It then mints the SAME FrontDoor URL the SDK consumes.
//
// Keep this on the server: it holds the private key and the raw access token; the browser only
// ever sees the short-lived FrontDoor URL. There is NO client secret in this flow — the RS256
// signature authenticates the client.
//
// Port of the Node/Express JWT Bearer reference (token-broker-jwt/server.js). Same contract,
// same env vars — pick whichever runtime fits your stack.
//
// Endpoints:
// GET /login -> runs the JWT Bearer exchange, stores the session, redirects to the SPA
// GET /getFrontdoorURL -> mints { frontdoorUrl, orgUrl } from the stored token (call from the SPA)
// GET /health -> { "ok": true }
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http.Headers;
using System.Security.Claims;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.IdentityModel.Tokens;
// ---- Config + signing key (from environment) ------------------------------------------
// Read directly from the environment (not appsettings.json/IConfiguration) so the env var
// names and defaults line up exactly with the Node reference's `.env.example`. A missing
// required var — or an unreadable/encrypted private key — fails fast, before we bind a port,
// mirroring the Node reference's `process.exit(1)`.
BrokerConfig config = BrokerConfig.LoadOrExit();
RSA privateKey = LoadPrivateKeyOrExit(config);
var builder = WebApplication.CreateBuilder(args);
// Server-side session: ASP.NET Core's session middleware stores the payload (accessToken,
// instanceUrl) in the configured cache — here, an in-memory distributed cache, the .NET analog
// of express-session's default MemoryStore — and puts only an opaque, server-generated session
// id in the cookie. The cookie never carries the token itself.
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession(options =>
{
options.Cookie.Name = ".TokenBroker.Session";
options.Cookie.HttpOnly = true;
options.Cookie.SameSite = SameSiteMode.Lax;
// On localhost, :8700 -> :8500 is the same *site*, so the Lax cookie is still sent
// cross-port even though CORS treats them as different origins.
options.IdleTimeout = TimeSpan.FromMinutes(30);
});
// A single named HttpClient (via IHttpClientFactory) for the two server-to-server POSTs:
// the JWT token exchange and the FrontDoor (single-access) mint.
builder.Services.AddHttpClient("salesforce", client =>
{
client.Timeout = TimeSpan.FromSeconds(15);
});
var app = builder.Build();
// CORS: the SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this
// broker (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these
// headers or the browser drops the response. Allow-Origin must name the exact origin (never
// "*") because credentials are involved. Hand-rolled (rather than the AddCors/UseCors
// abstraction) so every response — CORS or not, preflight or not — carries these exact headers,
// mirroring the Node reference's middleware byte-for-byte.
app.Use(async (context, next) =>
{
context.Response.Headers["Access-Control-Allow-Origin"] = config.AppOrigin;
context.Response.Headers["Access-Control-Allow-Credentials"] = "true";
context.Response.Headers["Access-Control-Allow-Headers"] = "Content-Type";
context.Response.Headers["Vary"] = "Origin";
if (HttpMethods.IsOptions(context.Request.Method))
{
context.Response.StatusCode = StatusCodes.Status204NoContent;
return;
}
await next();
});
app.UseSession();
// 1) Run the JWT Bearer exchange, stash the token server-side, then bounce to the SPA.
// There's NO interactive redirect to Salesforce — the exchange happens entirely server-side.
app.MapGet("/login", async (HttpContext context, IHttpClientFactory httpClientFactory) =>
{
var client = httpClientFactory.CreateClient("salesforce");
try
{
var (accessToken, instanceUrl) = await GetAccessTokenViaJwtAsync(client, config, privateKey);
context.Session.SetString("accessToken", accessToken);
context.Session.SetString("instanceUrl", instanceUrl);
return Results.Redirect(config.AppOrigin); // straight to the SPA — no Salesforce login screen
}
catch (JwtExchangeException ex)
{
// A Salesforce rejection (invalid_grant etc.) carries its own 4xx — forward it. A transport
// fault carries 502. Either way it's ex.UpstreamStatus, never a blanket 500.
return PlainText(ex.UpstreamStatus, ex.Message);
}
});
// 2) Mint a FrontDoor URL from the stored token. The SPA fetches this.
app.MapGet("/getFrontdoorURL", async (HttpContext context, IHttpClientFactory httpClientFactory) =>
{
var client = httpClientFactory.CreateClient("salesforce");
try
{
var accessToken = context.Session.GetString("accessToken");
var instanceUrl = context.Session.GetString("instanceUrl");
// No stored token yet (e.g. the SPA called us before /login): a JWT Bearer client can mint
// one non-interactively, so just run the exchange now — no user login required.
if (string.IsNullOrEmpty(accessToken) || string.IsNullOrEmpty(instanceUrl))
{
(accessToken, instanceUrl) = await GetAccessTokenViaJwtAsync(client, config, privateKey);
context.Session.SetString("accessToken", accessToken);
context.Session.SetString("instanceUrl", instanceUrl);
}
var response = await MintFrontdoorAsync(client, instanceUrl, accessToken);
// The access token expires. On 401/403, re-run the JWT exchange once and retry — there's no
// refresh-token dance here, because a JWT Bearer client re-mints silently with no user
// interaction. Mirrors the Node broker's re-run-on-401/403.
if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized
|| response.StatusCode == System.Net.HttpStatusCode.Forbidden)
{
response.Dispose();
(accessToken, instanceUrl) = await GetAccessTokenViaJwtAsync(client, config, privateKey);
context.Session.SetString("accessToken", accessToken);
context.Session.SetString("instanceUrl", instanceUrl);
response = await MintFrontdoorAsync(client, instanceUrl, accessToken);
}
// Capture status + body, then dispose the (final) response so no HttpResponseMessage leaks on
// any exit path below — the pre-retry response was already disposed in the retry branch above.
var isSuccess = response.IsSuccessStatusCode;
var statusCode = (int)response.StatusCode;
var body = await response.Content.ReadAsStringAsync();
response.Dispose();
if (!isSuccess)
{
// Surface Salesforce's own reason: the body carries {"error","error_description"}. No
// token/secret is in it, so it's safe to forward; truncate defensively.
var trimmed = (body ?? string.Empty).Trim();
var detail = trimmed.Length == 0 ? "" : ": " + (trimmed.Length > 500 ? trimmed[..500] + "…" : trimmed);
return Results.Json(new { error = $"Salesforce responded {statusCode}{detail}." }, statusCode: statusCode);
}
SingleAccessResponse? data;
try
{
data = JsonSerializer.Deserialize(body);
}
catch (JsonException)
{
return Results.Json(new { error = "Invalid response from Salesforce" }, statusCode: StatusCodes.Status500InternalServerError);
}
return Results.Json(new { frontdoorUrl = data?.FrontdoorUri, orgUrl = config.OrgUrl });
}
catch (JwtExchangeException ex)
{
// A Salesforce config rejection carries its own 4xx status; a transport fault on the token
// exchange carries 502. Both live on the exception — forward it, never a blanket 500.
return Results.Json(new { error = ex.Message }, statusCode: ex.UpstreamStatus);
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
// A transport fault on the FrontDoor (singleaccess) POST itself: the instance was
// unreachable / timed out. That's an upstream fault -> 502, not a 500.
return Results.Json(new { error = string.IsNullOrEmpty(ex.Message) ? "Failed to generate FrontDoor URL" : ex.Message }, statusCode: StatusCodes.Status502BadGateway);
}
// Anything else is a genuinely unexpected server fault — let it bubble to a framework 500.
});
app.MapGet("/health", () => Results.Json(new { ok = true }));
app.Urls.Add($"http://localhost:{config.Port}");
app.Lifetime.ApplicationStarted.Register(() =>
{
Console.WriteLine($"JWT Bearer token broker on http://localhost:{config.Port}");
Console.WriteLine($" Authenticate: http://localhost:{config.Port}/login (no login screen — bounces to the SPA)");
});
app.Run();
// ---- Helpers ---------------------------------------------------------------------------
static IResult PlainText(int statusCode, string body) => Results.Text(body, "text/plain", statusCode: statusCode);
// Sign the JWT assertion. Claims: iss=CLIENT_ID, sub=SF_USERNAME (the user to impersonate),
// aud=LOGIN_URL, exp≤5min. Framework-native System.IdentityModel.Tokens.Jwt: SigningCredentials
// with SecurityAlgorithms.RsaSha256 (RS256) over an RsaSecurityKey; the handler sets nbf/exp and
// the RS256 header. We bound exp to 3 minutes — Salesforce rejects a longer window.
static string CreateAssertion(BrokerConfig config, RSA privateKey)
{
var now = DateTime.UtcNow;
var signingCredentials = new SigningCredentials(new RsaSecurityKey(privateKey), SecurityAlgorithms.RsaSha256);
var token = new JwtSecurityToken(
issuer: config.ClientId, // iss
audience: config.LoginUrl, // aud — must equal LOGIN_URL
claims: new[] { new Claim("sub", config.Username) }, // the impersonated user
notBefore: now,
expires: now.AddMinutes(3), // exp
signingCredentials: signingCredentials);
return new JwtSecurityTokenHandler().WriteToken(token);
}
// Exchange the signed JWT for an access token. No client_secret — the signature is the auth.
// On a Salesforce-side rejection (e.g. invalid_grant) throw carrying the upstream HTTP status so
// callers can forward it — a config error is NOT a 5xx. A transport fault becomes a 502.
static async Task<(string AccessToken, string InstanceUrl)> GetAccessTokenViaJwtAsync(
HttpClient client, BrokerConfig config, RSA privateKey)
{
var form = new Dictionary
{
["grant_type"] = "urn:ietf:params:oauth:grant-type:jwt-bearer",
["assertion"] = CreateAssertion(config, privateKey),
// No client_secret in this flow.
};
HttpResponseMessage response;
try
{
response = await client.PostAsync($"{config.LoginUrl}/services/oauth2/token", FormUrlEncoded(form));
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
// The token host was unreachable / timed out — a transport fault, not a config error.
// 502 (an upstream we depend on failed), never a 4xx.
throw new JwtExchangeException($"JWT token exchange transport error: {ex.Message}", StatusCodes.Status502BadGateway);
}
var body = await response.Content.ReadAsStringAsync();
var isSuccess = response.IsSuccessStatusCode;
var statusCode = (int)response.StatusCode;
response.Dispose();
TokenResponse? token;
try
{
// TokenResponse's [JsonPropertyName] attributes map each property to Salesforce's exact
// snake_case key, so no custom JsonSerializerOptions are needed.
token = JsonSerializer.Deserialize(body);
}
catch (JsonException)
{
token = null;
}
if (!isSuccess || string.IsNullOrEmpty(token?.AccessToken))
{
// Salesforce returns {error, error_description}; forward its status (e.g. 400 invalid_grant)
// and reason — an expected config error. No secret/token is in this body.
var reason = token?.ErrorDescription ?? token?.Error ?? $"HTTP {statusCode}";
// A non-error status with no token is an upstream fault, not a config rejection.
var status = statusCode < 400 ? StatusCodes.Status502BadGateway : statusCode;
throw new JwtExchangeException($"JWT token exchange failed: {reason}", status);
}
return (token!.AccessToken!, token.InstanceUrl!);
}
// POST the access token to the singleaccess endpoint to mint a FrontDoor URL (identical to the
// PKCE broker): empty urlencoded body, Bearer auth.
static async Task MintFrontdoorAsync(HttpClient client, string instanceUrl, string accessToken)
{
using var request = new HttpRequestMessage(HttpMethod.Post, $"{instanceUrl}/services/oauth2/singleaccess")
{
Content = FormUrlEncoded(new Dictionary()), // empty body
};
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
return await client.SendAsync(request);
}
// Encodes a form body as application/x-www-form-urlencoded ourselves (rather than
// FormUrlEncodedContent, which appends "; charset=utf-8") so the outbound Content-Type header
// matches the broker contract exactly, and so an empty dictionary produces a genuinely empty body
// for the FrontDoor (single-access) POST.
static HttpContent FormUrlEncoded(IEnumerable> data)
{
var encoded = string.Join("&", data.Select(kv => $"{Uri.EscapeDataString(kv.Key)}={Uri.EscapeDataString(kv.Value)}"));
var content = new StringContent(encoded, Encoding.ASCII);
content.Headers.ContentType = new MediaTypeHeaderValue("application/x-www-form-urlencoded");
return content;
}
// Load the RSA signing key once, from PRIVATE_KEY (inline PEM, \n-escaped) or PRIVATE_KEY_PATH.
// RSA.ImportFromPem handles both PKCS#8 (-----BEGIN PRIVATE KEY-----) and PKCS#1 (-----BEGIN RSA
// PRIVATE KEY-----). The key must be UNENCRYPTED — the `openssl ... -nodes` command in the cert
// setup produces one; an encrypted key needs a passphrase and ImportFromPem will throw.
// Fail fast with a clean message rather than an unhandled exception dump. NOTE: PRIVATE_KEY_PATH
// is resolved relative to the CURRENT WORKING DIRECTORY, not this file — run from the broker's
// directory or set an absolute path.
static RSA LoadPrivateKeyOrExit(BrokerConfig config)
{
string pem;
try
{
pem = !string.IsNullOrEmpty(config.PrivateKeyInline)
? config.PrivateKeyInline.Replace("\\n", "\n")
: File.ReadAllText(config.PrivateKeyPath);
}
catch
{
Console.Error.WriteLine(
$"Cannot read private key at {config.PrivateKeyPath}. Copy private.key into this directory " +
"(or set PRIVATE_KEY_PATH to an absolute path). See the certificate & ECA setup section.");
Environment.Exit(1);
throw; // unreachable; satisfies the compiler's non-null return
}
try
{
var rsa = RSA.Create();
rsa.ImportFromPem(pem); // PKCS#8 or PKCS#1; throws on an ENCRYPTED key
return rsa;
}
catch (Exception ex)
{
Console.Error.WriteLine(
$"Private key at {config.PrivateKeyPath} could not be parsed ({ex.Message}). It must be an " +
"UNENCRYPTED RSA key (the openssl -nodes command in the cert setup produces one).");
Environment.Exit(1);
throw; // unreachable
}
}
// ---- Exceptions -------------------------------------------------------------------------
///
/// Thrown by the JWT token exchange. is the status the caller should
/// forward: Salesforce's own 4xx for a config rejection (invalid_grant etc.), or 502 for a
/// transport fault (token host unreachable) — never a blanket 500.
///
sealed class JwtExchangeException : Exception
{
public int UpstreamStatus { get; }
public JwtExchangeException(string message, int upstreamStatus)
: base(message) => UpstreamStatus = upstreamStatus;
}
// ---- Config -----------------------------------------------------------------------------
///
/// Broker configuration, read straight from the environment. ,
/// , , and are required; a
/// missing one fails startup immediately (mirrors the Node reference's process.exit(1)).
/// There is no client secret in the JWT Bearer flow. (PRIVATE_KEY)
/// wins over (PRIVATE_KEY_PATH, cwd-relative) when both are set.
///
sealed record BrokerConfig(
string Port,
string LoginUrl,
string OrgUrl,
string ClientId,
string Username,
string PrivateKeyPath,
string? PrivateKeyInline,
string AppOrigin,
string SessionSecret)
{
public static BrokerConfig LoadOrExit()
{
var port = GetEnv("PORT", "8500");
var loginUrl = RequireEnv("LOGIN_URL"); // also the JWT `aud`
var orgUrl = RequireEnv("ORG_URL"); // the SDK `orgUrl`
var clientId = RequireEnv("CLIENT_ID"); // the JWT `iss`
var username = RequireEnv("SF_USERNAME"); // the JWT `sub` — the user to impersonate
var privateKeyPath = GetEnv("PRIVATE_KEY_PATH", "./private.key");
var privateKeyInline = Environment.GetEnvironmentVariable("PRIVATE_KEY");
var appOrigin = GetEnv("APP_ORIGIN", "http://localhost:8700");
// Kept for parity with the other brokers' env var surface (SESSION_SECRET is documented
// everywhere). ASP.NET Core's session middleware identifies sessions by an opaque,
// server-generated id backed by the distributed cache rather than a value signed with this
// secret, so it isn't wired into the session mechanism itself.
var sessionSecret = GetEnv("SESSION_SECRET", "change-me-in-production");
return new BrokerConfig(port, loginUrl, orgUrl, clientId, username, privateKeyPath, privateKeyInline, appOrigin, sessionSecret);
}
private static string GetEnv(string name, string fallback)
{
var value = Environment.GetEnvironmentVariable(name);
return string.IsNullOrEmpty(value) ? fallback : value;
}
private static string RequireEnv(string name)
{
var value = Environment.GetEnvironmentVariable(name);
if (string.IsNullOrEmpty(value))
{
Console.Error.WriteLine($"Missing required env var: {name}. See .env.example.");
Environment.Exit(1);
}
return value!;
}
}
// ---- Salesforce response shapes ---------------------------------------------------------
/// Subset of the Salesforce /services/oauth2/token response we need.
sealed record TokenResponse(
[property: JsonPropertyName("access_token")] string? AccessToken,
[property: JsonPropertyName("instance_url")] string? InstanceUrl,
[property: JsonPropertyName("error")] string? Error,
[property: JsonPropertyName("error_description")] string? ErrorDescription);
/// Subset of the Salesforce /services/oauth2/singleaccess response we need.
sealed record SingleAccessResponse(
[property: JsonPropertyName("frontdoor_uri")] string? FrontdoorUri);
```
> **Troubleshooting the exchange:** if `/login` returns a `400` with `invalid_grant`, that's an
> expected config error (the broker forwards Salesforce's status, not a 502) — the usual causes are
> the `SF_USERNAME` (`sub`) user not being pre-authorized on the ECA, a `LOGIN_URL` (`aud`) mismatch,
> clock skew pushing `exp`, or the uploaded public cert not matching `private.key`. A `502` means the
> token host was unreachable (wrong `LOGIN_URL`, network). A `500` is a genuinely unexpected server
> fault. A successful `/getFrontdoorURL` returning a `frontdoorUrl` that renders in the SDK is the
> confirmation.
---
## Ruby (Sinatra) — JWT Bearer
> *JWT Bearer alternative — server-to-server, no login screen.* Signs a JWT with the org's private key and exchanges it for a token (impersonating `SF_USERNAME`), then mints the same FrontDoor URL the SDK consumes — so there is **no interactive redirect to Salesforce**. The Node JWT Bearer broker it ports was verified end-to-end on a real org (JWT → FrontDoor URL → dashboard rendered), and this is its faithful Ruby port (`ruby -c` syntax-clean here, not separately run on an org), but **not part of the official SDK guide**, which documents Auth Code + PKCE. There is **no `CLIENT_SECRET`** and **no `REDIRECT_URI`** in this flow — the RS256 signature is the auth. Same Sinatra `Rack::Session::Pool` server-side sessions and the same session/CORS contract as the PKCE port above. Complete the one-time [certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time) first (generate `private.key` + `public.crt`, upload the cert to the ECA, enable the JWT Bearer flow); this broker signs with the private key, which stays server-side.
**Run it.** From `token-broker-jwt/ruby/`, with the shared `.env` filled in (see the Node section for how `.env` loading and the `source` path work). First get the private key into place — `PRIVATE_KEY_PATH` is resolved **relative to the directory you run from**, not to `app.rb`, so the key must sit in `token-broker-jwt/ruby/` (or use an absolute path). The broker listens on **http://localhost:8500**.
```bash
cp /path/to/private.key token-broker-jwt/ruby/private.key # only public.crt was uploaded to the ECA; keep this local
cd token-broker-jwt/ruby
ls -la private.key # confirm it's actually here before you start
bundle install
set -a; source ../.env; set +a # re-run after ANY .env edit — a running process keeps the OLD values
echo "ORG_URL=$ORG_URL"
ruby app.rb
```
Then open **http://localhost:8500/login** once — it runs the exchange server-side (**no Salesforce login screen**) and bounces straight to your SPA, which calls `GET /getFrontdoorURL`.
> **Requires Ruby 3.x.** macOS's system Ruby (2.6) is too old for the Gemfile's `>= 3.0` floor — install a current Ruby with Homebrew and put it ahead of the system one on `PATH` (the same Homebrew fix shown in the PKCE Ruby section above). Env vars are the same set as the Node JWT `.env.example`, minus `CLIENT_SECRET` and `REDIRECT_URI`; add `SF_USERNAME` (the JWT `sub`) and `PRIVATE_KEY_PATH`.
**`token-broker-jwt/ruby/Gemfile`:**
```ruby
source 'https://rubygems.org'
ruby '>= 3.0' # matches the "Ruby 3.x" prereq; Sinatra 3.2 / Puma 6.6 run on Ruby 3
gem 'sinatra', '~> 3.2'
gem 'puma', '~> 6.6'
gem 'jwt', '~> 2.9' # RS256 signing of the JWT Bearer assertion
```
**`token-broker-jwt/ruby/app.rb`:**
```ruby
# frozen_string_literal: true
# Tableau Next embedding — server-side token broker (Ruby/Sinatra, JWT Bearer flow).
#
# ALTERNATIVE to the Authorization Code + PKCE broker (../ruby/app.rb / server.js). Instead of an
# interactive login, the server signs a JWT with its private key and exchanges it for an access
# token, impersonating SF_USERNAME, then mints the SAME FrontDoor URL the SDK consumes.
#
# Keep this on the server: it holds the private key and the raw access token; the browser only
# ever sees the short-lived FrontDoor URL. There is NO client secret in this flow — the RS256
# signature authenticates the client.
#
# Port of the reference Node JWT broker (see ../server.js) — same env vars, endpoints, and
# session/CORS contract.
#
# Endpoints:
# GET /login → runs the JWT Bearer exchange, stores the session, redirects to the SPA
# GET /getFrontdoorURL → mints { frontdoorUrl, orgUrl } from the stored token (call this from the SPA)
# GET /health → { ok: true }
require 'sinatra'
require 'rack/session/pool'
require 'net/http'
require 'uri'
require 'json'
require 'openssl'
require 'jwt'
# ---- Config (from environment) ---------------------------------------------------------
PORT = (ENV['PORT'] || 8500).to_i
# OAuth login host — this is BOTH where we POST the token request and the JWT `aud`.
# Prod: https://login.salesforce.com | Sandbox: https://test.salesforce.com | or a My Domain host.
LOGIN_URL = ENV['LOGIN_URL']
# Your org's Lightning My Domain host, e.g. https://yourorg.lightning.force.com — the SDK `orgUrl`.
ORG_URL = ENV['ORG_URL']
# ECA Consumer Key — becomes the JWT `iss` claim.
CLIENT_ID = ENV['CLIENT_ID']
# Salesforce username to impersonate — becomes the JWT `sub`. Must be pre-authorized on the ECA
# and hold a Tableau+/Tableau Next license.
SF_USERNAME = ENV['SF_USERNAME']
# Path to the RSA private key whose public cert is uploaded to the ECA. Resolved relative to the
# CURRENT WORKING DIRECTORY, not this file. (Or set PRIVATE_KEY to the PEM contents, \n-escaped.)
PRIVATE_KEY_PATH = ENV['PRIVATE_KEY_PATH'] || './private.key'
# Where to send the browser after login; also the CORS-allowed origin for /getFrontdoorURL.
APP_ORIGIN = ENV['APP_ORIGIN'] || 'http://localhost:8700'
SESSION_SECRET = ENV['SESSION_SECRET'] || 'change-me-in-production'
# There is deliberately NO CLIENT_SECRET and NO REDIRECT_URI in this flow.
{ 'LOGIN_URL' => LOGIN_URL, 'ORG_URL' => ORG_URL, 'CLIENT_ID' => CLIENT_ID, 'SF_USERNAME' => SF_USERNAME }.each do |name, value|
next unless value.nil? || value.empty?
warn "Missing required env var: #{name}. See .env.example."
exit 1
end
# Load the RSA signing key once, from PRIVATE_KEY (inline PEM, \n-escaped) or PRIVATE_KEY_PATH.
# Fail fast with a clean message if it's missing/unreadable — no raw backtrace. The key must be
# UNENCRYPTED (the `openssl ... -nodes` command in the cert setup produces one); an encrypted key
# needs a passphrase and OpenSSL::PKey::RSA.new will reject it here. Note: PRIVATE_KEY_PATH is
# cwd-relative — run this broker from token-broker-jwt/ruby/, or set an absolute path.
RSA_PRIVATE_KEY = begin
pem = ENV['PRIVATE_KEY'] ? ENV['PRIVATE_KEY'].gsub('\n', "\n") : File.read(PRIVATE_KEY_PATH)
OpenSSL::PKey::RSA.new(pem)
rescue StandardError
abort("Cannot read private key at #{PRIVATE_KEY_PATH}. Copy private.key into this directory " \
'or set an absolute path. See the certificate & ECA setup section.')
end
configure do
set :port, PORT
set :bind, '0.0.0.0'
set :session_secret, SESSION_SECRET
# Session state (access_token, instance_url) must stay server-side — the cookie may only carry
# an opaque session id, never the payload. Rack::Session::Pool keeps sessions in an in-memory
# server-side store and puts just a signed id in the cookie. A single-process in-memory Pool is
# fine for this demo; a real deployment should back sessions with Redis or another shared store.
set :session_store, Rack::Session::Pool
set :sessions, httponly: true, same_site: :lax
end
# Raised when Salesforce rejects the exchange (e.g. invalid_grant). Carries the upstream HTTP
# status so callers can forward it — a config error is an expected 4xx, NOT a 5xx.
class JwtExchangeError < StandardError
attr_reader :upstream_status
def initialize(message, upstream_status)
super(message)
@upstream_status = upstream_status
end
end
# ---- CORS ----------------------------------------------------------------------------------
# The SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this broker
# (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these headers or
# the browser drops the response. Allow-Origin must name the exact origin (not '*') when
# credentials are involved. On localhost, :8700 and :8500 are the same *site*, so the
# SameSite=Lax session cookie is still sent — CORS just permits reading the response.
before do
headers 'Access-Control-Allow-Origin' => APP_ORIGIN,
'Access-Control-Allow-Credentials' => 'true',
'Access-Control-Allow-Headers' => 'Content-Type',
'Vary' => 'Origin'
end
options '*' do
204
end
# ---- JWT Bearer helpers --------------------------------------------------------------------
# Sign the JWT assertion. Claims: iss=client_id, sub=user to impersonate, aud=login host,
# exp≤5min (~3m to match the Node broker), plus iat. RS256 with the unencrypted RSA private key.
def create_assertion
now = Time.now.to_i
payload = {
iss: CLIENT_ID,
sub: SF_USERNAME,
aud: LOGIN_URL,
iat: now,
exp: now + 180
}
JWT.encode(payload, RSA_PRIVATE_KEY, 'RS256')
end
# Exchange the signed JWT for an access token. No client_secret — the signature is the auth.
# On a Salesforce-side rejection (e.g. invalid_grant) we raise JwtExchangeError carrying the
# upstream HTTP status so callers can forward it — a config error is NOT a 5xx (see /login).
# (Net::HTTP.post_form enables SSL for https URIs, so LOGIN_URL over https works as-is.)
def get_access_token_via_jwt
body = {
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion: create_assertion
}
response = Net::HTTP.post_form(URI("#{LOGIN_URL}/services/oauth2/token"), body)
data = begin
JSON.parse(response.body)
rescue JSON::ParserError
{}
end
unless response.is_a?(Net::HTTPSuccess) && data['access_token']
# Salesforce returns {error, error_description}; forward it (no secret/token in the body).
reason = data['error_description'] || data['error'] || "HTTP #{response.code}"
raise JwtExchangeError.new("JWT token exchange failed: #{reason}", response.code.to_i)
end
[data['access_token'], data['instance_url']]
end
# POST the access token to the singleaccess endpoint to mint a FrontDoor URL (identical to the
# PKCE broker).
def mint_frontdoor(instance_url, access_token)
uri = URI("#{instance_url}/services/oauth2/singleaccess")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
request = Net::HTTP::Post.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = "Bearer #{access_token}"
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.body = ''
http.request(request)
end
# 1) Run the JWT Bearer exchange, stash the token server-side, then bounce to the SPA. There's no
# interactive redirect to Salesforce — the exchange happens entirely server-side.
get '/login' do
begin
access_token, instance_url = get_access_token_via_jwt
session[:access_token] = access_token
session[:instance_url] = instance_url
redirect APP_ORIGIN
rescue JwtExchangeError => e
# A Salesforce rejection (invalid_grant etc.) is an expected CONFIG error — forward its
# status (a 4xx). Reserve 502 for genuine transport faults (token host unreachable).
content_type :text
halt e.upstream_status, e.message
rescue StandardError => e
content_type :text
halt 502, "JWT authentication failed: #{e.message}"
end
end
# 2) Mint a FrontDoor URL from the stored token. The SPA fetches this. On 401/403 (token expired)
# just re-run the exchange once and retry — a JWT Bearer client can silently re-mint with no user
# interaction, so there's no refresh-token dance here.
get '/getFrontdoorURL' do
content_type :json
begin
if session[:access_token].nil? || session[:instance_url].nil?
access_token, instance_url = get_access_token_via_jwt
session[:access_token] = access_token
session[:instance_url] = instance_url
end
response = mint_frontdoor(session[:instance_url], session[:access_token])
if [401, 403].include?(response.code.to_i)
access_token, instance_url = get_access_token_via_jwt
session[:access_token] = access_token
session[:instance_url] = instance_url
response = mint_frontdoor(instance_url, access_token)
end
unless response.is_a?(Net::HTTPSuccess)
# Surface Salesforce's own reason: the body carries {"error","error_description"}. No
# token/secret is in it, so it's safe to forward; truncate defensively.
body = response.body.to_s.strip
detail = body.empty? ? '' : ": #{body.length > 500 ? "#{body[0, 500]}…" : body}"
halt response.code.to_i, { error: "Salesforce responded #{response.code}#{detail}." }.to_json
end
data = JSON.parse(response.body)
{ frontdoorUrl: data['frontdoor_uri'], orgUrl: ORG_URL }.to_json
rescue JwtExchangeError => e
# Same as /login: a Salesforce config rejection carries the upstream 4xx status; forward it.
halt e.upstream_status, { error: e.message }.to_json
rescue StandardError => e
# A transport fault (token/instance host unreachable, timeout) is a 502 — an upstream we
# depend on failed, not a bug in this broker. Matches the other ports' 502 for this case.
halt 502, { error: e.message || 'Failed to generate FrontDoor URL' }.to_json
end
end
get '/health' do
content_type :json
{ ok: true }.to_json
end
```
---
## PHP (built-in server) — JWT Bearer
> *The JWT Bearer alternative — server-to-server, no login screen.* Like the Node JWT broker, this
> signs an RS256 assertion with the org's private key and exchanges it for an access token,
> impersonating a fixed user; the browser only ever sees the short-lived FrontDoor URL. The Node JWT
> broker it mirrors was **verified end-to-end on a real org** (JWT → FrontDoor URL → dashboard
> rendered); this is its faithful PHP port (`php -l` syntax-clean here, not separately run on an
> org), but **not part of the official SDK guide**, which documents Auth Code + PKCE. Complete the one-time
> [certificate & ECA setup](#certificate--eca-setup-for-jwt-bearer-one-time) first (generate
> `private.key` + `public.crt`, upload the cert to the ECA, enable the JWT Bearer flow).
> Dependency-free like the PKCE PHP broker — a small `createAssertion()` builds the JWT and signs it
> with the built-in **OpenSSL** extension (`openssl_sign(..., OPENSSL_ALGO_SHA256)`), so there is no
> Composer and no `firebase/php-jwt`. There is **no `CLIENT_SECRET`** and **no `REDIRECT_URI`** in
> this flow — the RS256 signature is the authentication.
**Run it.** From `token-broker-jwt/php/`. First get the private key into place — `PRIVATE_KEY_PATH`
is resolved **relative to the directory you run from**, not to `broker.php`, so the key must sit in
`token-broker-jwt/php/` (or set an absolute path). Then load the shared `.env`, confirm it loaded,
and start PHP's built-in server. The broker listens on **http://localhost:8500**.
```bash
cp /path/to/private.key token-broker-jwt/php/private.key # only public.crt was uploaded to the ECA; keep this local
cd token-broker-jwt/php
ls -la private.key # PRIVATE_KEY_PATH is cwd-relative — confirm the key is actually here
set -a; source ../.env; set +a # re-run after ANY .env edit, then restart the server
echo "ORG_URL=$ORG_URL"
php -S localhost:8500 broker.php
```
Then open **http://localhost:8500/login** once. There is **no Salesforce login screen** — the
exchange runs entirely server-side and `/login` bounces straight to your SPA, which calls
`GET /getFrontdoorURL`. Requires **PHP 8.x** with the **cURL and OpenSSL** extensions (both ship
enabled in a standard build). Env vars are the same set as the Node JWT `.env.example` above, minus
`CLIENT_SECRET` and `REDIRECT_URI`, which this flow doesn't use.
**`token-broker-jwt/php/broker.php`:**
```php
runs the JWT Bearer exchange server-side, stores the session, redirects to the SPA (no login screen)
* GET /getFrontdoorURL -> mints { frontdoorUrl, orgUrl } from the stored token (call this from the SPA)
* GET /health -> { ok: true }
*/
declare(strict_types=1);
// -----------------------------------------------------------------------------------------
// Config (from environment)
// -----------------------------------------------------------------------------------------
/** Read an env var, falling back to $default when unset or empty. */
function env(string $name, ?string $default = null): ?string
{
$value = getenv($name);
return $value === false || $value === '' ? $default : $value;
}
/** Fail fast (matching the Node reference's process.exit(1) at startup) when config is missing. */
function requireEnv(array $required): void
{
foreach ($required as $name => $value) {
if (!$value) {
error_log("Missing required env var: {$name}. See .env.example.");
http_response_code(500);
header('Content-Type: text/plain; charset=utf-8');
echo "Server misconfigured: missing required env var {$name}. See .env.example.";
exit;
}
}
}
// The built-in server's listen port comes from the `php -S localhost:PORT` flag, not this var;
// read anyway so the env surface stays identical to the Node broker.
$port = env('PORT', '8500');
// OAuth login host. This is BOTH where we POST the token request AND the JWT `aud` claim.
$loginUrl = env('LOGIN_URL');
// Lightning My Domain host, e.g. https://yourorg.lightning.force.com — the SDK `orgUrl`.
$orgUrl = env('ORG_URL');
// ECA Consumer Key — becomes the JWT `iss` claim.
$clientId = env('CLIENT_ID');
// Salesforce username to impersonate — becomes the JWT `sub` claim. Must be pre-authorized on the ECA.
$sfUsername = env('SF_USERNAME');
// Optional: the private key PEM inline (\n-escaped). Takes precedence over PRIVATE_KEY_PATH.
$privateKeyInline = env('PRIVATE_KEY');
// Path to the unencrypted RSA private key whose cert is on the ECA. cwd-relative — see loadPrivateKey().
$privateKeyPath = env('PRIVATE_KEY_PATH', './private.key');
// SPA origin: where the browser is sent after /login, and the sole allowed CORS origin.
$appOrigin = env('APP_ORIGIN', 'http://localhost:8700');
// Read for env parity with the other brokers; PHP's native session module keys sessions by an
// unguessable server-side ID rather than a signed cookie, so this isn't consumed directly.
$sessionSecret = env('SESSION_SECRET', 'change-me-in-production');
requireEnv(['LOGIN_URL' => $loginUrl, 'ORG_URL' => $orgUrl, 'CLIENT_ID' => $clientId, 'SF_USERNAME' => $sfUsername]);
// -----------------------------------------------------------------------------------------
// Private key (fail fast)
//
// Load the signing key ONCE, from PRIVATE_KEY (inline PEM) or PRIVATE_KEY_PATH. Fail fast with a
// clean message — otherwise openssl_sign() later dies with a cryptic warning. PRIVATE_KEY_PATH is
// resolved relative to the CURRENT WORKING DIRECTORY, not this file — run the broker from its own
// directory or set an absolute path. The key must be UNENCRYPTED (the `openssl ... -nodes` command
// in the cert setup produces one); an encrypted key needs a passphrase this broker doesn't supply.
// -----------------------------------------------------------------------------------------
function loadPrivateKey(?string $inlinePem, string $path): OpenSSLAsymmetricKey
{
if ($inlinePem !== null && $inlinePem !== '') {
$pem = str_replace('\n', "\n", $inlinePem);
} else {
$pem = @file_get_contents($path); // @ so a missing file is a clean message, not a raw warning
if ($pem === false) {
error_log("Cannot read private key at {$path}.");
http_response_code(500);
header('Content-Type: text/plain; charset=utf-8');
echo "Cannot read private key at {$path}. Copy private.key into this directory "
. "(or set PRIVATE_KEY_PATH to an absolute path). See the certificate & ECA setup section.";
exit;
}
}
$key = openssl_pkey_get_private($pem);
if ($key === false) {
error_log('Private key is not a valid unencrypted PEM.');
http_response_code(500);
header('Content-Type: text/plain; charset=utf-8');
echo 'Private key is not a valid unencrypted PEM. It must be an UNENCRYPTED RSA key '
. '(generate it with the `openssl ... -nodes` command from the certificate & ECA setup).';
exit;
}
return $key;
}
$privateKey = loadPrivateKey($privateKeyInline, $privateKeyPath);
// -----------------------------------------------------------------------------------------
// JWT helpers
// -----------------------------------------------------------------------------------------
function base64UrlEncode(string $data): string
{
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
/**
* Build and RS256-sign the JWT assertion. Claims: iss=client_id, sub=user to impersonate,
* aud=login host, exp≤5min (Salesforce caps JWT Bearer assertions at 5 minutes), plus iat.
* `openssl_sign(..., OPENSSL_ALGO_SHA256)` over an RSA key IS RS256 — no library needed.
*/
function createAssertion(OpenSSLAsymmetricKey $key, string $clientId, string $sub, string $aud): string
{
$now = time();
$header = ['alg' => 'RS256', 'typ' => 'JWT'];
$claims = [
'iss' => $clientId,
'sub' => $sub,
'aud' => $aud,
'iat' => $now,
'exp' => $now + 180, // 3 min — comfortably under Salesforce's 5-minute ceiling
];
$signingInput = base64UrlEncode(json_encode($header, JSON_UNESCAPED_SLASHES))
. '.' . base64UrlEncode(json_encode($claims, JSON_UNESCAPED_SLASHES));
if (!openssl_sign($signingInput, $signature, $key, OPENSSL_ALGO_SHA256)) {
// Unexpected: the key was validated at startup. A genuine server fault -> 500 (see handlers).
throw new RuntimeException('Failed to sign the JWT assertion with the private key.');
}
return $signingInput . '.' . base64UrlEncode($signature);
}
// -----------------------------------------------------------------------------------------
// Errors
//
// Two distinct types so the handlers can map each to the RIGHT status: a Salesforce rejection is
// an expected 4xx config error, a dead token host is a 502, and anything else is a 500.
// -----------------------------------------------------------------------------------------
/** Salesforce rejected the assertion (e.g. invalid_grant). ->getCode() carries the upstream 4xx. */
final class JwtExchangeException extends RuntimeException {}
/** Transport-level failure (DNS, connect, timeout). Maps to 502. */
final class TransportException extends RuntimeException {}
// -----------------------------------------------------------------------------------------
// HTTP client helper (cURL)
// -----------------------------------------------------------------------------------------
/**
* POST application/x-www-form-urlencoded to $url and return [statusCode, body].
* $fields may be an empty array to send an empty body (used by mintFrontdoor).
*
* @throws TransportException on a transport-level failure (DNS, connect, timeout, ...).
*/
function httpPostForm(string $url, array $fields, array $extraHeaders = []): array
{
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($fields),
CURLOPT_HTTPHEADER => array_merge(
['Content-Type: application/x-www-form-urlencoded'],
$extraHeaders,
),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
if ($body === false) {
$error = curl_error($ch);
curl_close($ch);
throw new TransportException($error ?: 'cURL request failed');
}
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return [$status, (string) $body];
}
// -----------------------------------------------------------------------------------------
// Salesforce calls
// -----------------------------------------------------------------------------------------
/**
* Exchange the signed JWT for an access token. No client_secret — the RS256 signature is the auth.
*
* @return array{0: string, 1: ?string} [$accessToken, $instanceUrl]
* @throws JwtExchangeException on a Salesforce rejection, carrying the upstream HTTP status.
* @throws TransportException if the token host is unreachable.
*/
function getAccessTokenViaJwt(string $loginUrl, OpenSSLAsymmetricKey $key, string $clientId, string $sub): array
{
$assertion = createAssertion($key, $clientId, $sub, $loginUrl); // aud == LOGIN_URL
[$status, $body] = httpPostForm("{$loginUrl}/services/oauth2/token", [
'grant_type' => 'urn:ietf:params:oauth:grant-type:jwt-bearer',
'assertion' => $assertion,
]);
$data = json_decode($body, true) ?: [];
if ($status < 200 || $status >= 300 || empty($data['access_token'])) {
// Salesforce returns {error, error_description}; forward it (no secret/token in the body).
// Carry the upstream status (e.g. 400 invalid_grant) so callers forward a 4xx, not a 5xx.
$reason = $data['error_description'] ?? $data['error'] ?? "HTTP {$status}";
throw new JwtExchangeException("JWT token exchange failed: {$reason}", $status ?: 400);
}
return [$data['access_token'], $data['instance_url'] ?? null];
}
/** POST the access token to the singleaccess endpoint to mint a FrontDoor URL. */
function mintFrontdoor(string $instanceUrl, string $accessToken): array
{
return httpPostForm("{$instanceUrl}/services/oauth2/singleaccess", [], [
'Accept: application/json',
"Authorization: Bearer {$accessToken}",
]);
}
// -----------------------------------------------------------------------------------------
// Response helpers
// -----------------------------------------------------------------------------------------
function sendJson(int $status, array $payload): void
{
http_response_code($status);
header('Content-Type: application/json');
echo json_encode($payload);
}
function sendText(int $status, string $message): void
{
http_response_code($status);
header('Content-Type: text/plain; charset=utf-8');
echo $message;
}
// -----------------------------------------------------------------------------------------
// CORS
//
// The SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this broker
// (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these headers
// or the browser drops the response. Allow-Origin must name the exact origin (not '*') when
// credentials are involved. On localhost, :8700 and :8500 are the same *site*, so the
// SameSite=Lax session cookie is still sent — CORS just permits reading the response.
// -----------------------------------------------------------------------------------------
header('Access-Control-Allow-Origin: ' . $appOrigin);
header('Access-Control-Allow-Credentials: true');
header('Access-Control-Allow-Headers: Content-Type');
header('Vary: Origin');
$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';
if ($method === 'OPTIONS') {
http_response_code(204);
exit;
}
// -----------------------------------------------------------------------------------------
// Session
//
// Server-side session holding accessToken and instanceUrl. HttpOnly + SameSite=Lax so the token
// never touches JS and the cookie still rides along on the /login -> SPA redirect.
// -----------------------------------------------------------------------------------------
session_set_cookie_params([
'lifetime' => 0,
'path' => '/',
'secure' => false, // set true once the broker is served over HTTPS
'httponly' => true,
'samesite' => 'Lax',
]);
session_start();
// -----------------------------------------------------------------------------------------
// Route handlers
// -----------------------------------------------------------------------------------------
/**
* 1) Run the JWT Bearer exchange entirely server-side, stash the token, then bounce to the SPA.
* There is NO interactive redirect to Salesforce — no login screen appears.
*/
function handleLogin(
string $loginUrl,
OpenSSLAsymmetricKey $key,
string $clientId,
string $sub,
string $appOrigin,
): void {
try {
[$accessToken, $instanceUrl] = getAccessTokenViaJwt($loginUrl, $key, $clientId, $sub);
} catch (JwtExchangeException $e) {
// Salesforce rejected the assertion (invalid_grant etc.) — an expected CONFIG error;
// forward its 4xx status, NOT a 5xx.
sendText($e->getCode() ?: 400, $e->getMessage());
return;
} catch (TransportException $e) {
// Couldn't reach the token host (wrong LOGIN_URL, network) — a transport fault.
sendText(502, "JWT authentication failed: {$e->getMessage()}");
return;
} catch (Throwable $e) {
// Anything else is a genuine, unexpected server fault.
sendText(500, "JWT authentication failed: {$e->getMessage()}");
return;
}
$_SESSION['accessToken'] = $accessToken;
$_SESSION['instanceUrl'] = $instanceUrl;
header("Location: {$appOrigin}"); // straight back to the SPA; it will call /getFrontdoorURL
}
/**
* 2) Mint a FrontDoor URL from the stored token — running the exchange first if the session is
* empty. The SPA fetches this. A JWT Bearer client can silently re-mint with no user interaction,
* so on 401/403 we just re-run the exchange once and retry (no refresh-token dance).
*/
function handleGetFrontdoorUrl(
string $orgUrl,
string $loginUrl,
OpenSSLAsymmetricKey $key,
string $clientId,
string $sub,
): void {
try {
if (empty($_SESSION['accessToken']) || empty($_SESSION['instanceUrl'])) {
[$_SESSION['accessToken'], $_SESSION['instanceUrl']] = getAccessTokenViaJwt($loginUrl, $key, $clientId, $sub);
}
[$status, $body] = mintFrontdoor($_SESSION['instanceUrl'], $_SESSION['accessToken']);
if ($status === 401 || $status === 403) {
[$_SESSION['accessToken'], $_SESSION['instanceUrl']] = getAccessTokenViaJwt($loginUrl, $key, $clientId, $sub);
[$status, $body] = mintFrontdoor($_SESSION['instanceUrl'], $_SESSION['accessToken']);
}
} catch (JwtExchangeException $e) {
// Salesforce config rejection during the (re-)exchange — forward its 4xx.
sendJson($e->getCode() ?: 400, ['error' => $e->getMessage()]);
return;
} catch (TransportException $e) {
// Token host unreachable — transport fault.
sendJson(502, ['error' => "Token host unreachable: {$e->getMessage()}"]);
return;
} catch (Throwable $e) {
// Unexpected server fault.
sendJson(500, ['error' => $e->getMessage() ?: 'Failed to generate FrontDoor URL']);
return;
}
if ($status < 200 || $status >= 300) {
// singleaccess itself failed (not the token exchange). Surface Salesforce's own reason:
// the body carries {"error","error_description"} and holds no token/secret, so forward it,
// truncated defensively.
$trimmed = trim((string) $body);
$detail = $trimmed === '' ? '' : ': ' . (strlen($trimmed) > 500 ? substr($trimmed, 0, 500) . '…' : $trimmed);
sendJson($status, ['error' => "Salesforce responded {$status}{$detail}."]);
return;
}
$data = json_decode($body, true) ?: [];
sendJson(200, ['frontdoorUrl' => $data['frontdoor_uri'] ?? null, 'orgUrl' => $orgUrl]);
}
function handleHealth(): void
{
sendJson(200, ['ok' => true]);
}
// -----------------------------------------------------------------------------------------
// Router
// -----------------------------------------------------------------------------------------
$path = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/';
if ($method === 'GET' && $path === '/login') {
handleLogin($loginUrl, $privateKey, $clientId, $sfUsername, $appOrigin);
} elseif ($method === 'GET' && $path === '/getFrontdoorURL') {
handleGetFrontdoorUrl($orgUrl, $loginUrl, $privateKey, $clientId, $sfUsername);
} elseif ($method === 'GET' && $path === '/health') {
handleHealth();
} else {
sendText(404, 'Not Found');
}
```
> **Troubleshooting the exchange:** if `/login` returns a `400` with `invalid_grant`, that's an
> expected config error (the broker forwards Salesforce's status, not a 502) — the usual causes are
> the `sub` user not being pre-authorized on the ECA, an `aud` that doesn't match `LOGIN_URL`, clock
> skew pushing `exp`, or the uploaded public cert not matching `private.key`. A `502` means the token
> host was unreachable (wrong `LOGIN_URL`, network); a `500` is a genuine server fault (e.g. the
> private key couldn't sign). A successful `/getFrontdoorURL` returning a `frontdoorUrl` that renders
> in the SDK is the confirmation.
---
## Java (Spring Boot)
> *Reviewed against the contract, not executed here.* A Spring Boot app: an env-bound
> `@ConfigurationProperties`, a `@RestController` with the four endpoints, a `OncePerRequestFilter`
> for CORS, and `java.net.http.HttpClient` for the server-to-server POSTs. Session state lives in the
> servlet `HttpSession` (server-side; the cookie is only the opaque `JSESSIONID`).
**Run it.** From `token-broker/java/`, load the shared `.env` (see the Node section for how
`.env` loading and the `source` path work), confirm it loaded, then start. The broker
listens on **http://localhost:8500**.
```bash
cd token-broker/java
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
mvn spring-boot:run
```
Requires **JDK 21 (LTS)** and **Maven 3.9+**. Env vars are the same set as the Node
`.env.example` above. Pin JDK **21**, not "21+": the pinned Spring Boot 3.3.4 does **not**
support the newest JDKs (e.g. 26) — running Maven under one fails to build with obscure
compiler/bytecode errors. Install Zulu 21 (or any LTS 21 build) and point Maven at it.
> **Corporate / proxied Maven environments (Salesforce-internal especially): two-layer TLS wall.**
> On a first `mvn` behind the corporate Nexus proxy you'll likely hit
> `PKIX path building failed … unable to find valid certification path`. Two distinct layers,
> in order:
>
> 1. **Truststore.** The proxy chains to the *Salesforce Internal Root CA*, which is in the macOS
> System keychain but **not** in the JDK's own `cacerts`. Export the cert from Keychain Access
> and import it into the JDK you build with:
> ```bash
> keytool -import -trustcacerts -alias sfdc-internal-root \
> -file sfdc-internal-root.pem \
> -keystore "$(/usr/libexec/java_home -v 21)/lib/security/cacerts" -storepass changeit
> ```
> 2. **Which JDK Maven actually runs.** After importing, it can *still* fail if Maven is running
> under a **different** JDK than the one you imported into (a common trap: a Homebrew OpenJDK on
> `PATH` shadowing your Zulu 21). Force Maven onto the JDK that has the cert:
> ```bash
> export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
> mvn -version # confirm "Java version: 21" and the Zulu/LTS path before retrying
> ```
>
> On a clean, non-proxied setup none of this applies — it's specific to corporate TLS interception.
**`token-broker/java/pom.xml`:**
```xml
4.0.0
org.springframework.boot
spring-boot-starter-parent
3.3.4
com.example
token-broker
1.0.0
jar
token-broker
Salesforce OAuth token broker for the Analytics Embedding SDK
21
21
21
UTF-8
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-test
test
token-broker
org.springframework.boot
spring-boot-maven-plugin
```
**`token-broker/java/src/main/resources/application.properties`:**
```properties
# Port the broker listens on. Same env var / default as the Node reference (PORT=8500).
server.port=${PORT:8500}
# Keep Spring's banner/log noise down; the broker never logs secrets or tokens.
logging.level.root=INFO
logging.level.com.example.broker=INFO
# Session cookie: HttpOnly + SameSite=Lax, matching the Node reference.
# (:8700 -> :8500 on localhost is same-site, so the Lax cookie is still sent cross-port.)
server.servlet.session.cookie.http-only=true
server.servlet.session.cookie.same-site=lax
```
**`token-broker/java/src/main/java/com/example/broker/BrokerApplication.java`:**
```java
package com.example.broker;
import com.example.broker.config.BrokerProperties;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* Bootstraps the Salesforce OAuth token broker.
*
* Runs the Authorization Code + PKCE flow and mints a FrontDoor URL that the Analytics
* Embedding SDK uses as {@code authCredential}. The raw access token — and the client secret,
* if one is configured — never leave this process; the browser only ever receives the
* short-lived FrontDoor URL.
*
*
See {@link com.example.broker.api.TokenBrokerController} for the four endpoints this
* exposes, and {@link BrokerProperties} for how configuration is read (and validated) from the
* environment.
*/
@SpringBootApplication
public class BrokerApplication {
public static void main(String[] args) {
SpringApplication.run(BrokerApplication.class, args);
}
}
```
**`token-broker/java/src/main/java/com/example/broker/config/BrokerProperties.java`:**
```java
package com.example.broker.config;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.stereotype.Component;
/**
* Broker configuration, read straight from the environment (not Spring {@code @Value}/
* {@code application.properties}) so the env var names and defaults line up exactly with the
* Node reference implementation.
*
*
{@code LOGIN_URL}, {@code ORG_URL} and {@code CLIENT_ID} are required; a missing one fails
* application startup immediately (mirrors the Node reference's {@code process.exit(1)}).
* {@code CLIENT_SECRET} is optional: when set, it is appended to the token exchange request
* (confidential client) and is never returned to the browser.
*/
@Component
public class BrokerProperties {
private final String port;
private final String loginUrl;
private final String orgUrl;
private final String clientId;
private final String clientSecret;
private final String redirectUri;
private final String appOrigin;
private final String sessionSecret;
public BrokerProperties() {
this.port = env("PORT", "8500");
this.loginUrl = requireEnv("LOGIN_URL");
this.orgUrl = requireEnv("ORG_URL");
this.clientId = requireEnv("CLIENT_ID");
this.clientSecret = env("CLIENT_SECRET", null);
this.redirectUri = env("REDIRECT_URI", "http://localhost:" + this.port + "/getAccessToken");
this.appOrigin = env("APP_ORIGIN", "http://localhost:8700");
this.sessionSecret = env("SESSION_SECRET", "change-me-in-production");
}
private static String env(String name, String defaultValue) {
String value = System.getenv(name);
return (value == null || value.isBlank()) ? defaultValue : value;
}
/** Fails fast (mirrors the Node reference's {@code process.exit(1)} on a missing var). */
private static String requireEnv(String name) {
String value = System.getenv(name);
if (value == null || value.isBlank()) {
throw new IllegalStateException("Missing required env var: " + name + ". See .env.example.");
}
return value;
}
public String getPort() {
return port;
}
public String getLoginUrl() {
return loginUrl;
}
public String getOrgUrl() {
return orgUrl;
}
public String getClientId() {
return clientId;
}
/** May be {@code null} for a PKCE-only (public) client — never exposed outside this class. */
public String getClientSecret() {
return clientSecret;
}
public boolean hasClientSecret() {
return clientSecret != null && !clientSecret.isBlank();
}
public String getRedirectUri() {
return redirectUri;
}
public String getAppOrigin() {
return appOrigin;
}
/**
* Read for parity with the Node reference's env var contract. Unlike Express's signed-cookie
* session store, the embedded Tomcat session used here (cookie settings in {@code
* application.properties}) identifies sessions by an opaque, server-generated ID rather than a
* value derived from this secret, so it's not wired into the session mechanism itself. Swap in
* a signed/distributed session store (e.g. Spring Session) for production and use this value
* there.
*/
public String getSessionSecret() {
return sessionSecret;
}
/** Non-secret snapshot, safe to log at startup. */
public Map describeNonSecret() {
Map summary = new LinkedHashMap<>();
summary.put("port", port);
summary.put("loginUrl", loginUrl);
summary.put("orgUrl", orgUrl);
summary.put("redirectUri", redirectUri);
summary.put("appOrigin", appOrigin);
summary.put("clientSecretConfigured", String.valueOf(hasClientSecret()));
return summary;
}
}
```
**`token-broker/java/src/main/java/com/example/broker/config/CorsFilter.java`:**
```java
package com.example.broker.config;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
/**
* CORS for the SPA on {@code APP_ORIGIN}: a different origin than this broker, so its
* credentialed {@code fetch('/getFrontdoorURL')} needs these headers or the browser drops the
* response. {@code Access-Control-Allow-Origin} must name the exact origin (never {@code *})
* because credentials are involved; on localhost, {@code :8700 -> :8500} is the same *site*, so
* the {@code SameSite=Lax} session cookie is still sent regardless — CORS just lets the browser
* read the response.
*
* Runs ahead of every other filter ({@link Ordered#HIGHEST_PRECEDENCE}) so every response —
* including the OPTIONS preflight, which never reaches a controller — carries these headers.
* Mirrors the Node reference's hand-rolled middleware; for many origins or production, reach for
* {@code WebMvcConfigurer#addCorsMappings} instead.
*/
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class CorsFilter extends OncePerRequestFilter {
private final BrokerProperties properties;
public CorsFilter(BrokerProperties properties) {
this.properties = properties;
}
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN, properties.getAppOrigin());
response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_CREDENTIALS, "true");
response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_HEADERS, "Content-Type");
response.setHeader(HttpHeaders.VARY, "Origin");
if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
response.setStatus(HttpStatus.NO_CONTENT.value());
return;
}
chain.doFilter(request, response);
}
}
```
**`token-broker/java/src/main/java/com/example/broker/config/StartupLogger.java`:**
```java
package com.example.broker.config;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
/**
* Logs the broker's URL and a non-secret config summary once the embedded server is actually
* listening — mirrors the Node reference's post-{@code app.listen} console output.
*/
@Component
public class StartupLogger {
private static final Logger log = LoggerFactory.getLogger(StartupLogger.class);
private final BrokerProperties properties;
public StartupLogger(BrokerProperties properties) {
this.properties = properties;
}
@EventListener(ApplicationReadyEvent.class)
void logStartup() {
log.info("Token broker on http://localhost:{}", properties.getPort());
log.info(" Log in: http://localhost:{}/login", properties.getPort());
log.info("Config: {}", properties.describeNonSecret());
}
}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/Pkce.java`:**
```java
package com.example.broker.oauth;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Base64;
/**
* PKCE (RFC 7636) helper: a high-entropy random {@code code_verifier} plus its S256
* {@code code_challenge}. Matches the Node reference exactly — 64 random bytes, base64url with
* no padding, SHA-256 for the challenge (never {@code plain}).
*/
public final class Pkce {
private static final SecureRandom RANDOM = new SecureRandom();
private static final Base64.Encoder BASE64_URL_NO_PAD = Base64.getUrlEncoder().withoutPadding();
private Pkce() {}
/** One generated verifier/challenge pair; the verifier is what gets stashed in the session. */
public record Pair(String verifier, String challenge) {}
public static Pair generate() {
byte[] verifierBytes = new byte[64];
RANDOM.nextBytes(verifierBytes);
String verifier = base64Url(verifierBytes);
String challenge = base64Url(sha256(verifier.getBytes(java.nio.charset.StandardCharsets.US_ASCII)));
return new Pair(verifier, challenge);
}
/**
* A high-entropy random OAuth {@code state} value (32 bytes, base64url) for CSRF / login-mix-up
* protection — stored in the session at {@code /login} and verified on the callback.
*/
public static String generateState() {
byte[] stateBytes = new byte[32];
RANDOM.nextBytes(stateBytes);
return base64Url(stateBytes);
}
private static byte[] sha256(byte[] input) {
try {
return MessageDigest.getInstance("SHA-256").digest(input);
} catch (NoSuchAlgorithmException e) {
// SHA-256 is guaranteed present on every standard JVM; this can't actually happen.
throw new IllegalStateException("SHA-256 not available", e);
}
}
private static String base64Url(byte[] bytes) {
return BASE64_URL_NO_PAD.encodeToString(bytes);
}
}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/FormEncoding.java`:**
```java
package com.example.broker.oauth;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.StringJoiner;
/**
* Encodes a map of parameters as {@code application/x-www-form-urlencoded}. Shared by the
* outbound token-exchange / single-access POST bodies ({@link SalesforceOAuthClient}) and the
* {@code /login} authorize-URL query string, so the encoding rules live in exactly one place.
*/
public final class FormEncoding {
private FormEncoding() {}
public static String encode(Map params) {
StringJoiner joiner = new StringJoiner("&");
params.forEach((key, value) -> joiner.add(urlEncode(key) + "=" + urlEncode(value)));
return joiner.toString();
}
private static String urlEncode(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8);
}
}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/TokenResponse.java`:**
```java
package com.example.broker.oauth;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Subset of the Salesforce {@code /services/oauth2/token} response we care about. Unknown
* fields (e.g. {@code id}, {@code signature}, {@code issued_at}) are ignored.
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public record TokenResponse(
@JsonProperty("access_token") String accessToken,
@JsonProperty("instance_url") String instanceUrl,
@JsonProperty("refresh_token") String refreshToken,
@JsonProperty("error") String error,
@JsonProperty("error_description") String errorDescription) {}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/SingleAccessResponse.java`:**
```java
package com.example.broker.oauth;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/** Subset of the Salesforce {@code /services/oauth2/singleaccess} response we care about. */
@JsonIgnoreProperties(ignoreUnknown = true)
public record SingleAccessResponse(@JsonProperty("frontdoor_uri") String frontdoorUri) {}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/UpstreamException.java`:**
```java
package com.example.broker.oauth;
/**
* Raised when Salesforce responds to the token exchange or the FrontDoor (single-access)
* request with a non-2xx status, or the call itself fails (network error, timeout). Carries
* the HTTP status to propagate back to our own caller, per the broker contract.
*/
public class UpstreamException extends RuntimeException {
private final int statusCode;
public UpstreamException(int statusCode, String message) {
super(message);
this.statusCode = statusCode;
}
public UpstreamException(int statusCode, String message, Throwable cause) {
super(message, cause);
this.statusCode = statusCode;
}
public int getStatusCode() {
return statusCode;
}
}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/BrokerSession.java`:**
```java
package com.example.broker.oauth;
import jakarta.servlet.http.HttpSession;
/**
* Thin, typed wrapper over {@link HttpSession} for the values this broker stashes there: the
* PKCE verifier (between {@code /login} and {@code /getAccessToken}), and the access token +
* instance URL + refresh token (between {@code /getAccessToken} and {@code /getFrontdoorURL}).
* Keeps the raw attribute-name strings in one place instead of scattered across the controller.
*/
public final class BrokerSession {
private static final String CODE_VERIFIER = "codeVerifier";
private static final String OAUTH_STATE = "oauthState";
private static final String ACCESS_TOKEN = "accessToken";
private static final String INSTANCE_URL = "instanceUrl";
private static final String REFRESH_TOKEN = "refreshToken";
private final HttpSession session;
public BrokerSession(HttpSession session) {
this.session = session;
}
public void storeCodeVerifier(String verifier) {
session.setAttribute(CODE_VERIFIER, verifier);
}
public String getCodeVerifier() {
return (String) session.getAttribute(CODE_VERIFIER);
}
/** Stores the random per-session OAuth {@code state} (CSRF token) set at {@code /login}. */
public void storeOAuthState(String state) {
session.setAttribute(OAUTH_STATE, state);
}
public String getOAuthState() {
return (String) session.getAttribute(OAUTH_STATE);
}
/** Clears the OAuth state after the callback validates it — it's single-use. */
public void clearOAuthState() {
session.removeAttribute(OAUTH_STATE);
}
/**
* Stores the access token + instance URL, and the refresh token when present. The refresh
* token powers the 401/403 auto-refresh in {@code /getFrontdoorURL}; it's granted only if the
* ECA allowed the {@code refresh_token} scope, so it may be {@code null}.
*/
public void storeTokens(String accessToken, String instanceUrl, String refreshToken) {
session.setAttribute(ACCESS_TOKEN, accessToken);
session.setAttribute(INSTANCE_URL, instanceUrl);
if (refreshToken != null) {
session.setAttribute(REFRESH_TOKEN, refreshToken);
}
}
/** Updates just the access token (+ instance URL) after a successful refresh. */
public void updateAccessToken(String accessToken, String instanceUrl) {
session.setAttribute(ACCESS_TOKEN, accessToken);
if (instanceUrl != null) {
session.setAttribute(INSTANCE_URL, instanceUrl);
}
}
public String getAccessToken() {
return (String) session.getAttribute(ACCESS_TOKEN);
}
public String getInstanceUrl() {
return (String) session.getAttribute(INSTANCE_URL);
}
public String getRefreshToken() {
return (String) session.getAttribute(REFRESH_TOKEN);
}
public boolean isAuthenticated() {
return getAccessToken() != null && getInstanceUrl() != null;
}
}
```
**`token-broker/java/src/main/java/com/example/broker/oauth/SalesforceOAuthClient.java`:**
```java
package com.example.broker.oauth;
import com.example.broker.config.BrokerProperties;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.stereotype.Component;
/**
* The two server-to-server calls this broker makes to Salesforce: the authorization-code token
* exchange, and the FrontDoor (single-access) mint. Both are plain {@code application/x-www-
* form-urlencoded} POSTs over {@link HttpClient} — no need for a heavier REST client here.
*/
@Component
public class SalesforceOAuthClient {
private static final Duration REQUEST_TIMEOUT = Duration.ofSeconds(15);
private final HttpClient httpClient;
private final ObjectMapper objectMapper;
private final BrokerProperties properties;
public SalesforceOAuthClient(BrokerProperties properties) {
this.properties = properties;
this.httpClient = HttpClient.newBuilder().connectTimeout(REQUEST_TIMEOUT).build();
this.objectMapper = new ObjectMapper();
}
/**
* POSTs the authorization code + PKCE verifier to {@code /services/oauth2/token}.
* Appends {@code client_secret} only when {@link BrokerProperties#hasClientSecret()} — the
* secret never leaves this method.
*/
public TokenResponse exchangeCodeForToken(String code, String codeVerifier) {
Map form = new LinkedHashMap<>();
form.put("grant_type", "authorization_code");
form.put("client_id", properties.getClientId());
form.put("redirect_uri", properties.getRedirectUri());
form.put("code", code);
form.put("code_verifier", codeVerifier);
if (properties.hasClientSecret()) {
form.put("client_secret", properties.getClientSecret());
}
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(properties.getLoginUrl() + "/services/oauth2/token"))
.timeout(REQUEST_TIMEOUT)
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(FormEncoding.encode(form)))
.build();
HttpResponse response = send(request, "Token exchange");
TokenResponse token = parse(response.body(), TokenResponse.class, "token response");
if (response.statusCode() / 100 != 2 || token.error() != null) {
String reason = token.errorDescription() != null ? token.errorDescription() : token.error();
int status = response.statusCode() >= 400 ? response.statusCode() : 500;
throw new UpstreamException(status, "Token exchange failed" + (reason != null ? ": " + reason : ""));
}
return token;
}
/**
* Exchanges a refresh token for a fresh access token at {@code /services/oauth2/token}.
* Returns the new {@link TokenResponse} on success, or {@code null} if the refresh failed (e.g.
* the org withheld the scope, or the refresh token was revoked/expired) — callers treat null as
* "couldn't refresh" and fall back to asking the user to re-authenticate.
*/
public TokenResponse refreshAccessToken(String refreshToken) {
if (refreshToken == null || refreshToken.isEmpty()) {
return null;
}
Map form = new LinkedHashMap<>();
form.put("grant_type", "refresh_token");
form.put("client_id", properties.getClientId());
form.put("refresh_token", refreshToken);
if (properties.hasClientSecret()) {
form.put("client_secret", properties.getClientSecret());
}
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(properties.getLoginUrl() + "/services/oauth2/token"))
.timeout(REQUEST_TIMEOUT)
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(FormEncoding.encode(form)))
.build();
try {
HttpResponse response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2) {
return null;
}
TokenResponse token = objectMapper.readValue(response.body(), TokenResponse.class);
if (token.accessToken() == null || token.error() != null) {
return null;
}
return token;
} catch (IOException e) {
return null;
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return null;
}
}
/**
* POSTs (empty body) to {@code /services/oauth2/singleaccess} with the session's
* bearer token, to mint a short-lived FrontDoor URL.
*/
public SingleAccessResponse mintFrontdoorUrl(String instanceUrl, String accessToken) {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(instanceUrl + "/services/oauth2/singleaccess"))
.timeout(REQUEST_TIMEOUT)
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(""))
.build();
HttpResponse response = send(request, "FrontDoor request");
if (response.statusCode() / 100 != 2) {
// Surface Salesforce's own reason: the body carries {"error","error_description"} that
// distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
// it's safe to forward; truncate defensively.
String body = response.body() == null ? "" : response.body().strip();
String detail = body.isEmpty() ? "" : ": " + (body.length() > 500 ? body.substring(0, 500) + "…" : body);
throw new UpstreamException(response.statusCode(), "Salesforce responded " + response.statusCode() + detail);
}
return parse(response.body(), SingleAccessResponse.class, "single-access response");
}
private HttpResponse send(HttpRequest request, String label) {
try {
return httpClient.send(request, HttpResponse.BodyHandlers.ofString());
} catch (IOException e) {
throw new UpstreamException(502, label + " failed: " + e.getMessage(), e);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new UpstreamException(502, label + " interrupted", e);
}
}
private T parse(String body, Class type, String label) {
try {
return objectMapper.readValue(body, type);
} catch (IOException e) {
throw new UpstreamException(502, "Malformed " + label + " from Salesforce", e);
}
}
}
```
**`token-broker/java/src/main/java/com/example/broker/api/TokenBrokerController.java`:**
```java
package com.example.broker.api;
import com.example.broker.config.BrokerProperties;
import com.example.broker.oauth.BrokerSession;
import com.example.broker.oauth.FormEncoding;
import com.example.broker.oauth.Pkce;
import com.example.broker.oauth.SalesforceOAuthClient;
import com.example.broker.oauth.TokenResponse;
import com.example.broker.oauth.UpstreamException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpSession;
import java.net.URI;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* The four endpoints of the Salesforce OAuth token broker: {@code /login} kicks off the
* Authorization Code + PKCE flow, {@code /getAccessToken} is its callback, {@code
* /getFrontdoorURL} trades the session's access token for a short-lived FrontDoor URL the SPA
* can use as the SDK's {@code authCredential}, and {@code /health} is a liveness check.
*
* Mirrors the Node/Express reference route-for-route: same paths, same query params, same
* status codes, and the same split between plain-text errors ({@code /getAccessToken}, matching
* {@code res.send(...)}) and JSON errors ({@code /getFrontdoorURL}, matching {@code res.json(...)}).
*/
@RestController
public class TokenBrokerController {
private final BrokerProperties properties;
private final SalesforceOAuthClient oauthClient;
public TokenBrokerController(BrokerProperties properties, SalesforceOAuthClient oauthClient) {
this.properties = properties;
this.oauthClient = oauthClient;
}
/** Starts OAuth: stash a fresh PKCE verifier in the session, redirect to Salesforce. */
@GetMapping("/login")
public ResponseEntity login(HttpServletRequest request) {
Pkce.Pair pkce = Pkce.generate();
BrokerSession session = new BrokerSession(request.getSession(true));
session.storeCodeVerifier(pkce.verifier());
// Random per-session state for CSRF / login-mix-up protection: echoed back on the callback
// and must match. PKCE defends against code interception; state is the separate login-CSRF
// defense — you want both. (A fixed constant would leave the callback forgeable.)
String state = Pkce.generateState();
session.storeOAuthState(state);
Map params = new LinkedHashMap<>();
params.put("response_type", "code");
params.put("client_id", properties.getClientId());
params.put("redirect_uri", properties.getRedirectUri());
params.put("scope", "api refresh_token lightning web");
params.put("code_challenge", pkce.challenge());
params.put("code_challenge_method", "S256");
params.put("state", state);
URI authorizeUri =
URI.create(properties.getLoginUrl() + "/services/oauth2/authorize?" + FormEncoding.encode(params));
return ResponseEntity.status(HttpStatus.FOUND).location(authorizeUri).build();
}
/** OAuth callback: exchange {@code code} (+ the session's PKCE verifier) for an access token. */
@GetMapping("/getAccessToken")
public ResponseEntity getAccessToken(
@RequestParam(required = false) String code,
@RequestParam(required = false) String state,
@RequestParam(required = false) String error,
@RequestParam(name = "error_description", required = false) String errorDescription,
HttpServletRequest request) {
if (error != null) {
return plainText(
HttpStatus.BAD_REQUEST.value(), "OAuth error: " + (errorDescription != null ? errorDescription : error));
}
BrokerSession session = new BrokerSession(request.getSession(true));
// Reject the callback unless state matches the value stored at /login (CSRF defense).
String expectedState = session.getOAuthState();
if (state == null || expectedState == null || !state.equals(expectedState)) {
return plainText(HttpStatus.BAD_REQUEST.value(), "Invalid or missing OAuth state");
}
session.clearOAuthState(); // single-use
String codeVerifier = session.getCodeVerifier();
if (code == null || codeVerifier == null) {
return plainText(HttpStatus.BAD_REQUEST.value(), "Missing code or PKCE verifier");
}
TokenResponse token;
try {
token = oauthClient.exchangeCodeForToken(code, codeVerifier);
} catch (UpstreamException e) {
// Use the raw status code (not HttpStatus.valueOf) — Salesforce/UpstreamException may
// surface a code with no matching HttpStatus constant.
return plainText(e.getStatusCode(), e.getMessage());
}
session.storeTokens(token.accessToken(), token.instanceUrl(), token.refreshToken());
return ResponseEntity.status(HttpStatus.FOUND).location(URI.create(properties.getAppOrigin())).build();
}
/** Exchanges the session's access token for a FrontDoor URL. The SPA calls this. */
@GetMapping("/getFrontdoorURL")
public ResponseEntity getFrontdoorUrl(HttpSession httpSession) {
BrokerSession session = new BrokerSession(httpSession);
if (!session.isAuthenticated()) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
.body(new ErrorResponse("Not authenticated. Visit /login first."));
}
try {
var singleAccess = oauthClient.mintFrontdoorUrl(session.getInstanceUrl(), session.getAccessToken());
return ResponseEntity.ok(new FrontdoorResponse(singleAccess.frontdoorUri(), properties.getOrgUrl()));
} catch (UpstreamException e) {
// The access token expires (~2h). On 401/403, refresh once and retry so the SPA keeps
// working without bouncing the user back through /login.
if (e.getStatusCode() == 401 || e.getStatusCode() == 403) {
TokenResponse refreshed = oauthClient.refreshAccessToken(session.getRefreshToken());
if (refreshed != null) {
session.updateAccessToken(refreshed.accessToken(), refreshed.instanceUrl());
try {
var singleAccess =
oauthClient.mintFrontdoorUrl(session.getInstanceUrl(), session.getAccessToken());
return ResponseEntity.ok(new FrontdoorResponse(singleAccess.frontdoorUri(), properties.getOrgUrl()));
} catch (UpstreamException retryError) {
return upstreamFailure(retryError);
}
}
}
// Non-401/403, or 401/403 with no usable refresh token: same terminal shape as the
// other ports — status + "Salesforce responded N. Re-authenticate at /login."
return upstreamFailure(e);
}
}
/**
* Terminal FrontDoor failure response, matching the other six ports byte-for-byte: propagate
* the upstream status and append ". Re-authenticate at /login." to the message on every
* non-2xx path (not just the post-refresh retry).
*/
private static ResponseEntity upstreamFailure(UpstreamException e) {
return ResponseEntity.status(e.getStatusCode())
.body(new ErrorResponse(e.getMessage() + ". Re-authenticate at /login."));
}
@GetMapping("/health")
public HealthResponse health() {
return new HealthResponse(true);
}
private static ResponseEntity plainText(int status, String body) {
return ResponseEntity.status(status).contentType(MediaType.TEXT_PLAIN).body(body);
}
}
```
**`token-broker/java/src/main/java/com/example/broker/api/FrontdoorResponse.java`:**
```java
package com.example.broker.api;
import com.fasterxml.jackson.annotation.JsonInclude;
/** JSON body returned by {@code GET /getFrontdoorURL}: {@code {"frontdoorUrl", "orgUrl"}}. */
@JsonInclude(JsonInclude.Include.NON_NULL)
public record FrontdoorResponse(String frontdoorUrl, String orgUrl) {}
```
**`token-broker/java/src/main/java/com/example/broker/api/ErrorResponse.java`:**
```java
package com.example.broker.api;
/** JSON error body returned by the broker's endpoints: {@code {"error": "..."}}. */
public record ErrorResponse(String error) {}
```
**`token-broker/java/src/main/java/com/example/broker/api/HealthResponse.java`:**
```java
package com.example.broker.api;
/** JSON body returned by {@code GET /health}: {@code {"ok": true}}. */
public record HealthResponse(boolean ok) {}
```
---
## Python (FastAPI)
> *Reviewed against the contract, not executed here.* FastAPI + `httpx`, with Starlette's
> `SessionMiddleware` for server-side session state and `CORSMiddleware` for the credentialed origin.
**Run it.** From `token-broker/python/`, create a venv, install deps, load the shared `.env`
(see the Node section for how `.env` loading and the `source` path work), confirm it loaded,
then start. The broker listens on **http://localhost:8500**.
```bash
cd token-broker/python
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
uvicorn main:app --port 8500
```
Requires **Python 3.9+**. (Note: Starlette's `CORSMiddleware` answers preflight with `200`, not the
contract's literal `204`; browsers treat any 2xx preflight identically.)
**`token-broker/python/requirements.txt`:**
```text
fastapi==0.141.1
uvicorn[standard]==0.52.1
httpx==0.28.1
```
**`token-broker/python/main.py`:**
```python
"""Tableau Next embedding -- server-side token broker (Python / FastAPI).
Runs the OAuth Authorization Code + PKCE flow and mints a FrontDoor URL that the
frontend passes to the SDK as ``authCredential``. Keep this on the server: it holds the
client secret (if any) and the raw access token; the browser only ever sees the
short-lived FrontDoor URL.
Port of the Node/Express reference implementation (``token-broker/server.js``).
Endpoints:
GET /login -> starts OAuth (redirects to Salesforce)
GET /getAccessToken -> OAuth callback; exchanges code -> access token (stored in session)
GET /getFrontdoorURL -> exchanges access token -> {frontdoorUrl, orgUrl} (call this from the SPA)
GET /health -> {"ok": true}
"""
import base64
import hashlib
import os
import secrets
import sys
import threading
import httpx
from fastapi import FastAPI, Request, Response
from fastapi.responses import JSONResponse, PlainTextResponse, RedirectResponse
from starlette.middleware.cors import CORSMiddleware
# ---- Config (from environment) -----------------------------------------------------
PORT = int(os.environ.get("PORT", "8500"))
# Your org's login host, e.g. https://yourorg.my.salesforce.com or https://login.salesforce.com
LOGIN_URL = os.environ.get("LOGIN_URL")
# Your org's Lightning My Domain host, e.g. https://yourorg.lightning.force.com
ORG_URL = os.environ.get("ORG_URL")
# ECA Consumer Key
CLIENT_ID = os.environ.get("CLIENT_ID")
# ECA Consumer Secret. The reference ECA requires it (isSecretRequiredForTokenExchange: true);
# set it. Leave unset only for an ECA provisioned PKCE-only. invalid_client => it's required.
CLIENT_SECRET = os.environ.get("CLIENT_SECRET")
# Must exactly match a Callback URL registered on the ECA.
REDIRECT_URI = os.environ.get("REDIRECT_URI", f"http://localhost:{PORT}/getAccessToken")
# Where to send the user back after a successful login.
APP_ORIGIN = os.environ.get("APP_ORIGIN", "http://localhost:8700")
SESSION_SECRET = os.environ.get("SESSION_SECRET", "change-me-in-production")
for name, value in {"LOGIN_URL": LOGIN_URL, "ORG_URL": ORG_URL, "CLIENT_ID": CLIENT_ID}.items():
if not value:
print(f"Missing required env var: {name}. See .env.example.", file=sys.stderr)
sys.exit(1)
# ---- PKCE helpers --------------------------------------------------------------------
def _base64url(raw: bytes) -> str:
return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
def generate_pkce() -> tuple[str, str]:
"""Return a (verifier, challenge) pair for OAuth 2.0 PKCE, S256 only."""
verifier = _base64url(secrets.token_bytes(64))
challenge = _base64url(hashlib.sha256(verifier.encode("ascii")).digest())
return verifier, challenge
# ---- App -------------------------------------------------------------------------
app = FastAPI(title="Tableau Next Token Broker")
# CORS: the SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this
# broker (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these
# headers or the browser drops the response. Allow-Origin must name the exact origin (not '*')
# when credentials are involved. On localhost, :8700 and :8500 are the same *site*, so the
# SameSite=Lax session cookie is still sent -- CORS just permits reading the response.
app.add_middleware(
CORSMiddleware,
allow_origins=[APP_ORIGIN],
allow_credentials=True,
allow_methods=["GET", "OPTIONS"],
allow_headers=["Content-Type"],
)
# ---- Server-side session store -------------------------------------------------------
# CRITICAL: session state (codeVerifier, accessToken, instanceUrl) must stay SERVER-SIDE,
# exactly like the Node reference's express-session MemoryStore. The cookie carries ONLY an
# opaque, unguessable session id -- never the token itself. (Starlette's SessionMiddleware is
# a *signed cookie* store, which would serialize the raw access_token into the browser cookie;
# that violates the "token never leaves the server" invariant, so we don't use it.)
#
# This in-memory dict is fine for local dev / a single process. For production or multiple
# workers, back it with a shared store (Redis, a database, etc.) so sessions survive restarts.
SESSION_COOKIE = "token_broker_session"
_sessions: dict[str, dict] = {}
_sessions_lock = threading.Lock()
def _get_session(request: Request) -> dict:
"""Return the server-side session dict for this request (empty if none yet)."""
sid = request.cookies.get(SESSION_COOKIE)
if not sid:
return {}
with _sessions_lock:
return _sessions.get(sid, {})
def _save_session(response: Response, request: Request, data: dict) -> None:
"""Persist the session dict server-side and set the opaque-id cookie if new."""
sid = request.cookies.get(SESSION_COOKIE)
with _sessions_lock:
if not sid or sid not in _sessions:
sid = secrets.token_urlsafe(32)
_sessions[sid] = data
# HttpOnly + SameSite=Lax; the value is only the opaque id, never the token.
response.set_cookie(
SESSION_COOKIE, sid, httponly=True, samesite="lax", secure=False, path="/"
)
@app.get("/login")
async def login(request: Request) -> RedirectResponse:
"""Kick off OAuth with PKCE."""
verifier, challenge = generate_pkce()
# Random per-session `state` for CSRF / login-mix-up protection: it's echoed back on the
# callback and must match. PKCE defends against code interception; `state` is the separate
# login-CSRF defense -- you want both. (A fixed constant would leave the callback forgeable.)
state = secrets.token_urlsafe(32)
params = {
"response_type": "code",
"client_id": CLIENT_ID,
"redirect_uri": REDIRECT_URI,
"scope": "api refresh_token lightning web",
"code_challenge": challenge,
"code_challenge_method": "S256",
"state": state,
}
authorize_url = httpx.URL(f"{LOGIN_URL}/services/oauth2/authorize", params=params)
response = RedirectResponse(url=str(authorize_url), status_code=302)
# Stash the verifier + state server-side; the cookie on this redirect carries only the opaque id.
session = _get_session(request)
session["codeVerifier"] = verifier
session["oauthState"] = state
_save_session(response, request, session)
return response
@app.get("/getAccessToken")
async def get_access_token(request: Request):
"""OAuth callback: exchange the authorization code for an access token."""
query = request.query_params
error = query.get("error")
if error:
error_description = query.get("error_description", error)
return PlainTextResponse(f"OAuth error: {error_description}", status_code=400)
session = _get_session(request)
# Reject the callback unless `state` matches the value stored at /login (CSRF defense).
state = query.get("state")
expected_state = session.get("oauthState")
if not state or not expected_state or state != expected_state:
return PlainTextResponse("Invalid or missing OAuth state", status_code=400)
session.pop("oauthState", None) # single-use
code = query.get("code")
code_verifier = session.get("codeVerifier")
if not code or not code_verifier:
return PlainTextResponse("Missing code or PKCE verifier", status_code=400)
data = {
"grant_type": "authorization_code",
"client_id": CLIENT_ID,
"redirect_uri": REDIRECT_URI,
"code": code,
"code_verifier": code_verifier,
}
# Sent when configured. The reference ECA requires it; a PKCE-only ECA omits it.
if CLIENT_SECRET:
data["client_secret"] = CLIENT_SECRET
try:
async with httpx.AsyncClient() as client:
resp = await client.post(f"{LOGIN_URL}/services/oauth2/token", data=data)
except httpx.HTTPError as exc:
return PlainTextResponse(f"Token exchange error: {exc}", status_code=500)
token_data = resp.json()
if resp.is_error or token_data.get("error"):
message = token_data.get("error_description") or token_data.get("error") or "unknown"
return PlainTextResponse(
f"Token exchange failed: {message}", status_code=resp.status_code or 500
)
# Store the token + instance URL server-side, keyed by the same opaque session id.
response = RedirectResponse(url=APP_ORIGIN, status_code=302) # back to the SPA
session["accessToken"] = token_data["access_token"]
session["instanceUrl"] = token_data["instance_url"]
# Stored so we can silently re-mint after the ~2h access-token TTL elapses. Present only
# if the ECA granted the refresh_token scope (requested in /login); if the org withholds
# it, refresh_access_token() is a no-op and the user re-runs /login by hand.
session["refreshToken"] = token_data.get("refresh_token")
_save_session(response, request, session)
return response
async def _mint_frontdoor(client: httpx.AsyncClient, instance_url: str, access_token: str):
"""POST the access token to singleaccess to mint a FrontDoor URL."""
return await client.post(
f"{instance_url}/services/oauth2/singleaccess",
headers={
"accept": "application/json",
"authorization": f"Bearer {access_token}",
"content-type": "application/x-www-form-urlencoded",
},
content=b"",
)
async def _refresh_access_token(client: httpx.AsyncClient, session: dict) -> bool:
"""Exchange the stored refresh token for a fresh access token, updating the session in
place. Returns False if there's no refresh token or the refresh fails."""
refresh_token = session.get("refreshToken")
if not refresh_token:
return False
data = {"grant_type": "refresh_token", "client_id": CLIENT_ID, "refresh_token": refresh_token}
if CLIENT_SECRET:
data["client_secret"] = CLIENT_SECRET
try:
resp = await client.post(f"{LOGIN_URL}/services/oauth2/token", data=data)
except httpx.HTTPError:
return False
token_data = resp.json()
if resp.is_error or token_data.get("error") or not token_data.get("access_token"):
return False
session["accessToken"] = token_data["access_token"]
# A refresh grant returns instance_url but no new refresh_token; keep the stored one.
if token_data.get("instance_url"):
session["instanceUrl"] = token_data["instance_url"]
return True
@app.get("/getFrontdoorURL")
async def get_frontdoor_url(request: Request) -> JSONResponse:
"""Exchange the session's access token for a FrontDoor URL. The SPA calls this."""
session = _get_session(request)
access_token = session.get("accessToken")
instance_url = session.get("instanceUrl")
if not access_token or not instance_url:
return JSONResponse({"error": "Not authenticated. Visit /login first."}, status_code=401)
try:
async with httpx.AsyncClient() as client:
resp = await _mint_frontdoor(client, instance_url, access_token)
# The access token expires (~2h). On 401/403, refresh once and retry so the SPA
# keeps working without bouncing the user back through /login.
if resp.status_code in (401, 403) and await _refresh_access_token(client, session):
resp = await _mint_frontdoor(client, session["instanceUrl"], session["accessToken"])
except httpx.HTTPError as exc:
return JSONResponse({"error": str(exc) or "Failed to generate FrontDoor URL"}, status_code=500)
if resp.is_error:
# Still failing after the refresh attempt — the session is stale; the SPA should /login.
# Surface Salesforce's own reason: the body carries {"error","error_description"} that
# distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
# it's safe to forward; truncate defensively.
body = (resp.text or "").strip()
detail = f": {body[:500]}…" if len(body) > 500 else (f": {body}" if body else "")
return JSONResponse(
{"error": f"Salesforce responded {resp.status_code}{detail}. Re-authenticate at /login."},
status_code=resp.status_code,
)
data = resp.json()
return JSONResponse({"frontdoorUrl": data.get("frontdoor_uri"), "orgUrl": ORG_URL})
@app.get("/health")
async def health() -> JSONResponse:
return JSONResponse({"ok": True})
if __name__ == "__main__":
import uvicorn
print(f"Token broker on http://localhost:{PORT}")
print(f" Log in: http://localhost:{PORT}/login")
uvicorn.run(app, host="0.0.0.0", port=PORT)
```
---
## Go (net/http)
> *Reviewed against the contract; `go vet` clean.* Standard-library `net/http` with method-qualified
> `ServeMux` routes (Go 1.22+). Session state is an in-memory map keyed by a `crypto/rand` opaque id
> (server-side; the cookie carries only that id, `HttpOnly` + `SameSite=Lax`) — the closest match to
> the Node reference's `express-session` `MemoryStore`.
**Run it.** From `token-broker/go/`, load the shared `.env` (see the Node section for how
`.env` loading and the `source` path work), confirm it loaded, then run. The broker listens
on **http://localhost:8500**. There's no dependency-install step — this port is
**standard-library only**, so `go run .` compiles and starts it directly. (If you ran
`go mod download`, seeing `go: no module dependencies to download` is expected, not an
error.)
```bash
cd token-broker/go
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
go run .
```
Requires **Go 1.22+**. Reads config directly from `os.Getenv` (no `.env` loader) — export the same vars.
**`token-broker/go/go.mod`:**
```text
module tableau-next-token-broker
go 1.22
```
**`token-broker/go/main.go`:**
```go
// Command tableau-next-token-broker runs the Salesforce OAuth Authorization Code + PKCE
// flow and mints a FrontDoor URL for the Analytics Embedding SDK.
//
// Keep this server-side: it holds the client secret (if any) and the raw access token.
// The browser only ever receives the short-lived FrontDoor URL.
//
// Endpoints:
//
// GET /login starts OAuth (redirects to Salesforce)
// GET /getAccessToken OAuth callback; exchanges code -> access token (stored in session)
// GET /getFrontdoorURL exchanges access token -> {frontdoorUrl, orgUrl} (call from the SPA)
// GET /health liveness check
package main
import (
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"net/url"
"os"
"strings"
"sync"
)
// config holds the broker's settings, all sourced from the environment.
type config struct {
port string
loginURL string
orgURL string
clientID string
clientSecret string
redirectURI string
appOrigin string
// sessionSecret is read for parity with the other broker ports' env surface (SESSION_SECRET
// is documented everywhere), but this broker's in-memory session store keys sessions by an
// unguessable server-side id rather than a signed cookie, so it isn't consumed today.
sessionSecret string
}
// loadConfig reads configuration from the environment and fails fast if a required
// value is missing, mirroring the Node reference implementation.
func loadConfig() config {
port := getEnv("PORT", "8500")
cfg := config{
port: port,
loginURL: os.Getenv("LOGIN_URL"),
orgURL: os.Getenv("ORG_URL"),
clientID: os.Getenv("CLIENT_ID"),
clientSecret: os.Getenv("CLIENT_SECRET"),
redirectURI: getEnv("REDIRECT_URI", fmt.Sprintf("http://localhost:%s/getAccessToken", port)),
appOrigin: getEnv("APP_ORIGIN", "http://localhost:8700"),
sessionSecret: getEnv("SESSION_SECRET", "change-me-in-production"),
}
required := map[string]string{
"LOGIN_URL": cfg.loginURL,
"ORG_URL": cfg.orgURL,
"CLIENT_ID": cfg.clientID,
}
for _, name := range []string{"LOGIN_URL", "ORG_URL", "CLIENT_ID"} {
if required[name] == "" {
log.Fatalf("Missing required env var: %s. See .env.example.", name)
}
}
return cfg
}
func getEnv(name, fallback string) string {
if v := os.Getenv(name); v != "" {
return v
}
return fallback
}
// broker holds everything a request handler needs: config, an HTTP client for the
// server-to-server calls to Salesforce, and the session store.
type broker struct {
cfg config
sessions *sessionStore
client *http.Client
}
const sessionCookieName = "token-broker-session"
// sessionData is the state the broker stashes across requests: the PKCE verifier (between
// /login and /getAccessToken) and the access token + instance URL + refresh token (between
// /getAccessToken and /getFrontdoorURL). It lives only server-side -- never in the cookie.
type sessionData struct {
codeVerifier string
// oauthState is the random per-session CSRF token echoed back on the callback (set in
// handleLogin, verified + cleared in handleGetAccessToken).
oauthState string
accessToken string
instanceUrl string
// refreshToken is stored so we can silently re-mint after the ~2h access-token TTL
// elapses. Present only if the ECA granted the refresh_token scope (requested in /login);
// if the org withholds it, refreshAccessToken is a no-op and the user re-runs /login.
refreshToken string
}
// sessionStore is a minimal, single-process, in-memory session store: state lives in this
// map, keyed by a crypto/rand opaque id, and the browser's cookie carries only that id --
// never the session payload. This is the Go analog of express-session's default
// MemoryStore. A real deployment (multi-process, or one that must survive restarts) should
// back this with a shared store instead (e.g. Redis); see the README.
type sessionStore struct {
mu sync.Mutex
data map[string]*sessionData
}
func newSessionStore() *sessionStore {
return &sessionStore{data: make(map[string]*sessionData)}
}
// newSessionID returns a high-entropy, unguessable id (32 random bytes, base64url-encoded)
// suitable for use as an opaque session-cookie value.
func newSessionID() (string, error) {
raw := make([]byte, 32)
if _, err := rand.Read(raw); err != nil {
return "", err
}
return base64.RawURLEncoding.EncodeToString(raw), nil
}
// load returns the session named by the request's cookie, or nil if there isn't one --
// e.g. no cookie yet, or a stale id (this store doesn't survive restarts).
func (s *sessionStore) load(r *http.Request) *sessionData {
cookie, err := r.Cookie(sessionCookieName)
if err != nil {
return nil
}
s.mu.Lock()
defer s.mu.Unlock()
return s.data[cookie.Value]
}
// create allocates a new session under a fresh opaque id, sets that id as an
// HttpOnly+SameSite=Lax cookie on the response, and returns the (empty) session for the
// caller to populate.
func (s *sessionStore) create(w http.ResponseWriter) (*sessionData, error) {
id, err := newSessionID()
if err != nil {
return nil, err
}
sess := &sessionData{}
s.mu.Lock()
s.data[id] = sess
s.mu.Unlock()
http.SetCookie(w, &http.Cookie{
Name: sessionCookieName,
Value: id,
Path: "/",
HttpOnly: true,
SameSite: http.SameSiteLaxMode,
})
return sess, nil
}
// getOrCreate returns the request's existing session, or creates (and cookies) a fresh one
// if the request has none. A tampered or stale cookie shouldn't block login, so this never
// errors on a bad incoming cookie -- it just starts over.
func (s *sessionStore) getOrCreate(r *http.Request, w http.ResponseWriter) (*sessionData, error) {
if sess := s.load(r); sess != nil {
return sess, nil
}
return s.create(w)
}
// generatePKCE returns a high-entropy code_verifier and its S256 code_challenge, per
// RFC 7636. The verifier and challenge are both base64url-encoded with no padding.
func generatePKCE() (verifier, challenge string, err error) {
raw := make([]byte, 64)
if _, err = rand.Read(raw); err != nil {
return "", "", err
}
verifier = base64.RawURLEncoding.EncodeToString(raw)
sum := sha256.Sum256([]byte(verifier))
challenge = base64.RawURLEncoding.EncodeToString(sum[:])
return verifier, challenge, nil
}
// handleLogin starts the OAuth flow: it generates a PKCE pair, stashes the verifier in
// the session, and redirects the browser to Salesforce's authorize endpoint.
func (b *broker) handleLogin(w http.ResponseWriter, r *http.Request) {
verifier, challenge, err := generatePKCE()
if err != nil {
http.Error(w, "Failed to generate PKCE challenge", http.StatusInternalServerError)
return
}
sess, err := b.sessions.getOrCreate(r, w)
if err != nil {
http.Error(w, "Failed to persist session", http.StatusInternalServerError)
return
}
sess.codeVerifier = verifier
// Random per-session state for CSRF / login-mix-up protection: echoed back on the callback
// and must match. PKCE defends against code interception; state is the separate login-CSRF
// defense -- you want both. (A fixed constant would leave the callback forgeable.)
state, err := newSessionID()
if err != nil {
http.Error(w, "Failed to generate OAuth state", http.StatusInternalServerError)
return
}
sess.oauthState = state
params := url.Values{
"response_type": {"code"},
"client_id": {b.cfg.clientID},
"redirect_uri": {b.cfg.redirectURI},
"scope": {"api refresh_token lightning web"},
"code_challenge": {challenge},
"code_challenge_method": {"S256"},
"state": {state},
}
http.Redirect(w, r, b.cfg.loginURL+"/services/oauth2/authorize?"+params.Encode(), http.StatusFound)
}
// tokenResponse is the subset of Salesforce's /services/oauth2/token response we need.
type tokenResponse struct {
AccessToken string `json:"access_token"`
InstanceURL string `json:"instance_url"`
RefreshToken string `json:"refresh_token"`
Error string `json:"error"`
ErrorDescription string `json:"error_description"`
}
// handleGetAccessToken is the OAuth callback: it exchanges the authorization code (plus
// the PKCE verifier stashed in the session by handleLogin) for an access token, then
// stores the token and instance URL in the session before sending the browser home.
func (b *broker) handleGetAccessToken(w http.ResponseWriter, r *http.Request) {
q := r.URL.Query()
if oauthErr := q.Get("error"); oauthErr != "" {
desc := q.Get("error_description")
if desc == "" {
desc = oauthErr
}
http.Error(w, "OAuth error: "+desc, http.StatusBadRequest)
return
}
sess := b.sessions.load(r)
// Reject the callback unless state matches the value stored at /login (CSRF defense).
state := q.Get("state")
expectedState := ""
if sess != nil {
expectedState = sess.oauthState
}
if state == "" || expectedState == "" || state != expectedState {
http.Error(w, "Invalid or missing OAuth state", http.StatusBadRequest)
return
}
sess.oauthState = "" // single-use
code := q.Get("code")
verifier := ""
if sess != nil {
verifier = sess.codeVerifier
}
if code == "" || verifier == "" {
http.Error(w, "Missing code or PKCE verifier", http.StatusBadRequest)
return
}
form := url.Values{
"grant_type": {"authorization_code"},
"client_id": {b.cfg.clientID},
"redirect_uri": {b.cfg.redirectURI},
"code": {code},
"code_verifier": {verifier},
}
// Sent only when configured; the reference ECA requires it, a PKCE-only ECA omits it.
if b.cfg.clientSecret != "" {
form.Set("client_secret", b.cfg.clientSecret)
}
resp, err := b.client.Post(
b.cfg.loginURL+"/services/oauth2/token",
"application/x-www-form-urlencoded",
strings.NewReader(form.Encode()),
)
if err != nil {
http.Error(w, "Token exchange error: "+err.Error(), http.StatusInternalServerError)
return
}
defer resp.Body.Close()
var data tokenResponse
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
http.Error(w, "Token exchange error: invalid response from Salesforce", http.StatusInternalServerError)
return
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 || data.Error != "" {
status := resp.StatusCode
if status < 400 {
status = http.StatusInternalServerError
}
msg := data.ErrorDescription
if msg == "" {
msg = data.Error
}
if msg == "" {
msg = "unknown"
}
http.Error(w, "Token exchange failed: "+msg, status)
return
}
sess.accessToken = data.AccessToken
sess.instanceUrl = data.InstanceURL
sess.refreshToken = data.RefreshToken
// The verifier is single-use; drop it now that the exchange succeeded.
sess.codeVerifier = ""
http.Redirect(w, r, b.cfg.appOrigin, http.StatusFound)
}
// refreshAccessToken exchanges the session's refresh token for a fresh access token,
// updating the session in place. Returns false if there's no refresh token or the refresh
// fails (e.g. the org withheld the scope, or the refresh token was revoked/expired).
func (b *broker) refreshAccessToken(sess *sessionData) bool {
if sess.refreshToken == "" {
return false
}
form := url.Values{
"grant_type": {"refresh_token"},
"client_id": {b.cfg.clientID},
"refresh_token": {sess.refreshToken},
}
if b.cfg.clientSecret != "" {
form.Set("client_secret", b.cfg.clientSecret)
}
resp, err := b.client.Post(
b.cfg.loginURL+"/services/oauth2/token",
"application/x-www-form-urlencoded",
strings.NewReader(form.Encode()),
)
if err != nil {
return false
}
defer resp.Body.Close()
var data tokenResponse
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
return false
}
if resp.StatusCode/100 != 2 || data.Error != "" || data.AccessToken == "" {
return false
}
sess.accessToken = data.AccessToken
// A refresh grant returns instance_url but no new refresh_token; keep the stored one.
if data.InstanceURL != "" {
sess.instanceUrl = data.InstanceURL
}
return true
}
// mintFrontdoor POSTs the access token to the singleaccess endpoint to mint a FrontDoor URL.
func (b *broker) mintFrontdoor(instanceURL, accessToken string) (*http.Response, error) {
req, err := http.NewRequest(http.MethodPost, instanceURL+"/services/oauth2/singleaccess", strings.NewReader(""))
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
return b.client.Do(req)
}
// frontdoorResponse is the JSON shape returned to the SPA by handleGetFrontdoorURL.
type frontdoorResponse struct {
FrontdoorURL string `json:"frontdoorUrl,omitempty"`
OrgURL string `json:"orgUrl,omitempty"`
Error string `json:"error,omitempty"`
}
// singleAccessResponse is the subset of /services/oauth2/singleaccess we need.
type singleAccessResponse struct {
FrontdoorURI string `json:"frontdoor_uri"`
}
// handleGetFrontdoorURL exchanges the session's access token for a FrontDoor URL. This
// is the only endpoint the SPA needs to call after login; the raw access token never
// leaves the server.
func (b *broker) handleGetFrontdoorURL(w http.ResponseWriter, r *http.Request) {
sess := b.sessions.load(r)
accessToken, instanceURL := "", ""
if sess != nil {
accessToken, instanceURL = sess.accessToken, sess.instanceUrl
}
if accessToken == "" || instanceURL == "" {
writeJSON(w, http.StatusUnauthorized, frontdoorResponse{Error: "Not authenticated. Visit /login first."})
return
}
resp, err := b.mintFrontdoor(instanceURL, accessToken)
if err != nil {
writeJSON(w, http.StatusInternalServerError, frontdoorResponse{Error: "Failed to generate FrontDoor URL"})
return
}
defer resp.Body.Close()
// The access token expires (~2h). On 401/403, refresh once and retry so the SPA keeps
// working without bouncing the user back through /login.
if (resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden) && b.refreshAccessToken(sess) {
resp.Body.Close()
resp, err = b.mintFrontdoor(sess.instanceUrl, sess.accessToken)
if err != nil {
writeJSON(w, http.StatusInternalServerError, frontdoorResponse{Error: "Failed to generate FrontDoor URL"})
return
}
defer resp.Body.Close()
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
// Still failing after the refresh attempt — the session is stale; the SPA should /login.
// Surface Salesforce's own reason: the body carries {"error","error_description"} that
// distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
// it's safe to forward; truncate defensively.
raw, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
detail := strings.TrimSpace(string(raw))
if len(detail) > 500 {
detail = detail[:500] + "…"
}
if detail != "" {
detail = ": " + detail
}
writeJSON(w, resp.StatusCode, frontdoorResponse{Error: fmt.Sprintf("Salesforce responded %d%s. Re-authenticate at /login.", resp.StatusCode, detail)})
return
}
var data singleAccessResponse
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
writeJSON(w, http.StatusInternalServerError, frontdoorResponse{Error: "Invalid response from Salesforce"})
return
}
writeJSON(w, http.StatusOK, frontdoorResponse{FrontdoorURL: data.FrontdoorURI, OrgURL: b.cfg.orgURL})
}
func handleHealth(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, http.StatusOK, map[string]bool{"ok": true})
}
func writeJSON(w http.ResponseWriter, status int, body any) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(body)
}
// withCORS answers preflight requests and adds the CORS headers every response needs so
// the SPA on appOrigin can read a credentialed response. Access-Control-Allow-Origin must
// name the exact origin (never "*") because credentials are involved.
func withCORS(appOrigin string, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", appOrigin)
w.Header().Set("Access-Control-Allow-Credentials", "true")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
w.Header().Set("Vary", "Origin")
if r.Method == http.MethodOptions {
w.WriteHeader(http.StatusNoContent)
return
}
next.ServeHTTP(w, r)
})
}
func main() {
cfg := loadConfig()
b := &broker{
cfg: cfg,
sessions: newSessionStore(),
client: &http.Client{},
}
// Method-qualified patterns (Go 1.22+) so each path responds only to GET, matching the
// contract and the golden Express reference's app.get(...). A non-GET request to a known
// path gets a 405 from the mux rather than falling through to a handler.
mux := http.NewServeMux()
mux.HandleFunc("GET /login", b.handleLogin)
mux.HandleFunc("GET /getAccessToken", b.handleGetAccessToken)
mux.HandleFunc("GET /getFrontdoorURL", b.handleGetFrontdoorURL)
mux.HandleFunc("GET /health", handleHealth)
addr := ":" + cfg.port
log.Printf("Token broker on http://localhost:%s", cfg.port)
log.Printf(" Log in: http://localhost:%s/login", cfg.port)
if err := http.ListenAndServe(addr, withCORS(cfg.appOrigin, mux)); err != nil {
log.Fatal(err)
}
}
```
---
## C# (ASP.NET Core)
> *Execution-verified — built with `dotnet build` (0 warnings) and exercised end-to-end against a
> mock Salesforce server: `/login` → `/getAccessToken` → `/getFrontdoorURL`, including the PKCE
> round-trip, the `client_secret`-only-when-set assertion, and the empty-body Bearer call.* ASP.NET
> Core 8 minimal API, zero third-party NuGet packages. Session state uses distributed-memory-backed
> `HttpContext.Session` (server-side; the cookie is an opaque encrypted id).
**Run it.** From `token-broker/dotnet/`, load the shared `.env` (see the Node section for how
`.env` loading and the `source` path work), confirm it loaded, then run. The broker listens
on **http://localhost:8500**.
```bash
cd token-broker/dotnet
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
dotnet run
```
Requires the **.NET 8 SDK**. Env vars are the same set as the Node `.env.example` above.
**`token-broker/dotnet/broker.csproj`:**
```xml
net8.0
enable
enable
TokenBroker
token-broker
true
```
**`token-broker/dotnet/Program.cs`:**
```csharp
// Tableau Next embedding — server-side token broker (C# / ASP.NET Core 8, minimal API).
//
// Runs the OAuth Authorization Code + PKCE flow and mints a FrontDoor URL that the
// frontend passes to the SDK as `authCredential`. Keep this on the server: it holds the
// client secret (if any) and the raw access token; the browser only ever sees the
// short-lived FrontDoor URL.
//
// Port of the Node/Express reference implementation (token-broker/server.js). Same
// contract, same endpoints, same env vars — pick whichever runtime fits your stack.
//
// Endpoints:
// GET /login -> starts OAuth (redirects to Salesforce)
// GET /getAccessToken -> OAuth callback; exchanges code -> access token (stored in session)
// GET /getFrontdoorURL -> exchanges access token -> { frontdoorUrl, orgUrl } (call from the SPA)
// GET /health -> { "ok": true }
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.AspNetCore.WebUtilities;
using Microsoft.Extensions.Http;
// ---- Config (from environment) --------------------------------------------------------
// Read directly from the environment (not appsettings.json/IConfiguration) so the env var
// names and defaults line up exactly with the Node reference's `.env.example`. A missing
// required var fails fast — before we ever bind a port — mirroring the Node reference's
// `process.exit(1)`.
BrokerConfig config = BrokerConfig.LoadOrExit();
var builder = WebApplication.CreateBuilder(args);
// Server-side session: ASP.NET Core's session middleware stores the payload (codeVerifier,
// accessToken, instanceUrl) in the configured cache — here, an in-memory distributed cache,
// the .NET analog of express-session's default MemoryStore — and puts only an opaque,
// server-generated session id in the cookie. The cookie never carries the token itself.
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession(options =>
{
options.Cookie.Name = ".TokenBroker.Session";
options.Cookie.HttpOnly = true;
options.Cookie.SameSite = SameSiteMode.Lax;
// On localhost, :8700 -> :8500 is the same *site*, so the Lax cookie is still sent
// cross-port even though CORS treats them as different origins.
options.IdleTimeout = TimeSpan.FromMinutes(30);
});
// A single named HttpClient (via IHttpClientFactory) for the two server-to-server POSTs:
// the token exchange and the FrontDoor (single-access) mint.
builder.Services.AddHttpClient("salesforce", client =>
{
client.Timeout = TimeSpan.FromSeconds(15);
});
var app = builder.Build();
// CORS: the SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this
// broker (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these
// headers or the browser drops the response. Allow-Origin must name the exact origin (never
// "*") because credentials are involved. On localhost, :8700 -> :8500 is the same *site*, so
// the SameSite=Lax session cookie is still sent — CORS just permits reading the response.
// Hand-rolled (rather than the AddCors/UseCors abstraction) so every response — CORS or
// not, preflight or not — carries these exact headers, mirroring the Node reference's
// middleware and the Go/Java ports' equivalent wrappers byte-for-byte.
app.Use(async (context, next) =>
{
context.Response.Headers["Access-Control-Allow-Origin"] = config.AppOrigin;
context.Response.Headers["Access-Control-Allow-Credentials"] = "true";
context.Response.Headers["Access-Control-Allow-Headers"] = "Content-Type";
context.Response.Headers["Vary"] = "Origin";
if (HttpMethods.IsOptions(context.Request.Method))
{
context.Response.StatusCode = StatusCodes.Status204NoContent;
return;
}
await next();
});
app.UseSession();
// 1) Kick off OAuth with PKCE.
app.MapGet("/login", (HttpContext context) =>
{
var (verifier, challenge) = Pkce.Generate();
context.Session.SetString("codeVerifier", verifier);
// Random per-session state for CSRF / login-mix-up protection: echoed back on the callback
// and must match. PKCE defends against code interception; state is the separate login-CSRF
// defense — you want both. (A fixed constant would leave the callback forgeable.)
var state = WebEncoders.Base64UrlEncode(RandomNumberGenerator.GetBytes(32));
context.Session.SetString("oauthState", state);
var authorizeUrl = QueryHelpers.AddQueryString($"{config.LoginUrl}/services/oauth2/authorize", new Dictionary
{
["response_type"] = "code",
["client_id"] = config.ClientId,
["redirect_uri"] = config.RedirectUri,
["scope"] = "api refresh_token lightning web",
["code_challenge"] = challenge,
["code_challenge_method"] = "S256",
["state"] = state,
});
return Results.Redirect(authorizeUrl); // 302
});
// 2) OAuth callback -> exchange the code for an access token.
app.MapGet("/getAccessToken", async (HttpContext context, IHttpClientFactory httpClientFactory) =>
{
var query = context.Request.Query;
var error = query.TryGetValue("error", out var errorValues) ? errorValues.ToString() : null;
if (!string.IsNullOrEmpty(error))
{
var description = query.TryGetValue("error_description", out var descValues) ? descValues.ToString() : error;
return PlainText(StatusCodes.Status400BadRequest, $"OAuth error: {description}");
}
// Reject the callback unless state matches the value stored at /login (CSRF defense).
var state = query.TryGetValue("state", out var stateValues) ? stateValues.ToString() : null;
var expectedState = context.Session.GetString("oauthState");
if (string.IsNullOrEmpty(state) || string.IsNullOrEmpty(expectedState) || state != expectedState)
{
return PlainText(StatusCodes.Status400BadRequest, "Invalid or missing OAuth state");
}
context.Session.Remove("oauthState"); // single-use
var code = query.TryGetValue("code", out var codeValues) ? codeValues.ToString() : null;
var codeVerifier = context.Session.GetString("codeVerifier");
if (string.IsNullOrEmpty(code) || string.IsNullOrEmpty(codeVerifier))
{
return PlainText(StatusCodes.Status400BadRequest, "Missing code or PKCE verifier");
}
var form = new Dictionary
{
["grant_type"] = "authorization_code",
["client_id"] = config.ClientId,
["redirect_uri"] = config.RedirectUri,
["code"] = code,
["code_verifier"] = codeVerifier,
};
// Sent only when configured; the reference ECA requires it, a PKCE-only ECA omits it.
// It is only ever attached to this server-to-server request — never returned to the browser.
if (!string.IsNullOrEmpty(config.ClientSecret))
{
form["client_secret"] = config.ClientSecret;
}
var client = httpClientFactory.CreateClient("salesforce");
HttpResponseMessage response;
try
{
response = await client.PostAsync($"{config.LoginUrl}/services/oauth2/token", FormUrlEncoded(form));
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
return PlainText(StatusCodes.Status500InternalServerError, $"Token exchange error: {ex.Message}");
}
var body = await response.Content.ReadAsStringAsync();
TokenResponse? token;
try
{
// No custom JsonSerializerOptions needed: TokenResponse's [JsonPropertyName]
// attributes already map each property to Salesforce's exact snake_case key.
token = JsonSerializer.Deserialize(body);
}
catch (JsonException)
{
return PlainText(StatusCodes.Status500InternalServerError, "Token exchange error: invalid response from Salesforce");
}
if (!response.IsSuccessStatusCode || !string.IsNullOrEmpty(token?.Error))
{
// Normalize to 500 if Salesforce somehow returned a non-error status with an error
// body — a non-2xx should always propagate, never a misleading 2xx.
var status = (int)response.StatusCode;
if (status < 400)
{
status = StatusCodes.Status500InternalServerError;
}
var message = token?.ErrorDescription ?? token?.Error ?? "unknown";
return PlainText(status, $"Token exchange failed: {message}");
}
context.Session.SetString("accessToken", token!.AccessToken!);
context.Session.SetString("instanceUrl", token!.InstanceUrl!);
// Stored so we can silently re-mint after the ~2h access-token TTL elapses. Present only
// if the ECA granted the refresh_token scope (requested in /login); if the org withholds
// it, RefreshAccessTokenAsync is a no-op and the user re-runs /login by hand.
if (!string.IsNullOrEmpty(token.RefreshToken))
{
context.Session.SetString("refreshToken", token.RefreshToken);
}
return Results.Redirect(config.AppOrigin); // back to the SPA; it will call /getFrontdoorURL
});
// 3) Exchange the stored access token for a FrontDoor URL. The SPA fetches this.
app.MapGet("/getFrontdoorURL", async (HttpContext context, IHttpClientFactory httpClientFactory) =>
{
var accessToken = context.Session.GetString("accessToken");
var instanceUrl = context.Session.GetString("instanceUrl");
if (string.IsNullOrEmpty(accessToken) || string.IsNullOrEmpty(instanceUrl))
{
return Results.Json(new { error = "Not authenticated. Visit /login first." }, statusCode: StatusCodes.Status401Unauthorized);
}
var client = httpClientFactory.CreateClient("salesforce");
HttpResponseMessage response;
try
{
response = await MintFrontdoorAsync(client, instanceUrl, accessToken);
// The access token expires (~2h). On 401/403, refresh once and retry so the SPA keeps
// working without bouncing the user back through /login.
if ((response.StatusCode == System.Net.HttpStatusCode.Unauthorized
|| response.StatusCode == System.Net.HttpStatusCode.Forbidden)
&& await RefreshAccessTokenAsync(client, config, context.Session))
{
response.Dispose();
accessToken = context.Session.GetString("accessToken")!;
instanceUrl = context.Session.GetString("instanceUrl")!;
response = await MintFrontdoorAsync(client, instanceUrl, accessToken);
}
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
return Results.Json(new { error = string.IsNullOrEmpty(ex.Message) ? "Failed to generate FrontDoor URL" : ex.Message }, statusCode: StatusCodes.Status500InternalServerError);
}
// Capture status + body, then dispose the (final) response so no HttpResponseMessage leaks on
// any exit path below — the pre-retry response was already disposed in the retry branch above.
var isSuccess = response.IsSuccessStatusCode;
var statusCode = (int)response.StatusCode;
var body = await response.Content.ReadAsStringAsync();
response.Dispose();
if (!isSuccess)
{
// Still failing after the refresh attempt — the session is stale; the SPA should /login.
// Surface Salesforce's own reason: the body carries {"error","error_description"} that
// distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
// it's safe to forward; truncate defensively.
var trimmed = (body ?? string.Empty).Trim();
var detail = trimmed.Length == 0 ? "" : ": " + (trimmed.Length > 500 ? trimmed[..500] + "…" : trimmed);
return Results.Json(new { error = $"Salesforce responded {statusCode}{detail}. Re-authenticate at /login." }, statusCode: statusCode);
}
SingleAccessResponse? data;
try
{
data = JsonSerializer.Deserialize(body);
}
catch (JsonException)
{
return Results.Json(new { error = "Invalid response from Salesforce" }, statusCode: StatusCodes.Status500InternalServerError);
}
return Results.Json(new { frontdoorUrl = data?.FrontdoorUri, orgUrl = config.OrgUrl });
});
app.MapGet("/health", () => Results.Json(new { ok = true }));
app.Urls.Add($"http://localhost:{config.Port}");
app.Lifetime.ApplicationStarted.Register(() =>
{
Console.WriteLine($"Token broker on http://localhost:{config.Port}");
Console.WriteLine($" Log in: http://localhost:{config.Port}/login");
});
app.Run();
// ---- Helpers ---------------------------------------------------------------------------
static IResult PlainText(int statusCode, string body) => Results.Text(body, "text/plain", statusCode: statusCode);
// POST the access token to the singleaccess endpoint to mint a FrontDoor URL.
static async Task MintFrontdoorAsync(HttpClient client, string instanceUrl, string accessToken)
{
using var request = new HttpRequestMessage(HttpMethod.Post, $"{instanceUrl}/services/oauth2/singleaccess")
{
Content = FormUrlEncoded(new Dictionary()), // empty body
};
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
return await client.SendAsync(request);
}
// Exchange the session's refresh token for a fresh access token, updating the session in
// place. Returns false if there's no refresh token or the refresh fails.
static async Task RefreshAccessTokenAsync(HttpClient client, BrokerConfig config, ISession session)
{
var refreshToken = session.GetString("refreshToken");
if (string.IsNullOrEmpty(refreshToken))
{
return false;
}
var form = new Dictionary
{
["grant_type"] = "refresh_token",
["client_id"] = config.ClientId,
["refresh_token"] = refreshToken,
};
if (!string.IsNullOrEmpty(config.ClientSecret))
{
form["client_secret"] = config.ClientSecret;
}
HttpResponseMessage response;
try
{
response = await client.PostAsync($"{config.LoginUrl}/services/oauth2/token", FormUrlEncoded(form));
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
return false;
}
if (!response.IsSuccessStatusCode)
{
return false;
}
TokenResponse? token;
try
{
token = JsonSerializer.Deserialize(await response.Content.ReadAsStringAsync());
}
catch (JsonException)
{
return false;
}
if (token is null || string.IsNullOrEmpty(token.AccessToken) || !string.IsNullOrEmpty(token.Error))
{
return false;
}
session.SetString("accessToken", token.AccessToken);
// A refresh grant returns instance_url but no new refresh_token; keep the stored one.
if (!string.IsNullOrEmpty(token.InstanceUrl))
{
session.SetString("instanceUrl", token.InstanceUrl);
}
return true;
}
// Encodes a form body as application/x-www-form-urlencoded ourselves (rather than
// FormUrlEncodedContent, which appends "; charset=utf-8") so the outbound Content-Type
// header matches the broker contract exactly, and so an empty dictionary produces a
// genuinely empty body for the FrontDoor (single-access) POST.
static HttpContent FormUrlEncoded(IEnumerable> data)
{
var encoded = string.Join("&", data.Select(kv => $"{Uri.EscapeDataString(kv.Key)}={Uri.EscapeDataString(kv.Value)}"));
var content = new StringContent(encoded, Encoding.ASCII);
content.Headers.ContentType = new MediaTypeHeaderValue("application/x-www-form-urlencoded");
return content;
}
// ---- PKCE (RFC 7636) --------------------------------------------------------------------
///
/// A high-entropy random code_verifier and its S256 code_challenge — matching the Node
/// reference exactly: 64 random bytes, base64url with no padding, SHA-256 (never "plain").
///
static class Pkce
{
public static (string Verifier, string Challenge) Generate()
{
var verifierBytes = RandomNumberGenerator.GetBytes(64);
var verifier = WebEncoders.Base64UrlEncode(verifierBytes);
var challengeBytes = SHA256.HashData(Encoding.ASCII.GetBytes(verifier));
var challenge = WebEncoders.Base64UrlEncode(challengeBytes);
return (verifier, challenge);
}
}
// ---- Config -----------------------------------------------------------------------------
///
/// Broker configuration, read straight from the environment. ,
/// , and are required; a missing one fails
/// startup immediately (mirrors the Node reference's process.exit(1)).
/// is optional: when set, it's appended to the token exchange
/// (confidential client) and is never returned to the browser.
///
sealed record BrokerConfig(
string Port,
string LoginUrl,
string OrgUrl,
string ClientId,
string? ClientSecret,
string RedirectUri,
string AppOrigin,
string SessionSecret)
{
public static BrokerConfig LoadOrExit()
{
var port = GetEnv("PORT", "8500");
var loginUrl = RequireEnv("LOGIN_URL");
var orgUrl = RequireEnv("ORG_URL");
var clientId = RequireEnv("CLIENT_ID");
var clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET");
var redirectUri = GetEnv("REDIRECT_URI", $"http://localhost:{port}/getAccessToken");
var appOrigin = GetEnv("APP_ORIGIN", "http://localhost:8700");
// Kept for parity with the other brokers' env var surface (SESSION_SECRET is
// documented everywhere). ASP.NET Core's session middleware identifies sessions by
// an opaque, server-generated id backed by the distributed cache rather than a value
// signed with this secret, so it isn't wired into the session mechanism itself.
var sessionSecret = GetEnv("SESSION_SECRET", "change-me-in-production");
return new BrokerConfig(port, loginUrl, orgUrl, clientId, clientSecret, redirectUri, appOrigin, sessionSecret);
}
private static string GetEnv(string name, string fallback)
{
var value = Environment.GetEnvironmentVariable(name);
return string.IsNullOrEmpty(value) ? fallback : value;
}
private static string RequireEnv(string name)
{
var value = Environment.GetEnvironmentVariable(name);
if (string.IsNullOrEmpty(value))
{
Console.Error.WriteLine($"Missing required env var: {name}. See .env.example.");
Environment.Exit(1);
}
return value!;
}
}
// ---- Salesforce response shapes ---------------------------------------------------------
/// Subset of the Salesforce /services/oauth2/token response we need.
sealed record TokenResponse(
[property: JsonPropertyName("access_token")] string? AccessToken,
[property: JsonPropertyName("instance_url")] string? InstanceUrl,
[property: JsonPropertyName("refresh_token")] string? RefreshToken,
[property: JsonPropertyName("error")] string? Error,
[property: JsonPropertyName("error_description")] string? ErrorDescription);
/// Subset of the Salesforce /services/oauth2/singleaccess response we need.
sealed record SingleAccessResponse(
[property: JsonPropertyName("frontdoor_uri")] string? FrontdoorUri);
```
---
## Ruby (Sinatra)
> *Reviewed against the contract, not executed here.* Sinatra with `Rack::Session::Pool` — an
> in-memory **server-side** store, so the cookie carries only an opaque id (`HttpOnly` + `SameSite=Lax`).
**Run it.** From `token-broker/ruby/`, install gems, load the shared `.env` (see the Node
section for how `.env` loading and the `source` path work), confirm it loaded, then run. The
broker listens on **http://localhost:8500**.
```bash
cd token-broker/ruby
bundle install
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
ruby app.rb
```
Requires **Ruby 3.x**. Env vars are the same set as the Node `.env.example` above.
> **macOS ships a too-old system Ruby — `bundle install` will fail out of the box.** The
> built-in `/usr/bin/ruby` is **2.6.10** (Apple deprecated it and stopped updating it), so the
> Gemfile's `ruby '>= 3.0'` floor rejects it immediately:
> `Your Ruby version is 2.6.10, but your Gemfile specified >= 3.0`. This hits essentially every
> Mac user. Install a current Ruby with Homebrew and put it ahead of the system one on `PATH`:
> ```bash
> brew install ruby
> # brew's ruby is keg-only, so add it to PATH (Apple Silicon path shown; Intel is /usr/local):
> echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
> ruby -v # confirm 3.x before bundle install
> ```
> Do **not** `sudo gem install` into the system Ruby to work around it — that fights SIP and
> leaves a broken toolchain. Use the Homebrew Ruby (or a version manager like `rbenv`/`asdf`).
**`token-broker/ruby/Gemfile`:**
```ruby
source 'https://rubygems.org'
ruby '>= 3.0' # matches the "Ruby 3.x" prereq; Sinatra 3.2 / Puma 6.6 run on Ruby 3
gem 'sinatra', '~> 3.2'
gem 'puma', '~> 6.6'
```
**`token-broker/ruby/app.rb`:**
```ruby
# frozen_string_literal: true
# Tableau Next embedding — server-side token broker (Ruby/Sinatra port).
#
# Runs the OAuth Authorization Code + PKCE flow and mints a FrontDoor URL that the
# frontend passes to the SDK as `authCredential`. Keep this on the server: it holds the
# client secret (if any) and the raw access token; the browser only ever sees the
# short-lived FrontDoor URL.
#
# Port of the reference Node/Express implementation (see ../server.js) — same env vars,
# same endpoints, same session/CORS contract.
#
# Endpoints:
# GET /login → starts OAuth (redirects to Salesforce)
# GET /getAccessToken → OAuth callback; exchanges code → access token (stored in session)
# GET /getFrontdoorURL → exchanges access token → { frontdoorUrl, orgUrl } (call this from the SPA)
# GET /health → { ok: true }
require 'sinatra'
require 'rack/session/pool'
require 'securerandom'
require 'digest'
require 'base64'
require 'net/http'
require 'uri'
require 'json'
# ---- Config (from environment) ---------------------------------------------------------
PORT = (ENV['PORT'] || 8500).to_i
# Your org's login host, e.g. https://yourorg.my.salesforce.com or https://login.salesforce.com
LOGIN_URL = ENV['LOGIN_URL']
# Your org's Lightning My Domain host, e.g. https://yourorg.lightning.force.com
ORG_URL = ENV['ORG_URL']
# ECA Consumer Key
CLIENT_ID = ENV['CLIENT_ID']
# ECA Consumer Secret. The reference ECA requires it (isSecretRequiredForTokenExchange: true);
# set it. Leave unset only for an ECA provisioned PKCE-only. invalid_client => it's required.
CLIENT_SECRET = ENV['CLIENT_SECRET']
# Must exactly match a Callback URL registered on the ECA.
REDIRECT_URI = ENV['REDIRECT_URI'] || "http://localhost:#{PORT}/getAccessToken"
# Where to send the user back after a successful login; also the CORS-allowed origin.
APP_ORIGIN = ENV['APP_ORIGIN'] || 'http://localhost:8700'
SESSION_SECRET = ENV['SESSION_SECRET'] || 'change-me-in-production'
{ 'LOGIN_URL' => LOGIN_URL, 'ORG_URL' => ORG_URL, 'CLIENT_ID' => CLIENT_ID }.each do |name, value|
next unless value.nil? || value.empty?
warn "Missing required env var: #{name}. See .env.example."
exit 1
end
configure do
set :port, PORT
set :bind, '0.0.0.0'
set :session_secret, SESSION_SECRET
# Session state (code_verifier, access_token, instance_url) must stay server-side — the
# cookie may only carry an opaque session id, never the payload itself. Rack::Session::Pool
# keeps sessions in an in-memory server-side store and puts just a signed id in the cookie.
# (Sinatra 3.x's own session default, Rack::Protection::EncryptedCookie, is a *cookie* store
# too — same problem, plus it demands a 32-byte AES key and would reject the short/default
# SESSION_SECRET — so it's not used here either.) A single-process in-memory Pool is fine for
# this demo; a real deployment should back sessions with Redis or another shared store so
# they survive restarts and work across multiple processes.
set :session_store, Rack::Session::Pool
set :sessions, httponly: true, same_site: :lax
end
# ---- PKCE helpers ------------------------------------------------------------------------
def base64url(bytes)
Base64.urlsafe_encode64(bytes).delete('=')
end
def generate_pkce
verifier = base64url(SecureRandom.random_bytes(64))
challenge = base64url(Digest::SHA256.digest(verifier))
{ verifier: verifier, challenge: challenge }
end
# ---- CORS ----------------------------------------------------------------------------------
# The SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this broker
# (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these headers
# or the browser drops the response. Allow-Origin must name the exact origin (not '*') when
# credentials are involved. On localhost, :8700 and :8500 are the same *site*, so the
# SameSite=Lax session cookie is still sent — CORS just permits reading the response.
before do
headers 'Access-Control-Allow-Origin' => APP_ORIGIN,
'Access-Control-Allow-Credentials' => 'true',
'Access-Control-Allow-Headers' => 'Content-Type',
'Vary' => 'Origin'
end
options '*' do
204
end
# 1) Kick off OAuth with PKCE.
get '/login' do
pkce = generate_pkce
session[:code_verifier] = pkce[:verifier]
# Random per-session state for CSRF / login-mix-up protection: echoed back on the callback
# and must match. PKCE defends against code interception; state is the separate login-CSRF
# defense — you want both. (A fixed constant would leave the callback forgeable.)
state = base64url(SecureRandom.random_bytes(32))
session[:oauth_state] = state
params = {
response_type: 'code',
client_id: CLIENT_ID,
redirect_uri: REDIRECT_URI,
scope: 'api refresh_token lightning web',
code_challenge: pkce[:challenge],
code_challenge_method: 'S256',
state: state
}
redirect "#{LOGIN_URL}/services/oauth2/authorize?#{URI.encode_www_form(params)}"
end
# 2) OAuth callback → exchange the code for an access token.
get '/getAccessToken' do
content_type :text
if params[:error]
halt 400, "OAuth error: #{params[:error_description] || params[:error]}"
end
# Reject the callback unless state matches the value stored at /login (CSRF defense).
expected_state = session[:oauth_state]
if params[:state].nil? || expected_state.nil? || params[:state] != expected_state
halt 400, 'Invalid or missing OAuth state'
end
session.delete(:oauth_state) # single-use
code = params[:code]
code_verifier = session[:code_verifier]
halt 400, 'Missing code or PKCE verifier' if code.nil? || code_verifier.nil?
body = {
grant_type: 'authorization_code',
client_id: CLIENT_ID,
redirect_uri: REDIRECT_URI,
code: code,
code_verifier: code_verifier
}
# Sent when configured. The reference ECA requires it; a PKCE-only ECA omits it.
body[:client_secret] = CLIENT_SECRET if CLIENT_SECRET && !CLIENT_SECRET.empty?
begin
uri = URI("#{LOGIN_URL}/services/oauth2/token")
response = Net::HTTP.post_form(uri, body)
data = JSON.parse(response.body)
if !response.is_a?(Net::HTTPSuccess) || data['error']
status_code = response.code.to_i
status_code = 500 if status_code.zero?
halt status_code, "Token exchange failed: #{data['error_description'] || data['error'] || 'unknown'}"
end
session[:access_token] = data['access_token']
session[:instance_url] = data['instance_url']
# Stored so we can silently re-mint after the ~2h access-token TTL elapses. Present only
# if the ECA granted the refresh_token scope (requested in /login); if the org withholds
# it, refresh_access_token is a no-op and the user re-runs /login by hand.
session[:refresh_token] = data['refresh_token']
redirect APP_ORIGIN # back to the SPA; it will call /getFrontdoorURL
rescue StandardError => e
halt 500, "Token exchange error: #{e.message}"
end
end
# POST the access token to the singleaccess endpoint to mint a FrontDoor URL.
def mint_frontdoor(instance_url, access_token)
uri = URI("#{instance_url}/services/oauth2/singleaccess")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
request = Net::HTTP::Post.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = "Bearer #{access_token}"
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.body = ''
http.request(request)
end
# Exchange the session's refresh token for a fresh access token, updating the session in
# place. Returns true on success; false if there's no refresh token or the refresh fails.
def refresh_access_token(session)
refresh_token = session[:refresh_token]
return false if refresh_token.nil? || refresh_token.empty?
body = { grant_type: 'refresh_token', client_id: CLIENT_ID, refresh_token: refresh_token }
body[:client_secret] = CLIENT_SECRET if CLIENT_SECRET && !CLIENT_SECRET.empty?
response = Net::HTTP.post_form(URI("#{LOGIN_URL}/services/oauth2/token"), body)
data = JSON.parse(response.body)
return false unless response.is_a?(Net::HTTPSuccess) && data['access_token'] && data['error'].nil?
session[:access_token] = data['access_token']
# A refresh grant returns instance_url but no new refresh_token; keep the stored one.
session[:instance_url] = data['instance_url'] if data['instance_url']
true
rescue StandardError
false
end
# 3) Exchange the stored access token for a FrontDoor URL. The SPA fetches this.
get '/getFrontdoorURL' do
content_type :json
access_token = session[:access_token]
instance_url = session[:instance_url]
if access_token.nil? || instance_url.nil?
halt 401, { error: 'Not authenticated. Visit /login first.' }.to_json
end
begin
response = mint_frontdoor(instance_url, access_token)
# The access token expires (~2h). On 401/403, refresh once and retry so the SPA keeps
# working without bouncing the user back through /login.
if [401, 403].include?(response.code.to_i) && refresh_access_token(session)
response = mint_frontdoor(session[:instance_url], session[:access_token])
end
unless response.is_a?(Net::HTTPSuccess)
# Still failing after the refresh attempt — the session is stale; the SPA should /login.
# Surface Salesforce's own reason: the body carries {"error","error_description"} that
# distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
# it's safe to forward; truncate defensively.
body = response.body.to_s.strip
detail = body.empty? ? '' : ": #{body.length > 500 ? "#{body[0, 500]}…" : body}"
halt response.code.to_i, { error: "Salesforce responded #{response.code}#{detail}. Re-authenticate at /login." }.to_json
end
data = JSON.parse(response.body)
{ frontdoorUrl: data['frontdoor_uri'], orgUrl: ORG_URL }.to_json
rescue StandardError => e
halt 500, { error: e.message || 'Failed to generate FrontDoor URL' }.to_json
end
end
get '/health' do
content_type :json
{ ok: true }.to_json
end
```
---
## PHP (built-in server)
> *Reviewed against the contract, not executed here.* A single-file front controller, no framework.
> PHP's native `session_start()` keeps session data server-side (the cookie is only `PHPSESSID`,
> `HttpOnly` + `SameSite=Lax`). Config is validated per-request with a 500 fail-fast, the idiomatic
> equivalent of the Node reference's startup `process.exit(1)` under PHP's per-request model.
**Run it.** From `token-broker/php/`, load the shared `.env` (see the Node section for how
`.env` loading and the `source` path work), confirm it loaded, then start PHP's built-in
server. The broker listens on **http://localhost:8500**.
```bash
cd token-broker/php
set -a; source ../.env; set +a
echo "ORG_URL=$ORG_URL"
php -S localhost:8500 broker.php
```
Requires **PHP 8.x** with the cURL extension. Env vars are the same set as the Node `.env.example` above.
**`token-broker/php/broker.php`:**
```php
starts OAuth (redirects to Salesforce)
* GET /getAccessToken -> OAuth callback; exchanges code -> access token (stored in session)
* GET /getFrontdoorURL -> exchanges access token -> { frontdoorUrl, orgUrl } (call this from the SPA)
* GET /health -> { ok: true }
*/
declare(strict_types=1);
// -----------------------------------------------------------------------------------------
// Config (from environment)
// -----------------------------------------------------------------------------------------
/** Read an env var, falling back to $default when unset or empty. */
function env(string $name, ?string $default = null): ?string
{
$value = getenv($name);
return $value === false || $value === '' ? $default : $value;
}
/** Fail fast (matching the Node reference's process.exit(1) at startup) when config is missing. */
function requireEnv(array $required): void
{
foreach ($required as $name => $value) {
if (!$value) {
error_log("Missing required env var: {$name}. See .env.example.");
http_response_code(500);
header('Content-Type: text/plain; charset=utf-8');
echo "Server misconfigured: missing required env var {$name}. See .env.example.";
exit;
}
}
}
$port = env('PORT', '8500');
// Your org's login host, e.g. https://yourorg.my.salesforce.com or https://login.salesforce.com
$loginUrl = env('LOGIN_URL');
// Your org's Lightning My Domain host, e.g. https://yourorg.lightning.force.com
$orgUrl = env('ORG_URL');
// ECA Consumer Key
$clientId = env('CLIENT_ID');
// ECA Consumer Secret. The reference ECA requires it (isSecretRequiredForTokenExchange: true);
// set it. Leave unset only for an ECA provisioned PKCE-only. invalid_client => it's required.
// Optional — appended to the token exchange only when set. Never sent to the browser.
$clientSecret = env('CLIENT_SECRET');
// Must exactly match a Callback URL registered on the ECA.
$redirectUri = env('REDIRECT_URI', "http://localhost:{$port}/getAccessToken");
// Where to send the user back after a successful login; also the sole allowed CORS origin.
$appOrigin = env('APP_ORIGIN', 'http://localhost:8700');
// PHP's native session module keys sessions by an unguessable server-side ID rather than a
// signed cookie, so this isn't consumed directly today — read anyway so the env surface stays
// identical across every broker implementation.
$sessionSecret = env('SESSION_SECRET', 'change-me-in-production');
requireEnv(['LOGIN_URL' => $loginUrl, 'ORG_URL' => $orgUrl, 'CLIENT_ID' => $clientId]);
// -----------------------------------------------------------------------------------------
// PKCE helpers
// -----------------------------------------------------------------------------------------
function base64UrlEncode(string $data): string
{
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
/** @return array{0: string, 1: string} [$verifier, $challenge] */
function generatePkce(): array
{
$verifier = base64UrlEncode(random_bytes(64));
$challenge = base64UrlEncode(hash('sha256', $verifier, true));
return [$verifier, $challenge];
}
// -----------------------------------------------------------------------------------------
// HTTP client helper (cURL)
// -----------------------------------------------------------------------------------------
/**
* POST application/x-www-form-urlencoded to $url and return [statusCode, body].
* $fields may be an empty array to send an empty body (used by /getFrontdoorURL).
*
* @throws RuntimeException on a transport-level failure (DNS, connect, timeout, ...).
*/
function httpPostForm(string $url, array $fields, array $extraHeaders = []): array
{
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($fields),
CURLOPT_HTTPHEADER => array_merge(
['Content-Type: application/x-www-form-urlencoded'],
$extraHeaders,
),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
if ($body === false) {
$error = curl_error($ch);
curl_close($ch);
throw new RuntimeException($error ?: 'cURL request failed');
}
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return [$status, (string) $body];
}
// -----------------------------------------------------------------------------------------
// Response helpers
// -----------------------------------------------------------------------------------------
function sendJson(int $status, array $payload): void
{
http_response_code($status);
header('Content-Type: application/json');
echo json_encode($payload);
}
function sendText(int $status, string $message): void
{
http_response_code($status);
header('Content-Type: text/plain; charset=utf-8');
echo $message;
}
// -----------------------------------------------------------------------------------------
// CORS
//
// The SPA (APP_ORIGIN, e.g. http://localhost:8700) is a *different origin* than this broker
// (http://localhost:8500), so its credentialed fetch to /getFrontdoorURL needs these headers
// or the browser drops the response. Allow-Origin must name the exact origin (not '*') when
// credentials are involved. On localhost, :8700 and :8500 are the same *site*, so the
// SameSite=Lax session cookie is still sent — CORS just permits reading the response.
// -----------------------------------------------------------------------------------------
header('Access-Control-Allow-Origin: ' . $appOrigin);
header('Access-Control-Allow-Credentials: true');
header('Access-Control-Allow-Headers: Content-Type');
header('Vary: Origin');
$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';
if ($method === 'OPTIONS') {
http_response_code(204);
exit;
}
// -----------------------------------------------------------------------------------------
// Session
//
// Server-side session holding codeVerifier, accessToken, instanceUrl. HttpOnly + SameSite=Lax
// so the token never touches JS and the cookie still rides along on the /login redirect chain.
// -----------------------------------------------------------------------------------------
session_set_cookie_params([
'lifetime' => 0,
'path' => '/',
'secure' => false, // set true once the broker is served over HTTPS
'httponly' => true,
'samesite' => 'Lax',
]);
session_start();
// -----------------------------------------------------------------------------------------
// Route handlers
// -----------------------------------------------------------------------------------------
/** 1) Kick off OAuth with PKCE. */
function handleLogin(string $loginUrl, string $clientId, string $redirectUri): void
{
[$verifier, $challenge] = generatePkce();
$_SESSION['codeVerifier'] = $verifier;
// Random per-session state for CSRF / login-mix-up protection: echoed back on the callback
// and must match. PKCE defends against code interception; state is the separate login-CSRF
// defense — you want both. (A fixed constant would leave the callback forgeable.)
$state = base64UrlEncode(random_bytes(32));
$_SESSION['oauthState'] = $state;
$query = http_build_query([
'response_type' => 'code',
'client_id' => $clientId,
'redirect_uri' => $redirectUri,
'scope' => 'api refresh_token lightning web',
'code_challenge' => $challenge,
'code_challenge_method' => 'S256',
'state' => $state,
]);
header("Location: {$loginUrl}/services/oauth2/authorize?{$query}");
}
/** 2) OAuth callback -> exchange the code for an access token. */
function handleGetAccessToken(
string $loginUrl,
string $clientId,
?string $clientSecret,
string $redirectUri,
string $appOrigin,
): void {
$error = $_GET['error'] ?? null;
if ($error) {
$description = $_GET['error_description'] ?? $error;
sendText(400, "OAuth error: {$description}");
return;
}
// Reject the callback unless state matches the value stored at /login (CSRF defense).
$state = $_GET['state'] ?? null;
$expectedState = $_SESSION['oauthState'] ?? null;
if (!$state || !$expectedState || $state !== $expectedState) {
sendText(400, 'Invalid or missing OAuth state');
return;
}
unset($_SESSION['oauthState']); // single-use
$code = $_GET['code'] ?? null;
$codeVerifier = $_SESSION['codeVerifier'] ?? null;
if (!$code || !$codeVerifier) {
sendText(400, 'Missing code or PKCE verifier');
return;
}
$params = [
'grant_type' => 'authorization_code',
'client_id' => $clientId,
'redirect_uri' => $redirectUri,
'code' => $code,
'code_verifier' => $codeVerifier,
];
// Sent when configured. The reference ECA requires it; a PKCE-only ECA omits it.
if ($clientSecret) {
$params['client_secret'] = $clientSecret;
}
try {
[$status, $body] = httpPostForm("{$loginUrl}/services/oauth2/token", $params);
} catch (Throwable $e) {
sendText(500, "Token exchange error: {$e->getMessage()}");
return;
}
$data = json_decode($body, true) ?: [];
if ($status < 200 || $status >= 300 || isset($data['error'])) {
$message = $data['error_description'] ?? $data['error'] ?? 'unknown';
sendText($status ?: 500, "Token exchange failed: {$message}");
return;
}
$_SESSION['accessToken'] = $data['access_token'] ?? null;
$_SESSION['instanceUrl'] = $data['instance_url'] ?? null;
// Stored so we can silently re-mint after the ~2h access-token TTL elapses. Present only
// if the ECA granted the refresh_token scope (requested in /login); if the org withholds
// it, refreshAccessToken() is a no-op and the user re-runs /login by hand.
$_SESSION['refreshToken'] = $data['refresh_token'] ?? null;
header("Location: {$appOrigin}"); // back to the SPA; it will call /getFrontdoorURL
}
/** POST the access token to the singleaccess endpoint to mint a FrontDoor URL. */
function mintFrontdoor(string $instanceUrl, string $accessToken): array
{
return httpPostForm("{$instanceUrl}/services/oauth2/singleaccess", [], [
'Accept: application/json',
"Authorization: Bearer {$accessToken}",
]);
}
/**
* Exchange the session's refresh token for a fresh access token, updating $_SESSION in place.
* Returns true on success; false if there's no refresh token or the refresh fails.
*/
function refreshAccessToken(string $loginUrl, string $clientId, ?string $clientSecret): bool
{
$refreshToken = $_SESSION['refreshToken'] ?? null;
if (!$refreshToken) {
return false;
}
$params = ['grant_type' => 'refresh_token', 'client_id' => $clientId, 'refresh_token' => $refreshToken];
if ($clientSecret) {
$params['client_secret'] = $clientSecret;
}
try {
[$status, $body] = httpPostForm("{$loginUrl}/services/oauth2/token", $params);
} catch (Throwable $e) {
return false;
}
$data = json_decode($body, true) ?: [];
if ($status < 200 || $status >= 300 || isset($data['error']) || empty($data['access_token'])) {
return false;
}
$_SESSION['accessToken'] = $data['access_token'];
// A refresh grant returns instance_url but no new refresh_token; keep the stored one.
if (!empty($data['instance_url'])) {
$_SESSION['instanceUrl'] = $data['instance_url'];
}
return true;
}
/** 3) Exchange the stored access token for a FrontDoor URL. The SPA fetches this. */
function handleGetFrontdoorUrl(string $orgUrl, string $loginUrl, string $clientId, ?string $clientSecret): void
{
$accessToken = $_SESSION['accessToken'] ?? null;
$instanceUrl = $_SESSION['instanceUrl'] ?? null;
if (!$accessToken || !$instanceUrl) {
sendJson(401, ['error' => 'Not authenticated. Visit /login first.']);
return;
}
try {
[$status, $body] = mintFrontdoor($instanceUrl, $accessToken);
// The access token expires (~2h). On 401/403, refresh once and retry so the SPA keeps
// working without bouncing the user back through /login.
if (($status === 401 || $status === 403) && refreshAccessToken($loginUrl, $clientId, $clientSecret)) {
[$status, $body] = mintFrontdoor($_SESSION['instanceUrl'], $_SESSION['accessToken']);
}
} catch (Throwable $e) {
sendJson(500, ['error' => $e->getMessage() ?: 'Failed to generate FrontDoor URL']);
return;
}
if ($status < 200 || $status >= 300) {
// Still failing after the refresh attempt — the session is stale; the SPA should /login.
// Surface Salesforce's own reason: the body carries {"error","error_description"} that
// distinguishes e.g. an expired token from a missing scope. No token/secret is in it, so
// it's safe to forward; truncate defensively.
$trimmed = trim((string) $body);
$detail = $trimmed === '' ? '' : ': ' . (strlen($trimmed) > 500 ? substr($trimmed, 0, 500) . '…' : $trimmed);
sendJson($status, ['error' => "Salesforce responded {$status}{$detail}. Re-authenticate at /login."]);
return;
}
$data = json_decode($body, true) ?: [];
sendJson(200, ['frontdoorUrl' => $data['frontdoor_uri'] ?? null, 'orgUrl' => $orgUrl]);
}
function handleHealth(): void
{
sendJson(200, ['ok' => true]);
}
// -----------------------------------------------------------------------------------------
// Router
// -----------------------------------------------------------------------------------------
$path = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/';
if ($method === 'GET' && $path === '/login') {
handleLogin($loginUrl, $clientId, $redirectUri);
} elseif ($method === 'GET' && $path === '/getAccessToken') {
handleGetAccessToken($loginUrl, $clientId, $clientSecret, $redirectUri, $appOrigin);
} elseif ($method === 'GET' && $path === '/getFrontdoorURL') {
handleGetFrontdoorUrl($orgUrl, $loginUrl, $clientId, $clientSecret);
} elseif ($method === 'GET' && $path === '/health') {
handleHealth();
} else {
sendText(404, 'Not Found');
}
```
---
# Integrating into an existing app
The samples above are greenfield: a broker on `:8500`, a fresh SPA on `:8700`. The more
common case is grafting the embed into an app you **already have** — an existing frontend
plus its own backend (its own server, session, and CORS). The auth flow is identical; what
changes is that you **mount the broker into your server** instead of running a second one,
and you fit the frontend piece into your existing routing/render model. Four adaptations
cover it. (This section is static-reviewed against a representative Express + React app, not
separately run on an org — the flow it describes is the same one the samples exercise.)
**1. Mount the broker as a router — don't run a second server.** The
[Node reference](#nodejs-express) is a standalone `app` with its own `express-session` and
`cors`. Your app already has both, so strip them from the broker and expose it as a
`Router` you mount under a path prefix. The endpoint logic (the three handlers, PKCE, the
401/403 refresh-and-retry) is copied verbatim — only the wrapper changes:
```js
// tableauBroker.js — the reference broker's handlers, as a mountable router.
// No app.listen, no session(), no cors() here: the host app already owns those.
import { Router } from 'express';
const router = Router();
router.get('/login', (req, res) => {
/* …identical to the reference /login… */
});
router.get('/getAccessToken', async (req, res) => {
/* …identical… */
});
router.get('/getFrontdoorURL', async (req, res) => {
/* …identical… */
});
export default router;
```
```js
// In your existing server, mount it once:
import tableauBroker from './tableauBroker.js';
app.use('/api/tableau', tableauBroker); // now /api/tableau/login, /api/tableau/getFrontdoorURL, …
```
**2. Namespace the session keys.** The broker stashes `codeVerifier`, `oauthState`,
`accessToken`, `instanceUrl`, `refreshToken` on the session. Mounted into your app, that
session is **shared** with your own code — a bare `req.session.accessToken` can collide with
a field your app already uses. Prefix the broker's keys (e.g. `tnCodeVerifier`,
`tnAccessToken`, `tnInstanceUrl`) so the two never overlap. Same server-side-session rule
still holds: the token lives in the session, never in the cookie or the browser.
**3. Your ports and paths differ from the samples — three values must agree.** The samples
hardcode `:8500`/`:8700` and root-level endpoints. In your app the broker lives behind your
server's origin and your mount prefix, so re-point all three references to it:
- **`REDIRECT_URI`** → your callback's real URL (e.g.
`https://app.example.com/api/tableau/getAccessToken`), and register that **exact** URL as
a Callback URL on the ECA. A mismatch is a `redirect_uri_mismatch` at login.
- **`APP_ORIGIN`** → your frontend's real origin. If the frontend and the mounted broker are
the **same** origin (common — one server serves both), the cross-origin CORS block is moot;
if they're separate origins, `APP_ORIGIN` must name the frontend exactly (never `*`), as in
the reference.
- **The frontend fetch path** → `/api/tableau/getFrontdoorURL` (your mount prefix), not the
sample's bare `http://localhost:8500/getFrontdoorURL`. Keep `credentials: 'include'`.
**4. The React sample assumes a mount-once page; an existing app usually re-renders.** The
[React sample](#sample--react) calls `initializeAnalyticsSdk` at module load, which is safe
only because that page mounts exactly once. Inside an app with client-side routing (or React
`StrictMode`'s double-invoke in dev), the embedding component can mount, unmount, and remount
— and `initializeAnalyticsSdk` throws if called twice. Guard it with a module-scope sentinel
so init runs at most once per page load regardless of how often the component mounts:
```tsx
// AnalyticsEmbed.tsx — safe to mount/unmount/remount under routing or StrictMode.
let initialized = false; // module scope: survives component remounts, resets on full reload
export function AnalyticsEmbed({ dashboardId }: { dashboardId: string }) {
useEffect(() => {
if (initialized) return;
initialized = true;
(async () => {
const res = await fetch('/api/tableau/getFrontdoorURL', { credentials: 'include' });
if (!res.ok) return; // 401 → send the user through /api/tableau/login first
const { frontdoorUrl, orgUrl } = await res.json();
await initializeAnalyticsSdk({ orgUrl, authCredential: { token: frontdoorUrl } });
/* …create + append the component as in the sample… */
})();
}, [dashboardId]);
return ;
}
```
Everything else — the ECA setup, the FrontDoor exchange, the SDK API, the component
lifecycle — is unchanged from the greenfield path above.
---
# Runnable samples
Each sample runs on **port 8700** and calls the broker on **8500**. Full projects are on
disk under [`samples/`](samples/); the source of each is inlined here. For every sample:
1. Start the [token broker](#the-runnable-token-broker) and log in at `http://localhost:8500/login`.
2. Set your component id (and type) in the sample's config.
3. `npm install && npm run dev` (Angular: `npm start`) → `http://localhost:8700`.
4. Add `http://localhost:8700` to **Trusted Domains for Inline Frames** (IFrame Type =
Lightning Out).
## Sample — Vanilla JS
A single `index.html`, no build step. Serve on port 8700 (e.g. `npx serve . -l 8700` or
`python3 -m http.server 8700`) — don't open via `file://`, module imports need http.
**`samples/vanilla-js/index.html`:**
```html
Tableau Next embed — vanilla JS
Tableau Next — vanilla JS
Loading…
```
## Sample — TypeScript
Minimal Vite + TypeScript project. `package.json` → `{ "scripts": { "dev": "vite --port
8700", "build": "tsc && vite build" }, "dependencies": { "@salesforce/analytics-embedding-sdk":
"^2.0.0" }, "devDependencies": { "typescript": "^5.4.0", "vite": "^5.2.0" } }`. `tsconfig.json`
uses `"moduleResolution": "bundler"` (see the [TypeScript guide](#typescript)). `index.html`
loads `/src/main.ts` and has ``.
**`samples/typescript/src/main.ts`:**
```ts
import {
initializeAnalyticsSdk,
AnalyticsDashboard,
EventName,
Status,
} from '@salesforce/analytics-embedding-sdk';
import type {
AnalyticsSdkConfig,
DashboardProps,
} from '@salesforce/analytics-embedding-sdk';
// ---- Configure for your org / component ------------------------------------------
// The component's API name (e.g. 'Knowledge_Analytics_Dash'), from its URL or details panel; not a record ID
const DASHBOARD_ID = 'Your_Dashboard_API_Name';
const BROKER = 'http://localhost:8500';
const statusEl = document.getElementById('status')!;
const errorEl = document.getElementById('error')!;
const container = document.getElementById('container') as HTMLElement;
interface FrontdoorResponse {
frontdoorUrl: string;
orgUrl: string;
}
async function main(): Promise
{
try {
// 1. Get the FrontDoor URL from the token broker.
const resp = await fetch(`${BROKER}/getFrontdoorURL`, { credentials: 'include' });
if (!resp.ok) {
throw new Error(`Broker returned ${resp.status}. Log in first at ${BROKER}/login`);
}
const { frontdoorUrl, orgUrl }: FrontdoorResponse = await resp.json();
// 2. Initialize the SDK — fully typed config. init resolves with a status; it does NOT
// throw on auth/framing failure — so check the status. This is the fatal path.
const config: AnalyticsSdkConfig = { orgUrl, authCredential: frontdoorUrl };
const res = await initializeAnalyticsSdk(config);
if (res.status !== Status.SUCCESS) {
throw new Error(
`SDK init failed (${res.status}). Check Trusted Domains for Inline Frames and your FrontDoor URL.`,
);
}
// 3. Construct the component — typed props.
const props: DashboardProps = {
parentIdOrElement: container,
idOrApiName: DASHBOARD_ID,
orgUrl,
};
const dashboard = new AnalyticsDashboard(props);
// 4. Events. Component errors are often PARTIAL (a tile fails while the dashboard
// renders) — log them; don't paint the whole page as broken via the red #error banner.
dashboard.addEventListener(EventName.ERROR, (ev: Event) => {
const detail = (ev as CustomEvent<{ message?: string }>).detail;
console.warn('Analytics component reported an error (may be partial):', detail);
});
dashboard.addEventListener(EventName.COMPONENT_LOADED, () => {
statusEl.textContent = 'Loaded.';
});
// 5. Render. render() rejects if ANY asset fails to load, even when the dashboard itself
// renders — so treat a rejection as non-fatal too.
statusEl.textContent = '';
await dashboard.render().catch((e) => {
console.warn('render() rejected (may be partial):', e instanceof Error ? e.message : e);
});
} catch (e) {
// Fatal: broker/auth/init failed, so nothing rendered.
statusEl.textContent = '';
errorEl.textContent = e instanceof Error ? e.message : String(e);
}
}
void main();
```
## Sample — React
Vite + React + TS. `App.tsx` inits the SDK once (after fetching the FrontDoor URL) and
renders the reusable `AnalyticsEmbed` wrapper. All seven files of the project are inlined below
(`App.tsx`, `AnalyticsEmbed.tsx`, `main.tsx`, `index.html`, `vite.config.ts`, `tsconfig.json`,
`package.json`) — create them under `samples/react/` and you have a complete, runnable app.
**`samples/react/src/App.tsx`:**
```tsx
import { useEffect, useRef, useState } from 'react';
import { initializeAnalyticsSdk, Status } from '@salesforce/analytics-embedding-sdk';
import AnalyticsEmbed, { type ComponentType } from './components/AnalyticsEmbed';
// ---- Configure for your org / component ------------------------------------------
// The component's API name (e.g. 'Knowledge_Analytics_Dash'), from its URL or details panel; not a record ID
const COMPONENT_ID = 'Your_Component_API_Name';
const COMPONENT_TYPE: ComponentType = 'dashboard';
const BROKER = 'http://localhost:8500';
export default function App() {
const [orgUrl, setOrgUrl] = useState(null);
const [status, setStatus] = useState('Authenticating…');
const [isError, setIsError] = useState(false);
// Run the init exactly once. React StrictMode double-invokes effects in dev; the ref
// (which survives the remount) makes the second invocation a clean no-op, so the broker
// fetch + initializeAnalyticsSdk (which consumes the single-use FrontDoor URL) run once.
// NOTE: do NOT also add a per-run `cancelled` flag whose cleanup flips it true — with the
// ref already blocking the remount, that flag would only fire on the one legitimate run's
// cleanup and discard its successful result, hanging the app on "Authenticating…" forever.
const didInit = useRef(false);
// Initialize the SDK once, after fetching the FrontDoor URL from the broker.
useEffect(() => {
if (didInit.current) return;
didInit.current = true;
(async () => {
try {
const resp = await fetch(`${BROKER}/getFrontdoorURL`, { credentials: 'include' });
if (!resp.ok) {
throw new Error(`Broker returned ${resp.status}. Log in first at ${BROKER}/login`);
}
const { frontdoorUrl, orgUrl: org } = await resp.json();
// init resolves with a status; it does NOT throw on auth/framing failure — so check
// the status rather than assuming success once the await completes.
const res = await initializeAnalyticsSdk({ orgUrl: org, authCredential: frontdoorUrl });
if (res.status !== Status.SUCCESS) {
throw new Error(`SDK init failed (${res.status}). Check Trusted Domains for Inline Frames and your FrontDoor URL.`);
}
setOrgUrl(org);
setStatus('');
} catch (e) {
setIsError(true);
setStatus(e instanceof Error ? e.message : String(e));
}
})();
}, []);
return (
Tableau Next — React
{status && {status}
}
{orgUrl && (
console.warn('Analytics component reported an error (may be partial):', m)}
/>
)}
);
}
```
**`samples/react/src/components/AnalyticsEmbed.tsx`** (reusable wrapper for all four types):
```tsx
import {
AnalyticsDashboard,
AnalyticsMetric,
AnalyticsVisualization,
AnalyticsAgent,
EventName,
} from '@salesforce/analytics-embedding-sdk';
import { useEffect, useRef, forwardRef, useImperativeHandle } from 'react';
/**
* Reusable React wrapper for any Tableau Next component.
*
* Pattern mirrors the repo's verified wrapper
* (packages/playground/sdk_multiorg_react/src/components/Dashboard.tsx):
* - a plain ref passed to the SDK via `parentIdOrElement`
* - construct + render inside useEffect, guarded against re-entrancy
* - clear the container on cleanup
* - expose the underlying instance via a forwarded ref
*
* Assumes `initializeAnalyticsSdk(...)` has already run (see App.tsx).
*/
const COMPONENT_CLASSES = {
dashboard: AnalyticsDashboard,
metric: AnalyticsMetric,
visualization: AnalyticsVisualization,
agent: AnalyticsAgent,
} as const;
export type ComponentType = keyof typeof COMPONENT_CLASSES;
export interface AnalyticsEmbedProps {
type: ComponentType;
idOrApiName: string;
orgUrl: string;
onReady?: () => void;
onError?: (message: string) => void;
}
const AnalyticsEmbed = forwardRef
((props, ref) => {
const containerRef = useRef(null);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const instanceRef = useRef(undefined);
useImperativeHandle(ref, () => ({
getInstance: () => instanceRef.current,
reload: () => instanceRef.current?.reload?.(),
}));
useEffect(() => {
let isCancelled = false;
const container = containerRef.current;
const init = async () => {
// Small delay lets any previous cleanup finish before we re-mount.
await new Promise((r) => setTimeout(r, 100));
if (isCancelled) return;
try {
const Ctor = COMPONENT_CLASSES[props.type];
// Agent takes no `filters`; all four accept parentIdOrElement/idOrApiName/orgUrl.
const instance = new Ctor({
parentIdOrElement: container as HTMLElement,
idOrApiName: props.idOrApiName,
orgUrl: props.orgUrl,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any);
instanceRef.current = instance;
if (isCancelled) return;
instance.addEventListener(EventName.ERROR, (ev: Event) => {
const detail = (ev as CustomEvent<{ message?: string }>).detail;
props.onError?.(detail?.message ?? 'Component error');
});
instance.addEventListener(EventName.COMPONENT_LOADED, () => {
if (!isCancelled) props.onReady?.();
});
await instance.render();
} catch (e) {
if (!isCancelled) {
props.onError?.(e instanceof Error ? e.message : 'Failed to render');
}
}
};
void init();
return () => {
isCancelled = true;
// Remove the SDK-rendered iframe on unmount.
container?.replaceChildren();
instanceRef.current = undefined;
};
}, [props.type, props.idOrApiName, props.orgUrl]);
return ;
});
AnalyticsEmbed.displayName = 'AnalyticsEmbed';
export default AnalyticsEmbed;
```
**`samples/react/src/main.tsx`** (entry point):
```tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
// NOTE on StrictMode: the repo's multi-org sample leaves React.StrictMode OFF because its
// intentional double-invoke of effects can double-mount the SDK component in dev. This
// wrapper guards mount/unmount with an `isCancelled` flag and clears the container on
// cleanup, so StrictMode is safe to keep here. If you see a flash of a double-rendered
// component in dev, remove . (See SKILL.md § React.)
ReactDOM.createRoot(document.getElementById('root')!).render(
,
);
```
**`samples/react/index.html`:**
```html
Tableau Next embed — React
```
**`samples/react/vite.config.ts`** (serves on port 8700 to match `APP_ORIGIN`):
```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
server: { port: 8700 },
});
```
**`samples/react/tsconfig.json`** (`moduleResolution: bundler` so the SDK's `exports` map resolves):
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"strict": true,
"skipLibCheck": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"]
},
"include": ["src"]
}
```
**`samples/react/package.json`:**
```json
{
"name": "tableau-next-sample-react",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"preview": "vite preview"
},
"dependencies": {
"@salesforce/analytics-embedding-sdk": "^2.0.0",
"react": "^18.3.1",
"react-dom": "^18.3.1"
},
"devDependencies": {
"@types/react": "^18.3.3",
"@types/react-dom": "^18.3.0",
"@vitejs/plugin-react": "^4.3.1",
"typescript": "^5.4.0",
"vite": "^5.2.0"
}
}
```
Run: `npm install`, then `npm run dev` → open `http://localhost:8700` (after logging in once
at `http://localhost:8500/login`).
## Sample — Vue 3
Vite + Vue 3 (`
Tableau Next — Vue
{{ status }}
```
**`samples/vue/src/components/AnalyticsEmbed.vue`** (reusable wrapper):
```vue
```
**`samples/vue/src/main.ts`** (entry point):
```ts
import { createApp } from 'vue';
import App from './App.vue';
createApp(App).mount('#app');
```
**`samples/vue/index.html`:**
```html
Tableau Next embed — Vue
```
**`samples/vue/vite.config.ts`** (serves on port 8700 to match `APP_ORIGIN`):
```ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [vue()],
server: { port: 8700 },
});
```
**`samples/vue/tsconfig.json`:**
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"skipLibCheck": true,
"jsx": "preserve",
"lib": ["ES2020", "DOM", "DOM.Iterable"]
},
"include": ["src"]
}
```
**`samples/vue/package.json`:**
```json
{
"name": "tableau-next-sample-vue",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "vue-tsc && vite build",
"preview": "vite preview"
},
"dependencies": {
"@salesforce/analytics-embedding-sdk": "^2.0.0",
"vue": "^3.4.0"
},
"devDependencies": {
"@vitejs/plugin-vue": "^5.0.0",
"typescript": "^5.4.0",
"vite": "^5.2.0",
"vue-tsc": "^2.0.0"
}
}
```
Run: `npm install`, then `npm run dev` → open `http://localhost:8700`.
## Sample — Angular
Angular 18 standalone. All seven project files are inlined below (`app.component.ts`,
`analytics-embed.component.ts`, `main.ts`, `src/index.html`, `angular.json`, `tsconfig.json`,
`package.json`) — create them under `samples/angular/` for a complete, runnable app.
**`samples/angular/src/app/app.component.ts`:**
```ts
import { Component, NgZone, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import { initializeAnalyticsSdk, Status } from '@salesforce/analytics-embedding-sdk';
import { AnalyticsEmbedComponent } from './analytics-embed.component';
// ---- Configure for your org / component ------------------------------------------
// The component's API name (e.g. 'Knowledge_Analytics_Dash'), from its URL or details panel; not a record ID
const COMPONENT_ID = 'Your_Component_API_Name';
const COMPONENT_TYPE = 'dashboard' as const;
const BROKER = 'http://localhost:8500';
@Component({
selector: 'app-root',
standalone: true,
imports: [CommonModule, AnalyticsEmbedComponent],
template: `
Tableau Next — Angular
{{ status }}
`,
})
export class AppComponent implements OnInit {
readonly componentId = COMPONENT_ID;
readonly componentType = COMPONENT_TYPE;
orgUrl: string | null = null;
status = 'Authenticating…';
isError = false;
constructor(private readonly zone: NgZone) {}
async ngOnInit(): Promise {
try {
const resp = await fetch(`${BROKER}/getFrontdoorURL`, { credentials: 'include' });
if (!resp.ok) {
throw new Error(`Broker returned ${resp.status}. Log in first at ${BROKER}/login`);
}
const { frontdoorUrl, orgUrl } = await resp.json();
// init resolves with a status; it does NOT throw on auth/framing failure — so check the
// status rather than assuming success once the await completes.
const res = await initializeAnalyticsSdk({ orgUrl, authCredential: frontdoorUrl });
if (res.status !== Status.SUCCESS) {
throw new Error(
`SDK init failed (${res.status}). Check Trusted Domains for Inline Frames and your FrontDoor URL.`,
);
}
// initializeAnalyticsSdk resolves from a cross-iframe postMessage callback that zone.js
// does NOT patch — so this continuation runs OUTSIDE Angular's zone and template bindings
// (*ngIf="orgUrl") never refresh: init succeeds but the view stays frozen on
// "Authenticating…". Re-enter the zone for every state mutation after an SDK boundary.
// (React setState / Vue ref re-render on their own, so only Angular needs this.)
this.zone.run(() => {
this.orgUrl = orgUrl;
this.status = '';
});
} catch (e) {
const msg = e instanceof Error ? e.message : String(e);
this.zone.run(() => {
this.isError = true;
this.status = msg;
});
}
}
// A component/render error is often PARTIAL (render() rejects if any asset fails, even when
// the dashboard itself renders) — so surface it without tearing down the working embed.
onComponentError(m: string): void {
console.warn('Analytics component reported an error (may be partial):', m);
}
}
```
**`samples/angular/src/app/analytics-embed.component.ts`** (reusable wrapper):
```ts
import {
AfterViewInit,
Component,
ElementRef,
EventEmitter,
Input,
NgZone,
OnDestroy,
Output,
ViewChild,
} from '@angular/core';
import {
AnalyticsDashboard,
AnalyticsMetric,
AnalyticsVisualization,
AnalyticsAgent,
EventName,
} from '@salesforce/analytics-embedding-sdk';
type ComponentType = 'dashboard' | 'metric' | 'visualization' | 'agent';
const COMPONENT_CLASSES = {
dashboard: AnalyticsDashboard,
metric: AnalyticsMetric,
visualization: AnalyticsVisualization,
agent: AnalyticsAgent,
} as const;
/**
* Reusable Angular wrapper for any Tableau Next component. Assumes initializeAnalyticsSdk()
* has already run (see AppComponent). Lifecycle maps 1:1 onto the framework-neutral pattern:
* ngAfterViewInit -> construct + render (container exists by now)
* ngOnDestroy -> clear the container
*/
@Component({
selector: 'analytics-embed',
standalone: true,
template: '',
})
export class AnalyticsEmbedComponent implements AfterViewInit, OnDestroy {
@Input({ required: true }) type!: ComponentType;
@Input({ required: true }) idOrApiName!: string;
@Input({ required: true }) orgUrl!: string;
@Output() ready = new EventEmitter();
@Output() error = new EventEmitter();
@ViewChild('container', { static: true }) container!: ElementRef;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
private instance: any;
constructor(private readonly zone: NgZone) {}
async ngAfterViewInit(): Promise {
try {
const Ctor = COMPONENT_CLASSES[this.type];
this.instance = new Ctor({
parentIdOrElement: this.container.nativeElement,
idOrApiName: this.idOrApiName,
orgUrl: this.orgUrl,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any);
// These SDK events fire from cross-iframe postMessage callbacks that land OUTSIDE
// Angular's zone. This sample's parent only console.warns, so it wouldn't notice — but a
// consumer that binds (ready)/(error) to template state would hit the frozen-view bug
// (see AppComponent). Re-enter the zone so the emit drives change detection either way.
this.instance.addEventListener(EventName.ERROR, (ev: Event) => {
const detail = (ev as CustomEvent<{ message?: string }>).detail;
this.zone.run(() => this.error.emit(detail?.message ?? 'Component error'));
});
this.instance.addEventListener(EventName.COMPONENT_LOADED, () =>
this.zone.run(() => this.ready.emit()),
);
await this.instance.render();
} catch (e) {
const msg = e instanceof Error ? e.message : 'Failed to render';
this.zone.run(() => this.error.emit(msg));
}
}
ngOnDestroy(): void {
// Remove the SDK-rendered iframe.
this.container?.nativeElement.replaceChildren();
this.instance = undefined;
}
}
```
**`samples/angular/src/main.ts`** (entry point):
```ts
import 'zone.js';
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
```
**`samples/angular/src/index.html`:**
```html
Tableau Next — Angular
```
**`samples/angular/angular.json`** (serves on 8700; `ng serve --port 8700` in `package.json`):
```json
{
"$schema": "./node_modules/@angular/cli/lib/config/schema.json",
"version": 1,
"projects": {
"sample": {
"projectType": "application",
"root": "",
"sourceRoot": "src",
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:application",
"options": {
"outputPath": "dist",
"index": "src/index.html",
"browser": "src/main.ts",
"tsConfig": "tsconfig.json"
}
},
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"buildTarget": "sample:build"
}
}
}
}
}
}
```
> **The `buildTarget` is required, not optional.** Angular 18's `dev-server` builder has no
> default build to serve — omit `options.buildTarget` and `ng serve` dies immediately with
> `Schema validation failed … must have required property 'buildTarget'`. It points at the
> `build` target of this same project (`:build`, here `sample:build`).
**`samples/angular/tsconfig.json`:**
```json
{
"compileOnSave": false,
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler",
"strict": true,
"skipLibCheck": true,
"esModuleInterop": true,
"experimentalDecorators": true,
"lib": ["ES2022", "DOM", "DOM.Iterable"]
},
"angularCompilerOptions": {
"strictTemplates": true
},
"include": ["src"]
}
```
**`samples/angular/package.json`:**
```json
{
"name": "tableau-next-embedding-angular-sample",
"version": "1.0.0",
"private": true,
"scripts": {
"start": "ng serve --port 8700",
"build": "ng build"
},
"dependencies": {
"@angular/animations": "^18.2.0",
"@angular/common": "^18.2.0",
"@angular/compiler": "^18.2.0",
"@angular/core": "^18.2.0",
"@angular/forms": "^18.2.0",
"@angular/platform-browser": "^18.2.0",
"@angular/platform-browser-dynamic": "^18.2.0",
"@angular/router": "^18.2.0",
"@salesforce/analytics-embedding-sdk": "^2.0.0",
"rxjs": "^7.8.0",
"tslib": "^2.6.0",
"zone.js": "^0.14.10"
},
"devDependencies": {
"@angular-devkit/build-angular": "^18.2.0",
"@angular/cli": "^18.2.0",
"@angular/compiler-cli": "^18.2.0",
"typescript": "~5.5.0"
}
}
```
Run: `npm install`, then `npm start` → open `http://localhost:8700`.
> **HMR gotcha when you edit the init code.** Angular's dev-server hot-swaps the component
> class **without re-running `ngOnInit`**, so an edit to your init logic appears to do nothing —
> the already-pending `initializeAnalyticsSdk` from the pre-edit class keeps running. After
> changing anything in the auth/init path, **hard-reload** (Cmd+Shift+R) so the whole app
> re-bootstraps and your new code actually runs.
---
# Security notes
- **Never mint tokens in the browser.** The client secret and raw access token stay in the
broker; the browser only ever receives the short-lived FrontDoor URL.
- **PKCE + `state` are both enforced.** Every port uses `S256` PKCE and validates a random
per-session `state` on the callback; OAuth-error pages are `text/plain` (no reflected HTML).
- The scripted ECA-creation path (in the Salesforce repo's `metadata-utils`) uses SOAP
username/password — use it only against dev/scratch orgs, never production.
- `.env` holds credentials — keep it git-ignored.
- For production auth, prefer the manual ECA (Option A) and a confidential client with the
secret held server-side; use HTTPS and `SameSite=None; Secure` cookies if the broker and
app are on different sites, rotate the session id after login, and back sessions with a
shared store (see [Security invariants](#security-invariants-non-negotiable)).
Licensed Apache-2.0.