Windows Phone Authenticator SDK Integration

Adding the Authenticator SDK to your Windows Phone Project

To add the Authenticator SDK to your Windows Phone project, begin by adding the WhiteLabelSDK.dll as a reference to your project. After the Authenticator SDK has been successfully added, you will need to reference the following libraries within your project:

  • BouncyCastle.dll
  • Coding4Fun.Toolkit.controls.dll
  • GalaSoft.MvvmLight.Extras.WP8.dll
  • GalaSoft.MvvmLight.WP8.dll
  • Newtonsoft.Json.dll
  • RestSharp.WindowsPhone.dll
  • Zxing.wp8.0.dll
  • ZXingNetMobile.dll
  • System.Windows.Interactivity
  • Microsoft.Expression.Interactions
  • Microsoft.Practices.ServiceLocation

You should see these references in the References section in your project.

Next, in the WMAppManifest.xml under the Capabilities tab, enable the following permissions:

  • ID_CAP_IDENTITY_DEVICE
  • ID_CAP_ISV_CAMERA
  • ID_CAP_LOCATION
  • ID_CAP_MAP
  • ID_CAP_MEDIALIB_PLAYBACK
  • ID_CAP_NETWORKING
  • ID_CAP_PROXIMITY
  • ID_CAP_PUSH_NOTIFICATIONS
  • ID_CAP_SENSORS

Initializing the Authenticator SDK

In the root page of your Windows Phone app, before you make any additional calls to WhiteLabelSDK, you need to initialize the LaunchKeyManager. To do so, make this call:

Prototype:

public void Init(String sdkKey);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.Init("YOUR_SDK_KEY_HERE");

Your SDK Key can be found in the Keys tab of your Service’s Details page within Dashboard.

Register Windows Push Notification Token

In order to identify the User’s device and to receive push notifications from LaunchKey (more on this later), you will need to register for a Windows Push Notification token. To register for a notification token, make this call:

channel.ChannelUriUpdated += new EventHandler<NotificationChannelUriEventArgs>(channel_ChannelUriUpdated);

Next, in the callback function channel_ChannelUriUpdated, make a call to the LaunchKeyManager to register the device’s token with the LaunchKey Authenticator SDK via SetNotificationToken:

Prototype:

public void SetNotificationToken(String token);

Example:

void channel_ChannelUriUpdated(object sender, NotificationChannelUriEventArgs e)
{
    WhiteLabelSDK.LaunchKeyManager.Instance.SetNotificationToken(channel.ChannelUri.ToString());
}

Configuration Options - Optional

With the LaunchKey Configurator, you can modify various aesthetic and security configuration options for the Auth Modal by modifying the LaunchKeyConfigurator object with the following calls:

Background Color

