Authentication

xmppd supports two authentication backends, selected by the master supervisor based on configuration.

Local Authentication (xmppd-auth)#

The default backend. Credentials are stored locally in LMDB using SCRAM-SHA-256 derived keys.

Supported SASL mechanisms:

  • SCRAM-SHA-256 — recommended, supports channel binding
  • PLAIN — simple username/password (requires TLS)

Channel Binding (XEP-0440)#

xmppd supports SASL channel binding for enhanced security:

  • tls-server-end-point — binds to the server's TLS certificate
  • tls-exporter — binds to the TLS session (TLS 1.3)

Channel binding prevents man-in-the-middle attacks by cryptographically linking the SASL exchange to the TLS connection.

Rate Limiting#

Authentication attempts are rate-limited per IP address and per account:

[auth]
max_per_account = 5     # Max attempts per account per window
max_per_ip = 20         # Max attempts per IP per window
window_seconds = 120    # Window duration
lockout_threshold = 10  # Failures before temporary lockout
lockout_duration = 300  # Lockout duration in seconds

Account Lockout#

Two types of lockout:

  • Temporary — triggered by rate limiting (auto-expires after lockout_duration)
  • Permanent — set via xmppctl lock (persists until xmppctl unlock)

In-Band Registration (XEP-0077)#

Users can register accounts from their XMPP client if enabled:

[auth]
registration = true
require_invite = true   # Require invitation code

When require_invite = true, users need an invitation code created by an admin:

xmppctl invite create
# Output: INV-a1b2c3d4e5f6

OIDC Authentication (xmppd-auth-oidc)#

For environments with an existing Identity Provider (Rauthy, Keycloak, etc.), xmppd can delegate authentication to an OIDC provider.

Enable by adding an [oidc] section to the configuration. The master will spawn xmppd-auth-oidc instead of xmppd-auth.

[oidc]
issuer = https://auth.example.com/auth/v1
client_id = xmppd
client_secret = your-client-secret
token_endpoint = https://auth.example.com/auth/v1/oidc/token
jwks_uri = https://auth.example.com/auth/v1/oidc/certs
introspection_endpoint = https://auth.example.com/auth/v1/oidc/tokenInfo

Supported SASL mechanisms:

  • OAUTHBEARER (RFC 7628) — client presents a Bearer token directly
  • PLAIN — delegated to the IdP via Resource Owner Password Credentials (ROPC)

JWT Verification#

The OIDC backend verifies JWTs locally using the IdP's JWKS endpoint:

  • RS256 and EdDSA (Ed25519) signature algorithms
  • JWKS key cache with 1-hour TTL and automatic refresh on kid miss
  • Token introspection fallback (RFC 7662) for opaque tokens

JID Extraction#

The XMPP JID localpart is extracted from the JWT email claim. For example, alice@example.com becomes alice as the XMPP localpart.

Avatar Import#

On first login via OIDC, xmppd fetches the user's picture claim from the IdP's userinfo endpoint and stores it as a vCard photo. This gives new users an avatar immediately without manual setup.