VMware AirWatch Software Development Kit (SDK) Plugin v1.1 for Xamarin

Transcription

1 VMware AirWatch Software Development Kit (SDK) Plugin v1.1 for Xamarin Overview Use this document to install the VMware AirWatch SDK Plugin for Xamarin. The plugin helps enterprise app developers add enterprise- grade security, conditional access, and compliance capabilities to mobile applications. Initialization Initialization of the SDK includes many features that have corresponding configurations in the AirWatch Console. Application level passcode App level tunneling using ModernHTTPClient Integrated authentication and single sign on (SSO) Data Loss Prevention Disable screenshots (Android only) Restrict open-in for documents, web links, and to only approved applications Restrict copy and paste with an SDK-provided flag value Restrict access to the application when a device is offline Brand splash screens when the application is launched on devices Custom Settings Supported Components This plugin works with the listed versions. ios ios 8.0+ Xamarin Studio If you have Visual Studio with the Xamarin plug-in, this works. However, this document does not outline that method. AirWatch-enrolled ios test device The AirWatchSDK.dll from the Xamarin Component Store An ios application built with Xamarin to integrate with the Airwatch SDK If you do not have an application, you can create a new application in Xamarin Studio and integrate the SDK into that. Android Xamarin Studio or Visual Studio with the Xamarin plugin The AirWatch SDK binaries from the Xamarin Component Store An Android test device running Ice Cream Sandwich+ Xamarin Android application to integrate with the Airwatch SDK targeting Android 4.0(ICS)+ / API Level The AirWatch Agent v7.0+ for Android from the Google Playstore A whitelisted release/debug signing key for signing the Xamarin-built Android application ios Overview Integrate the AirWatch SDK with your Xamarin project. Add Applications to the AirWatch Console Export your application as a signed IPA and then upload it to the console as an internal application. You must assign an SDK profile to the application. Ask your AirWatch Administrator for details. The process is explained in the VMware AirWatch Online Help. See

2 Add Required SDK DLL to Project Get the VMware AirWatch SDK from the Xamarin Component Store. Add the AirWatch SDK DLL to your Xamarin project. This process enables the Xamarin IPA file to recognize and apply the AirWatch SDK functionality. 1. Open Xamarin Studio. 2. Right-click References and choose Edit References. 3. Select the.net Assembly tab and then choose Browse. 4. Select the AirWatchSDK.dll file from your file system. 5. Enable the Assembly check box, if it isn't already, and select OK. Enable Communication Between the AirWatch Agent and the Xamarin IPA File The application must communicate with the AirWatch Agent for ios. The application must register itself with the AirWatch environment. This action allows it to receive the SDK profiles assigned to it. Add a custom scheme in the application's PLIST file. Use the scheme in the callback scheme registration. sdkcontroller.callbackscheme = "mysamplescheme"; //defined in Info.plist Add Callback Scheme Registration 1. Double-click the Info.plist file in your Xamarin project. 2. Select the Advanced tab. 3. In the URL Types section, choose Add URL Type. 4. Set the values of Identifier and URL Schemes to the desired callback scheme. 5. Set the Role to Editor. 6. Save the file. Add SDK App Query Scheme 1. Double-click the Info.plist file in your Xamarin project. 2. Select the Source tab, and choose Add new entry. 3. Select the green "PLUS" in the selected row. 4. Double-click Custom Property and change it to LSApplicationQueriesSchemes. 5. Change the Type from String to Array. 6. Within the Array, select Add new entry. 7. Select the green "PLUS" in the selected row. 8. Double-click the Value column and set the value to airwatch. 9. Add another entry under LSApplicationQueriesSchemes for workspace. 10. Save the file. Note: The scheme for Workspace ONE is awws1enroll. Add an App Delegate to the Xamarin Project To complete the integration of Xamarin and the AirWatch SDK, use a custom App Delegate. Create a class to act as an AWSDKDelegate, define the callback scheme within the class, and set the class to recognize when initialization is complete. 1. Create a class to act as an AWSDKDelegate and to receive SDK callbacks. using Foundation; using System.Diagnostics; using System; using AirWatchSDK; namespace sdksampleapp public class AirWatchSDKManager: AWSDKDelegate private static AirWatchSDKManager instance; private static string LogCategory = "AirWatchSDK";

