APPENDIX A. Authentication methods

PortaBillingESPF supports these HTTP authentication schemes:

The authentication is done with user ID and password.

Credentials string is constructed by joining the username and the password with a single colon (":"). The result is then base64 encoded.

For example, let’s say that user ID is username and the password is secret (e.g., username:secret). The authorization header then looks as follows:

Authorization: Basic dXNlcm5hbWU6c2VjcmV0

The Application receives the request, decodes the base64-encoded user ID and password. It compares the decoded credentials username:secret with the ones that are stored in the Application’s database. If they match, the authorization is passed.

The authentication is done with custom type and credentials;

The Authorization header contains the name of a custom authentication scheme and credentials as it is configured in PortaBilling.

For example, let’s say that the custom type is Plain and the password is passexample. The authorization header then looks as follows:

Authorization: Plain passexample

The Application receives the request, compares the authentication schema and credentials with the ones that are stored in the Application’s database. If they match, the authorization is passed.

The authentication is done authenticate by signature key and key ID.

Credentials string is constructed of the originating date (the value from the Date header), signature key, and signature key ID.

The Date header is used to form a signing string. This signing string is then signed with the signature key to make a signature. The HMAC-SHA1 algorithm (Hash-based Message Authentication Code using the SHA1 hash function) is used to sign the signing string with the key.

For example, let’s say that the signature key is signature, the key ID is test and the Date header is Thu, 12 Apr 2018 15:24:00 GMT. The authorization header then looks as follows:

Authorization: Signature keyId="test",algorithm="hmac-sha1",signature="+IkiEg9UkyA+gh+pcI64iti

The Application receives the request, takes the value from the Date header field, and verifies the value from the key ID field. The Application then takes the key value from the Application’s database and runs the algorithm to calculate the signature. The Application compares the obtained signature value with the one that is received in the Authorization header. If they match, the authorization is passed.

Authentication is done using the JWT-encoded (JSON Web Token) access token.

The Authorization header is in the following format:

Authorization: Bearer <token>

An access token is an encrypted string, usually generated by the server in response to a login request and used in subsequent requests to protected resources (e.g., API). The "Bearer" scheme can be understood as "give access to the bearer of this token".

A JWT token consists of three base64-encoded parts separated by dots: <header>.<payload>.<signature>

The header includes the token type (JWT) and the signing algorythm (e.g., HMACSHA256).

The payload contains the claims. This is the information about the user and additional data. In PortaBilling, the claims are the i_env value and the token expiration time defined in the Unix Time format.

The signature part is used to verify that the message wasn’t changed along the way and that the token sender is who they says they are. It includes the encoded header and payload, a signature key and is signed using the signing algorithm. A signature key is defined in the BearerAuth.Key option on the Configuration server.

To put it all together, let’s say the signature key is superkey, the payload values are: i_env=3 and the expiration time is 1560338716 (Wed Jun 12 14:25:16 2019 EEST). The signing algorithm is HMACSHA256. The authorization header then looks as follows:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpX2VudiI6MywiRXhwIjoxNTYwMzQyMzE2fQ.PONYERv3xYs5g--XwbflOcaWddSuUNt7hAQqvoEcO4Q

The ESPF and the Application must know the signature key. When the Application receives the request, it:

• captures the value from the Authorization header;
• strips the "Bearer" prefix before the token;
• runs the same signature algorithm to receive the signature value;
• compares the obtained signature’s own hashing operation with the signature on the token itself.

If the signatures match, authorization is successful.