README

AUTH_JWT Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_mode (int)
              1.3.2. db_url (string)
              1.3.3. profiles_table (string)
              1.3.4. secrets_table (string)
              1.3.5. tag_column (string)
              1.3.6. username_column (string)
              1.3.7. secret_tag_column (string)
              1.3.8. secret_column (string)
              1.3.9. start_ts_column (string)
              1.3.10. end_ts_column (string)
              1.3.11. tag_claim (string)
              1.3.12. load_credentials (string)

        1.4. Exported Functions

              1.4.1.
                      jwt_db_authorize(jwt_token,out_decoded_token,o
                      ut_sip_username)

              1.4.2. jwt_script_authorize(jwt_token,key,
                      out_decoded_token)

              1.4.3.
                      extract_pub_key_from_cert(certificate,out_publ
                      ic_key)

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. db_mode parameter usage
   1.2. db_url parameter usage
   1.3. profiles_table parameter usage
   1.4. secrets_table parameter usage
   1.5. Set tag_column parameter
   1.6. Set username_column parameter
   1.7. Set secret_tag_column parameter
   1.8. set secret_column parameter
   1.9. set start_ts parameter
   1.10. set end_ts parameter
   1.11. set tag_claim parameter
   1.12. load_credentials parameter usage
   1.13. jwt_db_authorize usage
   1.14. jwt_script_authorize usage
   1.15. extract_pub_key_from_cert usage

Chapter 1. Admin Guide

1.1. 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.

1.2. Dependencies

1.2.1. 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) , in case the db_url parameter is set

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * libjwt-dev
     * openssl-dev or libssl-dev

1.3. Exported Parameters

1.3.1. db_mode (int)

   If set to 0, the module won't connect to the Database for
   reading the Keys for decoding JWTs - only jwt_script_authorize
   will be usable from the script.

   Default value is “0”.

   Example 1.1. db_mode parameter usage
modparam("auth_jwt", "db_mode", 0)

1.3.2. 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”.

   Example 1.2. db_url parameter usage
modparam("auth_jwt", "db_url", "dbdriver://username:password@dbhost/dbna
me")

1.3.3. profiles_table (string)

   Name of the DB table containing the jwt profiles

   Default value of this parameter is jwt_profiles.

   Example 1.3. profiles_table parameter usage
modparam("auth_jwt", "profiles_table", "my_profiles")

1.3.4. secrets_table (string)

   Name of the DB table containing the jwt secrets

   Default value of this parameter is jwt_secrets.

   Example 1.4. secrets_table parameter usage
modparam("auth_jwt", "secrets_table", "my_secrets")

1.3.5. tag_column (string)

   Column holding the JWT profile tag.

   Default value is “tag”.

   Example 1.5. Set tag_column parameter
...
modparam("auth_jwt", "tag_column", "my_tag_column")
...

1.3.6. username_column (string)

   Column holding the JWT profile associated SIP username.

   Default value is “sip_username”.

   Example 1.6. Set username_column parameter
...
modparam("auth_jwt", "username_column", "my_username_column")
...

1.3.7. secret_tag_column (string)

   Column holding the JWT secret associated tag.

   Default value is “corresponding_tag”.

   Example 1.7. Set secret_tag_column parameter
...
modparam("auth_jwt", "secret_tag_column", "my_secret_tag_column")
...

1.3.8. secret_column (string)

   Column holding the actual jwt signing secret.

   default value is “secret”.

   Example 1.8. set secret_column parameter
...
modparam("auth_jwt", "secret_column", "my_secret_column")
...

1.3.9. start_ts_column (string)

   Column holding the JWT secret start UNIX timestamp.

   default value is “start_ts”.

   Example 1.9. set start_ts parameter
...
modparam("auth_jwt", "start_ts", "my_start_ts_column")
...

1.3.10. end_ts_column (string)

   column holding the jwt secret end unix timestamp.

   default value is “end_ts”.

   Example 1.10. set end_ts parameter
...
modparam("auth_jwt", "end_ts", "my_end_ts_column")
...

1.3.11. tag_claim (string)

   The JWT claim which will be used to identify the JWT profile

   default value is “tag”.

   Example 1.11. set tag_claim parameter
...
modparam("auth_jwt", "tag_claim", "my_tag_claim")
...

1.3.12. 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 )”.

   Example 1.12. load_credentials parameter usage