3 // private, use the Instance below private AirWatchSDKManager () // singleton public static AirWatchSDKManager Instance get if (instance == null) instance = new AirWatchSDKManager (); return instance; // Below are all the protocol methods defined in AWSDKDelegate // Add customization here for SDK results override public void InitialCheckDoneWithError (NSError error) string message = String.Format ("InitialCheckDoneWithError received 0, SDK initialized if no error", error); Debug.WriteLine (message, LogCategory); override public void ReceivedProfiles (AWProfile[] profiles) string message = String.Format ("ReceivedProfiles received 0", profiles); Debug.WriteLine (message, LogCategory); override public void Wipe () Debug.WriteLine ("Wipe command received", LogCategory); override public void Lock () Debug.WriteLine ("Lock command received", LogCategory); override public void Unlock () Debug.WriteLine ("Unlock command received", LogCategory); public override void StopNetworkActivity(AWNetworkActivityStatus status) Debug.WriteLine("StopNetworkActivity received", LogCategory); override public void ResumeNetworkActivity () Debug.WriteLine ("ResumeNetworkActivity received", LogCategory); 2. Add the listed functionality to the AppDelegate.cs.

4 using System; using ObjCRuntime; using System.Diagnostics; using AirWatchSDK;... public override bool FinishedLaunching (UIApplication application, NSDictionary launchoptions) if (Runtime.Arch == Arch.SIMULATOR) Debug.WriteLine ("Running in Simulator, skipping initialization of the AirWatch SDK!"); return true; else Debug.WriteLine ("Running on Device, beginning initialization of the AirWatch SDK."); // Configure the Controller by: var sdkcontroller = AWController.ClientInstance (); // 1) defining the callback scheme so the app can get called back, sdkcontroller.callbackscheme = "mysamplescheme"; // defined in Info.plist // 2) set the delegate to know when the initialization has been completed. sdkcontroller.delegate = AirWatchSDKManager.Instance; return true; public override void OnActivated (UIApplication application) AWController.ClientInstance ().Start (); public override bool HandleOpenURL (UIApplication application, NSUrl url) return AWController.ClientInstance ().HandleOpenURL (url, ""); If you are using Xamarin Forms on ios, you need to add this to your AppDelegate, too. This exposes the UIWindow that is part of the ios AppDelegate but is hidden in Xamarin.Forms.Platform.iOS.FormsApplicationDelegate. [Export("window")] public UIWindow GetWindow() return UIApplication.SharedApplication.Windows[0]; ModernHTTPClient Integration for App Level Tunneling Functionality Use ModernHTTPClient to add tunneling functionality. Libraries using ModernHttpClient; using System.Net.Http; Request and Response Format var uri = new Uri(" //where xyz is internal url or the url which needs to go via tunnel var httpclient = new HttpClient(new NativeMessageHandler()); HttpResponseMessage response = await httpclient.getasync(uri); Note: See the sample application for an alternate tunneling method. SDK Callbacks override public void InitialCheckDoneWithError(NSError error): This is the first expected callback from SDK after initialization. If there is no error, then the SDK is successfully initialized and the user is authenticated.

5 override public void ReceivedProfiles(AWProfile[] profiles): Sent when the device receives the SDK or application profiles. override public void Wipe(): Sent when the device receives a wipe command from the console or is wiped from any other applications. override public void Lock(): Sent when the application is locked. The SDK shows the authentication screen when the system processes the lock action. override public void unlock(): Sent when the application is being unlocked. public override void StopNetworkActivity(AWNetworkActivityStatus status): Sent when the application should stop all the network activities due to violations of any settings in the console. override public void ResumeNetworkActivity(): Sent when the application can resume network activities. Functions allowcopypaste(): Returns a Boolean value that identifies if the copy paste operation is allowed between managed applications. Configure this function in the Data Loss Prevention (DLP) settings. restrictdocumenttoapps(): Returns a Boolean value that signifies if document-opening is allowed in specific applications. If allowed, then you can obtain a list of allowed applications from allowedapplicationslist(). allowedapplicationslist(): Returns a NSArray containing list of allowed applications for document opening when restrictdocumenttoapps is enabled. Configure this function in the DLP settings. allowcamera() Returns a Boolean value that signifies if camera access is allowed or not. Configure this function in the DLP settings. customsettings() Returns a string containing Custom settings. Set this function in the AirWatch Console Settings And Policies> Settings > Custom Settings. If this is a custom profile, set the function while creating a custom profile. allowintegratedauthentication(): Returns a Boolean that signifies if integrated authentication is allowed or not. allowedsiteslist(): Returns the list of allowed sites for integrated authentication. Configure this function in the Integrated Authentication settings. opendocumentfromurl(nsurl url, UIView view): Opens documents using AWDocumentInteractionController and provides the url and view. opendocumentfromfile(string filename, string fileext): Opens documents using AWDocumentInteractionController and gives the file name and extension. DLPEnabled(): Returns a Boolean value that identifies if DLP is enabled in the AirWatch Console. Troubleshooting Tip for SSO Ensure that Single Sign On (SSO) is enabled in the AirWatch Console and that an authentiation type is configured in the AirWatch Console. The application does not display an SSO passcode if these settings are not configured in the console. Ask your AirWatch Administrator to enable SSO and to select an authentication type in the console in Groups & Settings > All Settings > Settings and Policies > Security Policies. Android Overview This document describes how to integrate the VMware AirWatch SDK for Android components into an existing Xamarin Android application. Integrate the AirWatch SDK Integrate the AirWatch SDK into your Android application built with Xamarin. Enable Multi-Dexing and Add Binaries and Dependencies While integrating the AirWatch SDK, the application method count can exceed 64k due to library dependencies. To prevent issues, enable multidexing. 1. Enable the Multi-Dex option for the application in Xamarin. 2. Add the five AirWatch SDK for Android binaries (DLLs) downloaded through the Xamarin Component Store as References to the application. AWClientSDKBindings AWMixPanelBindings AWSQLCipherBindings AWFrameworkBindings AWNetworkLibraryBindings 3. Add the dependency NuGet packages from the NuGet Package Manager as References to the application. Xamarin.Android.Support.v13 version Xamarin.Android.Support.v7.AppCompat version Xamarin.Android.Support.v7.CardView version

6 Xamarin.Android.Support.v7.RecyclerView version Xamarin.Android.Support.Design version Xamarin.Android.Support.v14.Preference version Xamarin.GooglePlayServices.SafetyNet version Square.OkHttp3 version Initialize the AirWatch SDK. Initialize the AirWatch SDK 1. Extend the application class to the AWApplication class. Override the MainActivityIntent to return the application's main landing activity. Move the application's oncreate() business logic to onpostcreate(). namespace XamarinAndroidSampleApp.Landing [Application(Label = "@string/app_name", Icon = "@drawable/applogo", Theme = "@style/apptheme")] public class SampleApplication : AWApplication public SampleApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership) public override Intent MainActivityIntent get var intent = new Intent(ApplicationContext, typeof(mainactivity)); // MainActivity is application's main landi return intent; public override Intent MainLauncherIntent get var intent = new Intent(ApplicationContext, typeof(gatewaysplashactivity)); return intent; public override bool MagCertificateEnable get return true; // to fetch mag certificate during initial setup protected override bool IsInputLogoBrandable get return true; // to brand application logo public override void OnPostCreate() base.onpostcreate(); // App specific code here

7 2. Add 'AirWatchSDKIntentService' by setting the name as [AppPackageName].AirWatchSDKIntentService. 3. Set GatewaySplashActivity as your main launching activity. 4. Add 'AirWatchSDKBroadcastReceiver' broadcast receiver declarations in the manifest file. <application android:name="sampleapplication" tools:replace="android:label"> <activity android:name="com.airwatch.gateway.ui.gatewaysplashactivity" <intent-filter> <action android:name="android.intent.action.main" /> <category android:name="android.intent.category.launcher" /> </intent-filter> </activity> <activity android:name=".mainactivity" /> <receiver android:name="com.airwatch.sdk.airwatchsdkbroadcastreceiver" android:permission="com.airwatch.sdk.broadcast" <intent-filter> <action android:name="com.airwatch.xamarinsampleapp.airwatchsdk.broadcast" /> </intent-filter> <intent-filter> <action android:name="android.intent.action.package_added" /> <action android:name="android.intent.action.package_removed" /> <action android:name="android.intent.action.package_replaced" /> <action android:name="android.intent.action.package_changed" /> <action android:name="android.intent.action.package_restarted" /> <data android:scheme="package" /> </intent-filter> </receiver> </application> 5. For authentication, timeout, and data loss prevention features, all the application activities extend from Com.Airwatch.Gateway.UI.GatewayBaseActivity. This process enables the application to handle the lifecycle and to manage the state of the AirWatch SDK. Features Application level branding, authentication, timeout behavior, and offline access are enforced by integrating and extending the AirWatch base activity. For application level tunneling, use normal HTTP clients or Android WebView. Android WebView refers to the Tunnel URLs set in the AirWatch Console. Review the sample app for code. For integrated authentication, the application uses AirWatch wrapped HTTP clients or AWWebView for Basic, NTLM, or client certificate based authentication. Review the sample app for code. For data loss prevention, restricting screenshot actions is enforced when your activity extends GatewayBaseActivity. To restrict copy-paste actions, the application uses AirWatch wrapped textviews like AWEditText, AWTextView, and AWWebView. To restrict open-in for documents, weblinks, and , use UriOpenerFactory.Instance.OpenUri(context, uri) and UriOpenerFactory.Instance.OpenUri(context, filepath) as shown in the sample app. For custom settings, use the SDKManager API. You can use any SDKManager API. try // Below call will return SDKManager instance readily // as it is already initialised as part of Login flow. var sdkmanager = SDKManager.Init(this); textview.text = sdkmanager.customsettings; catch (AirWatchSDKException e) // exception while using SDKManager API Whitelist Signing Key Before you can use the AirWatch SDK for Android, ensure your application's signing key is whitelisted with your AirWatch Console. When your SDK-integrated application starts up, the SDK checks the signing public key. It compares it against the list of whitelisted applications to determine if your application is trusted.

8 AirWatch allows whitelisting for both applications deployed internally or deployed through a public app store. Internally Deployed Applications 1. After building the application APK, sign it using your own specific app signing key. 2. Upload the signed APK file to the AirWatch Console. The AirWatch Console extracts the application's public signing key and adds it to the whitelisted apps list. You must assign an SDK profile to the application. Ask your AirWatch Administrator for details. The process is explained in the VMware AirWatch Online Help. See Publicly Deployed Applications For applications that are deployed publicly through an app store, send the public signing key of the application to AirWatch for whitelisting. Note: Contact your VMware AirWatch representative for help with whitelisting the public signing key. AirWatch SDK Documentation For further details about the AirWatch SDK, navigate to and search for AirWatch SDK Technical Implementation Guides in the Application Management section. Questions and Feedback Let us know if you have any questions or feedback by ing us at support@air-watch.com.