TELUS APIs

Available APIs and Services

1. Mobile Connect
2. Get Terminal Location SOAP Service
3. Send SMS SOAP Service

Mobile Connect

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 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, and Rogers.

Apple: https://itunes.apple.com/ca/app/mobile-connect-canada/id1110404774?mt=8

Android: https://play.google.com/store/apps/details?id=com.mepin.android.mobileconnect.canada&hl=en

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.

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

1. Update your JSP login page
2. Create Authorization Request Servlet
3. Create Callback Servlet
4. Manage Mobile Connect configuration

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>

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.

Get Terminal Location SOAP Service

WSDL: http://webservices.telus.com/parlayx21/072007/parlayx_terminal_location_service_2_3.wsdl

The Terminal Location API allows you to look up the location of a cell phone by its phone number in your application. For this event, this API works only for TELUS phone numbers, and the user of the phone must have authorized your application to perform this query. You will get a set of credentials for your application, SSL certificates, and then you must whitelist numbers that your application will be allowed to query. Please note that you must have access to and control of any phones that you want to whitelist. To whitelist a number, please ask one of the TELUS representatives at the event.

This location service strictly uses network triangulation to determine location. This means it is generally less accurate but will work in situations where GPS is not available (like in a basement) and is also able to report the last known location if the device cannot be found (which you cannot do with GPS).

You can use this service by sending a SOAP request with the following format:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/parlayx/terminal_location/v2_3/local">

        <soapenv:Header/>

        <soapenv:Body>

            <loc:getLocation>

                <loc:address>tel:16042917290</loc:address>

                <loc:requestedAccuracy>5000</loc:requestedAccuracy>

                <loc:acceptableAccuracy>5000</loc:acceptableAccuracy>

            </loc:getLocation>

        </soapenv:Body>

    </soapenv:Envelope> 

loc:address -  The telephone number to find the location of

loc:requestedAccuracy -  The accuracy you would like on that location in meters

loc:acceptableAccuracy -  Location accuracy must be within this number of meters

Depending on the accuracy that you specify, different technologies will be used. Lower accuracy will take less time to ascertain.

We suggest using an accuracy level of 5000m or greater in order to get fast responses.

The response you receive will look something like this:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

            <ns2:getLocationResponse xmlns:ns2="http://www.csapi.org/schema/parlayx/terminal_location/v2_3/local" xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v2_1">

                <ns2:result>

                    <latitude>49.267</latitude>

                    <longitude>-123.0068</longitude>

                    <altitude>22.0</altitude>

                    <accuracy>182</accuracy>

                    <timestamp>2008-07-10T12:54:40.000-04:00</timestamp>

                </ns2:result>

            </ns2:getLocationResponse>

        </soap:Body>

    </soap:Envelope> 

 latitude, longitude: Coordinates where the subscriber is located

altitude: The subscribers elevation

accuracy: how accurate the location result is in meters

timestamp: the time at which the subscribers location was found

Send SMS SOAP Service

WSDL: http://webservices.telus.com/parlayx_sms_send_service_2_3.wsdl

The SMS API allows you to send SMS messages through your application. For this event, this API works only for TELUS phone numbers, and the user of the phone must have authorized your application to perform this query. You will get a set of credentials for your application, SSL certificates, and then you must whitelist numbers that your application will be allowed to query. Please note that you must have access to and control of any phones that you want to whitelist. To whitelist a number, please ask one of the TELUS representatives at the event.

While there are other services (like Twilio or, for TELUS customers, sending an email to <phone#>@msg.telus.com) that allow you to send SMS messages with fewer restrictions, those services have limitations in terms of the kind of content that can be sent and the frequency of content being sent. With this particular TELUS Send SMS service, there are no restrictions on content or frequency; it also allows for billing via SMS. As such, this service is most useful for premium SMS services.

Endpoint: https://webservices.telus.com/SendSmsService/services/SendSms

You can use this service by sending a SOAP request with the following format:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/parlayx/sms/send/v2_3/local">

        <soapenv:Header/>

        <soapenv:Body>

            <loc:sendSms>

                <!--1 or more repetitions:-->

                <loc:addresses>tel:16048183614</loc:addresses>

                <loc:senderName></loc:senderName>

                <loc:message>Message 1 on 12-01-2012</loc:message>

                <!-- Optional -->

                <loc:receiptRequest>

                    <endpoint>http://yourendpoint.com/SmsNotificationService/services/SmsNotification</endpoint>

                    <interfaceName>SmsNotification</interfaceName>

                    <correlator>1010</correlator>

                </loc:receiptRequest>

            </loc:sendSms>

        </soapenv:Body>

    </soapenv:Envelope>

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

            <ns2:sendSmsResponse xmlns:ns2=http://www.csapi.org/schema/parlayx/sms/send/v2_3/local xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v2_1">

                <ns2:result>267417690</ns2:result>

            </ns2:sendSmsResponse>

        </soap:Body>

    </soap:Envelope>

    <?xml version="1.0" encoding="UTF-8"?>

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

            <ns2:notifySmsDeliveryReceipt xmlns:ns2="http://www.csapi.org/schema/parlayx/sms/notification/v2_2/local" xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v2_1">

                <ns2:correlator>1010</ns2:correlator>

                <ns2:deliveryStatus>

                    <address>tel:16048183614</address>

                    <deliveryStatus>DeliveredToTerminal</deliveryStatus>

                </ns2:deliveryStatus>

            </ns2:notifySmsDeliveryReceipt>

        </soap:Body>

    </soap:Envelope>