Python (Django)


Table of Contents:

Prerequisites
Django SDK Installation
Run the Django Demo App
Creating your own Django App


Prerequisites


Creating an app involves two basic steps:

  1. Register/create an app in the portal and obtain credentials (this is detailed in the 'Register / Create a New App' menu section)
  2. Configure your app using an SDK, making use of these credentials

It is recommended that you first create a demo/test app with a redirect uri of http://127.0.0.1:8000/login in the portal, to enable you to run the SDK demo app and test the SDK functionality (8000 is the default port on which the django development server runs).

In the portal, when you create a new app, you will be issued with the Client ID and Client Secret credentials that you need to specify when building your app with the SDK. Note that your Client Secret will only be issued to you once so it must be grabbed when first displayed:

client secret

Client ID can then be copied at any time from the app settings screen:

app settings page

Note that you can control the Login Methods available (QR Code requires customer usage of the mobile app. While Browser Login enables logging in within the desktop browser, without the mobile app)

When creating your app in the portal, you also must specify a redirect_uri endpoint which comes from the url where you are hosting your app:

add app

You, of course, are in charge of what the base url of your app is. So it could be http://testapp.com/login, http://12.34.567.89:8080/login or http://127.0.0.1:8000/login as above. Note, however, that the MFA server will not accept 'localhost' as a base url.


Django SDK Installation


  1. The SDK has certain system package dependencies which need to be installed. For Ubuntu 14.04:

    sudo apt-get install build-essential (for compiling code in dependencies)
    sudo apt-get install python-dev or sudo apt-get install python3-dev (depending on python version used)
    sudo apt-get install libssl-dev
    sudo apt-get install libffi-dev
    sudo apt-get install python-setuptools

    Django 1.9 or above is required.

  2. Before downloading the Django SDK, you need to download and install the python SDK from:

    https://github.com/miracl/maas-sdk-python

    After downloading, go to the root maas-sdk-python folder and run:

    sudo python setup.py install

    This will install the miracl-api python package.

  3. Now clone or download the Django SDK from:

    https://github.com/miracl/maas-sdk-django

    After downloading go to the root maas-sdk-django folder and run:

    sudo python setup.py install

    This will install the mfa-auth python package.

  4. Open the sample/sample/settings.py file and make sure the mpad script has the correct url in order to communicate with the authentication server (note that it begins with 'mcl.cdn.mpin.io'):

    MPAD_JS = "https://mcl.cdn.mpin.io/mpad/mpad.js"

Run the Django demo app


  1. Still in sample/sample/settings.py, edit the credentials of the sample app:

    MFA_CLIENT_ID = ""
    MFA_SECRET = ""
    MFA_REDIRECT_URI = "http://127.0.0.1:8000/login"

    Enter your correct values for MFA_CLIENT_ID and MFA_SECRET, as obtained from the admin portal.

    For security, the client ID and secret for a genuine app should not be stored in clear text in a config file. This has only been done here for simple demo purposes. For a production scenario, the client ID and secret should be programmatically accessed via an encrypted API

  2. Now go to the first sample folder:

    cd sample

    And run:

    python manage.py migrate

    Followed by:

    python manage.py runserver

    You can now test the demo app at http://127.0.0.1:8000/home (or whichever port you have set!)

    image1

    After entering your email and clicking on 'login', a QR code will appear which you can scan with your mobile app. In the app you will then be prompted to:

    1. Confirm your identity (by email activation)
    2. Create a 4-digit PIN
    3. Login

    Once logged in you will be greeted by the refresh/logout page:

    image2


Creating your own Django App


