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
  • PLAIN - simple username/password (requires TLS)

Channel Binding (XEP-0440) - planned#

Channel binding is plumbed (gs2 flag, tls-server-end-point retrieval) but not yet negotiated: xmppd does not announce the urn:xmpp:sasl-cb:0 feature and does not offer the SCRAM-SHA-256-PLUS mechanism. When it lands, it will bind the SASL exchange to the TLS connection, preventing man-in-the-middle attacks. Tracked as issue #24.

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.