Security & Governance

Reference for security reviews and conversations with the Security team. As always: the IdP authenticates, it does not authorize applications.

1. Token model

Token	Format	Typical TTL	Issued by	Validated by
Authorization code	Opaque	5–10 min	OAuth engine	Engine (token endpoint)
OAuth access token	JWT ES256	30 min	Engine + hook	Client app via JWKS
Refresh token	Opaque, rotating	30 days	OAuth engine	OAuth engine
ID token (OIDC)	JWT ES256	30 min	Engine + hook	Client app
Internal B Brands JWT	JWT HS256	Short (900s exchange)	Exchange endpoint	B Brands internal authorizer

Key distinction: ES256 tokens prove identity and are consumed by the client app — they never reach the B Brands APIs. The HS256 token is consumed by the B Brands APIs via the existing internal authorizer.

Canonical OAuth access token claims (identity + account dimension)

{
  "iss": "https://auth.bbrands.io",
  "sub": "<user_id uuid>",
  "aud": "bbrands-idp",
  "exp": 1734268800,
  "iat": 1734267000,
  "jti": "<uuid>",
  "email": "user@example.com",
  "client_id": "<client uuid>",
  "https://bbrands.io/client_handle": "<client_handle>",
  "https://bbrands.io/platform_type": "<platform_type>",
  "https://bbrands.io/profile": {
    "account": "<account.document_id | null>",
    "odoo": "<account.external_id | null>",
    "user": "<user_id uuid>"
  }
}

Inviolable rules: iss is always the per-environment auth.* URL; aud is always the fixed IdP audience bbrands-idp; the requesting client is carried in https://bbrands.io/client_handle; jti is always present and drives the blacklist; there is no permissions or role claim. The https://bbrands.io/profile claim carries tenancy context only: account is the account bound to the user strictly through the primary_user role (one primary user per account), odoo is that account’s external system id (null until the account is mapped by the migration API) and user mirrors sub. The UserInfo endpoint returns the same object.

Client-side validation

import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://auth.bbrands.io/.well-known/jwks.json"),
  { cooldownDuration: 30_000, cacheMaxAge: 3_600_000 },
);

export async function validateAccessToken(token: string, myHandle: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://auth.bbrands.io",
    audience: "bbrands-idp",
    algorithms: ["ES256"],
  });
  if (payload["https://bbrands.io/client_handle"] !== myHandle) {
    throw new Error("Token was issued for another client");
  }
  return payload; // identity + account profile, never permissions
}

2. Where authorization lives

Scenario	Who authorizes	Mechanism
User acts inside a client app	The client app	Its own permission/group model
Client app consumes the B Brands APIs	B Brands	Existing internal RBAC
M2M process (no user) consumes the APIs	B Brands	API key + per-key permissions

The exchange JWT grants the client the user’s full permissions in B Brands (no per-client least-privilege). Acceptable for trusted first-party clients; introduce scoping in the exchange if you need to narrow it.

3. Secret management

Secret	Generated	Stored in B Brands	Stored in client	Rotation
OAuth `client_secret`	B Brands at onboarding	hashed in the engine	client secret manager	90 days
Provisioning webhook secret	B Brands at onboarding	for signing	to verify	180 days
Internal signing secret (HS256)	B Brands	server env	n/a	On suspected compromise
Engine service key	Engine	server env	n/a	365 days
ES256 signing key	Engine	managed KMS	n/a	Annual, with overlap
API key (M2M)	B Brands	hashed at rest	client secret manager	Existing policy

Storage rules: never in the repository, never in logs (mask Authorization headers), never in webhook payloads, encrypted at rest, access restricted to IdP admins.

`client_secret` rotation

Admin clicks Rotate

B Brands generates a new secret.

Grace period

Old and new are accepted simultaneously for a configurable grace window (default 24h).

Client updates config

At any point during the grace window.

Grace ends

The old secret stops being accepted; audit logs the rotation.

ES256 signing key rotation

The engine supports kid-based rotation. Generate the new key, keep both active, wait the max access-token TTL (30 min) + buffer (1h), retire the old key, then remove after retention. The JWKS endpoint must expose both during the window.

4. Threat model (mini-STRIDE)

#	Threat	Mitigation
T1	`client_secret` theft	Rotation, anomalous-use alerts, optional IP allowlist
T2	Authorization code interception	TLS + PKCE + `state`
T3	Token replay	`jti` + blacklist + short TTL
T4	Consent-screen phishing	Clear UI, no auto-approve without proper `trust_level`
T5	Long-TTL exchange JWT	Mandatory short TTL + blacklist
T6	User compromise	MFA in B Brands, anomalous-login alerts, kill switch
T7	API key theft (M2M)	Least privilege, rotation, audit
T8	Webhook replay	Idempotent `event_id`
T9	Forged webhook	HMAC signature + IP allowlist
T10	Hook compromise	Code review, deploy from main, change audit
T11	Client A token presented to client B	Each client validates `https://bbrands.io/client_handle`
T12	Timing attack on secret check	Constant-time comparison
T13	Revocation race	Blacklist checked on every validation

5. Revocation levels

Level	Scope	Immediate effect	How
L1: Single token	One access / exchange token	Yes (blacklist)	`POST /oauth/revoke`
L2: User session	All user refresh tokens	Next refresh fails	Engine admin API
L3: User × platform	Tokens for that client/user	Next refresh/exchange fails (≤ TTL)	`DELETE /idp/access/:user/:client`
L4: Whole client	All tokens of that client	Next refresh fails; live tokens last ≤ TTL	`POST /idp/clients/:handle/suspend`
L5: Whole user (kill switch)	All enablements, all platforms	Immediate if combined with blacklist	Kill-switch routine

6. Audit requirements

Immutable: append-only, no UPDATE/DELETE.
Traceable: actor, ip, user_agent, correlation_id.
Retention: 12 months online, longer in cold storage.
Exportable: /idp/audit/users/:id/export for GDPR/compliance.
Never logged: full tokens (only jti prefix), plaintext secrets, passwords.

7. Defense in depth

Layer	Control
Network	TLS, HSTS, strict CORS, WAF
OAuth client	PKCE, `state`, exact redirect URI, validate `iss` + `client_handle`
OAuth endpoint	Rate limit, strict validation, audit
Hook	Enablement check, failsafe-deny on error
Exchange	Verify subject token + enablement + short TTL + blacklist
Internal token	HS256, internal RBAC, blacklist
Operational	Admin MFA, audit log, alerts, runbooks

Get Started

API Documentation

OAuth & Identity (IdP)

Monitoring & Infrastructure

Realtime (Pusher)

Notifications (OneSignal)

1. Token model

Canonical OAuth access token claims (identity + account dimension)

Client-side validation

2. Where authorization lives

3. Secret management

`client_secret` rotation

ES256 signing key rotation

4. Threat model (mini-STRIDE)

5. Revocation levels

6. Audit requirements

7. Defense in depth

​1. Token model

​Canonical OAuth access token claims (identity + account dimension)

​Client-side validation

​2. Where authorization lives

​3. Secret management

​client_secret rotation

​ES256 signing key rotation

​4. Threat model (mini-STRIDE)

​5. Revocation levels

​6. Audit requirements

​7. Defense in depth

1. Token model

Canonical OAuth access token claims (identity + account dimension)

Client-side validation

2. Where authorization lives

3. Secret management

`client_secret` rotation

ES256 signing key rotation

4. Threat model (mini-STRIDE)

5. Revocation levels

6. Audit requirements

7. Defense in depth