VMware AirWatch SDK Plugin for Xamarin Instructions Add AirWatch Functionality to Enterprise Applicataions with SDK Plugins

Transcription

1 VMware AirWatch SDK Plugin for Xamarin Instructions Add AirWatch Functionality to Enterprise Applicataions with SDK Plugins v1.3 Have documentation feedback? Submit a Documentation Feedback support ticket using the Support Wizard on support.air-watch.com. This product is protected by copyright and intellectual property laws in the United States and other countries as well as by international treaties. VMware products are covered by one or more patents listed at VMware is a registered trademark or trademark of VMware, Inc. in the United States and other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies. 1

2 About VMware AirWatch SDK Plugin for Xamarin The VMware AirWatch SDK Plugin for Xamarin helps enterprise app developers add enterprise- grade security, conditional access, and compliance capabilities to mobile applications. Get the Plugin Find the plugin at the NuGet Gallery, Initialization Initialization of the SDK includes many features that have corresponding configurations in the Workspace ONE UEM console. Application level passcode App level tunneling using ModernHTTPClient Integrated authentication and single sign on (SSO) Data Loss Prevention o o o 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 9.0+ Xamarin Studio 2

3 If you have Visual Studio with the Xamarin plug-in, this works. However, this documentation does not outline that method. Use Visual Studio v7.5.x for macos or 15.7.x for Windows. Workspace ONE UEM-enrolled ios test device The VMware AirWatch SDK package from NuGet Gallery 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 VMware AirWatch SDK package from NuGet Gallery An Android test device running Ice Cream Sandwich+ Xamarin Android application to integrate with the AirWatch SDK targeting Android 4.1+ / 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 Instructions for ios Integrate the AirWatch SDK with your Xamarin project. Add Applications to the Workspace ONE UEM 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 Workspace ONE UEM Administrator for details. Add Required SDK Packages to Project Add the VMware AirWatch SDK package from the NuGet Gallery. This process enables the Xamarin IPA file to recognize and apply the AirWatch SDK functionality. 1. Open Xamarin Studio. 2. Right-click Packages and select Add Packages. 3. Search AWSDK on nuget.org and add it to the project. 4. Enable the Assembly check box, if it is not already enabled, 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 Workspace ONE UEM 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

4 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. Add the listed schemes depending on the enrollment application. If the device enrolled with the AirWatch Agent, use airwatch. If the evice enrolled with the Workspace ONE app, use awws1enroll. 9. Save the file. 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"; // private, use the Instance below 4

5 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 () 5

6 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. 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: 6

7 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 Note: See the sample application for an alternate tunneling method. 7

8 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); 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. 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 Workspace ONE UEM 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. 8

9 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 Workspace ONE UEM console. Troubleshooting Tip for SSO Ensure that Single Sign On (SSO) is enabled in the Workspace ONE UEM console and that an authentiation type is configured in the Workspace ONE UEM console. The application does not display an SSO passcode if these settings are not configured in the console. Ask your Workspace ONE UEM Administrator to enable SSO and to select an authentication type in the console in Groups & Settings > All Settings > Settings and Policies > Security Policies. Instructions for Android 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 multi-dexing. 1. Enable the Multi-Dex option for the application in Xamarin. 2. Add the VMware AirWatch SDK package from the NuGet Gallery. 3. Add the dependency NuGet packages from the NuGet Package Manager as References to the application. Square.OkHttp Square.OkIO Xamarin.Android.Arch.Core.Common Xamarin.Android.Arch.Lifecycle.Common Xamarin.Android.Arch.Lifecycle.Runtime Xamarin.Android.Support.Animated.Vector.Drawable Xamarin.Android.Support.Annotations Xamarin.Android.Support.Compat Xamarin.Android.Support.Core.UI Xamarin.Android.Support.Core.Utils Xamarin.Android.Support.Design Xamarin.Android.Support.Fragment Xamarin.Android.Support.Media.Compat Xamarin.Android.Support.Transition

10 Xamarin.Android.Support.v Xamarin.Android.Support.v7.AppCompat Xamarin.Android.Support.v7.CardView Xamarin.Android.Support.v7.Preference Xamarin.Android.Support.v7.RecyclerView Xamarin.Android.Support.v Xamarin.Android.Support.v Xamarin.Android.Support.Vector.Drawable Xamarin.Build.Download Xamarin.Google.Guava Xamarin.GooglePlayServices.Base Xamarin.GooglePlayServices.Basement Xamarin.GooglePlayServices.SafetyNet Xamarin.GooglePlayServices.Tasks Xamarin.Kotlin.StdLib 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 10

11 var intent = new Intent(ApplicationContext, typeof(mainactivity)); // MainActivity is application's main landing activity 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 11

12 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 Workspace ONE UEM base activity. For application level tunneling, use normal HTTP clients or Android WebView. Android WebView refers to the Tunnel URLs set in the Workspace ONE UEM console. Review the sample app for code. For integrated authentication, the application uses Workspace ONE UEM wrapped HTTP clients or AWWebView for Basic, NTLM, or client certificate based authentication. Review the sample app for code. 12

13 For data loss prevention o o o Restricting screenshot actions is enforced when your activity extends GatewayBaseActivity. To restrict copy-paste actions, the application uses Workspace ONE UEM 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 Workspace ONE UEM 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. Workspace ONE UEM 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 Workspace ONE UEM console. The Workspace ONE UEM 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 Workspace ONE UEM Administrator for details. Publicly Deployed Applications For applications that are deployed publicly through an app store, send the public signing key of the application to Workspace ONE UEM for whitelisting. Note: Contact your VMware Workspace ONE UEM representative for help with whitelisting the public signing key. Questions and Feedback Let us know if you have any questions or feedback by contacting us at 13