Authentication Factors

Learn how to increase security by enabling authentication factors in your applications.

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 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 provides a special JWT token named Auth Token whose content is shown below:

  "nbf": 1500940579,
  "exp": 1500940879,
  "iss": "",
  "auth_factor": [
  "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 /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 you may register only in the Application Settings page.

  2. clientId: the Id of the application in GrantID.
  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?

The redirect to GrantID must come from an URL that is registered to an application or else the request will fail.

Do not forget to URL encode the parameters or else the request will also fail.

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.

Even though the token has a fixed expiration of 5 minutes, you may use the nbf and exp parameters to determine a smaller window of validity per operation/action of your application.