Examples on Gate One

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

This example runs entirely on your machine: no identity provider and no external service. It uses the embedded dev provider, which is loopback-only and must never be used in production.

File

examples/getting-started/routes.json

{
 "authProvider": {
 "type": "dev",
 "loginBaseUrl": "http://login.demo.localhost:3000",
 "cookieDomain": "demo.localhost"
 },
 "routes": [{
 "host": "app.demo.localhost",
 "path": "/*",
 "frontend": true,
 "backend": "http://127.0.0.1:8080",
 "auth": {},
 "userBadge": {
 "position": "right",
 "claims": ["preferred_username", "email"],
 "logoutLabel": "Sign out"
 }
 }]
}

Direct OIDC with one IdP

Mon, 01 Jan 0001 00:00:00 +0000

This example points Gate One straight at one OIDC issuer: no external IAM to federate, no embedded IAM. Gate One is the relying party; the issuer is the IdP and, because it also carries roles and scopes, the authorization source for that deployment.

A single Keycloak realm is used here, but the same shape works for any one issuer — Zitadel, Entra ID, Okta or Auth0.

Multi-app SSO

Mon, 01 Jan 0001 00:00:00 +0000

This example starts from one protected application and adds a second route behind the same authentication provider. That is what creates SSO: the provider and the shared cookie domain are already in place, and the second route reuses the same Gate One session.

Changing the provider alone does not create SSO. Adding a route alone does not create SSO either. The two routes must use the same provider and share the same cookie domain.

Cross-domain SSO

Mon, 01 Jan 0001 00:00:00 +0000

This example puts two unrelated domains behind one IdP session. Each domain keeps its own Gate One cookie; no cookie crosses the TLD boundary.

Files

Shared group, per-domain providers

{
 "ssoGroups": [{
 "id": "company",
 "issuer": "https://idp.example.com/realms/company",
 "clientId": "gate-one",
 "clientSecretEnv": "OIDC_CLIENT_SECRET",
 "sessionKeyEnv": "OIDC_SESSION_KEY",
 "sessionStore": {
 "type": "redis",
 "url": "redis://redis:6379/0",
 "prefix": "cladone:auth:v1:"
 },
 "providers": [
 {
 "id": "app-a", "loginBaseUrl": "https://login.app-a.com",
 "cookieDomain": "app-a.com", "defaultAppUrl": "https://app-a.com/"
 },
 {
 "id": "app-b", "loginBaseUrl": "https://login.app-b.fr",
 "cookieDomain": "app-b.fr", "defaultAppUrl": "https://app-b.fr/"
 }
 ]
 }],
 "defaultAuthProvider": "app-a",
 "routes": [{
 "hosts": ["app-a.com", "app-b.fr"],
 "path": "/*",
 "frontend": true,
 "backend": "http://app:8080",
 "auth": {}
 }]
}

issuer, clientId, sessionStore and sessionKeyEnv are written once. Each provider entry only carries its domain, login host and optional cookie name. The route is written once; Gate One expands it to app-a.com and app-b.fr and binds each one to its provider.

Keycloak with Google

Mon, 01 Jan 0001 00:00:00 +0000

This example uses Keycloak as the IAM and OIDC issuer, with Google as an additional identity provider inside Keycloak. Gate One only sees the Keycloak issuer; it does not configure Google directly.

browser -> Gate One -> Keycloak -> Google

Embedded IAM

Mon, 01 Jan 0001 00:00:00 +0000

This example runs the optional embedded IAM cladone-auth as the single OIDC issuer for Gate One. cladone-auth federates one or more upstream IdPs (Google, Microsoft Entra, Auth0, any OIDC issuer — each keyed under upstreams) and normalizes their claims into the roles/scopes/claims Gate One enforces.

High Availability

Mon, 01 Jan 0001 00:00:00 +0000

This example runs several Gate One replicas behind a load balancer and uses Redis as the shared OIDC session/revocation store. It is the multi-instance variant of the multi-app SSO example.

File

examples/high-availability/routes.json

