Authorization Flow Explained

It is important to note that, in order to actually identify and verify the person who is trying to sign in to your service, MIRACL Trust® makes use of the OpenID Connect authentication protocol.

Detailed explanations of the protocol can be found at http://connect2id.com/learn/openid-connect and http://openid.net/connect/faq/.

For the purposes of this documentation, it is sufficient to know that, via the mpad.js javascript client, the protocol is used to initiate the authorization flow, identify users and to present the authentication server with an access token.

Once a token is received, the mpad.js client communicates with the platform to kick off the 'zero knowledge' authentication process, whereby the customer sets up a PIN in the mobile app which identifies them as an authorized user to your service/application.

A good illustration of how the SDKs can manage this process is found in the route handler setup in the Tornado demo app server.py script:

app = web.Application([
    (r"/", MainHandler),
    (r"/login", AuthHandler),
    (r"/logout", LogoutHandler),
    (r"/refresh", RefreshHandler)
],

This script creates the endpoints whereby the SDK and mpad.js can communicate with the authentication server, in that:

  • The "/" endpoint is where the authentication flow begins - a check to see if a user is authorised can be made, and the authorization url can be sent to the platform.

  • The "/login" endpoint is the redirect_uri, as explained in 'Register / Create a new app'. This is used to send the user back to your app once authentication has been approved.

  • The "/logout" and "/refresh" endpoints are used to enable the logout method and the refresh method (the refresh method can be used to clear user info but keep the access token and thus enable continued retrieval of user info without performing a fresh authorization)

The Generic Process

Each SDK follows a similar generic process to manage the authentication flow:

  1. Construct the Miracl Client object

    All SDKs must construct an instance of a Miracl Client object in order to interact with the Miracl APIs. The Miracl API requires a map-like object for storing state and additional data (this should be preserved between calls to the API).

  2. Initialize the Miracl Client object

    To authenticate your app, a Miracl Client object needs to be initialized and the client_id, client_secret and redirect_uri parameters (obtained from the developer portal as described in 'Create a New App') need to be sent to the API.

    The redirect_uri is the URI of your application end-point that will be responsible for obtaining the token. It must be registered in the portal with the same app as the client_id and client_secret.

    The Miracl Client can be initialized either when needed, or at application startup

  3. The End User Authorization Flow

    Authorization

    When an End User needs to be authorized, they scan the QR barcode with their mobile app to begin authorization on the server. For your application, this is controlled by the 'M-Pad':

    choose pin browser

    The M-Pad is called when an End User clicks on the MIRACL Trust® login button.

    The button itself is created in your app with a script as such:

    <div id="{{buttonElementID}}"></div>

    This makes use of the mpad.js library to send the authentication information to the server:

    <script src="https://mcl.cdn.mpin.io/mpad/mpad.js" data-authurl="" data-element="btmpin"></script>

    The parameters passed in this script are:

    data-element: the login button ID (corresponds with <div id> in the first of the above snippets)
    data-authurl: the authorization URL (this passes the client_id and redirect_uri to the authentication server). Each SDK has a 'Get Authorization Request URL' method for obtaining this.

    The authorization url must be obtained before the mpad.js script is loaded. This will be demonstrated in the sample apps for the SDKs

    Validation

    The final step is then to make use of a 'validate authorization' method to pass the session and query string which was received at the redirect_uri.

    The result of this authorization method will either be:

    1. A null/none/nil error if authorization is denied

      OR

    2. An access token if authorization has succeeded

    Status check and user data

    Each SDK then has methods to check the authorization status and to return the userID and email of the user, plus methods to log users out and clear user data.

    Once a user has been authenticated it is possible to make use of the get methods which return the string values of userID and email to e.g. check if the user is present in your database, or needs added as a new user.

Top