Integration
Data Flow Diagram
To apply two-factor authentication in your website it is required to perform the following:
- A user enters login and password on your website and the site checks data validity.
- If data is valid, the site requests Multifactor's API to create an access request. API response contains the unique address of the access page.
- The website forwards the user to the Multifactor access page, where the user will be suggested to use the second authentication factor. After successful completion, Multifactor creates an access token and returns the user to your website.
- The Website validates token and authorizes the user.
JWT token
JSON Web Token — is the up-to-date standard of creating the access token for sharing the authentication information between two parties. Despite the complicated name, JWT has a simple structure and is very convenient to use.
Structure
Token consists of three parts:
- Name
- Data
- Signature
The parts are interpointed and encoded in a format base64-url.
Please pay attention, not base64, but base64-url for secure transmission in parameters of an HTTP request.
Example:
xxx.yyy.zzz
The first and second parts contain JSON data in format key: value, signature — evaluated value for verification of the first two.
Header
In header the token format shall be described:
{
""typ"": ""JWT"", //тип : JWT
""alg"": ""HS256"" //signature algorythm: HMAC applying SHA-256
}
Data
In the second block the data about user and authentication are transmitted
{
""iss"": ""https://access.multifactor.ru"", //who issued
""aud"": ""https://example.com"", //whom issued
""sub"": ""user@example.com"", //user name
""jti"": ""RxMEyo9"", //token id
""iat"": 1571684399, //when issued
""exp"": 1571684699, //validity period
""returnUrl"": ""/"", //arbitrary key
""rememberMe"": ""False"", //arbitrary key
""createdAt"": ""10/21/19 6:59:55 PM"" //arbitrary key
}
The block contains the required and optional keys. The required keys are:
Key | Name | Description | Value |
---|---|---|---|
iss | Issuer | Party who issued token | Always https://access.multifactor.ru/ |
aud | Audience | To whom issued a token | Your website address from Personal account settings |
sub | Subject | User identifier | From parameter 'Identity' API |
jti | JWT ID | Token identifier | The same as access request identifier |
iat | Issued At | Date/issue time | in UNIX time format |
exp | Expiration Time | Date/expiration time | in UNIX time format |
The required keys are reserved by the Multifactor system and always exist in the token.
The optional are any parameters, transferred in API to create access request. It shall be: users roles in your system, additional security attributes, etc.
Signature
The third block JWT — token signature, which is computed as HMAC-SHA256(message, secret), where:
- message — first two parts of the message, encoded in base64-url and interpointed;
- secret — API Secret, accessible in the admin panel.
The signature guarantees that the token is issued by the Multifactor system and is given to you without any changes.
Token validation and authorization
After successful completion of second-factor authentication on Multifactor access page, the user returns to your website, to the address, mentioned in API upon request creation. The address gets the parameter accessToken, which shall be validated before user authorization. Validation shall obligatory include:
- Control of token issue date and token expiration date
- Signature validation
If all parameters are correct, the website authorizes the user (issues session cookies).
JWT token is not encoded, that is why it must not include the user password or any other private data in it.
Functions for token decoding and validation are presented in a range of libraries for all programming languages, see the list.