{
 "authProvider": {
 "type": "oidc",
 "issuer": "https://auth.example.com/realms/company",
 "clientId": "gate-one",
 "clientSecretEnv": "OIDC_CLIENT_SECRET",
 "loginBaseUrl": "https://login.example.com",
 "cookieDomain": "example.com",
 "sessionKeyEnv": "OIDC_SESSION_KEY",
 "sessionStore": {
 "type": "redis",
 "url": "redis://redis:6379/0",
 "passwordEnv": "REDIS_PASSWORD",
 "prefix": "cladone:auth:v1:"
 }
 },
 "routes": [{
 "host": "app.example.com", "path": "/*", "frontend": true,
 "backend": "http://app:8080", "auth": {}
 }]
}

APIs and MCP

Mon, 01 Jan 0001 00:00:00 +0000

This example separates the browser session from machine tokens and exposes one MCP service with its protected-resource metadata.

File

examples/protect-api-mcp/routes.json

{
 "authProviders": [
 {
 "id": "company", "type": "oidc",
 "issuer": "https://auth.example.com/t/company",
 "clientId": "gate-one",
 "clientSecretEnv": "MYCOMPANY_OIDC_SECRET",
 "loginBaseUrl": "https://login.example.com",
 "cookieDomain": "example.com",
 "sessionKeyEnv": "MYCOMPANY_SESSION_KEY"
 },
 {
 "id": "company-api", "type": "jwt",
 "issuer": "https://auth.example.com/t/company",
 "jwksUrl": "https://auth.example.com/t/company/jwks.json",
 "audience": "https://api.example.com"
 }
 ],
 "defaultAuthProvider": "company",
 "routes": [
 {
 "host": "app.example.com", "path": "/*", "frontend": true,
 "backend": "http://app:8080", "auth": {}
 },
 {
 "host": "api.example.com", "path": "/v1/*", "backend": "http://api:8080",
 "auth": {
 "provider": "company-api",
 "identity": { "scopes": ["read:things"] }
 }
 },
 {
 "host": "mcp.example.com", "path": "/mcp", "backend": "http://mcp:8080",
 "auth": { "provider": "company-api" },
 "mcp": {
 "enabled": true, "path": "/mcp", "name": "things",
 "resource": "https://mcp.example.com", "scope": "mcp-tools",
 "operations": [{ "name": "list_things", "operationId": "listThings" }]
 }
 }
 ]
}

Own account panel

Mon, 01 Jan 0001 00:00:00 +0000

This example keeps Gate One’s frontend guard but removes the built-in user badge. The application provides a burger button and a side panel, then reads the session from Gate One.

Files

index.html — application page and panel markup
panel.js — session, login and logout
panel.css — panel styling
routes.json — route without userBadge
README.md — run notes

IAM + IdP bridge

Mon, 01 Jan 0001 00:00:00 +0000

This example configures authProvider.type: "http-bridge" and points it at a service implementing the bridge contract. The bridge can adapt SAML, LDAP, mTLS, API keys or a legacy session service; Gate One only sees /auth, /auth/mcp and /health.

Important

The bridge supplies identity and IAM facts (user, roles, scopes, claims), but Gate One remains the policy enforcement point. auth, auth.identity and MCP scope checks are still performed by Gate One on every request. The bridge never bypasses route policy.

The provider type remains http-bridge; http is its deprecated alias. The reference auth-bridge deployment is the IAM + IdP shape. A custom bridge may return only the authenticated user, in which case Gate One still enforces authentication but has no roles or scopes to check.

MCP tools

Mon, 01 Jan 0001 00:00:00 +0000

This example builds one MCP surface from three sources: a documented REST API (derived into tools), an existing MCP server (proxied) and an aggregating set that groups both under one endpoint with its own audience, scope and identity.

File

examples/mcp-tools/routes.json

Abridged (the authProviders and tokenBroker blocks are omitted here; they are in the file):

{
 "mcpSets": {
 "developer-tools": {
 "host": "mcp.example.com",
 "endpoint": "/developer-tools",
 "resource": "https://mcp.example.com/developer-tools",
 "scope": "mcp-tools",
 "identity": { "roles": ["developer"] },
 "members": [
 { "service": "github", "path": "/github",
 "tools": ["list_repos", "get_repo"] },
 { "service": "metrics", "path": "/metrics" }
 ]
 }
 },
 "routes": [
 {
 "host": "mcp.example.com",
 "path": "/github",
 "backend": "https://api.github.com",
 "auth": {},
 "upstream": { "tokenBroker": { "provider": "github" } },
 "openapi": { "url": "http://landing/github-openapi.json", "public": false },
 "mcp": {
 "enabled": true,
 "name": "github",
 "standalone": false,
 "operations": [
 { "name": "list_repos", "operationId": "list_repos" },
 { "name": "get_repo", "operationId": "get_repo" },
 { "name": "list_issues", "operationId": "list_issues" }
 ]
 }
 },
 {
 "host": "mcp.example.com",
 "path": "/metrics",
 "backend": "http://metrics-mcp:8080",
 "auth": {},
 "mcp": {
 "enabled": true,
 "name": "metrics",
 "standalone": false,
 "upstream": {
 "url": "http://metrics-mcp:8080/mcp",
 "tools": { "include": ["list_*", "get_*"], "exclude": ["*_secret"] }
 }
 }
 }
 ]
}

