Mobile Connect

Hosted Code on Bluemix: https://hub.jazz.net/git/chlau/tmf-MobileConnect

Mobile Connect is a global standard for federated authentication. The idea is that you would use the Mobile Connect app on your phone to log into various websites and applications, rather than having a separate username and password for each site that you use. This is similar to using your Google or Facebook account to log into sites like Pinterest and Goodreads.

First, you install Mobile Connect on your phone (search for Mobile Connect Canada on the app store) and enroll yourself to use the service. You will be asked for your carrier billing information, which will be confirmed by your carrier to ensure your identity. You can then set a pin or fingerprint as your way to authenticate in the Mobile Connect app (so that your account is secure even in the event of a lost or stolen phone). Carriers that are currently supporting Mobile Connect in Canada include TELUS, Bell, Rogers, and their subsidiaries.

Next, when you visit a Mobile Connect enabled site on your laptop (or on any device), you can click the Mobile Connect button to log in rather than using a username and password. You enter your phone number and then you will receive a notification on your phone prompting you to authenticate in the Mobile Connect App. When you complete authentication in the app, you will be logged into the site on your laptop. Note that the site that has enabled Mobile Connect for authorization will not be able to see your phone number; they simply receive confirmation that you are authorized and a record that they will use to associate you to your account on the site.

No more remembering usernames and passwords: all authentication can be managed in one place through the Mobile Connect app. Add Mobile Connect authentication to your site or app to enable your users to use their phone as their login credentials. Try it out yourself here: https://demo.enstreamidentity.com/mc/telus2/ with username "username" and password "telus"

As a Developer:

To enable Mobile Connect on your Java site, you will need to do the following:

 You can check out https://developer.mobileconnect.io for additional support.

Here is a set of resources for your reference with the SDKs, as well as sample code and some additional documentation from Enstream: MobileConnectResources.zip

Update your JSP Login page 

You will want to update your regular login page to add a Mobile Connect log in button and dialogue box. To update your JSP login page, you will need to add the following scripts: 

    <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>

    <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>

    <script src="/mc/js/EnStreamServerSDK.js"></script>

    <script>

        var authorizationUrl = "http://localhost:8080/mc/servlets/start_authorization"; 

        var errorPageUrl = "http://localhost:8080/mc/servlets/mobile_connect_error";

        MobileConnectServerSDK.configure(authorizationUrl, errorPageUrl);

    </script>

JQuery components are required in order to perform AJAX Queries and to display the Mobile Connect dialogue on your page. EnStreamServerSDK.js includes the Mobile Connect logic.

Next, you have to add a button to your page:

    <style>

        div.mcButton {

            position: absolute;

            width: 246px;

            height: 60px;

            top: 605px;

            left: 605px;

            background-image: url("img/mc_logos/MC-button2-246x60-colour.png");

        }

    </style>

    <div class="mcButton" id="mobile_connect" ></div>

    <script>

        $("#mobile_connect").click(function() {

            MobileConnectServerSDK.startAuthorization();

        });

   </script>

The background image used is a Mobile Connect asset that will be provided to you. The script will be called when the user clicks the Mobile Connect button.

And lastly, you need to add an empty div for the Mobile Connect dialogue to use:

   <div id="mobileConnectDialog"  style="display: none ;"></div>

Your button will look something like this:

Create Authorization Request Servlet

Your authorization servlet will handle all log-in attempts accordingly based on the method that the user has chosen to use on your log in page. To manage Mobile Connect authorization, this is the code:

    private ResponseJson beginAuthorization(HttpServletRequest request, HttpServletResponse response, HttpSession session) {

        MobileConnectConfig config = ConfigurationReader.getMobileConnectConfig(session);      

        MobileConnectStatus mobileConnectStatus = MobileConnectInterface.callMobileConnectForStartAuthorization(oidc, config, request);

        return mobileConnectStatus.getResponseJson();

    }

You must load the MobileConnectConfig object with your settings, and then use callMobileConnectForStartAuthorization. The return of this will be the content to display inside the mobileConnectDialog div that we previously created in our login page. oidc is a global variable that is populated when your servlet is initialized using helper function Factory.getOIDC() from the Mobile Connect library.

Create Callback Servlet

Mobile Connect must wait for the user to confirm their login on their phone. Once they've done that, you'll be redirected to the callback URL that you will later specify in the MobileConnectConfig object. This Callback servlet exists to receive that authorization complete notification and react to it. It will look something like this:

protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

    MobileConnectConfig config = ConfigurationReader.getMobileConnectConfig(request.getSession());

    MobileConnectStatus mobileConnectStatus =

      MobileConnectInterface.callMobileConnectOnAuthorizationRedirect(oidc, config, request.getSession());

    if(mobileConnectStatus.isError()) { /* send to error page */ }

    if(!mobileConnectStatus.isComplete()) { /* send to error page */ }

    String pcr = mobileConnectStatus.getRequestTokenResponse().getResponseData().getParsedIdToken().get_pcr();

    /* Do work with Pseudonymous Customer Reference here:

     * If this is users first time using Mobile Connect on your site: map this PCR to the users account on your site, and save this in persistent storage for future reference

     * Otherwise: look up the PCR in your persistent storage to find the associated user account

     */

    request.getSession().setAttribute("pcr", pcr);

    RequestDispatcher rd = request.getRequestDispatcher(“authorized_page.jsp");

    rd.forward(request, response);

}

The request from Mobile Connect will contain the session information for the user that just finished authorization. We will use that to talk to Mobile Connect one last time with callMobileConnectOnAuthorizationRedirect. The MobileConnectStatus object that we get back from Mobile Connect will tell us about any errors, or if successful will give us what is called a PCR: Pseudonymous Customer Reference. The PCR is a unique user ID for this user to your application that allows you to map this user with their account on your site; it contains no personally identifiable information.  If there was a problem retrieving the PCR, you need to redirect the user to an error page. Otherwise, direct the user onwards to their account on your site. You are responsible for maintaining a mapping of PCR to the user account for your site. oidc is a global variable that is populated when your servlet is initialized using helper function Factory.getOIDC() from the Mobile Connect library.

Manage Mobile Connect configuration

Mobile Connect needs to know the callback URL to use for your application once the user has completed authorization, so that must be specified in the config under setApplicationURL. Mobile Connect also registers applications that are using its authorization and will grant you a Gateway Client ID and Client Secret that you also have to specify in your configuration. The application URL, gateway client id and secret used below are specific for the Mobile Connect demo application, and will only work for that specific application URL running on your local host. To host your application elsewhere, you will have to ask for a Client ID and Secret for the URL that you will be using as a callback.

    private static MobileConnectConfig loadConfig() {

        MobileConnectConfig mcconfig = new MobileConnectConfig();

        mcconfig.setSkipDiscoveryService(true);

        mcconfig.setApplicationURL("http://localhost:8080/mc/telusstaging/callback.jsp");

        mcconfig.setAuthorizationURL("https://login.mobileconnect.enstream.net/uas/oauth2/authorization");

        mcconfig.setTokenURL("https://login.mobileconnect.enstream.net/uas/oauth2/token");

        mcconfig.setUserInfoURL("https://login.mobileconnect.enstream.net/uas/oauth2/userinfo");

        mcconfig.setIdGatewayClientId("XsgD9ft2aIKSRoTw4f8avDKRNNr9xB1j");

        mcconfig.setIdGatewayClientSecret("HuYgWBl5xSZyGKFAKQh3M4aGQFXOpaq6");

        mcconfig.setAuthorizationAcr("3");

        mcconfig.setAuthorizationState(MobileConnectInterface.generateUniqueString("state_"));

        mcconfig.setAuthorizationNonce(MobileConnectInterface.generateUniqueString("nonce_"));

        return mcconfig;

    }

Note that with Mobile Connect, the users information is protected. The site developer does not get to see the contents entered into the mobileConnectDialogue on the login page, only Mobile Connect does. Mobile Connect will ask each operator if they recognize the phone number. When the operator owner of the phone number is identified, that operator will look up additional information about that user in order to verify their identity. But the operator will only send back the PCR for Mobile Connect to send back to the application, and the PCR contains no personally identifiable information. In this way, personal information about the phone owner is not shared with the application. This is more secure for the user than any other single-sign-on options available today. It is also more secure for the application, because they can trust the operator to authorize the user with certainty. To log in, a person must have access to the users phone, know the phone number, know how to unlock the phone, and know how to authorize in the Mobile Connect app. In case of lost or stolen phone, the user can call their operator to disable their phone and at the same time disable their Mobile Connect account.