The default color of the Auth Modal background is near-black (hex #1E1E29, RGB 30,30,41). To change this to a different color, modify the Configurator with this call:

Prototype:

public void SetModalBodyBackgroundColor(Color bodyBackgroundColor);

Example (setting modal background color to white):

LaunchKeyConfigurator.Instance.SetModalBodyBackgroundColor(Color.FromArgb(255, 255, 255, 255));

Background Alpha (Transparency)

The default alpha value for the Auth Modal background is .85 (85% opacity). To modify the alpha value, modify the Configurator with the following call:

Prototype:

public void SetModalOpacity(float opacity);

Example (setting opacity to 70%):

LaunchKeyConfigurator.Instance.SetModalOpacity(0.7F);

Text Color

The default text color in the Auth Modal is white (hex #FFFFFF, RGB 255,255,255). To change the text color, modify the Configurator with this call:

Prototype:

public void SetModalTextColor(Color modalTextColor);

Example (setting text color to black):

LaunchKeyConfigurator.Instance.SetModalTextColor(Color.FromArgb(255, 0, 0, 0));

Secondary Text Color

The default secondary text color (used in all text input fields) is near-black (hex #2E2E2E; RGB 46,46,46). To change the secondary text color, modify the Configurator and pass in a custom color with this call:

Prototype:

public void SetSecondaryTextColor(Color secondaryTextColor);

Example:

LaunchKeyConfigurator.Instance.SetSecondaryTextColor(Color.FromArgb(255, 0, 0, 0));

UI Theme Color

The Auth Modal includes various user interface graphics that can be set to either a dark (black) or light (white) theme to ensure they’re visible with your background color choice. To set the UI theme (default is light), modify the Configurator with one of the following calls:

Prototype:

// Dark theme
public void SetDarkTheme();

// Light theme
public void SetLightTheme();

Example:

// Dark theme
LaunchKeyConfigurator.Instance.SetDarkTheme();

// Light theme
LaunchKeyConfigurator.Instance.SetLightTheme();

Secondary Theme Color

The secondary theme color is the color used in interface elements such as buttons and form inputs. While the alpha for these elements is determined by the SDK, the alpha differs depending on the element and its current state. The default secondary theme color is determined from the UI Theme Color (above), but you can explicitly define a color by modifying the Configurator using this call:

Prototype:

public void SetSecondaryColor(Color secondaryBackgroundColor);

Example (setting secondary color to red):

LaunchKeyConfigurator.Instance.SetSecondaryColor(Color.FromArgb(255, 255, 0, 0));

Custom Launcher Image

The default user interaction to approve an Auth Request from your service is to slide an approval slder x upwards. The default launcher has a LaunchKey icon within it, but you can replace this icon with your own image (e.g. your company logo or avatar). Your launcher image should be a square PNG file, 93x93 pixels. To set a custom launcher image, modify the Configurator with this call:

Prototype:

public void SetLauncherImage(BitmapImage launcherImage);

Example:

LaunchKeyConfigurator.Instance.SetLauncherImage("bitmap_image");

Interacting with the Auth Modal

The Auth Modal is what your directory users will interact with inside your Mobile App to link/un-link their device, authenticate and respond to auth requests from your service, and configure various settings. The modal lives hidden from view within your Mobile App and slides into view as necessary.

Displaying the Auth Modal

To display the Auth Modal, add the view to your page’s XAML by adding the following to your page’s header so you can reference the LauncherView:

<Page
    xmlns:view="clr-namespace:WhiteLabelSDK.Views;assembly=WhiteLabelSDK"
>
<!-- Page stuff -->
</Page>

Next, add the following as the top-most element of the page to every page that will show the Auth Modal. It should span the height and width of the page.

<view:LauncherView VerticalAlignment="Center" HorizontalAlignment="Center" x:Name="thisLauncherView" ></view:LauncherView>

Display Pairing View

Use this view in the device linking/user registration process to give your User the ability to scan a QR linking code or manually enter a 7-character alphanumeric linking code provided externally by your service.

Note

Your Mobile App can also link the User’s device from within your own custom view using an exposed method. To do this, read the Performing Auth Modal Actions Directly In Your App - Optional section.

To display the Pairing View in the Auth Modal, make the following call:

Prototype:

public void ShowLaunchKeyPairView(LauncherView launcher, Action pairedCallback, Action<string, string> failureCallback);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.ShowLaunchKeyPairView(thisLauncherView, pairedCallback, failureCallback);

Once the device has been successfully linked, the account status will change to active. The status can be checked with the .IsAccountActive() method like this:

Prototype:

public Boolean IsAccountActive();

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.IsAccountActive();

Display Settings View

The Authenticator SDK provides the User with certain auth-related settings through the Auth Modal (e.g. enable/configure authentication factors, log out, unlink device). To display the Settings View in the Auth Modal, make the following call:

Prototype:

public void ShowLaunchKeySettingsView(LauncherView launcher, Action unPairedCallback);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.ShowLaunchKeySettingsView(thisLauncherView, unPairedCallback);

The unPairedCallback callback will be called if the User has unlinked their device from your directory.

Note

The Settings View will only be displayed if IsAccountActive() returns true, meaning the User has successfully linked their device.

Display Auth Request View

To give your Users the ability to authenticate and respond to pending Auth Requests from your service, make a call to:

Prototype:

public void ShowPendingAuthentication(LauncherView launcher, Action successCallback, Action<string, string> failureCallback);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.ShowPendingAuthentication(thisLauncherView, authorizeSuccessCallback, authorizeFailureCallback);

Note

The Auth Request View will only be displayed if IsAccountActive() returns true, meaning the User has successfully linked their device.

Configure Service For Push Notifications - Optional

Although optional, we recommend using push notifications in your Mobile App to provide a better user experience. With push notifications, LaunchKey will push alerts to your User’s device to notify them of pending Auth Requests from your service. Additionally, your Mobile App can check for these notifications and automatically display the Request View to the user.

Warning

Push notifications are dependent upon the proper function of the Windows Phone push notification system and your User’s mobile carrier. Slowdowns, outages, or other problems may affect the speed and ability of your User’s mobile device to receive push notifications. Therefore, in addition to push requests, it’s highly recommended that you provide a manual option for your User to check for pending Auth Requests within your Mobile App.

To use push notification, follow these steps:

Generate Windows Push Notification SSL Certificate

To use push notifications, you will need to generate a combined SSL certificate. It is highly recommended that this is a certificate made exclusively for this purpose only. Do not provide LaunchKey with your domain’s primary certificate and key! To get started, generate an OpenSSL certificate consisting of a signed cert, an intermediate cert, and a root cert. Combine these certs into one file with this command:

$ cat name_of_your_application.crt COMODORSADomainValidationSecureServerCA.crt COMODORSAAddTrustCA.crt > name_of_your_application.pem

Be sure to remove the password from the cert with this command:

$ openssl rsa -in name_of_your_application.key -out name_of_your_application.nopass.key

Authorize Certificate with Microsoft & Add to directory

Upload the cert to the Windows Phone dev center under MPN Certificates - https://dev.windowsphone.com/en-us/Account/Certificates. Then, add the certificate and private key to your directory:

  1. Log in to Dashboard, click on Organizations, and click on the name of your Organization.
  2. Scroll down to the directories section and click on the directory associated with this integration.
  3. Under the Push Notification Credentials section, upload your private key (.key) corresponding to Windows Private Key
  4. Under the Push Notification Credentials section, upload the combined certificate (.pem) corresponding to Windows Certificate.

Intercepting Push Notifications For Auth Requests - Optional

If you’re using push notifications, your Mobile App will receive a toast notification regarding the pending Auth Request from LaunchKey. Your Mobile App should intercept this notification in order to trigger the Request View of the Auth Modal. You can intercept the toast notification via the ShellToastNotificationReceived callback:

channel.ShellToastNotificationReceived += (s, e) => Deployment.Current.Dispatcher.BeginInvoke(() => ToastReceived(e));

void ToastReceived(NotificationEventArgs e) { }

In the ToastReceived callback, your Mobile App should trigger the Request View.

Performing Auth Modal Actions Directly In Your App - Optional

The Authenticator SDK exposes certain methods including User logout, device pairing/User registration, and device unlinking, so that your Mobile App can perform these actions outside of the Auth Modal. With this capability, you can use your own buttons, interfaces, and views for these actions instead of relying on the Auth Modal.

User Logout

To log out all active sessions for the current User, call:

Prototype:

public void LogOut(Action successCallback, Action<string, string> failureCallback);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.LogOut(successCallback, failureCallback);

Pair Device/Register User

Your Mobile App can also Link a device and register a User with your directory (same process) outside of the Auth Modal. Like linking a device through the Auth Modal, your Mobile App will need to obtain a linking code either by scanning a QR code or by having the User manually enter a 7-character alphanumeric linking code displayed by your external service. Once the linking code is obtained, you can register the User and link their device by calling:

Prototype:

public void RegisterUser(String qrCode, Action successCallback, Action<string, string> failureCallback);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.RegisterUser("PAIRING_CODE", successCallback, failureCallback);

Un-Pair Current Device

To unlink the User’s current device, call:

Prototype:

public void UnpairDevice(Action successCallback, Action<string, string> failureCallback);

Example:

WhiteLabelSDK.LaunchKeyManager.Instance.UnpairDevice(successCallback, failureCallback);

Add ApplicationID & Authentication Token

One of the authentication factors available to your Users is geo-fencing which allows the User to define one or more geographic zones their mobile device must be physically located within as a factor of authentication. Configuring this security factor requires use of the Map controller, but before you can publish a mobile app that uses the Map control, you must obtain an ApplicationID and AuthenticationToken from the Windows Phone Developer Center, and then add the values to your code. The values that you receive are specific to the individual app for which you request them.

To obtain these values:

  1. Once you have finished your app, begin the app submission process.
  2. On the Submit App page, click Map Services which will open the Map Services page.
  3. On that page, click Get Token, and the new ApplicationID and AuthenticationToken will be displayed.

Copy these values and update the LaunchKeyConfigurator instance with this call:

public void SetMapKey(String applicationId, String authenticationToken);

Done

The Authenticator SDK has now been configured and added to your Windows Phone project. The final step is to integrate the LaunchKey API within your service using one of the LaunchKey SDKs.

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×