AUTH_DB module

Admin Guide

Overview

This module contains all authentication related functions that need the access to the database. This module should be used together with auth module, it cannot be used independently because it depends on the module. Select this module if you want to use database to store authentication information like subscriber usernames and passwords. If you want to use radius authentication, then use auth_radius instead.

Dependencies

OpenSIPS Modules

The module depends on the following modules (in the other words the listed modules must be loaded before this module):

auth — Generic authentication functions
database — Any database module (currently mysql, postgres, dbtext)

External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

none

Exported Parameters

db_url (string)

This is URL of the database to be used. Value of the parameter depends on the database module used. For example for mysql and postgres modules this is something like mysql://username:password@host:port/database. For dbtext module (which stores data in plaintext files) it is directory in which the database resides.

Default value is “mysql://opensipsro:opensipsro@localhost/opensips”.

modparam("auth_db", "db_url", "dbdriver://username:password@dbhost/dbname")

calculate_ha1 (integer)

This parameter tells the server whether it should considered the loaded password (for authentification) as plaintext passwords or a pre-calculated HA1 string.

Possible meanings of this parameter are:

1 (calculate HA1) - the loaded password is a plaintext password, so OpenSIPS will internally calculate the HA1. As the passwords will be loaded from the column specified in the “password_column” parameter, be sure this parameter points to a column holding a plaintext password (by default, this parameter points to “ha1” column);
0 (do NOT calculate HA1) - the loaded password is an already computed HA1 value, so OpenSIPS does not have do any further computing (for HA1 value). Depending on the presence of a “@domain” part (some user agents append the domain to the username credentials parameter too), the modules will load the password (pre-computed HA1) from the “password_column_2” column (if domain present) or from the “password_column” column (if domain not present). Usually, most of the UAs do NOT include a domain part in the username credentials parameter.

