Client certificate authentication
Clients connected to MongooseIM may authenticate with their TLS certificates.
This method uses the
SASL EXTERNAL mechanism.
Properly configure Client-to-server (C2S) listener
A server must request the certificate from a client, so you'll need to enable
verify_peer option and provide a path to CA chain that may be used for client's certificate check (
Please check the Listener modules page for more information or simply follow the examples at the end of this section.
SASL EXTERNAL authentication is also possible for WebSocketSecure and BOSH connections over HTTPS.
Similarly as in the
client-to-server case, the server must request the certificate from the client.
In this case it's enabled by adding the following options to the
tls option of
tls.verify_peer = true- this is to tell Erlang's SSL to request the cert from the client
tls.cacertfile = "ca.pem"- this is to tell Erlang's SSL where the CA cert file is in order to check if the cert is correctly signed
Please check Options: Listen for more details regarding
http listener configuration.
SASL EXTERNAL mechanism
SASL EXTERNAL authentication mechanism is disabled by default.
In order to enable it, please configure
auth.sasl_mechanisms option in the MongooseIM config file.
Obviously the list may be longer, if the system should support both the certificate and password based authentication.
SASL EXTERNAL authentication mechanism requires a digital client certificate.
This digital certificate should contain
xmppAddr field(s), which is always checked first.
If there is more than one JID specified in the
xmppAddr fields, the client must include the authorisation entity which corresponds to the one of the specified JIDs.
xmppAddr is specified, the
cn (common name) field might be used to provide the client's username, but it is optional and can be configured with the
sasl_external option in the
If the client certificate does not contain a JID, the client must provide one in authorisation entity.
For the details please refer to XEP-0178: Best Practices for Use of SASL EXTERNAL with Certificates.
Enable compatible authentication method
You need to enable one of the following authentication methods by using the
auth.methods option in the MongooseIM configuration file.
"pki"- accepts user credentials,
"http"- accepts user credentials if the provided certificate is known and valid
"ldap"- accepts user credentials if a corresponding user account exists in LDAP.
By default MongooseIM doesn't accept self-signed certs for the SASL-EXTERNAL authentication. For development purposes, it is possible to tell MongooseIM to accept them.
Self-signed certificates for regular TCP/TLS connections
In order to tell MongooseIM to accept self-signed certs, the
listen.c2s.tls.verify_mode option needs to be configured like below:
1 2 3
tls.disconnect_on_failure is a boolean with the following meaning only for
true- the connection is closed if a certificate is invalid,
false- the connection isn't closed, but the certificate is not returned if it's invalid. This leads to an authentication failure but allows the client to choose a different auth method if available.
fast_tls backend, the configuration is the same, only the
disconnect_on_failure is ignored.
Self-signed certificates for WS or BOSH
In order to accept self-signed certs for WS or BOSH connections, the
tls options for
http listener must have the following configured:
Certificate authentication only.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
Authentication with a client certificate (validated with provided CA chain) or password (validated with data stored in RDBMS).
1 2 3 4 5 6 7 8 9
Client certificate prerequisites
SASL EXTERNAL will be offered by the server only when a client provides a valid certificate.
Please check documentation of a specific authentication backend you're going to use.
Usage example - Gajim
Verified with Gajim 0.16.8, installed from package
Generate client certificate
1 2 3 4 5 6
See examples in the section above. We recommend using the first snippet for simplicity.
You don't need to pre-create a user account in order to log in with a certificate.
Add an account in Gajim
- Edit -> Accounts -> Add.
- Pick "I already have an account I want to use".
- Jabber ID is
[Common Name from certificate]@localhost(domain is different if you've changed it in
hostsoption). Press "Next".
- Untick "Connect when I press Finish" and press "Advanced".
- Unfold "Client certificate" and choose the
.p12you've created earlier. Tick "Certificate is encrypted".
- Click "Close" and set status to "Available". Tell Gajim to ignore the unverified server certificate (by default it's self-signed).
If Gajim fails to connect, try to restart it. Version 0.16.8 sometimes "forgets" to ask for the client certificate password.