What follows is an explanation of how to implement the SDK in an existing Django project, as has been done in the sample app. This will give you a broad understanding of how to begin creating your own app. Note that the snippets of code which follow can be put to use, and you can also find the full files (complete with commented code) in the sample directory.

  1. Edit your settings.py file

    To enable the app for use you first need to add:

    INSTALLED_APPS = [
      ...,
      'mfa_auth'
    ]

    Then add the mfa_auth authentication backend. Note that it must appear first in the list:

    AUTHENTICATION_BACKENDS = (
      ...,
      'mfa_auth.auth_backend.MiraclAuthBackend',
      'django.contrib.auth.backends.ModelBackend',
    )

    The app credentials variables also need to be added, as well as the correct url for the mpad javascript which enables the login button:

    For security, the client ID and secret for a genuine app should not be stored in clear text in a config file. This has only been done here for simple demo purposes. For a production scenario, the client ID and secret should be programmatically accessed via an encrypted API

    MFA_CLIENT_ID = "..."
    MFA_SECRET = "..."
    MFA_REDIRECT_URI = "..."
    
    MPAD_JS = "https://mcl.cdn.mpin.io/mpad/mpad.js"
  2. Edit your urls.py file

    Add the following:

    url(r'', include('mfa_auth.urls', namespace='mfa_auth'))
  3. Create the main web page and login button

    Note that the use of col-md divs here assumes use of the bootstrap framework, as does the use of the {% %} tags to receive flash messages in the standard bootstrap categories of 'success', 'info' and 'danger'.

    In your main index.html file, the mfa_auth_tags library should be loaded before the closing</head> tag:

    {% load mfa_auth_tags %}
    </head>

    Still within the <head> section, you can set up a prerollid script. This will enable capturing the user's email address to bake it into the QR code. Ultimately, it will then be pre-populated in the user's phone app, saving them the trouble of entering their email address twice and enhancing the user experience.

    <script type="application/javascript">
      $(document).ready(function(){
          $("input[type=email]").keyup(function(){
              var email = $("input[type=email]").val();
              $("#btmpin").attr("data-prerollid", email);
          });
      });
    </script>  

    You should then listen out for messages:

    
    <div class="row">
      <div class="col-md-12">
          {% for message in messages %}
              <div{% if message.tags %} class="alert alert-{{ message.tags }}"{% endif %}>{{ message }}</div>
          {% endfor %}
      </div>
    </div>
    

    A request.user.is_authenticated check can then be made. If the user is already logged in, their email address can be displayed by making use of request.user.email. The mfa_auth:refresh and mfa_auth:logout methods can also be used to provide the logout and refresh functionality. Note that refresh clears user info from the session, but leaves the access token unchanged:

    
    <div class="row">
    {% if request.user.is_authenticated %}
        <div class="col-md-4">
            <b>E-mail:</b> {{ request.user.email }}<br/>
        </div>
        <div class="col-md-4"></div>
        <div class="col-md-4">
            <a href="{% url 'mfa_auth:refresh' %}" class="btn btn-primary action">Refresh user data</a>
            <a href="{% url 'mfa_auth:logout' %}" class="btn btn-primary action">Log out</a>
        </div>
     {% else %}
       div class="col-md-12">
           <div class="col-md-8" id="example-email">
               <div class="form-group">
                   <label for="example-email-input" class="col-xs-2 col-form-label">Log In As:</label>
                   <div class="col-xs-10">
                       <input class="form-control" type="email" id="example-email-input" placeholder="email address">
                   </div>
               </div>
           </div>
           <!-- Please add the following to load the login button -->
           <div id="btmpin"></div>
       </div>
     {% endif %}
    </div>   
       

    The else section above then creates an input form of type="email" which makes use of the prerollid script, as explained above. Then <div id="btmpin"></div> is used to render the login button.

    Finally, in order to enable the rendering of the login button, you must add the get_mfa_auth_script tag before the closing body tag:

    
    {% get_mfa_auth_script %}
    </body>
    

Important Note on User Management

In terms of managing your users, it is important to note that, in the process of providing a secure login solution, the service has also registered your users with a confirmed user email. Once a user has been authenticated it is possible to make use of the above request.user.email method to return string values.

This removes a considerable amount of pain from the process of managing users and databases!

For example, if you have a SQL user database and you want to make a check to see if a user is present, or needs added as a new user, then it is possible to make use of the above method.

Another example would be if you want to present a web form to capture more information that is needed to provide a user with access to your product features. Here you can use the above methods to prepopulate the email address field, and you do not need to initiate a 'verify by email' process, as this has already been done by the service.

For information on additional settings and customization please see the readme for the github repo at https://github.com/miracl/maas-sdk-django

Top