SASL Authentication Mechanisms API Reference

Strophe.js implements SASL (Simple Authentication and Security Layer) authentication through a pluggable mechanism system. Each mechanism extends the SASLMechanism base class and is selected automatically based on priority and server capability advertisement. You can register custom mechanisms, adjust priorities, or disable built-in mechanisms entirely to fit your application’s security requirements.

SASLMechanism Base Class

The SASLMechanism class is the abstract base from which all SASL mechanisms are derived. It defines the lifecycle hooks that Strophe.js calls during the authentication exchange. To implement a custom mechanism, extend this class and override the relevant methods.

Constructor

new SASLMechanism(name: string, isClientFirst: boolean, priority: number)

name

string

required

The SASL mechanism name as advertised in the XMPP stream features (e.g. 'SCRAM-SHA-256'). This becomes the mechname property.

isClientFirst

boolean

required

Set to true if the client sends the first message in the authentication exchange without waiting for a server challenge. When true, Strophe.js calls clientChallenge() before the first onChallenge() invocation.

priority

number

required

Numeric priority used when multiple mechanisms are available. Higher numbers take precedence. Strophe.js selects the mechanism with the highest priority that both the client and server support.

Properties

mechname

string

The SASL mechanism name string. Set by the constructor from the name argument.

isClientFirst

boolean

Whether the client sends the opening authentication message before receiving a server challenge.

priority

number

The mechanism’s selection priority. Higher values are preferred over lower values when the server supports multiple mechanisms.

_connection

Connection | null

Reference to the active Connection instance. Set by onStart() and cleared by both onSuccess() and onFailure(). Prefixed with _ to indicate it is managed internally.

Methods

test(_connection): boolean

Called to determine whether this mechanism can be used for the current connection. Return false to disable the mechanism entirely or conditionally based on connection state.

test(_connection: Connection): boolean

_connection

Connection

The connection being authenticated.

The default implementation always returns true. Override this method to add conditional logic — for example, requiring that authcid is set:

test(connection: Connection): boolean {
  return connection.authcid !== null;
}

To permanently disable a built-in mechanism at runtime, override test to return false on its prototype. See the Disabling a Mechanism section below.

onStart(connection): void

Called by Strophe.js immediately before the authentication exchange begins. The base implementation stores the connection reference in this._connection.

onStart(connection: Connection): void

connection

Connection

required

The connection that is about to begin authentication. Stored as this._connection.

Override this method if you need to perform setup work before the exchange starts, but always call super.onStart(connection) to ensure _connection is set.

onChallenge(_connection, _challenge?): string | Promise<string | false>

Called each time the server sends an authentication challenge. The return value is sent back as the client’s response. This method must be overridden; the base implementation throws an error.

onChallenge(
  _connection: Connection,
  _challenge?: string
): string | Promise<string | false>

_connection

Connection

required

The active connection instance.

_challenge

string

The challenge string received from the server. May be undefined on the first call for non-client-first mechanisms.

Return a plain string for synchronous mechanisms, or a Promise<string | false> for async mechanisms such as SCRAM variants. Return false (or resolve to false) to signal an authentication failure.

clientChallenge(connection): string | Promise<string | false>

Called instead of onChallenge() for the very first message when isClientFirst is true. The base implementation delegates to onChallenge(connection). SCRAM-based mechanisms override this to generate the client-first message with a nonce.

clientChallenge(connection: Connection): string | Promise<string | false>

connection

Connection

required

The active connection instance.

Calling clientChallenge() when isClientFirst is false throws an error. The method guards against this case in the base implementation.

onSuccess(): void

Called by Strophe.js when the server confirms authentication success. The base implementation clears this._connection. Override this to perform post-authentication cleanup or state management.

onSuccess(): void

onFailure(): void

Called by Strophe.js when authentication fails. The base implementation clears this._connection. Override this to handle failure states or reset internal mechanism data.

onFailure(): void

Built-in Mechanisms

Strophe.js ships with nine built-in SASL mechanisms. When the server advertises multiple supported mechanisms, Strophe.js selects the one with the highest priority that passes its test() check. The default priorities from highest to lowest are:

Mechanism	Class	Priority
SCRAM-SHA-512	`SASLSHA512`	72
SCRAM-SHA-384	`SASLSHA384`	71
SCRAM-SHA-256	`SASLSHA256`	70
SCRAM-SHA-1	`SASLSHA1`	60
PLAIN	`SASLPlain`	50
OAUTHBEARER	`SASLOAuthBearer`	40
X-OAUTH2	`SASLXOAuth2`	30
ANONYMOUS	`SASLAnonymous`	20
EXTERNAL	`SASLExternal`	10

