Security Best Practices

Integration checklist

Use this checklist to verify your integration follows security best practices:

Authentication flow

• Use Authorization Code flow with PKCE — Never use the Implicit flow. PKCE (S256) is mandatory.
• Validate the state parameter — Generate a random value, store it in the session, and verify it on callback to prevent CSRF attacks.
• Exchange the code server-side — The token exchange (code → tokens) must happen on your backend, never in the browser.
• Store the client secret server-side — Never expose it in frontend code, mobile apps, or version control.

Token handling

• Validate ID token signatures — Use the JWKS endpoint to verify the token was signed by Trousseau. Most OIDC libraries do this automatically.
• Check iss and aud claims — Verify the issuer matches your Trousseau issuer URL and the audience matches your client ID.
• Check token expiration (exp) — Reject expired tokens.
• Use short-lived access tokens — Access tokens expire in 5 minutes. Use refresh tokens to get new ones.
• Store refresh tokens securely — Encrypt at rest. Never send to the frontend. Rotate on use.

Session management

• Create your own application sessions — Don't rely solely on OIDC tokens for session state. Create a server-side session after validating the ID token.
• Implement logout properly — Clear your application session AND redirect to Trousseau's end-session endpoint to kill the SSO session.
• Handle backchannel logout (recommended) — Implement the backchannel logout endpoint to handle Trousseau-initiated logouts.

Network and infrastructure

• HTTPS only — All redirect URIs must use HTTPS. Trousseau rejects HTTP redirect URIs in production.
• Register exact redirect URIs — Don't use wildcards. Each redirect URI should be exact.
• Pin your issuer URL — Don't fetch the issuer dynamically from untrusted input.

Common mistakes to avoid

Storing tokens in localStorage

Problem: localStorage is accessible to any JavaScript on the page. An XSS vulnerability would leak all tokens.

Solution: Store tokens in HTTP-only cookies or server-side sessions.

Skipping token validation

Problem: Accepting an ID token without verifying its signature means anyone can forge a token.

Solution: Always validate using the JWKS endpoint. Use a trusted OIDC library that handles this.

Not implementing logout

Problem: Clearing only your application session leaves the Trousseau session active. The user can re-authenticate silently without entering credentials.

Solution: Always redirect to the end-session endpoint on logout. See the SSO Logout guide.

Hardcoding endpoint URLs

Problem: Endpoint URLs may change. Hardcoding them makes your integration fragile.

Solution: Use the OpenID Discovery endpoint (.well-known/openid-configuration) to resolve all URLs dynamically at startup.

Trousseau security measures

These measures are enforced on Trousseau's side and apply to all users in the ecosystem:

Password policies

See Password Policies for full details.

Multi-factor authentication

MFA is optional but available to all users. Supported methods:

Users enable MFA from their Trousseau account settings. If configured, MFA is prompted during every login — your application does not need to implement anything.

Infrastructure

Provisioning API security

If you have access to the provisioning API:

• Store the API token securely — Treat it like a password. Never commit to version control.
• Use HTTPS only — All API calls must use HTTPS.
• Scope your queries — Always filter by your group to avoid accessing users outside your scope.
• Don't delete users — Use deactivation (is_active: false) instead of deletion.
• Rotate tokens periodically — Request a new API token from the KeySuite team if you suspect compromise.

Reporting security issues

If you discover a security vulnerability in Trousseau or the OIDC integration:

1. Do not disclose it publicly
2. Contact the KeySuite security team at security@keysuite.app
3. Include steps to reproduce if possible
4. We aim to acknowledge within 24 hours and resolve critical issues within 72 hours