The “password_column_2” column contains also HA1 strings but they should be calculated including the domain in the username parameter (as opposed to password_column which (when containing HA1 strings) should always contain HA1 strings calculated without domain in username.

This ensures that the authentication will always work when using pre-calculated HA1 strings, not depending on the presence of the domain in username.

Default value of this parameter is 0.

modparam("auth_db", "calculate_ha1", 1)

use_domain (integer)

If true (not 0), domain will be also used when looking up in the subscriber table. If you have a multi-domain setup, it is strongly recommended to turn on this parameter to avoid username overlapping between domains.

IMPORTANT: before turning on this parameter, be sure that the domain column in subscriber table is properly populated.

Default value is “0 (false)“.

modparam("auth_db", "use_domain", 1)

load_credentials (string)

This parameter specifies credentials to be fetched from database when the authentication is performed. The loaded credentials will be stored in AVPs. If the AVP name is not specificaly given, it will be used a NAME AVP with the same name as the column name.

Parameter syntax:

load_credentials = credential (’;’ credential)*
credential = (avp_specification ’=’ column_name) | (column_name)
avp_specification = ‘$avp(’ + NAME + ’)’

Default value of this parameter is “rpid”.

# load rpid column into $avp(13) and email_address column
# into $avp(email_address)
modparam("auth_db", "load_credentials", "$avp(13)=rpid;email_address")

skip_version_check (int)

This parameter specifies not to check the auth table version. This parameter should be set when a custom authentication table is used.

Default value is “0 (false)“.

modparam("auth_db", "skip_version_check", 1)

user_column (string)

This is the name of the column in a ‘SUBSCRIBER’ like table holding the usernames. Default value is fine for most people. Use the parameter if you really need to change it.

Default value is “username”.

modparam("auth_db", "user_column", "user")

domain_column (string)

This is the name of the column in a ‘SUBSCRIBER’ like table holding the domains of users. Default value is fine for most people. Use the parameter if you really need to change it.

Default value is “domain”.

modparam("auth_db", "domain_column", "domain")

password_column (string)

This is the name of the column in a ‘SUBSCRIBER’ like table holding the passwords. Passwords can be either stored as plain text or pre-calculated HA1 strings. HA1 strings are MD5 hashes of username, password, and realm. HA1 strings are more safe because the server doesn’t need to know plaintext passwords and they cannot be obtained from HA1 strings.

Default value is “ha1”.

modparam("auth_db", "password_column", "password")

password_column_2 (string)

As described in the previous section this parameter contains name of column holding pre-calculated HA1 string that were calculated including the domain in the username. This parameter is used only when calculate_ha1 is set to 0 and user agent send a credentials containing the domain in the username.

Default value of the parameter is ha1b.

modparam("auth_db", "password_column_2", "ha1_2")

uri_user_column (string)

Column holding usernames in an ‘URI’ like table.

Default value is “username”.

...
modparam("auth_db", "uri_user_column", "username")
...

uri_domain_column (string)

Column holding domain in an ‘URI’ like table.

Default value is “domain”.

...
modparam("auth_db", "uri_domain_column", "domain")
...

uri_uriuser_column (string)

Column holding URI username in an ‘URI’ like table.

Default value is “uri_user”.

...
modparam("auth_db", "uri_uriuser_column", "uri_user")
...

Exported Functions

www_authorize(realm, table)

The function verifies the received credentials against a “SUBSCRIBER”-like table according to digest authentication as per RFC2617. If the credentials are verified successfully then the function will succeed and mark the credentials as authorized (marked credentials can be later used by some other functions). If the function was unable to verify the credentials for some reason then it will fail and the script should call www_challenge which will challenge the user again.

Negative codes may be interpreted as follows:

-5 (generic error) - some generic error occurred and no reply was sent out;
-4 (no credentials) - credentials were not found in request;
-3 (stale nonce) - stale nonce;
-2 (invalid password) - valid user, but wrong password;
-1 (invalid user) - authentication user does not exist.

Meaning of the parameters is as follows:

realm (string) - Realm is an opaque string that the user agent should present to the user so it can decide what username and password to use. Usually this is domain of the host the server is running on. If an empty string "" is used then the server will generate it from the request. In case of REGISTER requests To header field domain will be used (because this header field represents a user being registered), for all other messages From header field domain will be used. The string may contain pseudo variables.
table (string) - Table to be used to lookup usernames and passwords (usually subscribers table).

This function can be used from REQUEST_ROUTE.

...
if (!www_authorize("siphub.net", "subscriber"))
  www_challenge("siphub.net", "auth");
...

proxy_authorize(realm, table)

The function verifies the received credentials against a “SUBSCRIBER”-like table according to digest authentication as per RFC2617. If the credentials are verified successfully then the function will succeed and mark the credentials as authorized (marked credentials can be later used by some other functions). If the function was unable to verify the credentials for some reason then it will fail and the script should call proxy_challenge which will challenge the user again.

Negative codes may be interpreted as follows:

-5 (generic error) - some generic error occurred and no reply was sent out;
-4 (no credentials) - credentials were not found in request;
-3 (stale nonce) - stale nonce;
-2 (invalid password) - valid user, but wrong password;
-1 (invalid user) - authentication user does not exist.

Meaning of the parameters is as follows:

realm (string) - Realm is an opaque string that the user agent should present to the user so it can decide what username and password to use. Usually this is domain of the host the server is running on. If an empty string "" is used then the server will generate it from the request. From header field domain will be used as realm. The string may contain pseudo variables.
table (string) - Table to be used to lookup usernames and passwords (usually subscribers table).

This function can be used from REQUEST_ROUTE.

...
if (!proxy_authorize("", "subscriber"))
  proxy_challenge("", "auth");  # Realm will be autogenerated
...

db_is_to_authorized(table)

The function checks against a ‘URI’ like table to see if the username extracted from the To header URI is allowed/authorized to use the credentials (authentication username) validated by www authorize.

The function is part of the mechanism that allows to create mapping between the SIP users (from the FROM/TO headers) and the authentication users (from a SUBSCRIBER-like table) that they use. The mapping is stored into an URI-like table.

Meaning of the parameters is as follows:

table (string) - Table to be used to lookup for the URI/AUTH mappings (usually the URI table).

This function can be used from REQUEST_ROUTE.

...
if (!db_is_to_authorized("uri")) {
  xlog("User $tu is not authorized to authenticate with $au credential\n");
}
...

db_is_from_authorized(table)

Similar to db is to authorized but instead of checking the TO header URI, the FROM header URI is checked.

db_does_uri_exist(uri, table)

Checks if the username@domain from the given URI is an existing user in a ‘SUBSCRIBER’ like table.

Meaning of the parameters is as follows:

uri (string) - The SIP URI to be tested. It must hold a username part for a valid check. Variables are allowed.
table (string) - Table to be used to search for the URI (usually the SUBSCRIBER table).

This function can be used from REQUEST_ROUTE.

...
if (db_does_uri_exist($ru, "subscriber")) {
  ...
}
...

db_get_auth_id(table, uri, auth, realm)

Checks given uri-string username against an ‘URI’ like table. Returns true if the user exists in the database, and sets the given variables to the authentication id and realm corresponding to the given uri.

Meaning of the parameters is as follows:

table (string) - Table to be used to search for the URI (usually the URI table).
uri (string) - The input SIP URI to be tested. It must hold a username part for a valid check. Variables are allowed.
auth (var) - an output variable to store the found authentication id matching the given SIP URI.
realm (var) - an output variable to store the found authentication realm matching the given SIP URI.

This function can be used from REQUEST_ROUTE ,FAILURE_ROUTE and LOCAL_ROUTE.

...
if (db_get_auth_id("uri", $ru, $avp(auth_id), $avp(auth_realm))) {
  ...
}
...

Tips & FAQ

How to recalculate ha1 and ha1b

When you change the domain column in the subscriber table, you have to recalculate ha1 and ha1b fields. In order to do that you must have the password of each subscriber.

HA1 is a MD5 hash of “username:domain:password”. For example, if you have created a SIP account “1000@mydomain.com” using password “123456”, then HA1 is the MD5 hash of “1000:mydomain.com:123456” (without quotes). On the other hand HA1B is the MD5 hash of “username@domain:domain:password”; so using the same example above, HA1B would be the MD5 hash of “1000@mydomain.com:mydomain.com:123456” (without quotes).

To recalculate and update ha1 and ha1b columns in the subscriber table, just execute the following sql statement in mysql:

update subscriber
set ha1 = md5(concat(username, ':', domain, ':', password)),
ha1b = md5(concat(username, '@', domain, ':', domain, ':', password))

If you use a static challenge for www_authorize() (i.e. the first parameter of www_authorize() is not the empty string), then HA1 is MD5(“username:challenge:password”) and HA1B is MD5(“username@challenge:challenge:password”). If the challenge parameter of www_authorize() is empty, OpenSIPS automatically selects the domain as the challenge value, which gives the solution presented above.

If use_domain is false, then the HA1B field must be computed based on “username@:domain:password” or “username@:challenge:password”, depending on whether challenge is empty or defined, respectively.

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Bogdan-Andrei Iancu (@bogdan-iancu)	59	38	1389	501
2.	Jan Janak (@janakj)	51	29	1639	453
3.	Daniel-Constantin Mierla (@miconda)	30	20	323	385
4.	Liviu Chircu (@liviuchircu)	19	14	154	179
5.	Stefan Darius (@dariusstefan)	13	4	662	139
6.	Henning Westerholt (@henningw)	11	9	85	51
7.	Razvan Crainea (@razvancrainea)	10	8	32	50
8.	Vlad Patrascu (@rvlad-patrascu)	9	4	89	183
9.	Sergio Gutierrez	7	5	13	13
10.	Andrei Pelinescu-Onciul	6	4	81	33

All remaining contributors: Dan Pascu (@danpascu), Jiri Kuthan (@jiriatipteldotorg), Maksym Sobolyev (@sobomax), Anatoly Pidruchny, Kennard White, Konstantin Bokarius, Peter Lemenkov (@lemenkov), Julián Moreno Patiño, Richard Revels, Norman Brandinger (@NormB), Edson Gellert Schubert, Ionut Ionita (@ionutrazvanionita).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Bogdan-Andrei Iancu (@bogdan-iancu)	Jun 2005 - Jun 2026
3.	Razvan Crainea (@razvancrainea)	Jun 2011 - Jun 2026
4.	Liviu Chircu (@liviuchircu)	Mar 2014 - Mar 2021
5.	Vlad Patrascu (@rvlad-patrascu)	May 2017 - Jul 2019
6.	Peter Lemenkov (@lemenkov)	Jun 2018 - Jun 2018
7.	Julián Moreno Patiño	Feb 2016 - Feb 2016
8.	Ionut Ionita (@ionutrazvanionita)	Jan 2015 - Jan 2015
9.	Richard Revels	Sep 2011 - Sep 2011
10.	Kennard White	Jun 2011 - Jun 2011

All remaining contributors: Dan Pascu (@danpascu), Sergio Gutierrez, Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Anatoly Pidruchny, Norman Brandinger (@NormB), Jan Janak (@janakj), Andrei Pelinescu-Onciul, Maksym Sobolyev (@sobomax), Jiri Kuthan (@jiriatipteldotorg).

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Peter Lemenkov (@lemenkov), Kennard White, Sergio Gutierrez, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw), Anatoly Pidruchny, Jan Janak (@janakj).

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0