Embedded IAM configuration

Generated from schemas/embedded-iam.schema.json by scripts/gen-config-docs. Do not edit this page: edit the schema or the generator.

The optional cladone-auth embedded IAM configuration. Secrets are read from the environment; a *Env field names the variable.

Fields

Field Type Required Description

Field	Type	Required	Description
`publicUrl`	string	yes	External origin of the IAM, without a trailing slash (for example https://auth.example.com).
`listen`	string	no	Default listen address for cmd/cladone-auth (for example :8081).
`sessionCookieName`	string	no	IAM SSO cookie shared by all applications in one browser. Default cladone_iam_sid.
`tenants`	array of object	yes	Isolated issuers. Each tenant has its own key, client, upstream identity providers and policy.
`redis`	object	no	Shared store for flows, codes, refresh tokens and the revocation keyspace read by Gate One. Absent = in-memory store, single instance and tests only.
`smtp`	object	no	Outbound mail relay for local-account verification emails.

publicUrl

string

yes

External origin of the IAM, without a trailing slash (for example https://auth.example.com).

listen

string

Default listen address for cmd/cladone-auth (for example :8081).

sessionCookieName

string

IAM SSO cookie shared by all applications in one browser. Default cladone_iam_sid.

tenants

array of object

yes

Isolated issuers. Each tenant has its own key, client, upstream identity providers and policy.

redis

object

Shared store for flows, codes, refresh tokens and the revocation keyspace read by Gate One. Absent = in-memory store, single instance and tests only.

smtp

object

Outbound mail relay for local-account verification emails.

tenants

Field Type Required Description

Field	Type	Required	Description
`id`	string	yes	Tenant identifier; also the /t/{tenant} path segment and default audience. Minimum length: 1.
`clientId`	string	yes	Gate One OIDC client id registered with this tenant. Minimum length: 1.
`clientSecret`	string	no	Inline client secret. Prefer clientSecretEnv so the secret never lands in the file. Write-only; prefer the `*Env` form.
`clientSecretEnv`	string	no	Environment variable holding the Gate One client secret.
`redirectUris`	array of string	yes	Allowed Gate One callback URLs (https, or localhost for tests).
`postLogoutRedirectUris`	array of string	no	Allowed post-logout targets. List every application origin as https://app.example.com/* (the host Gate One sends as post_logout_redirect_uri). Empty falls back to redirectUris, which covers only the login host, so a logout from an application host would be refused.
`audiences`	array of string	no	Audiences allowed for access tokens. Empty = the tenant id.
`google`	object	no	Upstream OIDC identity provider configuration. The google key defaults to the Google issuer; other keys require issuer, clientId/Env and clientSecret/Env.
`upstreams`	map of object	no	Named OIDC upstreams (google, microsoft, …). The key is the idp authorize parameter and the chooser label.
`keyFile`	string	no	Active Ed25519 private key file (base64 raw seed). Empty = ephemeral key, tests/dev only. Mutually exclusive with keyFiles.
`keyFiles`	array of string	no	Published keys, oldest first, newest active. Used to rotate tokens without invalidating old ones.
`defaultRoles`	array of string	no	Roles granted to every authenticated user.
`allowedDomains`	array of string	no	Allowed upstream hosted/email domains. Empty = no restriction.
`adminEmails`	array of string	no	Email addresses granted the admin role.
`groupRoles`	map of string to array of string	no	Map an upstream group/claim value to IAM roles.
`accessTokenTtlSeconds`	integer	no	Access token lifetime in seconds. Default 600. Minimum: 1.
`idTokenTtlSeconds`	integer	no	ID token lifetime in seconds. Default 600. Minimum: 1.
`refreshTokenTtlSeconds`	integer	no	Refresh token lifetime in seconds. Default 2592000 (30 days). Gate One reads it from discovery to size revocation. Minimum: 1.
`sessionTtlSeconds`	integer	no	IAM SSO session lifetime in seconds. Default 43200 (12 hours). Minimum: 1.
`localAccounts`	boolean	no	Enable the local account lifecycle endpoints (register, verify email) for this tenant. Requires smtp.
`appOrigins`	array of string	no	Allowed application origins for a verification continueUrl.
`registrationSecretEnv`	string	no	Environment variable gating POST /register (server-to-server registration).
`mappings`	array of object	no	Ordered mapping rules translating upstream claims into IAM roles/scopes/claims. Evaluated on every federated login; results are not persisted on the user. The legacy groupRoles block remains supported for the groups claim.
`rules`	array of object	no	when/then policy rules: test the incoming token’s claims (when) and grant rights (then), including derived roles (rolesFrom) and copied claims (copyClaims). Evaluated on every login; results are not persisted on the user.

id

string

yes

Tenant identifier; also the /t/{tenant} path segment and default audience. Minimum length: 1.

clientId

string

yes

Gate One OIDC client id registered with this tenant. Minimum length: 1.

clientSecret

string

Inline client secret. Prefer clientSecretEnv so the secret never lands in the file. Write-only; prefer the *Env form.

clientSecretEnv

string

Environment variable holding the Gate One client secret.

redirectUris

array of string

yes

Allowed Gate One callback URLs (https, or localhost for tests).

postLogoutRedirectUris

array of string

Allowed post-logout targets. List every application origin as https://app.example.com/* (the host Gate One sends as post_logout_redirect_uri). Empty falls back to redirectUris, which covers only the login host, so a logout from an application host would be refused.

audiences

array of string

Audiences allowed for access tokens. Empty = the tenant id.

google

object

Upstream OIDC identity provider configuration. The google key defaults to the Google issuer; other keys require issuer, clientId/Env and clientSecret/Env.

upstreams

map of object

Named OIDC upstreams (google, microsoft, …). The key is the idp authorize parameter and the chooser label.

keyFile

string

Active Ed25519 private key file (base64 raw seed). Empty = ephemeral key, tests/dev only. Mutually exclusive with keyFiles.

keyFiles

array of string

Published keys, oldest first, newest active. Used to rotate tokens without invalidating old ones.

defaultRoles

array of string

Roles granted to every authenticated user.

allowedDomains

array of string

Allowed upstream hosted/email domains. Empty = no restriction.

adminEmails

array of string

Email addresses granted the admin role.

groupRoles

map of string to array of string

Map an upstream group/claim value to IAM roles.

accessTokenTtlSeconds

integer

Access token lifetime in seconds. Default 600. Minimum: 1.

idTokenTtlSeconds

integer

ID token lifetime in seconds. Default 600. Minimum: 1.

refreshTokenTtlSeconds

integer

Refresh token lifetime in seconds. Default 2592000 (30 days). Gate One reads it from discovery to size revocation. Minimum: 1.

sessionTtlSeconds

integer

IAM SSO session lifetime in seconds. Default 43200 (12 hours). Minimum: 1.

localAccounts

boolean

Enable the local account lifecycle endpoints (register, verify email) for this tenant. Requires smtp.

appOrigins

array of string

Allowed application origins for a verification continueUrl.

registrationSecretEnv

string

Environment variable gating POST /register (server-to-server registration).

mappings

array of object

Ordered mapping rules translating upstream claims into IAM roles/scopes/claims. Evaluated on every federated login; results are not persisted on the user. The legacy groupRoles block remains supported for the groups claim.

rules

array of object

when/then policy rules: test the incoming token’s claims (when) and grant rights (then), including derived roles (rolesFrom) and copied claims (copyClaims). Evaluated on every login; results are not persisted on the user.

tenants.google

Upstream OIDC identity provider configuration. The google key defaults to the Google issuer; other keys require issuer, clientId/Env and clientSecret/Env.

Field Type Required Description

Field	Type	Required	Description
`issuer`	string	no	Upstream OIDC issuer. Default https://accounts.google.com for the google upstream; required for other upstreams.
`clientId`	string	no	Upstream OIDC client id. Prefer clientIdEnv.
`clientIdEnv`	string	no	Environment variable holding the upstream client id.
`clientSecret`	string	no	Inline upstream client secret. Prefer clientSecretEnv. Write-only; prefer the `*Env` form.
`clientSecretEnv`	string	no	Environment variable holding the upstream client secret.
`prompt`	string	no	Forwarded to the upstream authorize endpoint (for example select_account).
`hostedDomain`	string	no	Google Workspace hosted domain (hd) restriction.
`scopes`	array of string	no	Upstream scopes. Default openid, profile, email.
`displayName`	string	no	Label shown on the identity provider chooser. Default: the upstream key.
`optional`	boolean	no	Skip this upstream when its client id/secret environment variables are empty, instead of refusing startup.

issuer

string

Upstream OIDC issuer. Default https://accounts.google.com for the google upstream; required for other upstreams.

clientId

string

Upstream OIDC client id. Prefer clientIdEnv.

clientIdEnv

string

Environment variable holding the upstream client id.

clientSecret

string

Inline upstream client secret. Prefer clientSecretEnv. Write-only; prefer the *Env form.

clientSecretEnv

string

Environment variable holding the upstream client secret.

prompt

string

Forwarded to the upstream authorize endpoint (for example select_account).

hostedDomain

string

Google Workspace hosted domain (hd) restriction.

scopes

array of string

Upstream scopes. Default openid, profile, email.

displayName

string

Label shown on the identity provider chooser. Default: the upstream key.

optional

boolean

Skip this upstream when its client id/secret environment variables are empty, instead of refusing startup.

tenants.upstreams

Upstream OIDC identity provider configuration. The google key defaults to the Google issuer; other keys require issuer, clientId/Env and clientSecret/Env.

Field Type Required Description

Field	Type	Required	Description
`issuer`	string	no	Upstream OIDC issuer. Default https://accounts.google.com for the google upstream; required for other upstreams.
`clientId`	string	no	Upstream OIDC client id. Prefer clientIdEnv.
`clientIdEnv`	string	no	Environment variable holding the upstream client id.
`clientSecret`	string	no	Inline upstream client secret. Prefer clientSecretEnv. Write-only; prefer the `*Env` form.
`clientSecretEnv`	string	no	Environment variable holding the upstream client secret.
`prompt`	string	no	Forwarded to the upstream authorize endpoint (for example select_account).
`hostedDomain`	string	no	Google Workspace hosted domain (hd) restriction.
`scopes`	array of string	no	Upstream scopes. Default openid, profile, email.
`displayName`	string	no	Label shown on the identity provider chooser. Default: the upstream key.
`optional`	boolean	no	Skip this upstream when its client id/secret environment variables are empty, instead of refusing startup.

issuer

string

Upstream OIDC issuer. Default https://accounts.google.com for the google upstream; required for other upstreams.

clientId

string

Upstream OIDC client id. Prefer clientIdEnv.

clientIdEnv

string

Environment variable holding the upstream client id.

clientSecret

string

Inline upstream client secret. Prefer clientSecretEnv. Write-only; prefer the *Env form.

clientSecretEnv

string

Environment variable holding the upstream client secret.

prompt

string

Forwarded to the upstream authorize endpoint (for example select_account).

hostedDomain

string

Google Workspace hosted domain (hd) restriction.

scopes

array of string

Upstream scopes. Default openid, profile, email.

displayName

string

Label shown on the identity provider chooser. Default: the upstream key.

optional

boolean

Skip this upstream when its client id/secret environment variables are empty, instead of refusing startup.

tenants.mappings

One claim-to-rights mapping rule.

Field Type Required Description

Field	Type	Required	Description
`claim`	string	yes	Dot path into the upstream token claims, for example groups, realm_access.roles or resource_access.gate-one.roles. Minimum length: 1.
`values`	array of string	no	Values to match. If omitted, the rule matches when the claim is present and non-empty.
`roles`	array of string	no	IAM roles added when the rule matches.
`scopes`	array of string	no	IAM scopes added when the rule matches.
`claims`	map of string to any	no	Claims copied into issued tokens when the rule matches. Reserved claims (iss, sub, aud, exp, iat, jti, nonce, tenant, roles, scope, sid, email, preferred_username) are refused.

claim

string

yes

Dot path into the upstream token claims, for example groups, realm_access.roles or resource_access.gate-one.roles. Minimum length: 1.

values

array of string

Values to match. If omitted, the rule matches when the claim is present and non-empty.

roles

array of string

IAM roles added when the rule matches.

scopes

array of string

IAM scopes added when the rule matches.

claims

map of string to any

Claims copied into issued tokens when the rule matches. Reserved claims (iss, sub, aud, exp, iat, jti, nonce, tenant, roles, scope, sid, email, preferred_username) are refused.

tenants.rules

A when/then policy rule: test the incoming token’s claims and grant rights. Evaluated on every login; results are not persisted on the user.

Field Type Required Description

Field	Type	Required	Description
`when`	array of object	yes	Conditions, combined with logical AND. A single condition object is also accepted as shorthand.
`then`	object	yes	Rights granted when every condition matches.

when

array of object

yes

Conditions, combined with logical AND. A single condition object is also accepted as shorthand.

then

object

yes

Rights granted when every condition matches.

tenants.rules.when

Test one claim of the incoming token.

Field Type Required Description

Field	Type	Required	Description
`claim`	string	yes	Dot path into the upstream token claims (email, sub, groups, realm_access.roles, …). Minimum length: 1.
`match`	string (one of: `exact`, `prefix`, `suffix`, `domain`, `glob`)	no	Matching operator. Default exact. prefix/suffix/domain/glob are case-insensitive.
`values`	array of string	no	Values to match. Omitted = the claim must be present and non-empty.

claim

string

yes

Dot path into the upstream token claims (email, sub, groups, realm_access.roles, …). Minimum length: 1.

match

string (one of: exact, prefix, suffix, domain, glob)

Matching operator. Default exact. prefix/suffix/domain/glob are case-insensitive.

values

array of string

Values to match. Omitted = the claim must be present and non-empty.

tenants.rules.then

Rights granted when every condition matches.

Field Type Required Description

Field	Type	Required	Description
`roles`	array of string	no	Constant IAM roles.
`scopes`	array of string	no	Constant IAM scopes.
`claims`	map of string to any	no	Constant claims copied into issued tokens. Reserved claims are refused.
`rolesFrom`	array of object	no	Derive roles from an incoming claim’s values.
`copyClaims`	array of object	no	Copy incoming claims into issued tokens, optionally renamed and reshaped.

roles

array of string

Constant IAM roles.

scopes

array of string

Constant IAM scopes.

claims

map of string to any

Constant claims copied into issued tokens. Reserved claims are refused.

rolesFrom

array of object

Derive roles from an incoming claim’s values.

copyClaims

array of object

Copy incoming claims into issued tokens, optionally renamed and reshaped.

tenants.rules.then.rolesFrom

Turn an incoming claim’s values into IAM roles.

Field Type Required Description

Field	Type	Required	Description
`claim`	string	yes	Dot path into the upstream token claims. Minimum length: 1.
`transforms`	array of string	no	Pipeline applied to each value: lower, upper, prefix:<p>, suffix:<p>, replace:<a>:<b>, keep:<sep>:<from>[:<to>] (keep fields from..to, negative counts from the end, joined by <sep>).

claim

string

yes

Dot path into the upstream token claims. Minimum length: 1.

transforms

array of string

Pipeline applied to each value: lower, upper, prefix:, suffix:, replace:<a>:, keep:<sep>:<from>[:<to>] (keep fields from..to, negative counts from the end, joined by <sep>).

tenants.rules.then.copyClaims

Copy an incoming claim into the issued token.

Field Type Required Description

Field	Type	Required	Description
`from`	string	yes	Source claim dot path. Minimum length: 1.
`to`	string	no	Destination claim name. Default: same as from. Reserved names are refused. Minimum length: 1.
`transforms`	array of string	no	Pipeline applied to each value: lower, upper, prefix:<p>, suffix:<p>, replace:<a>:<b>, keep:<sep>:<from>[:<to>] (keep fields from..to, negative counts from the end, joined by <sep>).

from

string

yes

Source claim dot path. Minimum length: 1.

to

string

Destination claim name. Default: same as from. Reserved names are refused. Minimum length: 1.

transforms

array of string

Pipeline applied to each value: lower, upper, prefix:, suffix:, replace:<a>:, keep:<sep>:<from>[:<to>] (keep fields from..to, negative counts from the end, joined by <sep>).

redis

Shared store for flows, codes, refresh tokens and the revocation keyspace read by Gate One. Absent = in-memory store, single instance and tests only.

Field Type Required Description

Field	Type	Required	Description
`url`	string	no	Redis URL (redis:// or rediss://). Mutually exclusive with sentinel mode.
`sentinelAddrs`	array of string	no	Sentinel addresses (host:port). Required with masterName.
`masterName`	string	no	Redis master name for Sentinel discovery.
`sentinelUsername`	string	no	ACL user for the Sentinel connections (sentinel mode only).
`sentinelPasswordEnv`	string	no	Environment variable holding the Sentinel password (sentinel mode only).
`username`	string	no	Redis ACL user.
`passwordEnv`	string	no	Environment variable holding the Redis password.
`db`	integer	no	Redis database number. Default 0. Minimum: 0.
`prefix`	string	no	Key prefix for IAM state. Default cladone:iam:v1:.
`authPrefix`	string	no	Key prefix the IAM writes revocations to, read by Gate One. Default cladone:auth:v1:.
`dialTimeoutMs`	integer	no	Dial timeout in milliseconds. Minimum: 1.
`readTimeoutMs`	integer	no	Read timeout in milliseconds. Minimum: 1.
`writeTimeoutMs`	integer	no	Write timeout in milliseconds. Minimum: 1.
`poolSize`	integer	no	Connection pool size. Minimum: 1.
`tls`	boolean	no	Use TLS for the Sentinel and master/replica connections.
`tlsCaFile`	string	no	CA bundle for TLS (system roots by default). Requires tls=true.
`tlsServerName`	string	no	TLS server name, useful when Sentinels are addressed by IP. Requires tls=true.

url

string

Redis URL (redis:// or rediss://). Mutually exclusive with sentinel mode.

sentinelAddrs

array of string

Sentinel addresses (host:port). Required with masterName.

masterName

string

Redis master name for Sentinel discovery.

sentinelUsername

string

ACL user for the Sentinel connections (sentinel mode only).

sentinelPasswordEnv

string

Environment variable holding the Sentinel password (sentinel mode only).

username

string

Redis ACL user.

passwordEnv

string

Environment variable holding the Redis password.

db

integer

Redis database number. Default 0. Minimum: 0.

prefix

string

Key prefix for IAM state. Default cladone:iam:v1:.

authPrefix

string

Key prefix the IAM writes revocations to, read by Gate One. Default cladone:auth:v1:.

dialTimeoutMs

integer

Dial timeout in milliseconds. Minimum: 1.

readTimeoutMs

integer

Read timeout in milliseconds. Minimum: 1.

writeTimeoutMs

integer

Write timeout in milliseconds. Minimum: 1.

poolSize

integer

Connection pool size. Minimum: 1.

tls

boolean

Use TLS for the Sentinel and master/replica connections.

tlsCaFile

string

CA bundle for TLS (system roots by default). Requires tls=true.

tlsServerName

string

TLS server name, useful when Sentinels are addressed by IP. Requires tls=true.

smtp

Outbound mail relay for local-account verification emails.

Field Type Required Description

Field	Type	Required	Description
`host`	string	yes	SMTP host.
`port`	integer	no	SMTP port. Default 587 (STARTTLS). Minimum: 1. Maximum: 65535.
`username`	string	no	SMTP username. Prefer usernameEnv.
`usernameEnv`	string	no	Environment variable holding the SMTP username.
`passwordEnv`	string	no	Environment variable holding the SMTP password.
`from`	string	yes	From address for verification emails.

host

string

yes

SMTP host.

port

integer

SMTP port. Default 587 (STARTTLS). Minimum: 1. Maximum: 65535.

username

string

SMTP username. Prefer usernameEnv.

usernameEnv

string

Environment variable holding the SMTP username.

passwordEnv

string

Environment variable holding the SMTP password.

from

string

yes

From address for verification emails.