# load my_extra_column into $avp(extra_jwt_info)
modparam("auth_jwt", "load_credentials", "$avp(extra_jwt_info)=my_extra_
column")

1.4. Exported Functions

1.4.1.
jwt_db_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.

   Example 1.13. jwt_db_authorize usage
...
if (!jwt_db_authorize("$avp(my_jwt_token)", $avp(decoded_token), $avp(si
p_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;
        }
}
...

1.4.2.  jwt_script_authorize(jwt_token,key, out_decoded_token)

   The function will read the first param ( jwt_token ), decode it
   and then try to validate it against the provided key. If the
   JWT decoding is succesful, the out_decoded_token pvar will be
   populated. Return codes are :
     * -2 : Failure in decoding the JWT ( out_decoded_token will
       not be populated )
     * -1 : Failure in validating the JWT ( out_decoded_token will
       be populated )
     * 1 : JWT succesfully validated with the key (
       out_decoded_token will be populated )

   Meaning of the parameters is as follows:
     * jwt_token (string) - The JWT token to perform auth on
       The string may contain pseudo variables.
     * key (string) - The key to be used for validating the JWT.
     * out_decoded_token (pvar) - PVAR used to store the decoded
       JWT

   This function can be used from REQUEST_ROUTE.

   Example 1.14. jwt_script_authorize usage
...
if (!jwt_script_authorize("$avp(my_jwt_token)",$avp(pub_key), $avp(decod
ed_token))) {
        send_reply(401,"Unauthorized");
        exit;
} else {
        xlog("Succesful JWT auth - $avp(decoded_token) \n");
}
...

1.4.3.  extract_pub_key_from_cert(certificate,out_public_key)

   The function will read the first param ( certificate ), decode
   it and then try to extract the public key with the certificate.
   If the extraction is succesful, the out_public_key will be
   populated. Useful to be used in conjuction with the
   jwt_script_authorize function, since most providers make their
   certificates public, but the JWTs are signed with the actual
   public key embeded in the certificate. Return codes are :
     * -1 : Failure in extracting the pub key
     * 1 : out_public_key succesfully populated

   Meaning of the parameters is as follows:
     * certificate (string) - The certificate to read and from
       which to extract the public key
       The string may contain pseudo variables.
     * out_public_key (pvar) - PVAR used to store the extracted
       public key

   This function can be used from REQUEST_ROUTE.

   Example 1.15. extract_pub_key_from_cert usage
...
if (extract_pub_key_from_cert("$avp(my_certificate)",$avp(my_pub_key)))
{
    xlog("Succesfully extracted public key - $avp(my_pub_key) \n");
}
...

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Vlad Paiu (@vladpaiu) 20 6 1521 16
   2. Liviu Chircu (@liviuchircu) 5 3 4 6
   3. Bogdan-Andrei Iancu (@bogdan-iancu) 4 2 6 7
   4. Alexandra Titoc 3 1 5 4
   5. Maksym Sobolyev (@sobomax) 3 1 3 3

   (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

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Liviu Chircu (@liviuchircu)         May 2023 - Sep 2024
   2. Alexandra Titoc                     Sep 2024 - Sep 2024
   3. Vlad Paiu (@vladpaiu)               Mar 2020 - Jul 2023
   4. Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   5. Bogdan-Andrei Iancu (@bogdan-iancu) Mar 2020 - Dec 2021

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Liviu Chircu (@liviuchircu), Vlad Paiu
   (@vladpaiu).