Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

JSON web token for enterprise

Tuwunel can accept signed JSON Web Tokens as proof of identity, both as a login flow (POST /_matrix/client/v3/login with type = org.matrix.login.jwt) and as a User-Interactive Authentication step for sensitive operations.

This is an enterprise feature intended for managed deployments where identity is owned by an external system. Two typical uses:

  • Externalized user management. A hosting provider or corporate identity service mints short-lived JWTs for its users; Tuwunel becomes a stateless consumer of those tokens and creates Matrix accounts on first login.

  • Account override. An operator-controlled signing key can mint a token that authenticates as any user for password resets, key recovery, or legal compliance without modifying the user’s credentials.

JWT login requires the jwt_login build feature, which is included in the default build. If you build without the default features and need JWT login, include jwt_login in your feature selection.

Warning

A binary built without jwt_login refuses to start with enable = true in [global.jwt].

Enabling JWT

The minimum configuration to accept JWTs is enable = true and a key:

[global.jwt]
enable = true
key = "yJKn0!E2g$5Hs!rUv9NQwL@ZmpQ3xVT"

With these defaults, Tuwunel will accept any HS256-signed token whose sub claim is the localpart of an MXID on this server.

POST /_matrix/client/v3/login then accepts:

{
  "type": "org.matrix.login.jwt",
  "token": "<jwt>"
}

GET /_matrix/client/v3/login advertises the flow as long as enable = true.

The sub (subject) claim is the localpart of the user’s MXID. Tuwunel combines it with this server’s server_name to form the full MXID. The subject is lowercased before lookup.

For a server with server_name = "matrix.example.org", a token with "sub": "alice" authenticates as @alice:matrix.example.org. The token issuer must agree with the server on this naming.

Configuration reference

FieldDefaultDescription
enablefalseMaster switch for JWT login. Also gates the UIAA flow.
key""Verification key. Plaintext, base64, or PEM depending on format. Sensitive: keep private when used as an HMAC secret.
format"HMAC"One of HMAC, B64HMAC, ECDSA, EDDSA, in any case (HMACB64 is also accepted for B64HMAC). Selects how key is decoded.
algorithm"HS256"JWT alg header value. Must be compatible with format.
register_usertrueAuto-create a Matrix account on first valid login if the user doesn’t already exist. Set to false to require pre-existing accounts.
expire_access_tokenfalseExpire the access token of a JWT login after access_token_ttl and withhold its refresh token, so the token issuer decides how long a login lasts. See Session lifetime.
audience[]Optional list of accepted aud claim values. When non-empty, tokens must claim at least one entry; aud becomes a required claim.
issuer[]Optional list of accepted iss claim values. When non-empty, tokens must claim at least one entry; iss becomes a required claim.
require_expfalseIf true, tokens without an exp claim are rejected. Defaults to false for Synapse compatibility.
require_nbffalseIf true, tokens without an nbf claim are rejected.
validate_exptrueWhen exp is present, enforce that the token has not expired.
validate_nbftrueWhen nbf is present, enforce that the token has reached its validity window.

key is also accepted under the alias secret to match Synapse config files.

Migrating from Synapse

Synapse’s JWT support uses a configuration of similar shape. To migrate a Synapse experimental_features.jwt_config block:

SynapseTuwunel
enabledenable
secretkey (also accepted as secret for direct migration)
algorithmalgorithm
audiencesaudience
issuerissuer (now a list; wrap a single value as ["..."])

Synapse defaults to optional exp/nbf and accepts the localpart in the sub claim. Tuwunel matches both behaviors out of the box, so a straight key+algorithm port should authenticate the same set of tokens.

Account lifecycle

The first time a token authenticates as a user that does not yet exist:

  • If register_user = true, Tuwunel creates the account with origin "jwt" and a placeholder password marker. The local password field is never read for a JWT-authenticated user; they can only re-authenticate by presenting another valid JWT.
  • If register_user = false, the request fails with M_NOT_FOUND and the account is not created.

Subsequent logins reuse the existing account. A deactivated account is refused with M_USER_DEACTIVATED, as it is for password login; a valid token does not bring it back.

JWT does not synchronize admin status, group membership, or display names; the token grants login only. If you need ongoing identity attribute synchronization, use LDAP or an OIDC identity provider instead.

Session lifetime

A JWT is checked once, at login. The session it opens then follows the usual rules: the access token never expires unless the client asks for a refresh token, and a refresh token keeps the session going for as long as it lasts, which by default is indefinitely. The JWT’s own exp has no say, so a login can far outlast the token that opened it.

Warning

A client that cannot obtain a fresh JWT would be signed out for good. This is why expire_access_token is off by default.

When you enable the option, remove the devices of earlier sessions once. With the option enabled, a JWT login retires its device’s refresh token. A client that only refreshes never logs in again and can keep refreshing. An access token issued without an expiry also keeps working.

