Integration for websites and applications

Data flow scheme

To enable two-factor authentication for a website, follow these steps:

1. The user enters a login and password on your website, the site checks the correctness of the data.
2. If the data is correct, the site requests API of Multifactor to create an access request. The API response contains the unique address of the access page.
3. The site redirects the user to the Multifactor access page, where he will be asked to go through the second authentication factor. Upon successful completion, Multifactor generates an access token and returns the user to your site.
4. The site verifies the token and authorizes the user.

JWT token

JSON Web Token is a modern standard for creating an access token for exchanging authentication information between two parties. Despite the complexity of the name, JWT has a simple structure and is very convenient to use.

Structure

The token consists of three parts:

1. Header
2. Payload
3. Signature

The parts are separated by dots and encoded in base64-url format.

Please note

Parts of the token are encoded not in base64 format, but in base64-url for secure transmission in HTTP request parameters.

Example:

xxx.yyy.zzz

The first two parts contain JSON data in the format key: value, signature - the calculated value for checking the first two.

Header

The header describes the token format:

{
  "typ": "JWT", //type: JWT
  "alg": "HS256" //signature algorithm: HMAC using SHA-256
}

Data

The second block contains user and authentication information

{
  "iss": "https://access.multifactor.kz", //who issued
  "aud": "rs_1a913e4ea690ac12ea163331dd60d", //issued to (ApiKey)
  "sub": "user@example.com", //username
  "jti": "RxMEyo9", //token id
  "iat": 1571684399, //when issued
  "exp": 1571684699, //expiration date
  "returnUrl": "/", //arbitrary key
  "rememberMe": "False", //arbitrary key
  "createdAt": "10/21/19 6:59:55 PM" //arbitrary key
}

The block contains mandatory and optional keys. The mandatory keys are:

Key	Name	Description	Value
iss	Issuer	The party where the token was issued	Always https://access.multifactor.kz/
aud	Audience	Who is the token intended for	ApiKey from the settings in your personal account
sub	Subject	User ID	From the 'Identity' parameter API
jti	JWT ID	Token ID	Coincides with the access request ID
iat	Issued At	Issue date/time	in UNIX time format
exp	Expiration Time	Expiration date/time	in UNIX time format

The mandatory keys are reserved by the Multi-factor system and always present in the token.

Optional parameters include any parameters passed to API to create an access request. These could be: user roles in your system, additional security attributes, etc.

Signature

The third JWT block contains the token signature. Multifactor supports two signature options:

*HS256 *RS256

The signature guarantees that the token was issued by the Multifactor system and transferred to you without changes.

###HS256 format

The signature is formed as HMAC-SHA256(message, secret), where:

• message - the first two parts of the message, encoded in base64-url and separated by a dot;
• secret — API Secret, available in personal account, in the "Resources" -> "Settings" section.

###RS256 format

The message is signed with a private key, known only to Multifactor, and you verify it using the public key, always available at https://api.multifactor.kz/.well-known/jwks.json.

This signature format is preferable because it eliminates the possibility of forgery of the token by an employee who knows the shared secret.

Token verification and authorization

After successfully passing the second factor of authentication on the Multifactor access page, the user returns to your website, to the address specified in API when creating the request. The address receives an accessToken parameter, which must be verified before authorizing the user.

The check must include:

• Control of the issuance date and validity period of the token
• Audience check (aud) - must match ApiKey
• Signature verification

If everything is correct, the site authorizes the user (issues a session cookie).

Important

JWT tokens are not encrypted, so it is unacceptable to include the user's password or other confidential information in them.

Functions for token decoding and verification are available in many libraries for all programming languages, see list.