Injectable UX

Mon, 01 Jan 0001 00:00:00 +0000

This example runs with the dev provider and demonstrates every injection surface in one route.

Files

Route

{
 "host": "app.demo.localhost", "path": "/*", "frontend": true,
 "backend": "http://127.0.0.1:8080", "auth": {},
 "inject": "bundle.json",
 "userBadge": {
 "position": "right",
 "claims": ["preferred_username", "email"],
 "roles": ["admin"],
 "logoutLabel": "Sign out"
 },
 "uiGate": [
 { "selector": ".danger-zone", "roles": ["admin"] },
 { "selector": ".beta-feature", "hidden": "before" },
 { "selector": "[data-feature=export]", "auth": "before" }
 ],
 "authGuard": { "forbidden": { "banner": true } },
 "csp": { "mode": "nonce" },
 "pwa": {
 "enabled": true,
 "networkOnly": {
 "excludePatterns": [
 "^https://idp\\.example\\.com/.*/\\.well-known/openid-configuration",
 "^https://idp\\.example\\.com/.*/protocol/openid-connect"
 ]
 }
 }
}

Enhance a proxied site

Mon, 01 Jan 0001 00:00:00 +0000

This example puts Gate One in front of a real external site and injects a userscript into every HTML page. The browser installs no extension and the upstream site contains no Gate One code.

The example is the Wikipedia+ demo, moved from the deprecated gate-one repository. It proxies the language editions of Wikipedia and adds a dark/light toggle and a reading-time badge.

Usage plugin

Mon, 01 Jan 0001 00:00:00 +0000

This example runs the dev provider and a reference audit plugin. It is the complete signed-plugin path: manifest, artefact, trust store, WAL and event subscription.

Files

Route and usage block

{
 "authProvider": {
 "type": "dev",
 "loginBaseUrl": "http://login.demo.localhost:3000",
 "cookieDomain": "demo.localhost"
 },
 "usage": {
 "dir": "./usage-wal",
 "nodeId": "gw-demo-1",
 "budgetBytes": 52428800,
 "subjectSecretEnv": "GATE_ONE_SUBJECT_SECRET",
 "pluginSecretEnv": "GATE_ONE_PLUGIN_SECRET",
 "trustStore": "trust-store.json",
 "types": {
 "auth": { "shareBytes": 10485760, "fsync": "always" },
 "error": { "shareBytes": 10485760, "fsync": "window_ms", "windowMs": 250 }
 },
 "plugins": [{
 "name": "com.cladone.audit",
 "url": "http://127.0.0.1:9100",
 "manifest": "audit.manifest.json",
 "artifact": "audit-echo.placeholder"
 }]
 },
 "routes": [{ "host": "app.demo.localhost", "path": "/*", "frontend": true,
 "backend": "http://127.0.0.1:8080", "auth": {} }]
}

Turnstile protection

Mon, 01 Jan 0001 00:00:00 +0000

Two examples with Cloudflare’s test keys: a form (mode: forms) and a whole-page gate (mode: gate). The test keys pass without a real widget; replace them before deploying.

Form protection

[examples/turnstile/routes.json](/examples/turnstile/routes.json)

{
 "turnstile": {
 "siteKey": "1x00000000000000000000AA",
 "secretEnv": "TURNSTILE_SECRET",
 "paths": ["/contact/*"],
 "forms": ["form#contact"]
 },
 "authProvider": {
 "type": "dev",
 "loginBaseUrl": "http://login.demo.localhost:3000",
 "cookieDomain": "demo.localhost"
 },
 "routes": [{
 "host": "app.demo.localhost", "path": "/*", "frontend": true,
 "backend": "http://127.0.0.1:8080"
 }]
}