Set expire_access_token to let the token issuer decide instead:

[global.jwt]
enable = true
key = "..."
expire_access_token = true
require_exp = true

Every JWT login then gets an access token that expires after access_token_ttl, and no refresh token, even when the client asks for one. Once the token expires the client is soft-logged-out: its requests fail with M_UNKNOWN_TOKEN and soft_logout: true, and it keeps its device and encryption keys. To stay signed in, it logs in with a fresh JWT and the same device_id.

The option also has limits to plan around:

  • The lifetime is server-wide. It comes from access_token_ttl in [global.authentication] (7 days by default), not from the JWT’s exp, and the same setting governs every session holding a refresh token.

  • The JWT itself must expire. A client can log in again with any JWT that is still valid, so have the issuer set exp, and keep require_exp = true to refuse a token without one.

  • Other sign-in routes stay open. Password, LDAP and SSO logins keep their usual lifetimes. A fresh JWT also passes the interactive authentication of /login/get_token, and the login token it yields opens a session outside this option. To hold a JWT-only deployment to the issuer’s decision, close both:

    [global.authentication.login]
    via_existing_session = false
    with_password = false
    

    with_password = false also turns off LDAP sign-in.

UIAA: JWT for account override

When enable = true, the m.login.jwt UIAA stage becomes available alongside m.login.password and m.login.sso for sensitive operations that require interactive re-authentication (deactivate account, change password, add 3PID, etc.).

A JWT presented at the UIAA stage validates the user but does not auto-register: the token’s subject must already exist as a Matrix account. This restriction prevents an account-override flow from accidentally creating new accounts when an operator intends only to substitute identity for an existing one.

A typical operator workflow for a forced password reset:

  1. Sign a JWT with sub set to the target user’s localpart.

  2. Submit it as the auth field of POST /_matrix/client/v3/account/password. The request must carry an access token; without one it is refused with 401 M_MISSING_TOKEN. An operator with no session can open one by logging in with a JWT for the same user (org.matrix.login.jwt, above). That login adds a device to the user’s account, so log it out (POST /_matrix/client/v3/logout) once the password is changed.

    {
      "auth": {
        "type": "org.matrix.login.jwt",
        "token": "<jwt>"
      },
      "new_password": "<new password>"
    }
    
  3. Tuwunel validates the signature, confirms the user exists, and completes the password change without ever consulting the user’s existing credentials.

Limit access to the signing key accordingly. Anyone with the HMAC secret, or the matching ECDSA/EdDSA private key, can authenticate as any user on the server.

Key formats and algorithms

format selects how key is interpreted. algorithm selects the JWT signing algorithm. The two must agree. Format names are case-insensitive. HMACB64 is also accepted for B64HMAC.

Warning

While enable = true, Tuwunel refuses to start or reload its configuration if key is empty or format is not one of the supported names below.

If key cannot be decoded or algorithm does not suit the format, Tuwunel reports the error at each login instead.

FormatAlgorithmKey content
HMAC (default)HS256, HS384, HS512Plaintext shared secret.
B64HMACHS256, HS384, HS512Base64-encoded shared secret, in the standard alphabet (+ and /) with = padding. Use this when the secret contains non-printable bytes.
ECDSAES256, ES384PEM-encoded ECDSA public key.
EDDSAEdDSAPEM-encoded Ed25519 public key.

For asymmetric formats (ECDSA, EDDSA) the key is the public key: Tuwunel only verifies, it never signs. The corresponding private key stays with the issuer.

# HMAC shared secret (Synapse-compatible default)
format = "HMAC"
algorithm = "HS256"
key = "..."

# ECDSA public-key
format = "ECDSA"
algorithm = "ES256"
key = """-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----"""

Time-bounded tokens

exp (expiration) and nbf (not-before) follow the spec semantics: seconds since the Unix epoch. Configure based on the issuer’s behavior:

  • Issuer always sets exp: set require_exp = true to reject any token without an expiration. validate_exp is true by default.
  • Issuer never sets exp: leave both require_exp and validate_exp at their defaults; tokens without exp are accepted as non-expiring (use cautiously).
  • Mixed: leave require_exp = false and validate_exp = true (the defaults). This is Synapse-compatible: exp is optional but enforced when present.

nbf is symmetric with exp and most deployments leave it unset on both issuer and consumer.

Audience and issuer validation

By default no aud or iss validation is performed. To restrict acceptance to tokens issued by, or destined for, specific systems, set the respective config field:

audience = ["https://matrix.example.org"]
issuer   = ["https://idp.example.org"]

When set, the corresponding claim becomes required in addition to being checked against the allowed list. Multiple values are treated as “any of these is acceptable.”