SASLAnonymous — ANONYMOUS (priority 20)

Provides anonymous authentication without any user credentials. The server assigns a temporary JID for the session duration.

Property	Value
`mechname`	`'ANONYMOUS'`
`isClientFirst`	`false`
`priority`	`20`

test() behavior: Returns true only when connection.authcid is null, meaning no username has been supplied.

import { SASLAnonymous } from 'strophe.js';

// SASLAnonymous is used automatically when no authcid is provided
const conn = new Strophe.Connection('wss://xmpp.example.com/ws');
conn.connect('example.com', null, onConnect); // authcid = null → ANONYMOUS selected

Use ANONYMOUS when building guest sessions, read-only chat clients, or any context where persistent identity is not required.

SASLExternal — EXTERNAL (priority 10)

Delegates authentication to an external mechanism, typically a client TLS certificate. The client sends its authorization identity (or an empty string if authcid matches authzid).

Property	Value
`mechname`	`'EXTERNAL'`
`isClientFirst`	`true`
`priority`	`10`

onChallenge() behavior: Returns connection.authzid unless authcid === authzid, in which case it returns an empty string, signalling the server should derive the identity from the certificate.

// The TLS certificate presented at the transport layer carries credentials.
// Strophe sends the authzid (or empty string) as the EXTERNAL response.
const conn = new Strophe.Connection('wss://xmpp.example.com/ws');
conn.connect('user@example.com', '', onConnect);

EXTERNAL requires that the underlying transport (WebSocket or BOSH) is secured by mutual TLS. Do not use EXTERNAL over unencrypted connections.

SASLOAuthBearer — OAUTHBEARER (priority 40)

Implements RFC 7628 OAuth 2.0 Bearer Token authentication. The OAuth access token is passed as connection.pass.

Property	Value
`mechname`	`'OAUTHBEARER'`
`isClientFirst`	`true`
`priority`	`40`

test() behavior: Returns true when connection.pass is not null.onChallenge() behavior: Constructs the GS2 bearer token message in the format n,[a=authzid],\x01auth=Bearer <token>\x01\x01, UTF-16 to UTF-8 encoded.

const accessToken = await getOAuthToken(); // your OAuth flow

const conn = new Strophe.Connection('wss://xmpp.example.com/ws');
conn.connect('user@example.com', accessToken, onConnect);

SASLPlain — PLAIN (priority 50)

Transmits the username and password in plaintext (null-separated). Simple and widely supported but must only be used over an encrypted transport (TLS/WSS).

Property	Value
`mechname`	`'PLAIN'`
`isClientFirst`	`true`
`priority`	`50`

test() behavior: Returns true when connection.authcid is not null.onChallenge() behavior: Constructs the string [authzid]\x00authcid\x00password (omitting authzid prefix when it equals authcid@domain), then encodes it as UTF-8.

const conn = new Strophe.Connection('wss://xmpp.example.com/ws');
conn.connect('user@example.com', 'secret', onConnect);

Never use PLAIN over an unencrypted connection. Prefer a SCRAM-SHA variant whenever the server supports it — SCRAM provides mutual authentication and never transmits the raw password.

SASLSHA1 — SCRAM-SHA-1 (priority 60)

Implements SCRAM (Salted Challenge Response Authentication Mechanism) using SHA-1 as the hash function, as defined in RFC 5802.

Property	Value
`mechname`	`'SCRAM-SHA-1'`
`isClientFirst`	`true`
`priority`	`60`

test() behavior: Returns true when connection.authcid is not null.Uses the Web Crypto API (crypto.subtle) with PBKDF2 key derivation. The clientChallenge() method generates a random nonce and constructs the client-first message. The onChallenge() method processes the server challenge and returns the client-final message.

SHA-1 is considered weak for new deployments. Prefer SCRAM-SHA-256 or higher when the server supports it. Strophe.js automatically selects the highest-priority mechanism the server offers.

SASLSHA256 — SCRAM-SHA-256 (priority 70)

SCRAM authentication using SHA-256, as defined in RFC 7677. Recommended for general use.

Property	Value
`mechname`	`'SCRAM-SHA-256'`
`isClientFirst`	`true`
`priority`	`70`

test() behavior: Returns true when connection.authcid is not null.Uses crypto.subtle with 'SHA-256' and 256-bit key derivation. Provides mutual authentication — both the client verifies the server and the server verifies the client.

