Table of Contents
List of Tables
List of Examples
db_url
parameter usageuser_column
parameter usagedomain_column
parameter usagepassword_column
parameter usagepassword_column_2
parameter usagecalculate_ha1
parameter usageuse_domain
parameter usageload_credentials
parameter usageskip_version_check
parameter usagewww_authorize
usageThis 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.
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)
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”.
Example 1.1. db_url
parameter usage
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”.
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”.
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”.
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.
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.
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)”.
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”.
Example 1.8. load_credentials
parameter usage
# load rpid column into $avp(13) and email_address column # into $avp(email_address) modparam("auth_db", "load_credentials", "$avp(13)=rpid;email_address")
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:
-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 - 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 - Table to be used to lookup usernames and passwords (usually subscribers table).
This function can be used from REQUEST_ROUTE.
Example 1.10. www_authorize
usage
... 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:
-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 - 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 - Table to be used to lookup usernames and passwords (usually subscribers table).
This function can be used from REQUEST_ROUTE.
Example 1.11. proxy_authorize usage
... if (!proxy_authorize("", "subscriber)) { proxy_challenge("", "1"); # Realm will be autogenerated } ...
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
Name | DevScore | Commits | Lines ++ | Lines -- | |
---|---|---|---|---|---|
1. | Jan Janak (@janakj) | 50 | 29 | 1610 | 424 |
2. | Bogdan-Andrei Iancu (@bogdan-iancu) | 40 | 32 | 332 | 236 |
3. | Daniel-Constantin Mierla (@miconda) | 29 | 20 | 130 | 382 |
4. | Liviu Chircu (@liviuchircu) | 14 | 11 | 40 | 71 |
5. | Henning Westerholt (@henningw) | 11 | 9 | 83 | 49 |
6. | Razvan Crainea (@razvancrainea) | 9 | 7 | 29 | 47 |
7. | Sergio Gutierrez | 7 | 5 | 13 | 13 |
8. | Andrei Pelinescu-Onciul | 6 | 4 | 81 | 33 |
9. | Dan Pascu (@danpascu) | 5 | 3 | 31 | 6 |
10. | Jiri Kuthan (@jiriatipteldotorg) | 5 | 3 | 5 | 2 |
All remaining contributors: Maksym Sobolyev (@sobomax), Anatoly Pidruchny, Kennard White, Konstantin Bokarius, Richard Revels, Julián Moreno Patiño, Norman Brandinger (@NormB), Edson Gellert Schubert, Ionut Ionita (@ionutrazvanionita), Vlad Patrascu (@rvlad-patrascu).
(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. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
Name | Commit Activity | |
---|---|---|
1. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jun 2005 - Jun 2020 |
2. | Liviu Chircu (@liviuchircu) | Mar 2014 - Nov 2019 |
3. | Razvan Crainea (@razvancrainea) | Jun 2011 - Sep 2019 |
4. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - May 2017 |
5. | Julián Moreno Patiño | Feb 2016 - Feb 2016 |
6. | Ionut Ionita (@ionutrazvanionita) | Jan 2015 - Jan 2015 |
7. | Richard Revels | Sep 2011 - Sep 2011 |
8. | Kennard White | Jun 2011 - Jun 2011 |
9. | Dan Pascu (@danpascu) | Feb 2006 - Jul 2010 |
10. | Sergio Gutierrez | Nov 2008 - Mar 2009 |
All remaining contributors: 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
Last edited by: Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Razvan Crainea (@razvancrainea), Kennard White, Sergio Gutierrez, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw), Anatoly Pidruchny, Jan Janak (@janakj).
doc copyrights:
Copyright © 2005 Voice Sistem SRL
Copyright © 2002-2003 FhG FOKUS