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 and digest authentication

  • TLS authentication allows to accept or denied a request by basing 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 declared the domains which are authorized to connect to the proxy. Requests which the domain of the From identity isn't authorized will be rejected without any authentication trying. If no domain are declared, any request will be rejected.

[module::Authentication]
enabled=true

# authorized users of example.org and example2.org
# users from other domains will be denied
auth-domains=example.com example2.org

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

A1 = MD5(user1:example.org:secret) = d3e352aa5b45dd0c75e503ef317b3fe7

Choose the digest algorithms

While digest authentication, the password is given to the server as digest. The algorithm to use to make 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). We called this first response 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 sent the same request but with the response to the challenge in it, which the server will accept or deny according the validity of the response.

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

[module::Authentication]

# challenges using MD5 only
available-algorithms=MD5

# challenges using both MD5 and SHA-256
# First challenge in the response is MD5
available-algorithms=MD5 SHA-256

# challenges using both MD5 and SHA-256
# First challenge in the response is SHA-256
available-algorithms=SHA-256 MD5

The example above shows that the challenges are put in the same order in the challenge response than the order of the algorithms in  available-algorithms. Please keep in mind however that a client may response to the second challenge even if it is able to compute the repose for the first one.

Configure the location of the password database

Use a static file as database

[module::Authentication]
db-implementation=file
file-path=/etc/flexisip/userdb

userdb file may look like this:

version:1

user1@example.org clrtxt:secret ;
user2@example.org md5:a6535e7d6fa4c5bd8d7a30b4bfe29fe0 ;
user3@example.org md5:bc76718853458c5c10e75f50c6c4e63d sha256:658b71a22ff5a861a394c31e88b06f51a7e62a3aa54119edca9ad820adf68972 ;

In this example:

  • the password of user1 is secret and is stored as plain so that Flexisip will be 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 over algorithms are available ;
  • the A1 of user3 is available as MD5 and SHA-256.

Use an SQL database

[module::Authentication]
db-implementation=soci
soci-backend=mysql
soci-connection-string=db=mydb user=user password='pass' host=myhost.com
soci-password-request=<your custom SQL request>

 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 on which you want TLS authentication. Using require-peer-certificate will make incoming connection to be refused if the client certificate isn't signed by a valid authority. TLS authentication will be bypass for requests coming from transports without require-peer-certificate enabled.

[global]
# Make all SIPS transports to require a valid client certificate
require-peer-certificate=true

# or make a client certificate to be required by some transports
transport=<sips:1.2.3.4;require-peer-certificate=1> <sips:localhost>

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 that 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 that matches one of the SIP URI given by the trusted-client-certificates parameter.
  3. The CN of one subject in the certificate is a domain name that 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 that matches the domain of the Request-URi.

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

If a request is not authorized by TLS authentication, it will 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

Tags: