Android Authenticator SDK Integration

Setup for Android Studio

To setup the Authenticator SDK in your Android Studio project:

  1. Download the Authenticator SDK for Android Studio

  2. Open your project in Android Studio and navigate to File -> New Module, and then select Import .JAR or .AAR Package from the More Modules list, and click Next. Then browse for the file, select it, and click Finish.

  3. The SDK should now be a part of your project as a module, but in order to make it a dependency for your application, navigate to File -> Project Structure and select the implementing application in the list of modules (e.g. app), and then navigate to the Dependencies tab. Add the module by clicking the plus button (+) and select Module Dependency. Select the library module which should now appear in the list and press OK, followed by OK once more to update the dependencies, and clean your project to include the build.gradle file.

  4. Lastly, make sure the application has all of the required libraries for the SDK to work properly. If missing, add these dependencies to your app module’s build.gradle file:

    dependencies{
        compile fileTree(dir: ‘libs’, include: [‘*.jar’])
        compile ‘com.android.support:support-v4:21.0.3’
        compile ‘com.android.support:appcompat-v7:21.0.3’
        compile ‘com.google.android.gms:play-services-location:6.5.87’
        compile ‘com.nineoldandroids:library:2.4.0’
    }
    

Initialize the Authenticator SDK

To initialize the Authenticator SDK within the Activity, instantiate the SDK manager:

WhiteLabelManager mWhiteLabelManager = WhiteLabelManager.getInstance();

Configuration Options - Optional

Note

If you are not modifying the default configuration options, you may skip to the next section: Initialize the SDK Manager

The Authenticator SDK provides multiple configuration options to customize the branding, aesthetics, and security of the Auth Modal itself. This is accomplished through a configuration object. To modify the default configuration options, instantiate a WhiteLabelConfig.Builder object, and call a series of chained methods with your desired configuration before calling the build() method which will return the complete configuration object. Instantiate the configuration object like this (explanation of options afterwards):

WhiteLabelConfig config =
            new WhiteLabelConfig.Builder(context)
            .sslPinning(boolean)
            .themeLauncherSwitchIconRes(int)
            .themeTextColor(int)   // or .themeTextColorRes(int)
            .themeBackgroundColor(int)   // or .themeBackgroundColorRes(int)
            .themeSecondaryColor(int)   // or .themeSecondaryColorRes(int)
            .themeAlpha(float)
            .themeColorScheme(int)
            .build();

Background Color

.themeBackgroundColorRes(int)
.themeBackgroundColor(int)

The default color of the Auth Modal background is near-black (hex #1E1E29, RGB 30,30,41). To change this to a different color, include the .themeBackgroundColor() method in your configuration options and pass a value (int) for your color in the argument (e.g. Color.BLACK). If instead you want to pass a reference value for a color in the argument (e.g. R.color.my_brand_blue), use the .themeBackgroundColorRes() method.

Background Alpha (Transparency)

.themeAlpha(float)

The default alpha value for the Auth Modal background is 0.85 (85% opacity). To modify the alpha value of the modal, include the .themeAlpha() method and pass an alpha value (float) between 0.0 (completely transparent) to 1.0 (completely opaque).

Text Color

.themeTextColor(int)
.themeTextColorRes(int)

The default text color in the Auth Modal is white (hex #FFFFFF, RGB 255,255,255). To change the text color, include the .themeTextColor() method in your configuration options and pass a value (int) for the color you prefer in the argument (e.g. Color.BLACK). If instead you want to pass a reference value for the text color in the argument (e.g. R.color.my_brand_blue), use the .themeTextColorRes() method.

UI Theme Color

.themeColorScheme(int)

The Auth Modal interface includes various graphic elements that can be set to either a dark (black) or light (white) theme to ensure they’re visible with your background color choice. To use the dark color scheme, pass a static value of WhiteLabelConfig.COLOR_SCHEME_DARK in the argument, and to use the light color scheme, pass a value of WhiteLabelConfig.COLOR_SCHEME_LIGHT in the argument. Default is light.

Secondary Theme Color

.themeSecondaryColor(int)
.themeSecondaryColorRes(int)

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 by the UI Theme Color, but you can explicitly define a secondary color by including the .themeSecondaryColor() method in your config object and passing a value (int) for your color in the argument (e.g. Color.BLACK). If instead you want to pass a reference value for a color in the argument (e.g. R.color.my_brand_blue), use the .themeSecondaryColorRes() method.

Custom Launcher Image

.themeLauncherSwitchIconRes(int)

The default User interaction to approve an Auth Request from your Application is to slide an approval slider 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, avatar, etc.). Your launcher image should be a square PNG image (93x93 pixels). To use your own launcher image, include the .themeLauncherSwitchIconRes() method, and pass a reference (int) to a drawable in the argument.

SSL Pinning (Extra Security)

.sslPinning(boolean)

The Authenticator SDK uses SSL for network communication to the LaunchKey Platform API to ensure secure data transmission. However, to protect against eavesdropping and ensure that man-in-the-middle attacks cannot occur over this connection, you can enable SSL pinning which will verify the hostname and SSL certificate returned from the Platform API handshake exactly matches those that are bundled in your Mobile App. If the certificate cannot be verified, all connections to the Platform API are terminated. To turn SSL pinning ON, include the .sslPinning() method in your configuration object and pass a value (boolean) of true to turn on, or false to explicitly turn it off.

Note

SSL pinning is turned OFF by default.

Warning

SSL pinning should only be enabled if you fully understand the consequences of enabling this feature as connectivity to the LaunchKey Platform API can be interrupted if SSL pinning is not properly configured.

Initialize the SDK Manager

Next, initialize the SDK manager. If you’ve modified the default configuration with your own configuration object, you’ll need to pass the config object along with context and your Authenticator SDK Key (string) like this:

mWhiteLabelManager.init(context, "WHITE_LABEL_SDK_KEY_HERE", config);

If you’re not modifying the default configuration, you can ignore the config argument:

mWhiteLabelManager.init(context, "WHITE_LABEL_SDK_KEY_HERE");

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.

Display Linking View

use this view in the device linking process to give your User the ability to scan a QR linking code or manually enter a 7-character alphanumeric linking code provided 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 section.

To display the Linking View, make the following call:

mWhiteLabelManager.displayLinkingUi(Context);

Once the device has been successfully linked, the account status will change to true. The status can be checked with the .isDeviceLinked() method.

Display Security View

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

mWhiteLabelManager.displaySecurityUi(Context);

Note

The Security View will only be displayed if the .isDeviceLinked() method 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:

mWhiteLabelManager.displayAuthRequestUi(Context);

Note

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

Listening For Specific Events

To ensure proper interaction between your Mobile App and User, it will be necessary for your Mobile App to listen for specific events from the Authenticator SDK such as successful authentication, failed authentication, successful device linking, and User logout. To listen for an event, mWhiteLabelManager.setEventListener(EventListener) needs to be called while passing the instantiated listener. Callbacks to methods of this listener will then be made when these events take place.

Example:

WhiteLabelManager.EventListener eventListener = new

WhiteLabelManager.EventListener() {
        @Override
        public void onAuthenticationSuccess() {
            // do something after user authenticates and authorizes your request
        }
        @Override
        public void onAuthenticationFailure() {
            // do something after failed authentication or request rejection
        }
        @Override
        public void onUnlink() {
            // check user status and display link or settings button if appropriate
        }
        @Override
        public void onLogout() {
            // do something when user logs out of session
        }
};

mWhiteLabelManager.setEventListener(eventListener);

Implementing Push Notifications - Optional

Although optional, we recommend using push notifications in your Mobile App to provide a better user experience. With push notifications, The Platform will push alerts to your User’s device to notify them of pending Auth Requests from your service. To use this feature, follow these steps:

Warning

Push notifications are dependent upon the proper function of the Android 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.

Additions to Android Manifest

First, you’ll need to make some additions to the AndroidManifest.xml file. Place these permissions on the same level as normal permissions:

<!—- GCM-required package-based permissions —->
<permission android:name="<YOUR PACKAGE>.permission.C2D_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="<YOUR PACKAGE>.permission.C2D_MESSAGE" />
<!—- All other GCM-required permissions are part of the SDK manifest and will be merged by Android —->

Then place these within the last <application> tag which is part of the same Android Manifest XML file:

<!—- GCM-related receiver and service —->
<receiver android:name="...android.whitelabel.sdk.gcm.GcmBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <category android:name="<YOUR PACKAGE>" />
    </intent-filter>
</receiver>
<service android:name="...android.whitelabel.sdk.gcm.GcmIntentService" />

Where <YOUR PACKAGE> is your Mobile App’s package (e.g. you.package.here). This code creates a couple of SDK classes to process the push notifications that will be sent to your Mobile App.

Generate Server & Android API Keys

Next, you’ll need to generate a Server and Android API Key from the Google Developer Console. To do so, follow these steps:

  1. Go to https://console.developers.google.com and create or open an existing project
  2. Write down or take note of the Project Number shown at the top of the project overview; this will be used in the next step.
  3. Under APIs & Auth, click Auth, and navigate to the Enabled APIs tab to make sure the Google Cloud Messaging for Android API is enabled. If it’s not part of the list, add this API from the API Library tab.
  4. Next, to generate the key for the Android app and the server, navigate to Credentials under API & Auth, and then click Create New Key under Public API Access.
  5. Choose Server Key, and then Create, and the list of API keys should be updated with the new key for Server Applications and all IPs allowed.
  6. Finally, click Create New Key under Public API Access, and choose Android Key and add required input before clicking Create. The list of API keys should be updated with a new key for Android Applications and its debug/production build certificate fingerprints and package.

Note

Remember, the debug certificate has a different fingerprint so it needs to be included at the time the Android service key is generated to make sure the debug builds also receive push notifications.

Add Android API Key to Android Project

Next, add the Android API Key from the previous step to your Android Project. This will allow your Mobile App to register for Push Notifications from Google Cloud Messaging since your Mobile App will be authorized with the provided package and cert fingerprint.

  1. Open your project

  2. Navigate to the values folder under the res folder and create a new resource file such as whitelabel.xml with a String value that will contain the Project Number from your project overview in the Google Developers Console (step 2 above) under the key whitelabel_gcm_sender_id. It should look similar to this:

    <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <string name="whitelabel_gcm_sender_id">123456789012</string>
    </resources>
    

    This key will be automatically retrieved by the Authenticator SDK. It’s also important to make sure that the Project Number string is part of the resources of your project.

Add Server API Key to directory

Next, add the Server API Key to your directory. Log into Dashboard and click on Organizations to navigate to your Organization details page. Finally, click on the relevant group under the directory*s section and add your Server API Key to the *Android Server API Key field.

Intercepting Push Notification to Trigger Auth Request View

Finally, to ensure Auth Requests are fetched and shown automatically when pushed to your Mobile App, a couple of calls have to be added to the activity or fragment. Call the respective onResume() and onPause() methods of the SDK manager within the activity or fragment’s own methods.

Example:

@Override
    protected void onResume() {
        super.onResume();
        ...
        mWhiteLabelManager.onResume(this); // or getActivity() if within a fragment
        ...
    }

@Override
protected void onPause() {
        super.onPause();
        ...
        mWhiteLabelManager.onPause();
        ...
}

Enable Google Maps for Geo-Fencing

One of the authentication factors available to Users is geo-fencing. Users can define one or many geo-fences, and when enabled, their mobile device will ensure that it’s located within these bounds before allowing authorization to proceed. To configure this factor, your Mobile App will need access to Google Maps. To ensure your Mobile App has this access, do the following:

  1. Navigate to https://console.developers.google.com and modify the project related to your Mobile App.

  2. Enter the project and navigate to APIs under APIs & Auth. Make sure Google Maps Android API v2 is listed in the Enabled APIs tab, and if it isn’t, add it from the API Library tab.

  3. Go to Credentials under APIs & Aut. If there is already an Android key generated for your service, skip to step 5

  4. Click Create New Key and choose Android Key. Follow the instructions to enter your service's cert fingerprint and package before clicking Create.

  5. The key generated for your Android app has to be included in your Android Manifest within the <application> tag, just before it closes, as a meta-data element like this:

    <meta-data android:name="com.google.android.geo.API_KEY" android:value="API_KEY_HERE" />
    

    Where API_KEY_HERE should be replaced with your Android Key which should look like something similar to AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0

With this in place, your Mobile App should now be able to make use of the Google Maps API for Android. The permissions are included in the SDK, but if you experience any problems, refer to the official Getting Started documentation for Google Maps API v2 for Android at https://developers.google.com/maps/documentation/android/start

Performing Auth Modal Actions Directly In Your App - Optional

The Authenticator SDK exposes certain methods involving User logout, device link / User register, and device un-link, 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:

mWhiteLabelManager.logout(Context);

Done

The Authenticator SDK has now been configured and added to your Android project. The final step is to integrate the LaunchKey Platform API within your service using one of the Platform 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. ×