Authentication factors are additional information that must be presented by an user after he provides his email and password in order to complete the login proccess.

The following factors are supported:

• Email: an e-mail containing a code is sent to the user.
• SMS: a SMS message containing a code is sent to the user.
• Mobile Authenticator: the user must enter a code generated by the GrantID (HML) Authenticator App.
• Second Password: the user must enter a second password which was previously registered.

Authentication factors are disabled by default when you create an application, but it's really easy to enable them by navigating to the Application Settings page and choosing the Authentication Factors tab:

There are two modes available when enabling the factors:

• Request one: in this mode, the user needs to authenticate with only one of the selected factors. If multiple factors are selected, the user will be able to choose the one he prefers.
• Request all: in this mode, the user needs to authenticate with all of the selected factors.

Requiring a factor for a specific operation

You may want to add security to specific actions or operations in your application by requesting that one or multiple factors are presented by the user.

In order to accomplish this, GrantID (HML) provides a special JWT token named Auth Token whose content is shown below:

{
  "nbf": 1500940579,
  "exp": 1500940879,
  "iss": "http://sub.grantid.com",
  "auth_factor": [
    "email",
    "mobile_app"
  ],
  "sub": "ed6adcde-2e5e-488b-8afb-eecf33bec202"
}

This token is issued after an user successfully completes a number of authentication factor requests. It has a default expiration of 5 minutes and contains the following information:

1. sub: the unique Id of the authenticated user.
2. auth_factor: a list of the completed authentication factors.
3. iss: the subscription URL for which the token has been issued (issuer).
4. nbf: the issuing date of the token.
5. exp: the expiration date of the token.

To retrieve an Auth Token for an user, an Application must redirect the user (preferably already authenticated) to the GrantID (HML) /Factor/Authenticate URI and provide the following parameters:

1. redirectUrl: the URL to which the user will be redirected to after the request is successfully completed. It must be registered as an available Redirect URL in the Application Settings page.

   Additional query parameters in the return URL do not need to be registered, as you may have a single callback that redirects to multiple pages inside your application.
   
   For instance, if you want the user to be redirected to https://app.com/Auth/Callback?r=/Home/Restricted you may register only https://app.com/Auth/Callback in the Application Settings page.

2. clientId: the Id of the application in GrantID (HML).
3. factors: a list of keys for the desired factors separated by spaces:

   Authentication Factor	Key
   Email	email
   SMS	sms
   Mobile Authenticator	mobile_app
   Second Password	second_password

The following example requests both the Email and Mobile Authenticator factors:

GET /Factor/Authenticate?redirectUrl=http%3A%2F%2Fapp.com%2FHome%2FAuthCallback%3Fr%3D%2FHome%2FRestricted&clientId=app&factors=email%20mobile_app
Host: sub.grantid.com

After the user successfully completes the factors request, he will be redirected to the requested URL which will have an additional parameter named "auth_token" whose value is the Auth Token.

Finally, it's the responsibility of the application to validate the following information inside the token:

• The sub claim to check if the user who has completed the authentication request is the same as the logged user.
• The integrity and validity of the token in order to determine if it is expired or not.
• The issuer of the token as it must be the URL of the application's subscription.
• The factors list to check if all of the requested factors where completed by the user.