---
title: 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](/doc/authentication) 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 {#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 {#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 {#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 {#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 {#anonymous}

Allows login without credentials, using a generated temporary username.

Mechanisms:

- `ANONYMOUS`

## oauthbearer {#oauthbearer}

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

Mechanisms:

- `OAUTHBEARER`

## external {#external}

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

Mechanisms:

- `EXTERNAL`

# Which mechanisms are offered? {#offered_mechanisms}

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](https://blog.prosody.im/channel-binding/)
  for more information on channel binding.
- [mod_saslauth](/doc/modules/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](/doc/developers/sasl#backend-profiles).