// SCRAM-SHA-256 is selected automatically when the server advertises it
const conn = new Strophe.Connection('wss://xmpp.example.com/ws');
conn.connect('user@example.com', 'secret', onConnect);

SASLSHA384 — SCRAM-SHA-384 (priority 71)

SCRAM authentication using SHA-384. Offers a slightly larger security margin than SHA-256 at a small performance cost.

Property	Value
`mechname`	`'SCRAM-SHA-384'`
`isClientFirst`	`true`
`priority`	`71`

test() behavior: Returns true when connection.authcid is not null.Uses crypto.subtle with 'SHA-384' and 384-bit key derivation via PBKDF2.

SASLSHA512 — SCRAM-SHA-512 (priority 72)

SCRAM authentication using SHA-512. This is the highest-priority built-in mechanism and will be selected first whenever the server supports it.

Property	Value
`mechname`	`'SCRAM-SHA-512'`
`isClientFirst`	`true`
`priority`	`72`

test() behavior: Returns true when connection.authcid is not null.Uses crypto.subtle with 'SHA-512' and 512-bit key derivation via PBKDF2. Provides the strongest security of all built-in SCRAM variants.

SASLXOAuth2 — X-OAUTH2 (priority 30)

Google’s proprietary X-OAUTH2 extension mechanism. Passes an OAuth 2.0 access token as connection.pass. This is a non-standard extension primarily used with Google Talk / Google Workspace XMPP services.

Property	Value
`mechname`	`'X-OAUTH2'`
`isClientFirst`	`true`
`priority`	`30`

test() behavior: Returns true when connection.pass is not null.onChallenge() behavior: Constructs \x00[authzid]\x00token encoded as UTF-8.

const conn = new Strophe.Connection('wss://talk.google.com/ws');
conn.connect('user@gmail.com', oauthToken, onConnect);

Prefer OAUTHBEARER (RFC 7628) for new OAuth 2.0 integrations. X-OAUTH2 is a legacy mechanism and may not be supported by all servers.

Custom Mechanisms

You can implement your own SASL mechanism by extending SASLMechanism and passing it via the mechanisms connection option. Strophe.js will include it in mechanism selection alongside the built-ins.

import Strophe, { SASLMechanism } from 'strophe.js';
import type Connection from 'strophe.js/connection';

class MySASLMechanism extends SASLMechanism {
  constructor() {
    super('MY-MECH', true, 60);
  }

  test(connection: Connection): boolean {
    return connection.authcid !== null;
  }

  async onChallenge(connection: Connection, challenge?: string): Promise<string | false> {
    // Process the server challenge and return the response string.
    // Return false to abort authentication.
    return btoa(connection.authcid + ':' + connection.pass);
  }
}

// Pass the class (not an instance) via the mechanisms option
const conn = new Strophe.Connection('wss://xmpp.example.com/ws', {
  mechanisms: [MySASLMechanism],
});

The mechanisms option accepts an array of mechanism classes. Strophe.js instantiates them internally. Custom mechanisms are merged with the built-ins — pass only [MySASLMechanism] if you want to restrict authentication to your mechanism exclusively, or include additional built-in classes alongside it.

Disabling a Mechanism

To permanently disable a built-in mechanism for all connections in a runtime, override its test method to return false:

import { SASLPlain } from 'strophe.js';

// Disable PLAIN authentication globally — forces use of SCRAM or other mechanisms
SASLPlain.prototype.test = () => false;

To disable a mechanism only for a specific connection, use the mechanisms option to provide an explicit allowlist:

import Strophe, { SASLSHA256, SASLSHA512 } from 'strophe.js';

// Only allow SCRAM-SHA-256 and SCRAM-SHA-512
const conn = new Strophe.Connection('wss://xmpp.example.com/ws', {
  mechanisms: [SASLSHA256, SASLSHA512],
});

Connection

Stanza Building

SASL Mechanisms

Utilities & Constants

SASL Authentication Mechanisms API Reference

SASLMechanism Base Class

Constructor

Properties

Methods

Built-in Mechanisms

Custom Mechanisms

Disabling a Mechanism

Build docs developers (and LLMs) love

Connection

Stanza Building

SASL Mechanisms

Utilities & Constants

Documentation Index

​SASLMechanism Base Class

​Constructor

​Properties

​Methods

​Built-in Mechanisms

​Custom Mechanisms

​Disabling a Mechanism

Build docs developers (and LLMs) love

SASLMechanism Base Class

Constructor

Properties

Methods

Built-in Mechanisms

Custom Mechanisms

Disabling a Mechanism