AUTH_JWT module
Admin Guide
Section titled “Admin Guide”Overview
Section titled “Overview”The module implements authentication over JSON Web Tokens. In some cases ( ie. WebRTC ) the user authenticates on another layer ( other than SIP ), so it makes no sense to double-authenticate it on the SIP layer. Thus, the SIP client will simply present the JWT auth token it received from the server, and pass it on to OpenSIPS which will use that for authentication purposes.
It relies on two DB tables, one containing JWT profiles ( a profile name and it’s SIP username associated to it ) and one containing JWT secrets. Each secret has a corresponding profile, the KEY used for signing the JWT and two timestamps describing a validation interval. Multiple JWT secrets can point to the same JWT profile.
Dependencies
Section titled “Dependencies”OpenSIPS Modules
Section titled “OpenSIPS Modules”The module depends on the following modules (in the other words the listed modules must be loaded before this module):
- database — Any database module (currently mysql, postgres, dbtext)
External Libraries or Applications
Section titled “External Libraries or Applications”The following libraries or applications must be installed before running OpenSIPS with this module loaded:
- libjwt-dev
Exported Parameters
Section titled “Exported Parameters”db_url (string)
Section titled “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_jwt", "db_url", "dbdriver://username:password@dbhost/dbname")profiles_table (string)
Section titled “profiles_table (string)”Name of the DB table containing the jwt profiles
Default value of this parameter is jwt_profiles.
modparam("auth_jwt", "profiles_table", "my_profiles")secrets_table (string)
Section titled “secrets_table (string)”Name of the DB table containing the jwt secrets
Default value of this parameter is jwt_secrets.
modparam("auth_jwt", "secrets_table", "my_secrets")tag_column (string)
Section titled “tag_column (string)”Column holding the JWT profile tag.
Default value is “tag”.
...modparam("auth_jwt", "tag_column", "my_tag_column")...username_column (string)
Section titled “username_column (string)”Column holding the JWT profile associated SIP username.
Default value is “sip_username”.
...modparam("auth_jwt", "username_column", "my_username_column")...secret_tag_column (string)
Section titled “secret_tag_column (string)”Column holding the JWT secret associated tag.
Default value is “corresponding_tag”.
...modparam("auth_jwt", "secret_tag_column", "my_secret_tag_column")...secret_column (string)
Section titled “secret_column (string)”Column holding the actual jwt signing secret.
default value is “secret”.
...modparam("auth_jwt", "secret_column", "my_secret_column")...start_ts_column (string)
Section titled “start_ts_column (string)”Column holding the JWT secret start UNIX timestamp.
default value is “start_ts”.
...modparam("auth_jwt", "start_ts", "my_start_ts_column")...end_ts_column (string)
Section titled “end_ts_column (string)”column holding the jwt secret end unix timestamp.
default value is “end_ts”.
...modparam("auth_jwt", "end_ts", "my_end_ts_column")...tag_claim (string)
Section titled “tag_claim (string)”The JWT claim which will be used to identify the JWT profile
default value is “tag”.
...modparam("auth_jwt", "tag_claim", "my_tag_claim")...load_credentials (string)
Section titled “load_credentials (string)”This parameter specifies credentials to be fetched from the JWT profiles table 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 “none ( empty )”.
# load my_extra_column into $avp(extra_jwt_info)modparam("auth_jwt", "load_credentials", "$avp(extra_jwt_info)=my_extra_column")Exported Functions
Section titled “Exported Functions”jwt_authorize(jwt_token,out_decoded_token,out_sip_username)
Section titled “jwt_authorize(jwt_token,out_decoded_token,out_sip_username)”The function will read the first param ( jwt_token ), extract the tag claim and then try to authenticate it against the DB secrets for the respective profile tag. In case of success, it populates the out_decoded_token pvar with the decoded JWT ( in plaintext format header_json.payload_json ) and the out_sip_username with the SIP username corresponding to that JWT profile.
Negative codes may be interpreted as follows:
- -1 ( error) - JWT authentication failed
Meaning of the parameters is as follows:
- jwt_token (string) - The JWT token to perform auth on The string may contain pseudo variables.
- out_decoded_token (pvar) - PVAR used to store the decoded JWT upon succesful auth
- out_sip_username (pvar) - PVAR used to store the SIP username corresponding to the JWT profile, upon succesful auth
This function can be used from REQUEST_ROUTE.
...if (!jwt_authorize("$avp(my_jwt_token)", $avp(decoded_token), $avp(sip_username) )) { send_reply("401","Unauthorized"); exit;} else { xlog("Succesful JWT auth - $avp(decoded_token) \n"); if ($fU != $avp(sip_username)) { send_reply("403","Forbidden AUTH ID"); exit; }}...Contributors
Section titled “Contributors”By Commit Statistics
Section titled “By Commit Statistics”Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| # | Name | DevScore | Commits | Lines++ | Lines— |
|---|---|---|---|---|---|
| 1. | Vlad Paiu (@vladpaiu) | 12 | 2 | 1136 | 0 |
| 2. | Stefan Darius (@dariusstefan) | 8 | 4 | 303 | 28 |
| 3. | Bogdan-Andrei Iancu (@bogdan-iancu) | 4 | 2 | 8 | 9 |
| 4. | Razvan Crainea (@razvancrainea) | 3 | 1 | 2 | 2 |
| 5. | Liviu Chircu (@liviuchircu) | 2 | 1 | 0 | 2 |
(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
Section titled “By Commit Activity”| # | Name | Commit Activity |
|---|---|---|
| 1. | Stefan Darius (@dariusstefan) | Jun 2026 - Jul 2026 |
| 2. | Razvan Crainea (@razvancrainea) | Jun 2026 - Jun 2026 |
| 3. | Liviu Chircu (@liviuchircu) | May 2024 - May 2024 |
| 4. | Bogdan-Andrei Iancu (@bogdan-iancu) | Mar 2020 - Dec 2021 |
| 5. | Vlad Paiu (@vladpaiu) | Mar 2020 - Mar 2020 |
(1) including any documentation-related commits, excluding merge commits
Documentation
Section titled “Documentation”Contributors
Section titled “Contributors”Last edited by: Razvan Crainea (@razvancrainea), Vlad Paiu (@vladpaiu).
License
Section titled “License”All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0