Table of Contents VMware Workspace ONE for iOS Developer Guide · Workspace ONE for iOS (Swift)...
Transcript of Table of Contents VMware Workspace ONE for iOS Developer Guide · Workspace ONE for iOS (Swift)...
DeveloperGuide
WorkspaceONEforiOS(Swift) Page1of64
VMwareWorkspaceONEforiOSDeveloperGuideTheVMwareWorkspaceONE®SoftwareDevelopmentKitforiOS(Swift),isasetoftoolsthatincorporatesfunctionalityintocustom-built,iOSapplications.Itenhancesthesecurityandfunctionalityofthoseapplicationsandhelpssavetimeandmoney.
TableofContentsSoftwareVersionandCompatibility............................................................................................................3
OperationalData.......................................................................................................................................4
SetUptheSDKwithYourApp...................................................................................................................5
InitializetheWorkspaceONESDKforiOS(Swift)........................................................................................6
ConfiguretheInfo.plist..............................................................................................................................8
RequiredandOptionalAWControllerDelegateCallbackMethods................................................................9
KeychainAccessGroupEntitlements.........................................................................................................10
ClusterSessionManagementandReducedFlipBehaviorforSSO...............................................................12
CreatetheAWSDKDefaultSettings.plist.....................................................................................................13
TesttheSDK-BuiltApp.............................................................................................................................14
DeleteWorkspaceONESDKData.............................................................................................................15
SDKStoredCertificateInformation............................................................................................................16
APItoRetrieveIdentityCertificates...........................................................................................................18
SDKPayloadsReference,CodeandConsole.............................................................................................19
AuthenticationTypePayloadDescription..................................................................................................22
PrerequisitestoUseSSO.........................................................................................................................23
IntegratedAuthenticationandtheChallengeHandler................................................................................26
ChangestoActiveDirectoryPasswords....................................................................................................29
ConfigureVMwareTunnelforAppTunneling............................................................................................30
BehaviorofCopyandPasteforSDK-BuiltApplications..............................................................................32
SetUptheBundleandPLISTforCopyandPaste......................................................................................33
BehavioroftheThird-PartyKeyboardRestriction......................................................................................34
UseDLPtoControlLinkstoOpeninWorkspaceONEWebandWorkspaceONEBoxer.............................35
RestrictionofDocumentSharing...............................................................................................................37
SetUptheDataSamplerModuleforAnalytics...........................................................................................39
UsetheBrandingPayloadtoAddLogosandPrimaryHighlightColors........................................................41
DeveloperGuide
WorkspaceONEforiOS(Swift) Page2of64
BeaconDataSentUponApplicationUnlockorSentManually....................................................................43
ChecktheCompromisedStatusofDeviceswithCompromisedProtection..................................................44
QueryDevicesforMDMInformationwithDeviceInformationController.......................................................45
SDKLoggingAPIsforLevels....................................................................................................................46
OfflineAccess.........................................................................................................................................49
CustomSettingsfortheSDK....................................................................................................................50
EncryptDataonDevices...........................................................................................................................51
EnableandCodeAPNsintheApplication.................................................................................................53
APIstoUseCustomCertificatesforYourSDK-BuiltApps...........................................................................55
VMwareWorkspaceONESDKforiOS(Swift)andtheAppleAppReview....................................................57
MigratetheObjective-CVersiontotheSwiftVersion................................................................................60
Appendix:UIWindowSceneDelegateFeatureNotSupported.....................................................................62
DocumentInformation.............................................................................................................................64
DeveloperGuide
WorkspaceONEforiOS(Swift) Page3of64
SoftwareVersionandCompatibilityThisversionoftheWorkspaceONESoftwareDevelopmentKit(SDK)foriOS(Swift)iscompatiblewiththefollowingsoftware.
Software Version
WorkspaceONESDKforiOS(Swift) 20.10
WorkspaceONEUEMmanagementconsole 1904orlater
AppleiOS 12orlater
AppleXcode 11.7and12.0
Swiftlanguage AnysupportedbytheaboveXcodeversions
DeveloperResourcesResourcesforintegrationofthesoftwaredevelopmentkit(SDK)byapplicationdeveloperscanbefoundontheVMwarewebsite,here:https://code.vmware.com/web/sdk/Native/airwatch-ios
TheresourcesincludeearlierversionsoftheDeveloperGuidedocumentation,othertechnicaldocumentation,andtheSDKitself.YouwillrequireaMyWorkspaceOnelogininordertodownloadtheSDK.SpeakwithyourWorkspaceONEUEMrepresentativeforaccess.
CorrespondingObjective-CInterfacesTheexamplesinthisdocumentareinSwift.SeetheAWControllerInterfacefileforcorrespondingObjective-CInterfacesifyouimporttheWorkspaceONESDKforiOS(Swift)intoanObjective-Capplication.
Objective-CFeaturesNotSupportedintheSwiftVersionTheWorkspaceONESDKforiOS(Objective-C)supportsthedetectionofauserchangeonshareddevices.TheWorkspaceONESDKforiOS(Swift)doesnotsupportthisfeature.
TheWorkspaceONESDKforiOS(Swift)doesn’tsupporttheUIWindowSceneDelegateclassintroducedinXcodeversion11.Tomitigateorfixpossibleissues,makeafewupdatesinyourapplicationpropertylistfileandAppDelegatemethod.SeeUIWindowSceneDelegateFeatureNotSupportedfordetails.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page4of64
OperationalDataVMwarecollectsalimitedsetofinformationfromtheWorkspaceONESDKtooperateandsupporttheSDKwithinthird-partyapps,suchasnotifyingcustomersaboutfeatureremovalorplatformcompatibility.Thisdataisanonymizedandanalyzedinaggregate,andcannotbeusedtoidentifytheapplicationcontainingtheSDKorenduser.Thisdataissenttoscapi.vmware.com.PleaserefertoVMware’sPrivacyNoticesonlineformoreinformationaboutVMwaredatacollectionandprivacypolicies.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page5of64
SetUptheSDKwithYourAppSetupyourapplicationandtheSDKandtestthesetup.Performsetupstepsinordertoreduceissueswithintegration.
Procedure1. InitializebyaddingcodetoimporttheSDKandtorunthecorrectprotocol.2. Registeracallbackschemeandconfiguretheinfo.plist.3. SetAWControllerDelegatecallbackmethods.4. Setkeychainsharingtoallowapplicationstoshareasinglesignonsessionandtosharedata.
Usekeychainaccessgroupstosharedatabetweenapplicationsinthegroup.EnablekeychainsharingforSDK-builtapplicationsthatalreadysharethesameAppIdentifierPrefixandthesamekeychainaccessgroup.
5. ConfigureanAWSDKDefaultSettings.plisttocustomizetheapplicationwithWorkspaceONESDKforiOS(Swift)features.
6. TesttheintegrationofyourapplicationwiththeWorkspaceONESDKforiOS(Swift),includingthedeliveryofprofilesfromtheWorkspaceONEUEMconsoletoyourapplication.
--
DeveloperGuide
WorkspaceONEforiOS(Swift) Page6of64
InitializetheWorkspaceONESDKforiOS(Swift)ImporttheSDKanddefineinitialvaluessothattheSDK-builtappcanstart,connect,andcommunicatesuccessfulstartuporstartuperrors.
Procedure1. UnziptheWorkspaceONESDKDMGfile.
2. DraganddroptheDMGframeworkfileandtheattachedAWCMWrapperfileintoyourEmbeddedBinaries,whichisontheGeneraltabofyourprojectsettings.IfyouaddtheframeworkfilestoonlytheLinkBinarywithLibraries,theapplicationcrashes.WhenyouaddittotheEmbeddedBinaries,thisactionautomaticallyaddsthefiletotheLinkBinarywithLibraries,too.
3. Registeryourcallbackscheme.
4. ImporttheWorkspaceONESDKmodule.
5. MakeyourAppDelegateconformtotheAWControllerDelegateprotocol.
importAWSDKclassAppDelegate:UIResponder,UIApplicationDelegate,AWControllerDelegate{
6. IntheAppDelegate,addthefollowingcodetoinitializeandstarttheSDK.DonotcallthestartmethodinapplicationWillEnterForegroundorapplicationDidBecomeActive.ThesestartmethodsresultininconsistentUIbehavior.
funcapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplicationLaunchOptionsKey:Any]?)->Bool{letawcontroller=AWController.clientInstance()awcontroller.callbackScheme="myCallbackScheme"awcontroller.delegate=selfawcontroller.start()returntrue}
7. IntheAppDelegate,implementthelistedmethodandcodetoenabletheSDKtoreceiveandhandlecommunicationfromotherWorkspaceONEUEMapplications.
funcapplication(_application:UIApplication,openurl:URL,options:[UIApplicationOpenURLOptionsKey:Any]=[:])->Bool{//`AWController.handleOpenURL`methodwillreconnecttheSDKbacktoits//previousstatetocontinue.//IfyouarehandlingapplicationspecificURLschemes.Pleasemakesurethat//theURLisnotintendedforSDKController.//Anexamplewaytoperformthis.letsourceApplication:String?=options[UIApplicationOpenURLOptionsKey.sourceApplication]lethandedBySDKController=AWController.clientInstance().handleOpenURL(url,fromApplication:sourceApplication)ifhandedBySDKController{AWLogInfo("HandedoveropenURLtoAWController")//SDKControllerwillcontinuewiththeresultfromOpenURL.returntrue}//HandleifthisURLisfortheApplication.returnfalse}
DeveloperGuide
WorkspaceONEforiOS(Swift) Page7of64
8. ImplementtherequireddelegatemethodcontrollerDidFinishInitialCheck.
funccontrollerDidFinishInitialCheck(error:NSError?){iferror!=nil{AWLogError("InitialCheckDoneError:\(error)")return}AWLogInfo("SDKInitialCheckDone!")}
TroubleshootingIncaseoferrors,checkthefollowing.
airWatchApplicationSchemeNotInAllowedListserrorcode11.
ThiserrorwillbepassedtothecontrollerDidFinishInitialCheckdelegatemethodifthewsonesdkschemehasn’tbeenconfigured.Forconfigurationinstructions,seetheConfiguretheInfo.plistsection.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page8of64
ConfiguretheInfo.plistRegisteracallbackschemefortheWorkspaceONESDKforiOS(Swift)andconfiguretheinfo.plistfiletoreceiveacallbackfromtheWorkspaceONEIntelligentHubforiOSorWorkspaceONE.
IfyourapplicationusesQRscansandFaceID,addcorrespondingparameters(NSCameraUsageDescriptionandNSFaceIDUsageDescription)andpermissionstotheinfo.plistfile.
PrerequisitesInitializetheWorkspaceONESDKforiOS(Swift).
Procedure1. InXcode,navigatetoSupportingFiles.
2. SelectthefileYourAppName-Info.plist.
3. NavigatetotheURLTypessection.Ifitdoesnotexist,additattheInformationPropertyListrootnodeofthePLIST.
4. ExpandtheURLTypessectionandaddaURLSchemesentry.
5. EnterthedesiredcallbackschemeintheURLSchemestextbox.
6. AddallWorkspaceONEUEManchorapplicationschemestotheLSApplicationQueriesSchemesentry.
Itemnumber Type Value
Item0 String airwatch
Item1 String AWSSOBroker2
Item2 String awws1enroll
Item3 String wsonesdk
7. IfthisapplicationscansQRcodeswiththedevicecamera,addpermissionsforNSCameraUsageDescription.ProvideadescriptionfortheapplicationtopromptuserstoscanwithQRcodes.
8. IfthisapplicationusesFaceID,addpermissionsforNSFaceIDUsageDescription.ProvideadescriptionfortheapplicationtopromptuserstoturnonFaceID.Ifyoudonotincludeadescription,theiOSsystempromptsuserswithnativemessagesthatmightnotalignwiththecapabilitiesoftheapplication.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page9of64
RequiredandOptionalAWControllerDelegateCallbackMethodsEnsurethatyouaddedtherequiredinitial-checkmethodduringinitializationanduseoptionaldelegatecallbackmethodsthatarepartoftheAWController.
RequiredAWControllerDelegateMethodscontrollerDidFinishInitialCheck(error:NSError?)CalledoncetheSDKfinishesitssetup.
OptionalAWControllerDelegateMethodscontrollerDidReceive(profiles:[Profile])Calledwhentheconfigurationsprofilesarereceivedfromthemanagementconsole.TheAWControllerinstanceordelegatecannowaccesstheconfigurationprofiles.
controllerDidWipeCurrentUserData()CalledwhentheSDKhaswipedallofitsdata.Theapplicationwipesanyofitsapplicationspecificdata.
controllerDidLockDataAccess()CalledwhentheSDKhaslocked,userwillneedtounlockwithusername/password,passcode,touch-idinordertoaccessapplication.
controllerDidUnlockDataAccess()CalledwhentheSDKhasbeenunlockedbysomeformofacceptableauthentication(username/password,passcode,touch-id).
applicationShouldStopNetworkActivity(reason:AWSDK.NetworkActivityStatus)Calledtoalerttheapplicationtostopitsnetworkactivityduetosomerestrictionsetbytheadmin’spoliciessuchascellulardataconnectiondisabledwhileroaming,ifairplanemodeisswitchedon,SSIDdoesnotmatchwhatisonconsole,proxyfailed,etc.
applicationCanResumeNetworkActivity()Calledtoalerttheapplicationtoresumeitsnetworkactivitybecauseitisnowfinetodosobasedonthedevice’scurrentconnectivitystatusandpoliciessetbyadministrator.
controllerDidDetectUserChange()Calledwhenthecurrentlyloggedinuserhaschangedtoalerttheapplicationofthechange.
controllerDidReceive(enrollmentStatus:AWSDK.EnrollmentStatus)CalledwhentheSDKhasreceivedtheenrollmentstatusofthisdevicefromconsole.TheapplicationcannowquerytheSDKfortheenrollmentstatususingtheDeviceInformationControllerclassafterthispointorusetheenrollmentStatusparametergiveninthisdelegatecall.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page10of64
KeychainAccessGroupEntitlementsDecidewhethertoenableordisablekeychainsharingdependingonwhatbehavioryouwanttouseintheapp.Ifyouenablesharing,usethecorrectformatsothesystemsignstheappwiththeentitlementandsoappscansharedata.EnableorDisableKeychainSharing
EnableorDisableKeychainSharingEnablekeychainsharingentitlementstosignapplicationswithakeychainaccessgroup
Disablekeychainsharingtonotsharedataandtosigntheapplicationwithanotherstring.
FormatofEntitlementsTheformatforkeychainaccessgroupentitlementsis\accessGroupName.ThegroupnamesaredefinedinalistandmultipleapplicationshavethesameAppIdentifierPrefixtosharedata.
TheAppIdentifierPrefixstringassociatestothebundleIDoftheapplication.Forapplicationstosharedata,theapplicationsinthegroupmustsharethesamekeychainaccessgroup.YoucreatethebundleIDintheAppleDeveloperportalandyouassociatethebundleIDwithaprefixorgroup.
ForinformationonkeychainitemsandsharingontheAppleDevelopersitearticleSharingAccesstoKeychainItemsAmongaCollectionofAppsasofDecemberof2018.
Table1.KeychainSettingDecideswhatStringSignstheApp
Keychainsharingenabled Applicationsignedwiththelistedstring
Yes WithgroupnamesasAirWatchSDKTestAppAccessGroup1andAirWatchSDKTestAppAccessGroup2,thesystemsignstheapplicationwiththeprefixstring.FZJQX8D5U8.AirWatchSDKTestAppGroup1FZJQX8D5U8.AirWatchSDKTestAppGroup2
No ThesystemsignstheapplicationwiththebundleID.FZJQX8D5U8.com.MyCompany.AirWatchSDKTestApp
EnableKeychainSharingforSDK-BuiltApplicationsEnablekeychainsharingforSDK-builtapplicationsthatalreadysharethesame‘AppIdentifierPrefix’andthesamekeychainaccessgroupsotheseappscansharedata.
Procedure1. InXcode,selectyourapplication’stargetandgotoCapabilities.2. GotoKeychainSharingandturniton.3. Selecttheplusicon(+)andnamethegroupasawsdk.
4. DragthenewaccessgrouptothetopoftheKeychainGroupslist.
TipstoTroubleshootKeychainEnablementKeychainsharingdoesnotworkifitisnotenabled,iftheapplicationsinakeychainaccessgroupdonothavethesameAppIdentifierPrefix,oriftheapplicationsareindifferentgroups.
DisabledKeychainSharingProblem-TheSDKcannotinitializebecausethekeychain-savescannothappen.
Solution-Enablekeychainsharingbysigningtheapplicationwiththekeychainaccessgroup.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page11of64
DifferentAppIdentifierPrefixProblem-Applicationsinakeychainaccessgroupcannotsharepasscodesordataiftheyhavedifferentprefixes.Thesystemtreatsthedifferentprefixesasseparateclusters.
Solution-EdittheprefixesforapplicableapplicationsontheAppleDeveloperportal.However,beforeyouchangeprefixes,ensureyoudonotneedthedatastoredwiththeolderprefix.Thisolderdataislostwhentheprefixchanges.DifferentKeychainAccessGroups
Problem-Applicationswiththesameprefixcannotsharepasscodesordataiftheyareindifferentkeychainaccessgroups.Thesystemtreatsthedifferentgroupsasseparateclusters.
Solution-Ensurethattheapplicablekeychainaccessgroupshaveenabledkeychainsharing.Mergingapplicationsfromdifferentgroupsthatusethesameaccountandservicenamescanresultindatacollisions.Checkforthelistedsituationstopreventcollisions.
ThekSecAttrAccessGroupattributeisoneoftherequiredattributethatcanuniquelyidentifytheitemstoredorretrievedfromthekeychain.Allotherattributes,forexamplekSecAttrAccountandkSecAttrService,thatuniquelyidentifytheitemstoredandretrievedarethesame.ThekSecAttrAccessGroupattributeisnotspecifiedintheactualquerytostoreandretrievefromthekeychain.
MoreInformationSeeAppledocumentationformoreinformationonentitlementsandkeychainsatthelistedsites(asofMarch2018).
TechnicalNoteTN2415EntitlementsTroubleshootingKeychainServicesguide
DeveloperGuide
WorkspaceONEforiOS(Swift) Page12of64
ClusterSessionManagementandReducedFlipBehaviorforSSOAnapplicationbuiltwithSwiftthatusestheSDKdoesonlyflipstoretrieveaccountinformation.Itdoesnotfliptotheanchorapplicationtoretrievedata,likeenvironmentinformation,andtolockandunlockoperations.
IntheWorkspaceONESDKforiOS(Objective-C),applicationsneededtofliptotheanchorapplicationtoretrieveenvironmentinformation,accountdetails,andtoperformalllockandunlockoperations.
ClusterSessionManagementExplanationTheWorkspaceONESDKforiOS(Swift)includesamechanismthatusesthesharedkeychainforSDKappstocommunicatewithotherSDKappsonthedevice.Thisapproachprovidesbenefitsfrombothsecurityanduserexperienceperspectives.
SDKapplicationsbuiltbythesamedeveloperaccountandthatarealsointhesamekeychaingroupor“cluster”cannowshareanapppasscodeandanSSOsessionwithoutrequiringafliptotheWorkspaceONEIntelligentHub,Container,orWorkspaceONEeverytimeauthenticationisrequired.
However,applicationsonthesamedevicebuiltbydifferentkeychaingroupscannottakeadvantageofthispasscodesharingcapability.TherearesomescenariosthatstillrequireafliptotheWorkspaceONEIntelligentHuboranchorapptoobtaintheserverURLandothersetupinformation.Thisparticularflipshouldonlyoccuronceperclusterofapplications.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page13of64
CreatetheAWSDKDefaultSettings.plistCreateaPLISTentitledAWSDKDefaultSettingssoyoucanaddSDKfeaturestoyourapplication.YouusethisPLISTtoenableordisablemanyfeaturesthatpertaintoiOSortheWorkspaceONESDK.ToseewhatfeaturesaresetintheAWSDKDefaultSettings.plist,seeSDKPayloadsReference,CodeandConsole.
Procedure1. InyourXcodeproject,createabundlenamedAWSDKDefaults.IfiOSdoesnotofferanon-unittestingbundle,addamacOSbundleandmodifyitsbuildsettingasaniOScompatible.Todothis,modifytheBaseSDKtoiOS.
2. AddthebundletotheBundleResourcesofyourapplication.3. CreateaPLISTnamedAWSDKDefaultSettings.plistandputitintheAWSDKDefaultsbundle.
EntriestoSetintheAWSDKDefaultSettings.plistUseentriesintheAWSDKDefaultSettings.plisttocustomizetheapplicationwithWorkspaceONESDKforiOS(Swift)features.ManyoftheseentriesrequireyoutoconfiguretheircounterpartsintheSDKdefaultsettingsandpoliciessectionoftheWorkspaceONEUEMconsole.
Branding,AvailableEntriesUsetheavailableentries,withthefollowingstructure,toaddfunctionalitytotheapplication.
Root(Dictionary)Branding(Dictionary)Colors(Dictionary)EnableBranding(Boolean=YES)PrimaryHighlight(Dictionary)Red(Number=238)Green(Number=139)Blue(Number=48)Alpha(Number=255)
AppLogo_1x(String=logoFileName)AppLogo_2x(String=logoFileName)SplashLogo_1x(String=splashLogoFileName)SplashLogo_2x(String=splashLogoFileName)
-
DeveloperGuide
WorkspaceONEforiOS(Swift) Page14of64
TesttheSDK-BuiltAppTesttheintegrationofyourapplicationwiththeWorkspaceONESDKforiOS(Swift),includingthedeliveryofprofilesfromtheWorkspaceONEUEMconsoletoyourapplication.InitializetheSDKinyourapplicationtosetcommunicationwiththeWorkspaceONEUEMserverandtotesttheapplication.
Procedure1. EnrollyourtestdevicestotheWorkspaceONEUEMconsoletoenablecommunicationbetweenthem.TheSDKdoesnotcurrentlysupporttestinginasimulator.
2. UploadtheSDK-builtapporaplaceholderapplicationthathasthesamebundleIDasthetestingapplication.1. CreateanemptyapplicationwiththebundleIDofthetesting-applicationtoidentifytheapplication.2. UploadtheemptyapplicationtotheconsoleandassignadefaultorcustomSDKprofiletoit.
3. AssignanSDKprofiletotheapplication.Ifyoudonotassignaprofile,theSDKdoesnotinitializecorrectly.Thisstepenablestheconsoletosendcommandstotheapplicationwiththerecord.
4. Pushtheapplicationtotestdevices.Savetheapplicationandassignitusingtheflexibledeploymentfeature.UsedevicesfortestingthatareWorkspaceONEUEMmanageddevices.Youdonothavetorepushtheapplicationeverytimeyoumakeachange.Flexibledeploymentrulespushtheapplicationtotestdeviceswiththeappcatalog.
5. RunyourapplicationinXcode.
ResultsTheconsolepushestheinitializationdatatotheapplicationwhentheapplicationinstallsontestdevices.
WhattodonextAftertheapplicationinitializes,youcanruntheapplicationasmanytimesasyouwanttodebugit.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page15of64
DeleteWorkspaceONESDKDataUsethefuncdestroyContainerData()methodintheclassWS1SDKContainerCleanertodeleteWorkspaceONESDKdatafromyourWorkspaceONESDK-builtappandappsthatsharetheiOSkeychainwithit.
Important:Youcannotrecoverdatadeletedbythismethod.
Aftercallingthemethod,thereisanerrorinSDKinitialization,WorkspaceONESDKforiOS(Swift)mustgetrestarted.
UnsuccessfulinitializationresultsinthedelegatecallbackfunccontrollerDidFinishInitialCheck(error:NSError?)gettingcalledwithanon-nilerror.SuccessfulinitializationresultsinthedelegatecallbackfunccontrollerDidFinishInitialCheck(error:NSError?)gettingcalledwithnoerror.
QuitandrelaunchappsthatsharetheiOSkeychainwiththeSDK-builtapptoavoidundefinedbehavior.
MethodUsageletws1SDKDataCleaner=WS1SDKContainerCleaner()ws1SDKDataCleaner.destroyContainerData()
DeveloperGuide
WorkspaceONEforiOS(Swift) Page16of64
SDKStoredCertificateInformationTotroubleshootyourSDK-builtapplication,useanAWControllerAPItofindanddisplaytheWorkspaceONESDKstoredcertificateinformation.TheAPIsupportsnumerouscertificatetypesandcertificateattributestoquery.
APIExampleNote:CallingthisAPIwithoutwaitinguntiltheSDKcallsinitialcheckDone(_:)alwaysfailswiththeerrorInvalidOperation.ContainerLocked.
AWController.clientInstance().retrieveStoredCertificates{(certificateMap,error)inifletintegratedAuthCert=certificateMap[CertificateUsageKey.identity].first{letissuer:String?=integratedAuthCert.value(forCertificateAttribute:CertificateInfoKey.issuer)letcertOCSPRespondersList:[String]?=integratedAuthCert.value(forCertificateAttribute:CertificateInfoKey.ocspResponderList)//...}ifletmagCert=certificateMap[CertificateUsageKey.magSigning].first{letvalidFrom:Date?=magCert.value(forCertificateAttribute:CertificateInfoKey.startDate)letvalidUntil:Date?=magCert.value(forCertificateAttribute:CertificateInfoKey.endDate)//...}}
SupportedCertificateTypes@objc(AWCertificateUsageKey)publicclassCertificateUsageKey:NSObject{///CertificateofUsagekeytoreflectIntegratedAuthenticationpublicstaticletintegratedAuthIdentity:String///CertificateofUsagekeytoreflectIntegratedAuthenticationpublicstaticletuncategorizedIdentity:String///CertificateofthisusageareusedforsigningrequestsforMAGProxypublicstaticletmagSigning:String///CertificateofthisusageareusedforsigningrequestsforTunnelProxypublicstaticlettunnelSigning:String///CertificatesoftypeSSLpublicstaticletselfSignedSSLCerts:String///CertificatesoftypeCustomAnchorspublicstaticletcustomTrustedAnchorCerts:String///SDKdoesn'thavespecificusageforthistypeofcertificatespublicstaticletothers:String}
SupportedCertificateAttributestoQuery//////Usethesestringsaskeysforretrievingattributesandrawdataofcertificates///fromAWController.storedCertificates()API@objc(AWCertificateInfoKey)publicclassCertificateInfoKey:NSObject{///RawCertificatedatainDERformatpublicstaticletrawCertificate:String="exportCertificateData"///Returntypeofvalue-String?publicstaticletsubjectName:String="subjectName"///Returntypeofvalue-String?publicstaticletsubjectUserID:String="subjectUserID"///Returntypeofvalue-String?publicstaticletsubjectIdentifier:String="subjectIdentifier"///Returntypeofvalue-String?publicstaticletemailAddress:String="emailAddress"///Returntypeofvalue-Data?publicstaticletserialNumber:String="serialNumber"///Returntypeofvalue-String?publicstaticletcommonName:String="commonName"///Returntypeofvalue-String?publicstaticletissuer:String="issuer"
DeveloperGuide
WorkspaceONEforiOS(Swift) Page17of64
///Returntypeofvalue-String?publicstaticletalgorithm:String="algorithm"///Returntypeofvalue-Date?publicstaticletstartDate:String="startDate"///Returntypeofvalue-Date?publicstaticletendDate:String="endDate"///Returntypeofvalue-String?publicstaticletsubjectAlternativeName:String="subjectAlternativeName"///Returntypeofvalue-String?publicstaticletkeyUsage:String="keyUsage"///Returntypeofvalue-String?publicstaticletextendedKeyUsage:String="extendedKeyUsage"///Returntypeofvalue-String?publicstaticletuniversalPrincipalName:String="universalPrincipalName"///Returntypeofvalue-[String]?publicstaticletocspResponderList:String="ocspResponderList"}
DeveloperGuide
WorkspaceONEforiOS(Swift) Page18of64
APItoRetrieveIdentityCertificatesTheWorkspaceONESDKforiOS(Swift)providesanAPItoretrieveallstoredidentitiesfetchedfromtheWorkspaceONEUEMconsolesothatSDK-builtappscanaccessresourcessecuredwithcertificates.
TheadminconfigurestrustedcertificatesasCredentialsintheSDKprofile.WhentheSDKfetchestheSDKprofile,italsofetchesandstorestheCAcertificates.
APItoRetrieveIdentityCertificatesexportIdentityCertificates(completion:@escapingIdentityCertficatesCompletionHandler)
DiscussionUsethisAPItoretrieveallSDKstoredidentitycertificatesalongwithpasswords.CallthisAPIaftertheSDKinitialisestogetthelatestsetofstoredcertificates.AllvalidPKCS#12alongwiththeirpasswordsarereturned.ThisAPIensuresthereturnedcertificatesarevalidatthetimeofcall.
ThecompletionhandlerisnotcalledonMainThread.
ParameterExplanationsThecompletionhandlertakesthelistedparameters.
Theparametercompletionisablocktoexecuteaftercertificateretrievalcompletes.
((_pkcs12CertificateMap:[String:[PKCS12Certificate]]?,_error:NSError?)->Void)
Thepkcs12CertificateMapparameterisadictionarywithanarrayofPKCSstoredintheSDK.
ExpectthemapwithkeysfromCertificateUsageKey.integratedAuthIdentityandCertificateUsageKey.uncategorizedIdentity.ThemapisemptyincasethereisnostoredcertificateintheSDK.
Theparametererrorisanerrorobjectthatreturnsoneoftwovalues;whytheSDKfailedtoreturncertificatesorniliftherequestwassuccessful.
Forthelistedscenarios,thecompletionhandlerreturnsthelistedmapsanderrors.
Iftherearenocertificatesstored,thenthehandlerreturnsanemptymapandanilerror.Iftherearevalidandexpiredcertificatesinstorage,thenthehandlerreturnsamapthatcontainsvalidcertificatesandanilerror.Ifanerroroccurs,thenthemapisnilandtheerrorindicateswhytheSDKfailedtoreturncertificates.Ifstoredcertificatesarevalid,thenthemapisnotemptyandthehadlerreturnsanilerror.
ProtocolExampleforP12/PKCS#12CertificateDatapublicprotocolPKCS12Certificate{vardata:Data{get}varimportExportPassphrase:String{get}}
IssueswithP12PasswordsthatUseCipher98rc2–40-cbcTheAPIrotatestheP12passwordtoarandomstringsothattheSDKdoesnotgivetheactualpasswordtotheapp.IfanystoredP12passwordusethecipher98rc2–40-cbc(whichisnotFIPScompliant),theSDKexportsthatP12passwordtoaFIPScompliantcipherandreturnsitwithanupdatedpassword.However,iftheAPImustexportandupdatethepassword,itdoesnotreturntheapplicablecertificate.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page19of64
SDKPayloadsReference,CodeandConsoleSomefeatures,alsocalledpayloads,requireextracodeintheapplication,entriesinconfigfiles,andsettingsintheconsoletowork.Othersonlyrequire,extracode,configentries,oraconsolesetting.
SDKPayloadsTable1.WorkspaceONESDKforiOS(Swift)PayloadsandNeededConfigurations
SDKCapability
AddCodeorConfigEntries(BeyondAWController) SetintheConsole
ForceToken
ForApp
Authentication
No Yes
Enable
ThissettingcontrolshowthesystemallowsuserstoaccessSDK-built
applications,eitherinitiallyorthroughaforgot-passcodeprocedure.
Whenenabled,thesystemforcestheusertogenerateanapplication
tokenthroughtheSelf-ServicePortal(SSP)anddoesnotallowuser
nameandpassword.
Authentication Yes YesEnable
Setatype.
SSO Yes
Enablekeychainsharing.
Yes
Enable
Integrated
authentication
Yes
Usethechallengehandler.
YesEnable
Enterallowedsites.
Setanauthenticationoption.
Apptunnel
proxy
No YesEnable
Selectamode.
ConfiguretheproxycomponentsoftheVMwareTunnel.
IfnotusingVMwareTunnel,ensuretheintegrationoftheselectedproxywithyourWorkspaceONEUEMdeployment.
Dataloss
prevention
(DLP)
YesSettheAWSDKDefaultbundleandtheAWSDKDefaultSettings.plist.
Tousethethird-partykeyboardsfeature,implementtheshouldAllowExtensionPointIdentifierAPIintheUIApplicationDelegate.
YesEnable
Setthesupportedrestriction.
Analytics YesSettheAWDataSampler.
SettheAnalyticsHelper.
DecidetousetheSDKortheWorkspaceONEIntelligentHubfortelecomdata.
YesEnable
IfthesettingisDoNotDisturb,setprivacy.
Branding Yes
Addvaluestothe
AWSDKDefaultSettings.plist.
YesEnable
Setcolors.
Uploadimages.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page20of64
SDKCapability
AddCodeorConfigEntries(BeyondAWController) SetintheConsole
Sampledata
andMDM
information
YesUsethebeacon.TheSDKsendsthebeaconbutyoucanmanuallysendthebeaconwhendesired.
QuerytheDeviceInformationControllersingletonclass.
No
Compromised
protection
No
Usecodetocheckthestatusof
deviceswiththeapplication.
Yes
Enable
Dynamic
Compromise
Detection
No
Havetheappconsumethesupported
SDKversion.
No
EnsurethatdevicescanaccessspecifiedURLsforruleupdates.
Custom
settings
Yes
UsetheAWCustomPayloadobject.
YesEnable
Entercode.
Geofencing Yes
Implementregionmonitoring.Seethe
Appledeveloperwebsitefordetails,
forexample:MonitoringtheUser's
ProximitytoGeographicRegions.
YesEnable
Setthearea.
Logging Yes
AddAPIsforlogging.Seethesample
applicationsforexamples.
YesEnable
Setthelevel.
Setwi-fi.
Offlineaccess No YesEnable
Settimeallowedtobeoffline.
Encryption Yes
UsemethodsintheAWControllerto
encryptanddecryptdata.
No
However,thestrengthoftheencryptiondependsonthe
authenticationmethodsetintheWorkspaceONEUEMconsole.
SDKApp
Compliance>
Application
Version
No
UsethelatestSDKframeworks.
YesEnable
Addtheapplicationidentifier.
Selectanoperator.
Entertheapplicableapplicationversion.
Theconsoleblocksnon-compliantdevices.
SDKApp
Compliance
>OSVersion
No
UsethelatestSDKframeworks.
YesEnable
Selectanoperator.
SelecttheOSversion.
Selectanaction.Theconsolesupportstheblockandwipeactions.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page21of64
SDKCapability
AddCodeorConfigEntries(BeyondAWController) SetintheConsole
ApplePush
Notifications
Yes
AddmethodstoAppDelegate.swift.
YesEnableAPNsintheapp.
UploadtheproductionAPNscertificates.
Certificates
and
Credentials
Payloads
Yes
UseAPIstofetchcertificates,
authenticate,andvalidatetheserver
trust.
Yes
AdminconfiguresandaddscertificatestotheconsolewithanSDK
profile.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page22of64
AuthenticationTypePayloadDescriptionSetaccesstoyourapplicationwiththeauthenticationtypepaload.Usealocalpasscode,WorkspaceONEUEMcredentials,orrequirenoauthentication.
SelectanauthenticationtypeintheWorkspaceONEUEMconsoleandusetheprovidedSDKhelperclassesinyourapplication.
Setting Description
Passcode Designatesalocalpasscoderequirementfortheapplication.Deviceuserssettheirpasscodeondevicesattheapplicationlevelwhentheyfirstaccesstheapplication.
UsernameandPassword
RequiresuserstoauthenticatetotheapplicationwiththeirWorkspaceONEUEMcredentials.
Disabled Requiresnoauthenticationtoaccesstheapplication.
AuthenticationTypeandSSOSettingBehaviorsYoucanusekeychainsharing,theauthenticationtype,andthesinglesign-on(SSO)optiontomakeaccesstoyourapplicationpersistent.
KeychainAccessGroupRequiredYoumusthaveasharedspace,akeychainaccessgroup,sothatapplicationssignedinthecorrectformatcansharekeychainentries.SeeKeychainAccessGroupEntitlementsforinformationonthesigningformat.SeeTipstoTroubleshootKeychainEnablementforcommonissueswithkeychainsharing.
EnableAuthenticationTypeandSSOIfyouenablebothauthenticationtypeandSSO,thenusersentereithertheirpasscodeorcredentialsonce.TheydonothavetoreenterthemuntiltheSSOsessionends.
EnableAuthenticationTypeWithoutSSOIfyouenableanauthenticationtypewithoutSSO,thenusersmustenteraseparatepasscodeorcredentialsforeachindividualapplication.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page23of64
PrerequisitestoUseSSOWorkspaceONEUEMallowsaccesstoiOSapplicationswithsinglesignon,however.TouseSSO,setconsole,application,andanchorapplicationcomponentsandquerytheSSOstatus.
SSOComponentsEnabletheSSOsettingintheSDKdefaultsettingsandpoliciesintheWorkspaceONEUEMconsole.InitializetheSDKintheAppDelegate.EnsureananchorapplicationisondevicesliketheWorkspaceONEIntelligentHuborWorkspaceONE.TheanchorapplicationdeploymentispartoftheWorkspaceONEUEMmobiledevicemanagementsystem.
QuerytheCurrentSSOStatusToquerytheSSOstatusoftheiOSapplication,waitforthecontrollerDidFinishInitialCheckmethodtofinish.LookintheDeviceInformationControllerclassforthessoStatusproperty.IfthecontrollerDidFinishInitialCheckmethodisnotfinished,theSSOstatusreturnsasSSOdisabled.
SSOConfigurationsandSystemLoginBehaviorforiOSApplicationsWorkspaceONEUEMallowsaccesstoiOSapplicationswithsinglesignonenabledintwophases.WorkspaceONEUEMcheckstheidentityoftheapplicationuserandthenitsecuresaccesstotheapplication.
ApplicationAccessWithSSOEnabledTheauthenticationprocesstoanapplicationwithWorkspaceONEUEMSSOenabledincludestwophases:accessingtheappandsecuringpersistentaccess.
1. Identifyuserforappaccess-Thefirstphaseensuresthattheuser’scredentialsarevalid.Thesystemidentifiestheuserfirstbysilentlogin.Ifthesilentloginprocessfails,thenthesystemusesaconfigured,authenticationsystem.WorkspaceONEUEMsupportsusernameandpassword,token,andSAML.
2. Securepersistentappaccess-Thesecondphasegrantstheuseraccesstotheapplicationandkeepsthesessionlivewitharecurringauthenticationprocess.WorkspaceONEUEMsupportspasscode,usernameandpassword,andnoauthentication(disabled).
AuthenticationBehaviorBySSOConfigurationTheSSOconfigurationcontrolstheloginbehaviorusersexperiencewhentheyaccessapplications.TheauthenticationsettingandtheSSOsettingaffecttheexperienceofaccessingtheapplication.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page24of64
Table1.LoginBehaviorforUserswhenPasscodeisSetforSSO
AuthenticationPhase SSOEnabled SSODisabled
Identify Silentlogin:ThesystemregisterscredentialswiththemanagedtokenforMDM.Ifsilentloginfails,thesystemmovestothenextidentificationprocess.
Authenticate:Thesystemidentifiescredentialsagainstacommonauthenticationsystem(usernameandpassword,token,andSAML).
Silentlogin:ThesystemregisterscredentialswiththemanagedtokenforMDM.Ifsilentloginfails,thesystemmovestothenextidentificationprocess.
Authenticate:Thesystemidentifiescredentialsagainstacommonauthenticationsystem(usernameandpassword,token,andSAML).
Secure Promptifpasscodeexists:Thesystemdoesnotpromptforthepasscodeifthesessioninstanceislive.Promptifpasscodedoesnotexist:Thesystempromptsuserstocreateapasscode.Sessionshared:ThesystemsharesthesessioninstanceacrossapplicationsconfiguredwithWorkspaceONEUEMSSOenabled.
Promptifpasscodeexists:Thesystempromptsuserstheapplicationpasscodes.Promptifpasscodedoesnotexist:Thesystempromptsuserstocreateapasscode.Sessionnotshared:Thesystemdoesnotsharethesessionorthepasscodewithotherapplications.
Table2.LoginBehaviorforUserswhenUsernameandPasswordisSetforSSO
AuthenticationPhase SSOEnabled SSODisabled
Identify Silentlogin:ThesystemregisterscredentialswiththemanagedtokenforMDM.Ifsilentloginfails,thesystemmovestothenextidentificationprocess.
Authenticate:Thesystemidentifiescredentialsagainstacommonauthenticationsystem(usernameandpassword,token,andSAML).
Silentlogin:ThesystemregisterscredentialswiththemanagedtokenforMDM.Ifsilentloginfails,thesystemmovestothenextidentificationprocess.
Authenticate:Thesystempromptsforapplicationlogincredentials.
Secure Prompt:Thesystemdoesnotpromptforthelogincredentialsifthesessioninstanceislive.Sessionshared:ThesystemsharesthesessioninstanceacrossapplicationsconfiguredwithWorkspaceONEUEMSSOenabled.
Prompt:Thesystempromptsforthelogincredentialsfortheapplicationoneveryaccessattempt.Sessionnotshared:Thesystemdoesnotsharethesessionwithotherapplications.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page25of64
Table3.LoginBehaviorforUserswhenDisabledisSetforSSO
Authenticationphase SSOenabled SSOdisabled
Identify Silentlogin:ThesystemregisterscredentialswiththemanagedtokenforMDM.Ifsilentloginfails,thesystemmovestothenextidentificationprocess.
Authenticate:Thesystemidentifiescredentialsagainstacommonauthenticationsystem(usernameandpassword,token,andSAML).
Silentlogin:ThesystemregisterscredentialswiththemanagedtokenforMDM.Ifsilentloginfails,thesystemmovestothenextidentificationprocess.
Authenticate:Thesystempromptsforapplicationlogincredentials.
Secure Prompt:Thesystemdoesnotpromptusersforauthentication.
Prompt:Thesystemdoesnotpromptusersforauthentication.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page26of64
IntegratedAuthenticationandtheChallengeHandlerUseintegratedauthenticationtopasssinglesignon(SSO)credentialsorcertificatestoauthenticatetowebsiteslikecontentrepositoriesandwikis.SetthepayloadintheWorkspaceONEUEMconsoleandaddalistofallowedsites.Thenusethechallengehandlerinyourapplicationtohandleincomingauthenticationchallenges.
ChallengeHandlerMethodsforChallengesFindthechallengehandlerintheAWControllerclassoftheSDK.InsidetheAWController,usethelistedmethodstohandleanincomingauthenticationchallengeforconnectionsmadewithNSURLConnectionandNSURLSession.
Table1.DescriptionsofChallengeMethods
Method DescriptionfunccanHandle(_protectionSpace:URLProtectionSpace,withErrorerror:Error?)->Bool
ChecksthattheWorkspaceONESDKcanhandlethistypeofauthenticationchallenge.TheSDKmakesseveralcheckstodeterminethatitcanhandlechallenges.1. IstheWebsitechallengingforauthenticationonthelistofallowedsitesintheSDKprofile?
2. Isthechallengeoneofthesupportedtypes?BasicNTLMClientcertificate
3. DoestheSDKhaveasetofcredentialstorespond?CertificateUsernameandpassword
Ifallthreeofthecriteriaaremet,thenthismethodreturnsYES.
TheSDKdoesnothandleservertrust,soyourapplicationmusthandleNSURLAuthenticationMethodServerTrust.
funchandleChallenge(forURLSessionChallengechallenge:URLAuthenticationChallenge,completionHandler:@escaping(_disposition:URLSession.AuthChallengeDisposition,_credential:URLCredential)->Void)->Bool
RespondstotheactualauthenticationchallengefromanetworkcallmadeusingNSURLSession.ThismethodisthesameasthehandleChallengemethod,exceptthesystemusesthismethodwithcallsmadewithNSURLSession.Thiscallinvolvesusingacompletionblocktohandleauthenticationchallenges.
RequirementsforIntegratedAuthenticationForintegratedauthenticationtowork,communicationbetweentheallowedsitesandthechallengehandlermustusea401statuscode,specificauthenticationmethods,andthecorrectcredentials.
TheURLoftherequestedwebsitemustmatchanentryinyourlistofAllowedSites.
ThesystemmustmakethenetworkcallsothattheprocessprovidesanNSURLAuthenticationChallengeobject.
Thewebsitemustreturna401statuscodethatrequestsauthenticationwithoneofthelistedauthenticationmethods.
NSURLAuthenticationMethodBasicNSURLAuthenticationMethodNTLMNSURLAuthenticationMethodClientCertificate
---
DeveloperGuide
WorkspaceONEforiOS(Swift) Page27of64
Thechallengehandlercanonlyusetheenrollmentcredentialsoftheuserwhenattemptingtoauthenticatewithawebsite.Ifawebsiterequiresadomaintologin,forexampleACME\jdoe,andusersenrolledwithabasicusername,likejdoe,thentheauthenticationfails.
Ifyourapplicationusesanembeddedwebview,youcanusetheSDKhandleChallengemethodeitherinaURLSessionchallengehandler,orinaWKWebViewchallengehandler.IfyouusehandleChallengeinaURLSessionchallengehandler,displaytheresponseinaUIWebVieworWKWebViewinstance.
SCEPSupporttoRetrieveCertificatesforIntegratedAuthenticationTheWorkspaceONESDKsupportstheSCEPprotocol,withlimitations,toretrievecertificatesforintegratedauthentication.TouseSCEPcertificatesforyourSDK-builtapplication,ensureintegratedauthenticationisenabledandthatSCEPisconfiguredintheconsoleasacertificateauthority.
SupportedSANInformationTypesTheSDKfullysupportsthelistedSubjectAlternativeNames(SAN)informationtypesincertificateattributes.
dNSNamentPrincipalNameNote:Whenyouconfigurethisinformationtype,itdisplaysasanentrynestedundertheotherNameattribute.AlthoughotherNameisnotsupported,ntPrincipalNameissupportedevenasanestedentryofotherName.rfc822NameuniformResourceIdentifier
SupportedwithCorrectFormatTheWorkspaceONESDKsupportsthelistedSANinformationtypesbutyoumustusethecorrectformatortheSDKignoresthem.
iPAddressregisteredID
NotSupportedTheWorkspaceONESDKdoesnotsupportthelistedSANinformationtypes.Ifyouconfigurethem,theSCEPprocessfails.
CustomdirectoryNameediPartyNameotherNamex400Address
MethodsforaPendingStatusfromtheSCEPCertificateAuthorityUsetheAWControllermethodtomodifySCEPcertificatefetchestoaccountforwhentheSCEPcertificateauthorityreturnsapendingstatusforthefetch.
PendingStatusofCertificateFetchesSomeconfigurationssettheSCEPcertificateauthoritytonotissuethecertificateuntilarequestisapproved.Inthisscenario,theauthorityreturnsapendingstatustotheSDK.YoucanusethemethodsinAWControllertoconfiguretheretrylogicandmonitortheretryprogress.
EnsuretheCertificateAuthorityServerHandlesRetryRequestsTheWorkspaceONESDKretriesthefetchrequestbasedontheparametersinthemodifiedcodeorusingthedefaultbehavior(retriesevery5millisecondsfor10tries).Ifacertificateauthorityserverisnotconfiguredtohandleretryrequestscausedbythependingstatus,thefetchnevercompletes.
MethodsforPendingStatus
DeveloperGuide
WorkspaceONEforiOS(Swift) Page28of64
UsetheAWControllertomodifytheretrytimeoutandmaximumnumberofretryattemptswhenfetchingSCEPcertificates.Also,usetheSDKdelegatemethodtonotifytheSDK-builtapplicationontheprogressofthependingSCEPcertificatefetch.
Table1.PendingStatusMethods
Configuration CodeExamples
Modifytheretrytimeoutandmaximumnumberofretryattempts.
ModifytheAWController.
publicfuncsetPendingCertificateRetry(timeout:Double,maxAttempts:Int)->Bool
Hereisanexampleofcodemodificationsthatsetthetimeoutvalueto10secondsandthemaximumnumberofretryattemptsto8.
letsuccess=AWController.clientInstance.setPendingCertificateRetry(timeout:10.0,maxAttempts:8)
Note:Ifyoudonotconfigurethetimeoutandretryattempts,thenthetimeoutvaluedefaultsto5millisecondsandthemaximumnumberofretryattemptsdefaultsto10.
Usethedelegatemethodforpendingstatusnotifications.
Useadelegatemethodtonotifyaboutthependingstatusofthefetch.
@objc(didFinishPollingForPendingCertificateIssued:error:)optionalpublicfunccontrollerDidFinishPollingForPendingCertificate(certificateIssued:Bool,error:NSError?)
Hereisanexampleofthedelegatemethodfornotification.
funccontrollerDidFinishPollingForPendingCertificate(certificateIssued:Bool,error:NSError?){//Applicationlogicgoeshere}
Table2.ErrorCodesforPendingStatus
ErrorCode Description
certificateIssuancePending Thecertificateispending.
retryIntervalNotReached Thetimeoutisnotreachedforretry.YoucansetinsetPendingCertificateRetry.
maximumAllowedAttemptsEllapsed Themaximumattemptshavebeenreachedforpolling.YoucansetitinsetPendingCertificateRetry.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page29of64
ChangestoActiveDirectoryPasswordsUseanAPItoupdatetheWorkspaceONESDKforiOS(Swift)credentialswhenthereareActiveDirectorypasswordchanges..
IfanActiveDirectory(AD)passwordchangesandbecomesoutofsyncwiththeobjectaccountoftheSDK,useanAPItoupdatetheSDKcredentials.AnexampleforusingthisAPIisforsituationswherethepasswordchangedforaccesstositescontrolledbyintegratedauthenticationconfigurations.
AWController.clientInstance().updateUserCredentials(with:{(success,error)in///insertcompletionhandlercodehere})
FindthenewcredentialsintheSDKaccountobjectafterthecallbacksuccessfullyreturns.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page30of64
ConfigureVMwareTunnelforAppTunnelingTheVMwareWorkspaceONETunnelprovidesseveralsecuremethodsforindividualapplicationsthatusetheVMwareWorkspaceONESDKtoaccesscorporateresources.Selectfromtwooptions,VMwareTunnelandVMwareTunnel-Proxy.
VMwareTunnel:TheWorkspaceONESDKforiOS(Swift)providesapptunnelingwithoutaddingcodetotheapplication.However,youneedtoconfigureapptunnelingintheWorkspaceONEUEMconsole.ThisoptionisthepreferredTunnel.VMwareTunnel-Proxy:TheTunnel-ProxycomponentusesHTTPStunnelingtouseasingleporttofiltertrafficthroughanencryptedHTTPStunnelforconnectingtointernalsitessuchasSharePointorawiki.TheWorkspaceONESDKforiOS(Swift)providesapptunnelingwithoutaddingcodetotheapplication.However,youneedtoconfigureapptunnelingintheWorkspaceONEUEMconsole.
Note:Ifusersaccessaninternalresourcethroughanon-standardport(aportthatisnotport80or443),youmustexplicitlylisttheportnumberintheURLyouenterinAppTunnelURLs.Forexample,iftheresourceURLisdata.company.comanditisaccessedthroughport7777,youmustadddata.company.com:7777intheAppTunnelURLsfield.
PrerequisitesYoumusthaveavalidTunneldeployment.AccessVMwareTunnelonWindowsorVMwareTunnelonLinuxfordetails.
Procedure1. NavigatetoGroups&Settings>AllSettings>Settings&Policies>SecurityPolicies>AirWatchAppTunnel.
2. Enablethesetting.3. Selectanapptunnelmode,eitherVMwareTunnel-ProxyorVMwareTunnel.4. IntheAppTunnelURLsfield,entertheURLsthatyoudonotwanttotunnel.
EnternoURLsandeveryURLgoesthroughtheVMwareTunnel.EnteroneormoreURLsandthesystemsplitsthetraffic.Thisconfiguressplittunneling.ThesystemdoesnotsendtheURLsenteredinthisfieldthroughtheVMwareTunnel.ThesystemdoessendallotherURLsthroughtheVMwareTunnel.
AppTunnelingKnownLimitationsandOtherConsiderationsDuetoplatformandothertechnicallimitations,onlynetworktrafficmadefromcertainnetworkclassescantunnel.
Table1.SupportedNetworkClasses
NetworkClass Supported
NSURLConnection CallsmadewithNSURLConnectiontunnel.Thereisoneexceptiontothisbehavior.Ifcallsaremadesynchronouslyonthemainthread,theydonottunnel.
NSURLSession CallsmadeusingNSURLSessiontunnelonlyoniOS8+devicesanddependingontheconfigurationused.Defaultandephemeralconfigurationtypestunnel.However,backgroundconfigurationtypesdonottunnel.
CFNetwork MostcallsmadeusingCFNetworktunnelexceptforCFSocketStream,whichdoesnottunnel.
--
DeveloperGuide
WorkspaceONEforiOS(Swift) Page31of64
Table2.NetworkClassesNotSupported
NetworkClass NotSupported
URLsthatcontain.local
RequestswithURLscontaining.localdonottunnel.VariousAppleservicesonthedeviceusethis.localstringpattern.TheSDKdoesnottunneltheserequeststhroughtheVMwareTunneltoavoidinterferingwiththeseservices.
WKWebView RequestsmadewithWKWebViewdonottunnelsouseUIWebView.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page32of64
BehaviorofCopyandPasteforSDK-BuiltApplicationsThecopyandpastepayloads,EnableCopyandPasteOutandEnableCopyandPasteInto,restrictactionswhensettoNo.TheyallowactionswhensettoYes.
EnableCopyandPasteOut-WhenyousetEnableCopyandPasteOuttoNo,youcanonlypastecopieddatafromyourSDK-builtapplicationouttootherSDK-builtapplications.EnableCopyandPasteInto-WhenyousetEnableCopyandPasteIntotoNo,youcanonlypastecopieddatafromotherSDK-builtapplicationsintoyourSDK-builtapplication.
LimitsofDLPCopyandPaste
ThecopyandpastepayloadsfortheWorkspaceONESDKforiOS(Swift)arelimitedbyparameters,outofprocessclasses,SSOandDLPconfigurations,andkeychaingroups.TherearespecificlimitationswithcertainUIclasses.
UIWebViewandWKWebView-YoucannotcopyimagesinDOCandPDFfilesloadedinUIWebVieworWKWebViewduetoatechnicallimitation.OutofProcessClasses-TheWorkspaceONESDKdoesnotsupportcopy-outandcopy-inrestrictionsinviewsthatareoutofprocess.Forexample,thefeaturedoesnotworkinthelistedviews,andthislistisnotexhaustive.SFSafariViewControllerUIDocumentInteractionViewControllerQLPreviewController
OtherLimitationsTwosetsofSDK-builtapplicationsthathavedifferentSSOsettings(forexample,oneissetwithSSOonandanotherwithSSOoff)cannotsharethepasteboard.Youcannotcopyfromanapplicationwhichhasnorestriction(EnableCopyandPasteOutsettoYes)andpastethatcontentintoarestrictedapplication(EnableCopyandPasteIntosettoNo).Youcannotshareapasteboardbetweentwoormoresetsofapplicationsthatareindifferentkeychaingroups.Forexample,VMwareWorkspaceONEproductivityapplicationsandcustomSDK-builtapplicationscannotsharetheclipboard.However,multiplecustomSDK-builtapplicationsfromthesamedeveloperthatareinthesamekeychaingroupcansharetheclipboard.
---
-
-
-
DeveloperGuide
WorkspaceONEforiOS(Swift) Page33of64
SetUptheBundleandPLISTforCopyandPasteTocontrolthecopyandpasteinteractionbetweenyourSDK-builtapplicationsandnon-SDK-builtapplications,createabundleandPLISTfile,locally,andsetthekeysandvalues.
FordetailsoncreatingthebundleandPLISTduringinitialsetup,seeCreatetheAWSDKDefaultSettings.plist.
Procedure1. CreateabundlenamedAWSDKDefaultsifyoudidnotcreateitduringinitialsetup.2. CreateaPLISTnamedAWSDKDefaultSettings.plistandputitintheAWSDKDefaultsbundleifyoudidnot
dothisduringinitialsetup.3. InthePLIST,createaBooleannamedAWClipboardEnabledandsetittoYES.
ResultsAfteryouaddthelocalflag,andyouradminsetsthedefaultorcustomSDKpoliciesforthesefeaturesintheconsole,theSDKenforcestherestriction.Itenforcesitacrossyourapplication’suserinterfacesthatusecut,copy,andpasteinthelistedclassesandsubclasses.
UITextFieldUITextViewUIWebViewWKWebView
Notethattherestrictionisn’tenforcedinthefollowingclasses.
UISearchTextFieldinteractionswon’tberestricted.UISearchBarinteractionswon’tberestricted.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page34of64
BehavioroftheThird-PartyKeyboardRestrictionRunthethird-partykeyboardrestrictionbystartingtheAWControllerandconfiguringthedatalosspreventionsettingintheWorkspaceONEUEMconsole.Thispayloadbehavesdependingonthemostrestrictivesetting.
RequestyourWorkspaceONEUEMadmintoconfigurethedatalossprevention(DLP)menuitem.FindtheconsolesettingsinGroups&Settings>AllSettings>Apps>SettingsandPolicies>SecurityPolicies>DataLossPrevention>EnableThirdPartyKeyboards.
WhenthisfeatureissettoNo,anythirdpartykeyboardsusedintheapplicationareautomaticallyreplacedwiththenativesystemkeyboard.
SDKBehavesAccordingtotheMostRestrictiveImplementationIfyourapplication’scodeoverridestheshouldAllowExtensionPointIdentifierdelegatemethod,theWorkspaceONESDKforiOS(Swift)honorsthemorerestrictiveimplementation.
Forexample,iftheSDKsettingallowsthirdpartykeyboardsbutyourapplicationforciblyreturnsnotodisallowcustomkeyboards,thencustomkeyboardsaredisallowedintheapplication.IftheSDKsettingdoesnotallowthirdpartykeyboardsthenthethirdpartykeyboardisnotallowedregardlessofyourapplicationsimplementationofthemethod.
Table1.ThirdPartyKeyboardRestrictionBehaviorDependsonConsoleSettingsandCode
DataLossPreventionSetting
EnableThirdPartyKeyboardSetting
IsshouldAllowExtensionPointIdentifierImplementedintheApplication KeyboardBehavior
Disabled NA Implemented Thirdpartykeyboardsbehavedependingontheimplementationofthedelegatemethod.
Enabled SettoNo. Implementationdoesnotmatter. Thirdpartykeyboardsarenotavailable.
Enabled SettoYes. Implemented Thirdpartykeyboardsareavailable.
Enabled SettoYes. Implementedandreturnsyes. Thirdpartykeyboardsareavailable.
Enabled SettoYes. Implementedandreturnsno. Thirdpartykeyboardsarenotavailable.
RuntheApplicationtoSeeExpectedBehaviorsWhentheEnableThirdPartyKeyboardsettingisconfiguredintheconsole,theSDKdoesnotenforcetherestrictionuntilthenexttimetheuserrunstheapplicationaftertheapplicationretrievesthenewSDKprofile.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page35of64
UseDLPtoControlLinkstoOpeninWorkspaceONEWebandWorkspaceONEBoxerConfigureapplicationsbuiltwiththeWorkspaceONESDKtoopenintheWorkspaceONEWebandtocomposeemailsinWorkspaceONEBoxer.ThisfeatureenablesenduserstousealternativesystemsotherthanSafariandtheMailapp.Todevelopthisfeature,createabundleinyouriOSapplicationandconfigureWorkspaceONEUEMtoenforcethebehaviorsinthebundle.
Configurebothsystems,thebrowserandemailsystems,forthisfeaturetowork.Performtheproceduresinthelistedorder.
Procedure1. InitialSetUpoftheBundleandPLISTPerformthesestepsbeforeyouenableanylinks.UsethisbundleandPLISTforbothHTTP/HTTPSlinksandMAILTOlinks.1. CreateabundlenamedAWSDKDefaults.
2. CreateaPLISTnamedAWSDKDefaultSettings.plistandputitintheAWSDKDefaultsbundle.
2. EnableLinksforWorkspaceONEBoxerToenabletheapplicationtoopenMAILTOlinksinWorkspaceONEBoxer,enableafewdictionaryandPLISTflags.1. WorkintheAWSDKDefaultsbundle.2. CreateadictionarynamedAWMailtoSchemeConfigurationandputitinthe
AWSDKDefaultSettings.plist.3. ConfiguretheAWMailtoSchemeConfigurationdictionary,createanewBooleanentrywiththekey
nameasenabledandsettheBooleanvaluetoYes.IfyousettheBooleanvalueasNo,thenMAILTOlinksopeninthenativemail.IfsettoYes,thenyourSDKapplookstoseeifyouenableddatalosspreventionintheSDKprofile.DLPEnabled–TheappopensinWorkspaceONEBoxer.DLPDisabled–TheappopensintheiOSMailapp.
3. EnableLinksforWorkspaceONEWeb.ToenabletheapplicationtoopenHTTP/HTTPSlinksintheWorkspaceONEWeb,enableafewdictionaryandPLISTflags.1. WorkintheAWSDKDefaultsbundle.2. CreateadictionarynamedAWURLSchemeConfigurationandputitintheAWSDKDefaultSettings.plist.3. InsidetheAWURLSchemeConfigurationdictionary,createanewBooleanentrywiththekeyname
enabledandsettheBooleanvaluetoYes.IfyousettheBooleanvaluetoNo,thentheHTTPandHTTPSlinksopeninSafari.IfsettoYes,thenyourSDKappopensinWorkspaceONEWeb.
4. ContainDatatoWorkspaceONEWebUsethedatalossprevention,DLP,settingsintheWorkspaceONEUEMdefaultSDKprofiletoenforcetheapplicationtouseWorkspaceONEWebandWorkspaceONEBoxer.IfyoudonotenabledatalosspreventionintheSDKpolicy,theapplicationopenslinksinSafariandcomposesemailintheiOSMailapp.1. NavigatetoGroups&Settings>AllSettings>Apps>SettingsandPolicies>SecurityPolicies.2. SelectEnabledforDataLossPrevention.3. DisabletheEnableComposingEmailcheckboxfortheMAILTOlinks.Ifyoudonotdisablethisoption,
theapplicationopensfromtheMailappandnotfromInbox.
LimitationWithMFMailComposeViewControllerIfyouusetheMFMailComposeViewControllerschemeinyourMessageUIframework,thisfunctionalityisnotsupported.Thesystemcannotspecifyhowendusersaccessyourapplicationwhenitisanattachmentinanemail.End-usersaccesstheapplicationwiththeMailappandnotInbox.
SupportInformationControllerTheSupportInformationControllerclassallowsyoutoqueryfortheemailaddressandtelephonenumbersforcontactingenrollmentsupportwhichyoucandisplayontheapplicationUI.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page36of64
DisabletheDefaultBlockerScreenTheWorkspaceONESDKdisplaysablockerscreentocovertheapplication’scontentwhentheapplicationisnotactive.Whentheappisintheforeground,theWorkspaceONESDKclosestheblockerscreen.YoucandisablethisscreenanduseyourowncustombackgroundblockerscreenorusetheWorkspaceONESDKscreen.
Procedure1. WorkintheAWSDKDefaultsbundle.2. CreateadictionarynamedAWBlockerViewEnableKeyandputitintheAWSDKDefaultSettings.plist.3. ConfiguretheAWBlockerViewEnableKeydictionary,createanewBooleanentrywiththekeynameas
enabledandsettheBooleanvaluetoNo.IfyousetAWBlockerViewEnableKeytoNo,thentheWorkspaceONESDKdisablestheblockerscreensothatyoucanuseyourownblockerscreen.IfyousetAWBlockerViewEnableKeytoYesthentheWorkspaceONESDKusesitsblockerscreen.IfAWBlockerViewEnableKeyisempty,theWorkspaceONESDKdisplaysitsblockerscreen.
-
-
DeveloperGuide
WorkspaceONEforiOS(Swift) Page37of64
RestrictionofDocumentSharingWorkspaceONEdatalosspreventionsupportstherestrictionofdocumentsharingbetweenmobileapplications.Restrictingdocumentsharingisoptional.Ifitisinuse,adocumentfilethatisinoneappcanonlybeopenedinanotherappiftheotherappisonalistofapprovedapplications.
ThelistofapprovedapplicationsisconfiguredintheWorkspaceONEUnifiedEndpointManager(UEM)console.RestrictionofdocumentsharingisimposedatruntimebytheWorkspaceONEmobileSoftwareDevelopmentKit(SDK),ifconfiguredinthemobileapplication.
ConsoleConfigurationThelistofapprovedapplicationsisconfiguredinthemanagementconsole.TheconfigurationcanbeinanSDKprofile,forexample,andtheprofilecanbeassignedtoyourapp.AdministratorprivilegesintheenterpriseWorkspaceONEUEMconsolewillberequiredtomaketheconfiguration.
Thefollowinginstructionsareanoutlineforguidance.Fulldocumentationcanbefoundintheonlinehelp.
1. Navigateto:Groups&Settings,AllSettings,Apps,SettingsandPolicies,SecurityPolicies.
ThisopenstheSecurityPoliciesconfigurationscreen,onwhichanumberofsettingscanbeswitchedonandoff,andconfigured.
2. FortheDataLossPreventionsetting,selectEnabled.
WhenEnabledisselected,furthercontrolswillbedisplayed.
3. FortheLimitDocumentstoOpenOnlyinApprovedAppssetting,selectYes.
WhenYesisselected,TheAllowedApplicationsListcontrolwillbedisplayed.
4. EntereachoftheapprovedapplicationsintheAllowedApplicationsListtextbox.
5. SelectSavetofinalizetheconfiguration.
Thisconcludestheconsoleconfiguration.
ApplicationConfigurationIntegratewithdocumentsharingrestrictioninyourappconfigurationbyaddingpropertysettingstotheAWSDKDefaultSettings.plistfile.
Thefollowingscreencaptureshowsanexampleconfiguration.
Configurationintheapplicationproject
Thepropertiesforintegrationareasfollows.
EnableSecureDocumentControllerTheEnableSecureDocumentControllerpropertycontrolsdocumentsharingviathenativeUIDocumentInteractionControllerinterface.ThepropertytakesaBooleanvalue.
IfEnableSecureDocumentControllerYESissetthenthefollowingrestrictionswillbeappliedtoafilesenttoaUIDocumentInteractionController,ifspecifiedinthesecuritypolicy.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page38of64
Thefilecanbecopiedtoanappthatisontheapprovedlistfromthemanagementconsole.Inthiscase,copyingmeanssendingthefiletotheotherappdirectly,nottoanappextension.Whenafileiscopied,thedeviceuserinterfacewillfliptotheotherapp.
Thefilecannotbecopiedtoanappthatisn’tontheapprovedlist.NotethatthisappliesequallytotheVMWareWorkspaceONEProductivityAppssuite.
Thefilecannotbesenttoanappextension.Thisapplieseveniftheappthathoststheextensionisontheapprovedlist.
Somesharingactionswon’tbeavailable.Sharingactionsmeansoptions,suchasCopyandPrint,thatappearinthedefaultdocumentinteractionuserinterface.
IfEnableSecureDocumentControllerNOissetthentheaboverestrictionswon’tbeappliedtoafilesenttoaUIDocumentInteractionController.Theapprovedlistfromthemanagementconsolewillbeignored.Thisisthedefault.
DisableActivityViewControllerTheDisableActivityViewControllerpropertycontrolsdatasharingviathenativeUIActivityViewControllerinterface.ThepropertytakesaBooleanvalue.
IfDisableActivityViewControllerYESissetthendatacannotbesharedviaaUIActivityViewController,ifspecifiedinthesecuritypolicy.Thisoptionmustn’tbeusedinthefollowingcases.
Don’tsetDisableActivityViewControllerYESifyourapplicationusestheUIDocumentInteractionControllerinterface.
Don’tsetDisableActivityViewControllerYESifyousetEnableSecureDocumentControllerYES.
IfDisableActivityViewControllerNOissetthendatacanbesharedviaaUIActivityViewController.Thisisthedefault.
SecurityPolicyApplicationTheaboveapplicationconfigurationdirectstheSDKtoapplythesecuritypolicyoftheenterprisetopartsofthenativeuserinterface.Thesecuritypolicywillbereceivedatruntime,forexampleintheSDKprofilefromthemanagementconsole.
Thepolicymightn’tspecifydatalossprevention,ormightspecifythatdocumentsharingisn’trestricted.Inthatcase,theSDKwon’tmodifythebehaviourofthenativeuserinterface.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page39of64
SetUptheDataSamplerModuleforAnalyticsTheDataSamplermodulesamplesdetaileddevicedataandreportsitbacktotheWorkspaceONEUEMconsole.DevicedetailssuchasanalyticsandnetworkadaptersareallsampledwiththeDataSampler.
TheDataSamplersamplesandtransmitsontwodifferenttimeintervals.Devicesamplesremainontothediskandthesystemremovesthemaftertransmitted.ThisprocessallowsthedevelopertosamplestatisticsmultipletimesbeforesendingthemtoWorkspaceONEUEM.Samplesstoredonthediskareusefulwhenadevicedoesnothavenetworkconnectivity.
AWDataSamplerisasingletonobject.TherecanonlybeoneDataSamplerforeachprocess.
ConfigurationTheseparametersarerequiredtosetupaDataSampler.
sampleModules–Namesthebitmaskwhoseflagsspecifywhichmodulestouse.defaultSampleInterval–SpecifiesthetimeinsecondsbetweenDataSamplersamplesforallmodulesbydefault.defaultTransmitInterval–SpecifiesthetimeinsecondsbetweenDataSamplertransmissionsforallmodulesbydefault.traceLevel–DeterminestheerrorandinformationloggingleveloftheDataSamplermodulewhenitisrunning.
ModulesAvailableforSamplingThesemodulesareavailableforsamplingintheDataSampler.
AWDataSamplerModuleSystemAWDataSamplerModuleAnalyticsAWDataSamplerModuleNetworkDataAWDataSamplerModuleNetworkAdapterAWDataSamplerModuleWLAN2Sample
GatherTelecomDataDisabletheAWDataSamplerModuleNetworkDatamaskifyougathertelecomdatausingtheWorkspaceONEIntelligentHub.IfyouenablethismaskfortheSDK,thenyoureceiveduplicatedatafromtheWorkspaceONEIntelligentHubandfromtheSDK.
UseAnalyticsHelperTheAnalyticsHelperisasingletonwithapropertyandafunction.Sendyourcustomanalyticseventfromyourapplicationtotheconsolewiththisprocess.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page40of64
Procedure1. AskyouradmintoenabletheAnalyticssettingintheSDKprofilefortheSDK-builtapplication.ThissettingisintheconsoleatGroups&Settings>AllSettings>Apps>SettingsandPolicies>Settings>Analytics.
2. Intheapplication,calltherecordEventmethodonthesingletonafterthecontrollerDidFinishInitialCheckdelegatecallbackreturns.
funcsendAnalytics(){letanalytics=AnalyticsHandler.sharedInstanceanalytics.recordEvent(AWSDK.AnalyticsEvent.customEvent,eventName:"EVENT_NAME",eventValue:"EVENT_VALUE",valueType:AWSDK.AnalyticsEventValueType.string)}
ResultsAfterthesystemrecordstheevent,itsavestheeventintheSDKcontainerfortwohours.Afterthetwohourspasses,theSDKsendsanalyticsrecordedtodisktotheconsoletheapplicationre-starts.
WhattodonextLocatethedataintheconsoleinApps&Books>Applications>Logging>SDKAnalytics.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page41of64
UsetheBrandingPayloadtoAddLogosandPrimaryHighlightColorsUsethebrandingpayloadtoaddlogosandprimaryhighlightstocustomizethelookoftheapplication.
BrandingbyOrganizationGroupManyorganizationsbrandapplicationsaccordingtotheapplicationsassignedorganizationgroupintheWorkspaceONEUEMconsole.Thistechniqueisusefulforupdatingthebrandingpayloadovertheair(withouthavingtoupdatetheapplication)fortime-sensitiveeventsormarketinginitiatives.
AccessBrandingSettingsintheSDKThebrandingpayloadisavailableafterthecontrollerDidReceive(profiles:[Profile])functioniscalled.Withinthebrandingpayload,itispossibletoviewtherawvaluessetintheconsole.UsethelistedAPI.
letbrandingPayload=AWController.clientInstance().sdkProfile()?.BrandingPayload
ThevaluesinAWBrandingbecomesetaftercontrollerDidFinishInitialCheck.Ifavalueisnotsetintheconsole,thenthesystemreturnsnil.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page42of64
AddValuestoAWSDKDefaultSettings.plistYoucanaddaprimaryhighlightcolortobrandthebuttonsontheauthenticationscreen.Youcanalsoaddtwocompanylogos(AppLogoandSplashLogo)withintheBrandingdictionaryinsideyourAWSDKDefaultSettings.plist.
Table1.AvailableBrandingEntriesintheAWSDKDefaultSettings.plist
Entry Type
Branding Dictionary
Colors Dictionary
PrimaryHighlight String
AppLogo_1x String
AppLogo_2x String
SplashLogo_1x String
SplashLogo_2x String
AppLogo-TheSDKputstheAppLogoonalloftheauthenticationscreens.
SplashLogo-TheSDKputstheSplashLogoontheloadingscreenandonthesecondapplicationloginscreen.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page43of64
BeaconDataSentUponApplicationUnlockorSentManuallyThebeaconisaregularupdatesentfromtheVMwareWorkspaceONESDKforiOS(Swift)totheWorkspaceONEUEMconsole.TheSDKsendsthisdataeverytimeitisunlocked.Youcanalsoforcethebeaconwhenyouwantdata.
BeaconUpdateContentsThebeaconupdatecontainsthelistedinformation.
Table1.ContentsintheBeaconUpdate
TypeofInformation Data
General DevicenameOrganizationalgroupApplicationbundleidentifier
Platform Deviceoperatingsystem(Apple,iOS)Deviceoperatingsystemversion
User UseremailUserfullnameUserdisplayname
Enrollment DeviceenrolledDeviceunenrolledDevicewipepending
Compliance DevicecomplianceApplicationcompliance
SendtheBeaconManuallyUseanAPItosendthebeaconmanually.
letbeaconTransmitter=SDKBeaconTransmitter.sharedTransmitter()//TosendimmediatelybeaconTransmitter.sendDeviceStatusBeacon(completion:SendBeaconCompletion?)beaconTransmitter.sendBeacon(updatedAPNSToken:String,completion:SendBeaconCompletion?)//Tostartascheduleofhowfrequentlytosend.//(Ifgiventimeintervalislessthan60,frequencywilldefaultto60)publicfuncstartSendingDeviceStatusBeacon(transmitFrequency:TimeInterval=60)//TostopthesendingthescheduledbeaconpublicfuncstopSendingDeviceStatusBeacon()
CertificatePinningUsecertificatepinningtohelppreventman-in-the-middle(MITM)attacksbyenablinganadditionallayeroftrustbetweenlistedhostsanddevices.
Certificatepinningrequiresnocode.JustenableSSLpinningintheWorkspaceONEUEMconsoleanduploadyourcertificate.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page44of64
ChecktheCompromisedStatusofDeviceswithCompromisedProtectionWorkspaceONEUEMdetectsjailbrokendevicesandcanwipecompromiseddevicesifenabledintheWorkspaceONEUEMconsole.
Compromisedprotectionrequiresnocodeunlessyouwanttomanuallycheckthestatusofthedevice.
CheckCompromisedProtectionStatusTocheckthestatusofadevicedirectlyinyourapplication,whetherthedeviceisonlineoroffline,calltheisCurrentDeviceCompromised()APIfromtheDeviceInformationControllersingletonclass.
//SwiftletdeviceInfoController=DeviceInformationController.sharedController()letcompromisedStatus=deviceInfoController.isCurrentDeviceCompromised()ifcompromisedStatus==true{AWLogDebug("Mydeviceisjailbroken!")}
DynamicCompromiseDetectionRequirementsDynamiccompromisedetectionforiOSsetsSDK-builtappstosecurelyupdatethecompromisedetectionalgorithmover-the-air.Appsthatusethisfeaturedonotneedtoupdateorre-releaseaftercompromisedetectionruleupdates.Toconfigurethisfeature,updatetothesupportedSDKversionandensurethatdevicescanaccessspecificURLs.Tousedynamiccompromisedetection,updatetheSDKversionandensurethatdevicescanaccessspecificURLs.
TheSDK-builtappmustconsumeWorkspaceONESDKforiOS(Swift)v19.2orlater.Toreceivethelatestcompromisedetectionrules,ensurethatdevicescanconnecttothelistedURLs.api.na1.region.data.vmwservices.comdiscovery.awmdm.comsigning.awmdm.com
IfdevicescannotaccesstheseURLs,theystillgetcompromisedetectionbutrulesonlyupdatewhentheSDK-builtappconsumesthelatestSDK.Thislapseinruleupdatesmightresultinfalsepositives.
Note:IfyouuseVMwareWorkspaceONETunnel,ensurethatyourtrafficrulesareconfiguredtoallowdevicestoconnecttothelistedURLs.
---
DeveloperGuide
WorkspaceONEforiOS(Swift) Page45of64
QueryDevicesforMDMInformationwithDeviceInformationControllerUsetheDeviceInformationControllersingletonclasstoquerydevicesformobiledevicemanagement(MDM)information.
TheclassreturnsthelistedMDMinformation.
EnrollmentstatusCompliancestatusManagedstatusManagementtypeOrganizationalgroupnameOrganizationalgroupIDDeviceservicesURLSinglesignonstatusCompromisedstatus
RequeryMethodThemethodqueriestheconsole,andtheconsolesendsaquerycommandtothedevicetocollectcertaintypesofdeviceinformation.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page46of64
SDKLoggingAPIsforLevelsWorkspaceONEUEMgroupsloggingmessagesintocategoriestodistinguishcriticalissuesfromnormalactivities.
TheWorkspaceONEUEMconsolereportsthemessagesthatmatchtheconfiguredlogginglevelplusanylogswithahighercriticalstatus.Forexample,ifyousettheloggingleveltoWarning,messageswithaWarningandErrorleveldisplayintheWorkspaceONEUEMconsole.TheSDK-builtapplicationcollectslogsovertimeandstoresthemlocallyonthedeviceuntilanotherAPIorcommandisinvokedtotransmitthelogs.
Note:Whenanenterprisewipeoccurs,theconsoledoesnotpurgethelogfiles.Youcanretrievelogsafteradevicere-enrollstodeterminewhatissuesoccurredinthelastenrollmentsessiontocausetheenterprisewipe.
Table1.SDKLoggingLevelAPIsandLevelDescriptions
Level LoggingAPI Description
Error AWLogError("{logmessage}")
Recordsonlyerrors.AnerrordisplaysfailuresinprocessessuchasafailuretolookupUIDsoranunsupportedURL.
Warning AWLogWarning("{logmessage}")
Recordserrorsandwarnings.Awarningdisplaysapossibleissuewithprocessessuchasbadresponsecodesandinvalidtokenauthentications.
Information AWLogInfo("{logmessage}")
Recordsasignificantamountofdataforinformationalpurposes.Aninformationloggingleveldisplaysgeneralprocesses,warning,anderrormessages.
DebugorVerbose
AWLogVerbose("{logmessage}")
Recordsalldatatohelpwithtroubleshooting.Thisoptionisnotavailableforallfunctions.
SDKLoggingAPIstoSendtotheConsoleUsetwowaystotransmitSDKlogs.ThedevelopercanmanuallytriggerthetransmissionofSDKlogstotheWorkspaceONEUEMconsolewithAPIs.TheWorkspaceONEUEMadmincanusetheViewLogsmenuitemtogetlogsforanapplication.
DeveloperAPIsiOS(Swift)-AWController
publicfuncsendLogDataWithCompletion(completion:@escaping(success:Bool,_error:NSError?)->Void)
iOS(Objective-C)-AWLog
-(void)sendApplicationLogsWithCompletion:(void(^)(BOOLsuccess,NSError*error))completion;-(BOOL)hasAWLogs;
DeveloperGuide
WorkspaceONEforiOS(Swift) Page47of64
SDKLogTypesWorkspaceONEUEMdisplayslogsforapplicationsthatreportapplicationfailuresandthatreportapplication-specificdata.TheselogsintegratewiththeVMwareWorkspaceONESDKsothatyoucanmanageapplicationsbuiltbyit.
FindlogsforapplicationsinApps&Books>Analytics>AppLogs.
Setting Description
ApplicationLogs
Thistypeoflogcapturesinformationaboutanapplication.YousettheloglevelinthedefaultSDKprofilessection,ettings>AllSettings>Apps>SettingsandPolicies>Settings>Logging.YoumustaddcodeintotheapplicationtouploadtheselogstotheWorkspaceONEUEMconsole.
CrashLogs Thistypeoflogcapturesdatafromanapplicationthenexttimetheapplicationrunsafteritcrashes.TheselogsareautomaticallycollectedanduploadedtotheWorkspaceONEUEMconsolewithouttheneedforextracodeintheSDKapplication.
ConfigureLoggingfortheDefaultSDKProfileUseLoggingsothesystemrecordsdataforapplicationstheusetheVMwareWorkspaceONESDKframework.TheWorkspaceONEUEMsystemcollectslogsuntilthelogfilesizereaches200MBforSaaSenvironments.Ifthelogsizeexceeds200MB,thesystemstopscollectinglogs.TheWorkspaceONEUEMconsolenotifiesyouwhenyourapplicationlogsizereaches75%of200MB.Toactontheapplicationlogsize,contactyourWorkspaceONEUEMRepresentative.
Askforanincreaseinyourapplicationlogsize.Askforapurgeofyourapplicationlog.Thesystemcanpurgelogsolderthantwoweeks.
Procedure1. NavigatetoGroups&Settings>AllSettings>Apps>SettingsandPolicies>Settings.2. SelectEnabledforLogging.3. ChooseyourLoggingLevelfromaspectrumofrecordingfrequencyoptions.4. SelectSendlogsoverWi-Fionlytopreventthetransferofdatawhileroamingandtolimitdatacharges.5. Saveyoursettings.
RequestApplicationLogsforSDK-BuiltAppsRequestapplicationslogsforyourSDK-builtapplicationsfromthedevicerecordintheconsole.
Procedure1. NavigatetoDevices>ListViewandselectthedevice.2. SelecttheAppstab,selecttheSDK-builtapp,andchooseRequestLogs.
TheRequestLogsbuttondisplaysafteryouselecttheapplication.3. CompletethesettingsintheRequestLogswindow.Youcanretrievelogsthatarecurrentlyavailableor
youcanselecttocapturealogtypeforadurationoftime.4. Toretrievethelogs,navigatetoApps&Books>Applications>Logging>AppLogs.5. FindthelogfortheapplicationwiththeAppNamecolumnanddownloadthefile.
ConfigureViewLogsforInternalApplicationsUsetheViewLogsfeaturetoaccessavailablelogfilespertainingtoapplicationsthatusetheWorkspaceONESDKframework.Logtypesincludealllogs,crashlogs,andapplicationlogs.Withthisfeature,youcandownloadordeletelogs.
FilteroptionsusingtheLogTypeandLogLevelmenussothatyoucanfindthetypeoramountofinformationtoresearchandtroubleshootapplicationsthatusetheSDKframework.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page48of64
Procedure1. NavigatetoApps&Books>Applications>NativeandselecttheInternaltab.2. SelecttheapplicationandthenselectMore>View>Logsoptionfromtheactionsmenu.3. Selectdesiredoptionsdependingonifyouwanttoactonspecificdevices(selected)ortoactonall
devices(listed).
Setting Description
DownloadSelected
DownloadselectedlogswithinformationpertainingtoapplicationsthatusetheWorkspaceONESDKframework.
DownloadListed
DownloadalllogsinallpageswithinformationpertainingtoapplicationsthatusetheWorkspaceONESDKframework.
DeleteSelected
DeleteselectedlogswithinformationaboutapplicationsthatusetheWorkspaceONESDKframework.
DeleteListed DeletealllogsinallpageswithinformationaboutapplicationsthatusetheWorkspaceONESDKframework.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page49of64
OfflineAccessTheofflineaccessfunctionallowsaccesstotheapplicationwhenthedeviceisnotcommunicatingwiththenetwork.ItalsoallowsaccesstoWorkspaceONEUEMapplicationsthatusetheSSOfeaturewhilethedeviceisoffline.
OfflineBehaviorTheWorkspaceONESDKautomaticallyparsestheSDKprofileandhonorstheofflineaccesspolicyonceAWControllerisstarted.Ifyouenableofflineaccessandanend-userexceedsthetimeallowedoffline,thentheSDKautomaticallypresentsablockerviewtopreventaccessintotheapplication.ThesystemcallsthelockmethodoftheAWSDKDelegatesoyourapplicationcanactlocally.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page50of64
CustomSettingsfortheSDKTheVMwareWorkspaceONESDKforiOS(Swift)allowsyoutodefineyourowncustomsettingsforyourapplicationusinganSDKprofile.
Youcanpasterawtextinthecustomsettingssection,andtheSDKmakesthiscontentavailableinsidetheapplicationusingtheAWCustomPayloadobject.
YoucandefineanXML,JSON,key-valuepairs,CSV,orplaintextforyoursettings.Parsetherawtextintheapplicationonceitisreceived.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page51of64
EncryptDataonDevicesTheVMwareWorkspaceONESDKforiOS(Swift)offerstheuseofbasicencryptanddecryptmethodstooperateonrawdatathatthesystemencryptsusingtheSDK’sinternalencryptionkeys.
ThesemethodsaredefinedintheAWController.Important:Donotusetheseencryptionmethodsonanymissioncriticaldataordatathatyoucannotrecover.Examplesofunrecoverabledataincludenobackuponaserverorifthedatacannotbere-derivedthroughothermeans.Theencryptedkey(andassociatedencrypteddata)islostintheeventthatanenduserdeletestheapplicationorifanenterprisewipe.
PrequisitesBeforeyoucalltheencryptionmethods,ensuretheAWControllerDelegatereceivesnoerrors.
Swift:ApplicationsmustensurethatAWControllerDelegatereceivesthecontrollerDidFinishInitialCheck(error:NSError?)callbackwithnoerrorsbeforetheycalltheencryptionmethods.
Objective-C:TheAWControllerDelegatecallbackmethodis-(void)initialCheckDoneWithError:(NSError*_Nullable)error;
EncryptionStrengthandAuthenticationModeThestrengthoftheencryptiondependsontheenablingoftheauthenticationmode.
Ifyousetauthenticationpasscodeorusernameandpassword,thenthesystemderivesthekeyusedforencryptionfromthepasscodeorusernameandpasscodetheuserenters.Thesystemkeepsthekeyindevicevolatilememoryforadditionalsecurity.
Ifyoudisableauthentication,thesystemrandomlygeneratestheencryptionkeyandpersistsitindevicestorage.
EncryptDatanotStoredwithCoreDataTheWorkspaceONESDKforiOS(Swift)providestheabilitytoencryptdatathatCoreDatadoesnotstore.Thesemethodstakeinthedatainputandreturnbackeithertheencryptedordecrypteddata.Thesemethodsareonlyusedforthetransformationofthedata.Theapplicationdeveloperisresponsibleforthestorageoftheencrypteddata.
EncryptionMethod:Swift
publicfuncencrypt(_data:Data)throws->Datapublicfuncdecrypt(_data:Data)throws->Data
EncryptionMethod:Objective-C
(NSData*_Nullable)encrypt:(NSData*_Nonnull)dataerror:(NSError*_Nullable*_Nullable)errorSWIFT_WARN_UNUSED_RESULT;(NSData*_Nullable)decrypt:(NSData*_Nonnull)dataerror:(NSError*_Nullable*_Nullable)errorSWIFT_WARN_UNUSED_RESULT;
ErrorCodesDefinedandExamplesTheenumAWSDKCryptErrordefinestheerrorcodesfortheerrorthrownbythemethods.
Encrypt
letcontroller=AWController.clientInstance()letplainData:Data=..//assigndatatobeencrypteddo{letencryptedData=trycontroller.encrypt(plainData)//saveencryptedDataforfutureuse//...}catchleterror{print("failedtoencryptdatawitherror:\(String(describing:error))")}
DeveloperGuide
WorkspaceONEforiOS(Swift) Page52of64
Decrypt
letcontroller=AWController.clientInstance()letencryptedData=..//fetchdatapreviouslyencryptedusingEncryptmethodabovedo{letdecryptedData=trycontroller.decrypt(encryptedData)//dosomethingwithdecryptedData//...}catchleterror{print("failedtoencryptdatawitherror:\(String(describing:error))")}
DeveloperGuide
WorkspaceONEforiOS(Swift) Page53of64
EnableandCodeAPNsintheApplicationTouseApplepushnotificationsinyourSDK-builtapplicationandWorkspaceONEUEM,enabletheuseofAPNsandaddcodetosupportpushnotifications.
SettingatokenvaluetoAWControllerinitiatesthecalltotheconsolebecauseitsendsthebeacon.AssignthetokenvaluetoAWControlleronlyafterthetokenvaluehaschanged.
Settingthetokenvaluetonilclearsthetokenvaluefromtheconsoleandyoucannotusethetokentosendpushnotifications.Note:Thesamplecodeisforreferenceandcanbeadjustedpertheapprequirements.Seethesampleappformoreexamplesofhowthelistedmethodsareused.
Procedure1. SelectTargetandenablepushnotificationsincapabilities.YouseetwochecksinPushNotification.
PushNotificationsExample
2. AddimportUserNotificationstothetopofAppDelegate.swift.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page54of64
3. AddapplicablemethodstotheendofAppDelegate.swift.
funcregisterForPushNotifications(){if#available(iOS10.0,*){UNUserNotificationCenter.current().requestAuthorization(options:[.alert,.sound,.badge]){granted,errorinprint(“PermissionGranted\(granted)”)guardgrantedelse{return}self.getNotificationSettings()}}else{letnotificationSettings=UIUserNotificationSettings(types:[.alert,.badge,.sound],categories:nil)DispatchQueue.main.async{UIApplication.shared.registerUserNotificationSettings(notificationSettings)}}}@available(iOS10.0,*)funcgetNotificationSettings(){UNUserNotificationCenter.current().getNotificationSettings{settingsinprint("Notificationsettings\(settings)")guardsettings.authorizationStatus==.authorizedelse{return}DispatchQueue.main.async{UIApplication.shared.registerForRemoteNotifications()}}}funcapplication(_application:UIApplication,didRegisterForRemoteNotificationsWithDeviceTokendeviceToken:Data){lettokenParts=deviceToken.map{datainString(format:"%02.2hhx",data)}lettoken=tokenParts.joined()print("DeviceToken:\(token)")letcontroller=AWController.clientInstance()controller.APNSToken=token}funcapplication(_application:UIApplication,didFailToRegisterForRemoteNotificationsWithErrorerror:Error){print("Failedtoregister:\(error)")}
4. AddregisterForPushNotifications()neartheendofapplication(_:didFinishLaunchingWithOptions:),andbeforereturn:.
EnableAPNsintheConsoleUseSDK-builtapplicationstosendApplepushnotificationstoapplicabledevices.EnabletheSDK-builtapptouseAPNs.ThistaskassumesthattheSDK-builtappisalreadyuploadedandmanagedintheWorkspaceONEUEMconsole.TheseappsareavailableinanappstoreandtheyuseProductionAPNscertificates.
PrerequisitesGenerateyourproductionAPNscertificatessoyoucanuploadthecertificatestotheWorkspaceONEUEMconsole.Fordetails,visitthetopicRegisteringYourAppwithAPNsontheAppleDevelopersite.
Procedure1. NavigatetoApps&Books>Applications>SDK-builtappandchooseEdit.2. SelecttheFilestabandselectYesforApplicationSupportsAPNs.3. SelectProductionforAPNsCertificate.4. UseUploadtoaddyourcertificatestotheconsoleasanAPNsProductionCertificate.5. SelectSave&Assign.Editingtheassignmentisoptionalandnotnecessarytofinishthistask.Youcan
SaveandPublishfromtheassignmentmodule.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page55of64
APIstoUseCustomCertificatesforYourSDK-BuiltAppsTheWorkspaceONESDKforiOS(Swift)hasAPIstoevaluateservertrustandverifyconfiguredcertificates.APItoValidateServerTrust
Declaration
funcvalidate(serverTrust:SecTrust,trustStore:CertificatesTrustStore,strictness:SSLTrustStrictness)->Bool
TheadminconfigurestrustedcertificatesasCredentialsintheSDKprofile.WhentheSDKstarts,itfetchescustomanchorsandSSLcertificatesconfiguredbytheadminandstoresthemsecurelyasconfigured.Whileconnectingtoanetworkhost,theappcanreceiveachallenge.Duringthischallenge,theappcanuseanAPItovalidatetheservertrustandcandecidetoalloworcanceltheconnection.
ParameterExplanations-ServerTrust,TrustStore,andSSLTrustStrictness
ServerTrustRetrievetheSecTrustobjectfromtheProtectionSpacegiventotheappforauthenticationbytheURLSessiontask.
TheAPIcopiesthecertificatechainandpoliciesforevaluation,sothattheappcanperformadditionaloperationsontheSecTrustinitsoriginalform.
TrustStoreTheAPIconsiderstheTrustStoretypewhileitevaluatestheServerTrust.TheAPIsupportsonlydeviceAndCustomandcustomtypesforTrustStore.
Ifyouconfigurethetypeascustom,theAPIusesonlycustomanchorsorself-signedSSLcertificates(thoseanchorsorcertificatesconfiguredbytheadmininaCredentialspayload)toevaluatetrust.Ifyourserverusesintermediatecertificateauthorities,youmustaddtheintermediatecertificateauthoritiesintheCredentialspayload.
IftypeisdeviceAndCustom,theSDKusessystemtruststorecombinedwiththeconfiguredcertificatestoevaluatetheServerTrust.
Note:Youcanuseself-signedSSLcertificateswithorwithoutanyCAcertificatesbyaddingthemdirectlytotheSDKCredentialspayload.
SSLTrustStrictnessTheSDKusesSSLTrustStrictnesstoconsiderrecoverableTrustFailureSecTrustResultTypeasanendresult,tobetrustedornottrusted.
Ifthevalueforstrictnessisstrict,theSecTrustResultTypeendresultisrecoverableTrustFailureandisnottrusted.
Ifthevalueforstrictnessisignore,theSecTrustResultTypeendresultisrecoverableTrustFailureandistrusted.
IftheTrustStoreiscustom,theSDKformsacompletechainwiththecertificatesfromtheSecTrustandvalidatesthechain.ValidationisaccordingtothepoliciessetintheSecTrust.IfTrustStoreisdeviceAndCustomThe,theSDKformsthechainuptoacertificatethatisinthetrustedlist.
-
-
-
-
-
DeveloperGuide
WorkspaceONEforiOS(Swift) Page56of64
CertificatesConsideredforServerTrustValidation
RootCAcertificatesIntermediateCAcertificatesSSLcertificates
UploadpublicX509certificatesinDERorPEMformat.TheSDKdoesnotconsidercertificatesuploadedwithaprivatekeyforservertrustevaluation.
APItoRetrieveConfiguredCertificatesDeclaration
funcretrieveStoredPublicCertificates(completion:(_certificateMap:[String:[PublicCertificate]]?,_error:NSError?)->Void)
ParameterExplanationCompletionThecompletionblockiscalledwiththeconfiguredcertificatesmap.Itreturnsanerrorifthereisanyproblemwhileretrievingthecertificates.
TheAPIreturnsamap.ThekeysarerepresentedusingtheconstantsfromAWCertificateUsageKeyclass.CorrespondingvaluesarearrayofPublicCertificateObjects.Youcanquerycertainx509attributesfromthePublicCertificateobjectsandverifytheconfiguration.
@objc(AWCertificateUsageKey)publicclassCertificateUsageKey:NSObject{//CertificateofUsagekeytoreflectIntegratedAuthenticationpublicstaticletintegratedAuthIdentity:String//CertificateofUsagekeytoreflectIntegratedAuthenticationpublicstaticletuncategorizedIdentity:String//CertificateofthisusageareusedforsigningrequestsforMAGProxypublicstaticletmagSigning:String//CertificateofthisusageareusedforsigningrequestsforTunnelProxypublicstaticlettunnelSigning:String//CertificatesoftypeSSLpublicstaticletselfSignedSSLCerts:String//CertificatesoftypeCustomAnchorspublicstaticletcustomTrustedAnchorCerts:String//SDKdoesn'thavespecificusageforthistypeofcertificatespublicstaticletothers:String}
---
DeveloperGuide
WorkspaceONEforiOS(Swift) Page57of64
VMwareWorkspaceONESDKforiOS(Swift)andtheAppleAppReviewDeployappsthatusetheWorkspaceONESDKforiOS(Swift)totheAppStorewithoutdependencyonotherWorkspaceONEUEMcomponents.TheSDKincludesamodeforyourapplicationforuseduringtheAppleAppReviewprocess.
ThisappreviewmoderemovesdependenciesonthebrokerapplicationssuchastheWorkspaceONEIntelligentHubforiOS,Container,andtheWorkspaceONEapplication.ItalsoenablestheappreviewertoaccesstheapplicationwithoutenrollingwithWorkspaceONEUEM.
ExplanationoftheProcessBuildyourapplicationandincorporatetheWorkspaceONESDKforiOS(Swift).Then,buildatestenvironmentinWorkspaceONEUEMandpreparetheapplicationforsubmissiontotheappreviewprocess.Forgeneralstepsintheprocess,seeStepstoConfigureAppReviewMode.
BuildaTestEnvironmentinWorkspaceONEUEMCreateatestenvironmentinWorkspaceONEUEMthatyouuseonlyforthisappreviewprocess.Fordetailsonhowtocreatethisenvironmentandhowtouploadyourapplicationtoit,seeConfigureanAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsole.
IdentifytheServerURLandGroupIDTohelpyourapplicationworkforthereviewprocesswithoutdependenciesonotherWorkspaceONEUEMcomponents,followtheprocedureinDeclaretheAppReviewServerandGroupIDintheSDKPLIST.
StepstoConfigureAppReviewModeDeployappsthatusetheVMwareWorkspaceONESDKforiOS(Swift)totheAppStorewithoutdependencyonotherWorkspaceONEUEMcomponents.TheSDKincludesamodeforyourapplicationforuseduringtheAppleAppReviewprocess.
ThisappreviewmoderemovesdependenciesonthebrokerapplicationssuchastheWorkspaceONEIntelligentHubforiOS,VMwareContainer,andtheWorkspaceONEapplication.ItalsoenablestheappreviewertoaccesstheapplicationwithoutenrollingwithWorkspaceONEUEM.
Important:UsethisworkflowonlyonapplicationsbuiltwiththeWorkspaceONESDKthatyousubmittotheAppStoreforreview.Donotusethisworkflowforanyotherapplicationdevelopmentprocesses.Also,donotusetheprocessinaproductionenvironment.ThisprocessisonlysupportedforuseinatestenvironmentforapplicationsyousubmittoApple’sAppReview.
Procedure1. IntegratetheSDKwithyourapplication.
2. ConfiguretheappreviewmodetestingenvironmentintheWorkspaceONEUEMconsole,uploadtheapplicationIPAfile,assignitanSDKprofile,anddeployittothetestenvironment.
SeeConfigureanAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsole.
3. AssignanappreviewmodeserverandagroupIDtotheSDKPLIST.
SeeDeclaretheAppReviewServerandGroupIDintheSDKPLIST.
4. TesttheIPAinthetestenvironment.
SeeTesttheAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsole.
5. Runtheappstorebuildscript.
SeeBuildScriptInformationforAppStoreSubmission.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page58of64
6. SubmityourapplicationforreviewtotheAppleAppStoreensuringtoaddtheappreviewmodeserver,groupID,andusercredentialsfromthetestenvironmenttothesubmission.
ConfigureanAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsoleWithhelpfromyouradmin,configureatestingenvironmentintheWorkspaceONEUEMconsole.UploadyourapplicationtothisenvironmentsothattheappreviewercanreviewyourapplicationwithoutdependenciesonotherWorkspaceONEUEMcomponents.
PrerequisitesIntegratetheWorkspaceONESDKforiOS(Swift)withyourapplication.YouneedWorkspaceONEUEMsystemadminpermissionstoconfigurethesecomponents.Ifyoudonothavethesepermissions,askyourWorkspaceONEUEMAdminforhelp.Ensurethatyoucreateatestingenvironmentthathostsnoproductionapplicationsandcomponents.Usethisappreviewmodeenvironmentonlyfortheappreviewprocess.Configurealloptionsintheapprevieworganizationgroup.
Procedure1. ConfigureaspecialorganizationgroupforappreviewmodeintheWorkspaceONEUEMconsole.RecordthegroupIDforlaterentrytotheSDKPLIST.
2. ConfigureanappreviewmodeuserwithcredentialsintheWorkspaceONEUEMconsole.Yougivethesecredentialstotheappreviewersorecordthecredentials.
3. Createasmartgroupandaddtheusertothegroup.WorkspaceONEUEMdeploysapplicationsbasedonassignmentgroups,specificallythesmartgrouptype.
4. ConfiguretheSDKprofile.UsethedefaultSDKprofileoracustomSDKprofile.WhateverSDKprofileyouuse,ensurethatthedesiredSDKfeaturesareenabled.FeaturestoreviewaretheAuthenticationType,SingleSignOn,andtheAppTunnelMode.
5. Uploadtheapplicationbinary(IPA)totheinternalapplicationareaorthepublicapplicationareaoftheWorkspaceONEUEMconsole.EnsurethatyouassigntheSDKprofiletotheapplicationandassignthetestsmartgrouptotheapplication.ThebundleidentifiermustmatchtheapplicationsubmittedtotheAppReviewprocess.
6. DisabletherequirementforMDMenrollmentsotheappreviewercanaccesstheapplicationwithoutenrollingwithMDM.AlthoughthesettingarenestedundertheContentLocker,itappliestoallapplications.Improvementstotheuserinterfaceareplannedforthefuture.Ensureyouareintheappreviewmodeorganizationgroup.NavigatetoGroups&Settings>AllSettings>Content>Applications>ContentLocker.IntheGeneralarea,disableRequireMDMEnrollment.SelectSave.
DeclaretheAppReviewServerandGroupIDintheSDKPLISTTopreparetosubmityourapplicationtotheAppleAppReviewprocess,addtheappreviewmodeserverURLandthegroupID.ThesestringsallowthereviewertoreviewyourapplicationwithouttheneedforotherWorkspaceONEUEMcomponents.
Procedure1. Ifyouhavenotdoneso,inyourXcodeproject,createabundlenamedAWSDKDefaults.
2. IftheAWSDKDefaultsbundledoesnothaveaPLISTnamedAWSDKDefaultSettings.plist,createthisPLISTinthebundle.
3. CreateakeyinthePLISTwiththedatatypestring.Namethiskeycom.vmware.air-watch.enrollment.test-server-url.
Thisnameiscasesensitive.
----
DeveloperGuide
WorkspaceONEforiOS(Swift) Page59of64
4. SetthevalueofthiskeytotheserverURLoftheWorkspaceONEUEMenvironmentyousetupinConfigureanAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsole.
EnsuretomeettheserequirementsfortheURL.
Includehttps://beforetheURL.EnsuretheURListheexactdeviceservicesserverURL.DonotusetheconsoleorAPIserverURL.Donotinclude/deviceservicesattheendoftheURL.TheSDKappendsthisautomatically.
5. CreateanotherkeyinthePLISTwiththedatatypestring.Namethiskeycom.vmware.air-watch.enrollment.test-org-group-id.
Thisnameiscasesensitive.
6. SetthevalueofthiskeytothegroupIDoftheappreviewgroupyousetupinConfigureanAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsole.
TesttheAppReviewModeTestingEnvironmentintheWorkspaceONEUEMConsoleTestthattheIPAfile,serverURL,groupID,andusercredentialsworkbeforeyousubmittheapplicationforreview.
Procedure1. Attempttoruntheapponadevicewithoutanypreviousappdata.
ThisactionensuresthatstaleURLanddeviceinformationisnotpresentonthedevice.ItalsoensurestherearenootherWorkspaceONEUEMappsonthedevice.
2. EntertheserverURLandgroupIDwhentheapppromptfortheseoptions.
3. Entertheusercredentialswhenprompted.
ResultsIftheSDKpermitsyoutocontinuewithouterrorandcontrollerDidFinishInitialCheckiscalled,thetestenvironmentandcomponentsaresuccessful.
BuildScriptInformationforAppStoreSubmissionThisprocessrequiresaseparatebuildscriptthatyourunbeforeyousubmittheapplicationforreview.
ReasonfortheSpecialScriptRunthebuildscripttostripthesimulatorarchitectures.TheapplicationfailstheAppleAppReviewstaticanalysisifyoudonotrunthescript.
AccesstheScriptUsethescriptlocatedonStackOverflow,athttps://stackoverflow.com/questions/30547283/submit-to-app-store-issues-unsupported-architecture-x86/30866648#30866648asofOctober,2018,tostripthenon-appstorerelatedarchitecturesfromyourapplication.
(SomePDFviewersincorrectlyescapethehashanchormarkerintheabovelinks.Ifthathappens,editthelinkinthebrowseraddressbar.)
---
DeveloperGuide
WorkspaceONEforiOS(Swift) Page60of64
MigratetheObjective-CVersiontotheSwiftVersionTomigratetoaversionoftheWorkspaceONESDKforiOS(Swift),removetheoldSDKandaddthecurrentonetoyourenvironment.
SeeComponentChangesintheWorkspaceONESDKforiOS(Swift)forchangestomaketoyourprojecttopreventbuilderrors.
ShareYourKeychainShareyourkeychainbetweentheSDKapplicationssoyoucanusealltheSDKcapabilities.SeeKeychainAccessGroupEntitlements.
RemovetheObjective-CVersionoftheSDKDeletethelistedWorkspaceONESDKforiOS(Swift)frameworksandlibrariestoremovetheSDK.
Procedure1. OntheGeneraltabinyourproject,deletetheAWSDK.frameworkfromboththeEmbeddedBinariesandLinkFrameworkandLibrariesareas.
2. OpentheBuildPhasestabintheprojectsettingsofyourapplication.3. DeleteAWKitfromyourproject.4. DeleteAWlocalizationfromyourproject.
AddtheSwiftVersionoftheSDKAddWorkspaceONESDKforiOS(Swift)frameworksandeditthelocationsofthelistedcallstomigrateSDKbehaviorstothecurrentversion.Ifyoudonoteditthelistedcalllocations,theUIbehaviorisinconsistentwiththepreviousSDKversion.
Procedure1. DraganddropthecurrentAirWatchSDKframeworkandtheAWCMWrapperfileintoyourLinkBinarywithLibrariesstepinthebuildphasesectionofyourprojectsettings.
2. ChangethelocationofyourStartSDKcall.CallitinthedidFinishLaunchingWithOptionsmethodthatisinsideyourapplicationdelegateclass.InversionsbeforetheWorkspaceONESDKv17.x,youcalledawcontroller.start()withintheapplicationDidBecomeActivemethod.
3. Buildyourproject.4. ResolvenamingdifferencesandAPIdifferencesthatchangedinthenewSDKcausingbuilderrors.
ComponentChangesintheWorkspaceONESDKforiOS(Swift)IfyoumigrateanolderversionoftheSDKtoinstallit,reviewthelistofchangedcomponents.UpdatenamesandlocationsofcomponentstopreventorresolvebuilderrorscausedbythedifferencesbetweenSDKversions.
Samplespresenttheoldversionofthecodefollowedbythecurrentcode.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page61of64
Component SampleCode
AWControllerstart
InthepreviousSDKyoucalledawcontroller.start()withintheapplicationDidBecomeActivemethod.
InthecurrentSDK,starttheSDKwithinthedidFinishLaunchingWithOptionsmethodinsideyourapplicationdelegateclass.
///5.9.XImplementationfuncapplicationDidBecomeActive(_application:UIApplication)letawc=AWController.clientInstance()awc.delegate=selfawc.callbackScheme="myAppName"awc.start()}
///SwiftversionImplementationfuncapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplicationLaunchOptionsKey:Any]?)->Bool{letawc=AWController.clientInstance()awc.delegate=selfawc.callbackScheme="myAppName"awc.start()returntrue}
CanhandleProtectionSpace(IntegratedAuthentication)
Updatethecodeforauthenticationchallengesandchainvalidation.
///5.9.XImplementationtryAWController.clientInstance().canHandle(challenge.protectionsSpace)
///SwiftversionImplementationtryAWController.clientInstance().canHandle(protectionsSpace:challenge.protectionsSpace)
AWLogsingleton(Logging)
UsethisinsteadoftheAWControllertosendlogs.
///5.9.XImplementationAWLog.sharedInstance().sendApplicationLogs(success,errorName)
///SwiftversionImplementationAWController.clientInstance().sendLogDataWithCompletion{(success,error)}
NetworkStatus
UpdatethefrontoftheenumtoAWSDK.
///5.9.XImplementationAWNetworkActivityStatus
///SwiftversionImplementationAWSDK.NetworkActivityStatus
Profilesandprofilepayloads
DroptheAWfromthefrontofprofiles.
///5.9.XImplementationAWProfile
///SwiftversionImplementationProfile
CustomSettings
AccesscustomsettingsthroughAWControllerinsteadofAWCommanManager
///5.9.XImplementationAWCommandManager().sdkProfile().customPayload
///SwiftversionImplementationAWController.clientInstance().sdkProfile()?.customPayload
Accountobject
TheaccountobjectisnowapropertyonAWControllerinsteadofanaccessormethod.
///5.9.XImplementationAWController.clientInstance().account()
///SwiftversionImplementationAWController.clientInstance().account
DeveloperGuide
WorkspaceONEforiOS(Swift) Page62of64
Component SampleCode
Usercredentials ///5.9.XImplementationAWController.clientInstance().updateUserCredentials(completions:{(success,error)in{...})
///SwiftversionImplementationAWController.clientInstance().updateUserCredentials(with:{(success,error)in{...})
OpenInURLcalls ///5.9.XImplementationAWController.clientInstance().handleOpen(url,fromApplication:sourceApplication)
///SwiftversionImplementationAWController.clientInstance().handleOpenURL(url,fromApplication:sourceApplication)
DeviceInformationController
ReplaceMDMInformationControllerwithDeviceInformationController
NA
Manuallyloadcommands
UseanAPIonAWControllertoforcecommandstoreloadinsteadofusingthecommandmanager.
///5.9.XImplementationAWCommandHandler.sharedHandler().loadCommands()
///SwiftversionImplementationAWController.clientInstance().loadCommands()
Appendix:UIWindowSceneDelegateFeatureNotSupportedTheWorkspaceONESDKforiOS(Swift)doesnotsupportUIWindowSceneDelegateintroducedinXcode11.Tomitigateorfixpossibleissues,makeafewupdatesinyourPLISTandAppDelegatemethod.
Xcode11supportsmultiplescenesinapplicationsoniPads.Awindowscenecoordinateswithitscorrespondingscenedelegate,theUIWindowsSceneDelegateobject.ThiscoordinationremovesthewindowmanagementfromtheAppDelegateandgivesittotheUIWindowSceneDelegate.ThismanagementprocessimpactsSDKscreenslikeauthenticationandenrollment.
Issuesyoucanseeinyourappincludethefollowinglist:
donotseeSDKscreensinyourSDK-builtapplication.Anappusercannotauthenticate.Ifyourappusesauthentication,theSDKdoesnotinitializeproperly,andtheappcannotcommunicatewithinternalnetworks.
Procedure1. RemovetheUIApplicationSceneManifestkeyfromthePLIST.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page63of64
2. RemoveallUISceneSessionlifecycledelegatesfromyourapplication’sdelegateobject.
funcapplication(_application:UIApplication,configurationForConnectingconnectingSceneSession:UISceneSession,options:UIScene.ConnectionOptions)->UISceneConfigurationfuncapplication(_application:UIApplication,didDiscardSceneSessionssceneSessions:Set<UISceneSession>)
3. Ifitisnotadded,addthewindowproperty‘varwindow:UIWindow?’toyourAppDelegate.
DeveloperGuide
WorkspaceONEforiOS(Swift) Page64of64
DocumentInformationRevisionHistory30jun2020 Finalfor20.6SDK.
15sep2020 Updatefor20.9SDK.
16oct2020 Updatefor20.10SDK.
LegalVMware,Inc.3401HillviewAvenuePaloAltoCA94304USATel877–486–9273Fax650–427–5001www.vmware.comCopyright©2020VMware,Inc.Allrightsreserved.ThisproductisprotectedbyU.S.andinternationalcopyrightandintellectualpropertylaws.VMwareproductsarecoveredbyoneormorepatentslistedathttps://www.vmware.com/go/patents.VMwareisaregisteredtrademarkortrademarkofVMware,Inc.anditssubsidiariesintheUnitedStatesandotherjurisdictions.Allothermarksandnamesmentionedhereinmaybetrademarksoftheirrespectivecompanies.