SASL profiles

This is a technical document describing how Prosody (and XMPP) handles authentication. You are not required to understand it - everything should work out of the box. But if you are thinking of customizing your setup or you are debugging authentication mechanisms, this page is here to help you.

XMPP clients authenticate to the server using a standard protocol called ‘SASL’. SASL isn’t one kind of authentication, but a framework which supports various mechanisms, each with different properties and features, strengths and weaknesses. Because of SASL, we are able to integrate with a wide range of backends for authentication, but not all of them are equal.

Prosody’s authentication providers supply backend profiles, rather than implementing SASL mechanisms themselves. Each profile provides a particular way of checking credentials, such as retrieving a password or testing a supplied password.

Each of Prosody’s SASL mechanisms declare which profiles they can use. A mechanism is available if the configured authentication provider supplies at least one of its supported profiles.

An authentication provider can supply multiple profiles; the available mechanisms are the combined set enabled by those profiles. The module’s documentation lists the profiles it supplies.

This page describes the profiles supported by Prosody’s built-in SASL library. Providers using a separate SASL implementation, such as Cyrus SASL, determine their mechanisms independently.

Profiles

plain

An authentication provider supporting this profile provides access to the user’s plaintext password. This allows a lot of flexibility, and is compatible with most mechanisms. The downside is that it means the user’s plaintext password is being stored somewhere.

Mechanisms:

  • PLAIN
  • SCRAM-SHA-1 and SCRAM-SHA-1-PLUS
  • SCRAM-SHA-256 and SCRAM-SHA-256-PLUS

plain_test

This profile means the authentication provider cannot provide Prosody with the plaintext password, but it can tell it whether a given password is correct or not. This obviously requires the client to send us the password.

Because this profile requires the client to send us the password, it is not compatible with challenge-response mechanisms such as SCRAM which only send a hash of the password.

Mechanisms:

  • PLAIN

scram_sha_1

In this profile, the authentication provider can give Prosody SCRAM credentials derived using SHA-1: stored key, server key, iteration count and salt.

Mechanisms:

  • SCRAM-SHA-1 and SCRAM-SHA-1-PLUS

scram_sha_256

In this profile, the authentication provider can give Prosody SCRAM credentials derived using SHA-256: stored key, server key, iteration count and salt.

Mechanisms:

  • SCRAM-SHA-256 and SCRAM-SHA-256-PLUS

anonymous

Allows login without credentials, using a generated temporary username.

Mechanisms:

  • ANONYMOUS

oauthbearer

Validates a bearer token and identifies the account it grants access to.

Mechanisms:

  • OAUTHBEARER

external

Checks an identity authenticated outside SASL, for example using a TLS client certificate.

Mechanisms:

  • EXTERNAL

Which mechanisms are offered?

Profile support determines which mechanisms are compatible with the authentication provider, but does not guarantee that all of them will be advertised on every connection:

  • The SCRAM mechanisms ending in -PLUS require TLS channel binding. Prosody must have a channel binding handler available for the connection, e.g. using tls-exporter. See this blog post for more information on channel binding.
  • mod_saslauth can filter mechanisms through disable_sasl_mechanisms and insecure_sasl_mechanisms. Encryption requirements can also prevent the availability of weaker mechanisms on unencrypted connections.
  • The client must support one of the offered mechanisms and have suitable credentials.

Developer documentation is available which describes profile callback signatures and implementation details, see Writing SASL handlers.