Overview

Authentication is handled by the Authentication module.

The main role of this module is to validate (by any method) that the sender of a request is the owner of the SIP identity given by the From header. If the validation succeeds, the request can pass through to be processed by the subsequent modules. Otherwise, the request is stopped and a response with an appropriate SIP error code is sent back to the sender.

Two authentication methods are supported:

• TLS authentication: allows to accept or refuse a request based on a potential client certificate.
• Digest authentication: checks the password of the sender by using a password database (see Digest Access Authentication).

TLS authentication is systematically performed before the digest authentication when a client certificate has been provided. A successful TLS authentication makes the request to be accepted, bypassing the digest authentication. However, what happens when the TLS authentication fails depends of the reject-wrong-client-certificates parameter.

Digest authentication cannot be disabled.

Enabling authentication

Of course, the Authentication module must be enabled.

Next, you have to declare the domains which are authorized to connect to the proxy. Requests from which the domain of the From identity aren't authorized will be rejected without any authentication tries. If no domain are declared, any request will be rejected.

Once a request enters the Authentication module, it cannot pass through without being correctly authenticated. However, you may bypass the module on some request criteria by using a Filter.

Configure digest authentication (mandatory)

About hashed passwords (A1)

Digests (A1) which are stored in the database are not digest of the simple password but of a concatenation of the username, the realm and the password, separated by columns. By default, the realm is the domain of the user's SIP identity.

For example, given the password of user1@example.org is secret, then

Choose the digest algorithms

During the digest authentication, the password is given to the server as digest. The algorithm used to compute the digest is imposed by the server and is notified to the client by responding to the request using a reserved error code (401 for REGISTER requests and 407 for INVITEs). This first response is called the "challenge", because it contains all the information to compute the digest which is required by the server (digest algorithm, salt, etc.).

After receiving the challenge, the client sends the same request but with the response to the challenge. Then, the server will accept or refuse according to the validity of the response.

The available-algorithms parameter allows to customize the algorithms which will be used in the challenge. Several algorithms may be specified, the challenge response will contain several challenges in this case ; thus the client may response to one of them or both.

Configure the location of the password database

Use a static file as database

userdb file may look like this:

In this example:

• the password of user1 is secret and is stored as plain so that Flexisip is able to make a challenge for each algorithm in available-algorithm ;
• the A1 of user2 has been hashed by MD5 ; only an MD5 challenge will be generated even if other algorithms are available ;
• the A1 of user3 is available as MD5 and SHA-256.

Use an SQL database

 See the reference documentation of soci-password-request to know how to write your request.

TLS authentication

Enabling

SIPS transports must be set for checking x509 client certificates either by using require-peer-certificate global parameter or by adding require-peer-certificate=1 on each transports to which you want TLS authentication. Using require-peer-certificate will make incoming connections to be refused if the client certificate isn't signed by a valid authority. TLS authentication will be bypassed for requests coming from transports without require-peer-certificate enabled.

Authorization checks

A request with a trusted client certificate is accepted if one of the following conditions is fulfilled, in the given order:

1. The CN of one subject in the certificate is a SIP URI which matches the SIP URI of the From header.
2. (non-REGISTER request only)The CN of one subject in the certificate is a SIP URI which matches one of the SIP URIs given by the trusted-client-certificates parameter.
3. The CN of one subject in the certificate is a domain name which matches the domain of the SIP URI of the From header.
4. (non-REGISTER request only and if trust-domain-certificates=true) The CN of one subject in the certificate is a domain name which matches the domain of the Request-URi.

Furthermore, if a regex has been given by the tls-client-certificate-required-subject parameter, the CN which has been picked out by the process above must match the regex to accept the request.

If a request is not authorized by TLS authentication, it will be carried out by the digest authentication except if reject-wrong-client-certificates=true ; the request will be refused by replying "403 Bad tls client certificate" in this case.

See also

Reference documentation of the Authentication module