Auth_db Module

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

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

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")

This is the name of the column holding 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")

This is the name of the column holding 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")

This is the name of the column holding 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")

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")

This parameter tells the server whether it should use plaintext passwords or a pre-calculated HA1 string for authentification.

If the parameter is set to 1 and the username parameter of credentials contains also “@domain” (some user agents append the domain to the username parameter), then the server will use the HA1 values from the column specified in the “password_column_2” parameter. If the username parameter doesn't contain a domain, the server will use the HA1 values from the column given in the “password_column”parameter.

If the parameter is set to 0 then the HA1 value will be calculated from the column specified in the “password_column” 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)

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)
		

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:

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")

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)
		

The function verifies credentials according to 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:

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE.

...
if (www_authorize("siphub.net", "subscriber")) {
	www_challenge("siphub.net", "1");
};
...

The function verifies credentials according to 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:

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE.

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