SDK for iOS (Swift)
VMware Workspace ONE UEM
You can find the most up-to-date technical documentation on the VMware website at:
https://docs.vmware.com/
If you have comments about this documentation, submit your feedback to
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
Copyright
©
2019 VMware, Inc. All rights reserved. Copyright and trademark information.
SDK for iOS (Swift)
VMware, Inc. 2
Contents
1 Supported Components for VMware Workspace ONE SDK for iOS (Swift) 5
2 Set Up the SDK with Your App 6
Initialize the Workspace ONE SDK for iOS (Swift) 6
Configure the Info.plist 8
Required and Optional AWController Delegate Callback Methods 9
Keychain Access Group Entitlements 10
Enable Keychain Sharing for SDK-Built Applications 10
Tips to Troubleshoot Keychain Enablement 11
Cluster Session Management and Reduced Flip Behavior for SSO in the Workspace ONE SDK for
iOS (Swift) 12
Create the AWSDKDefaultSettings.plist 12
Entries to Set in the AWSDKDefaultSettings.plist 13
Test the SDK-Built App 13
SDK Stored Certificate Information 14
3 SDK Payloads Reference, Code and Console 17
Authentication Type Payload Description 20
Authentication Type and SSO Setting Behaviors 20
Prerequisites to Use SSO 21
SSO Configurations and System Login Behavior for iOS Applications 21
Integrated Authentication and the Challenge Handler 23
Requirements for Integrated Authentication 24
SCEP Support to Retrieve Certificates for Integrated Authentication 25
Methods for a Pending Status from the SCEP Certificate Authority 25
Changes to Active Directory Passwords 27
Configure VMware Tunnel for App Tunneling 28
App Tunneling Known Limitations and Other Considerations 28
Behavior of Copy and Paste for SDK-Built Applications 29
Limits of DLP Copy and Paste 29
Set Up the Bundle and PLIST for Copy and Paste 30
Behavior of the Third-Party Keyboard Restriction in the Workspace ONE SDK for iOS (Swift) 31
Use DLP to Control Links to Open in Workspace ONE Web and Workspace ONE Boxer 32
Initial Set Up of the Bundle and PLIST 32
Enable Links for Workspace ONE Web 32
Enable Links for Workspace ONE Boxer 33
Contain Data to Workspace ONE Web 33
Disable the Default Blocker Screen 34
VMware, Inc.
3
Set Up the DataSampler Module for Analytics 34
Use AnalyticsHelper 35
Use the VMware Workspace ONE SDK for iOS (Swift) Branding Payload to Add Logos and Primary
Highlight Colors 36
Beacon Data Sent Upon Application Unlock or Sent Manually 38
Certificate Pinning 39
Check the Compromised Status of Devices with Compromised Protection 39
Dynamic Compromise Detection Requirements 40
Query Devices for MDM Information with DeviceInformationController 40
Geofence Capabilities 41
SDK Logging APIs for Levels 41
SDK Logging APIs to Send to the Console 42
SDK Log Types 42
Configure Logging for the Default SDK Profile 42
Request Application Logs for SDK-Built Apps 43
Configure View Logs for Internal Applications 43
Offline Access 44
Custom Settings for the SDK 44
Encrypt Data on Devices 44
Enable and Code APNs in the Application 46
Enable APNs in the Console 48
APIs to Use Custom Certificates for Your SDK-Built Apps 49
4 Delete Workspace ONE SDK Data 52
5 VMware Workspace ONE SDK for iOS (Swift) and the Apple App Review 53
Steps to Configure App Review Mode 54
Configure an App Review Mode Testing Environment in the Workspace ONE UEM Console 54
Declare the App Review Server and Group ID in the SDK PLIST 55
Test the App Review Mode Testing Environment in the Workspace ONE UEM Console 56
Build Script Information for App Store Submission 56
6 Migrate the Objective-C Version to the Swift Version 58
Remove the Objective-C Version of the SDK 58
Add the Swift Version of the SDK 58
Component Changes in the VMware Workspace ONE SDK for iOS (Swift) 59
SDK for iOS (Swift)
VMware, Inc. 4
Supported Components for
VMware Workspace ONE SDK
for iOS (Swift) 1
The Workspace ONE SDK for iOS (Swift), is a set of tools that incorporates functionality into custom-built,
iOS applications. It enhances the security and functionality of those applications and helps save time and
money. To work, it requires specific versions of components like iOS, Xcode, and Swift.
Version of Workspace ONE SDK for iOS (Swift) and
Workspace ONE UEM Console
n Workspace ONE SDK for iOS (Swift) v19.8
n Workspace ONE UEM console v9.3+
Supported iOS Components
n Apple iOS - 9.0+
n Xcode - 10.1 and 10.2
n Swift Versions - All Swift versions included with the listed Xcode versions
Get the SDK
Download the SDK package from https://my.workspaceone.com/products/AirWatch-SDK. You must have
permissions to access this site. Speak with your Workspace ONE UEM representative for access.
Corresponding Objective-C Interfaces
The examples in this document are in Swift. See the AWController Interface file for corresponding
Objective-C Interfaces if you import the Workspace ONE SDK for iOS (Swift) into an Objective-C
application.
Objective-C Features Not Supported in the Swift Version
The Workspace ONE SDK for iOS (Objective-C) supports the detection of a user change on shared
devices. The Workspace ONE SDK for iOS (Swift) does not support this feature.
VMware, Inc.
5
Set Up the SDK with Your App 2
Set up your application and the SDK and test the setup. Perform setup steps in order to reduce issues
with integration.
Procedure
1 Initialize the Workspace ONE SDK for iOS (Swift) by adding code to import the SDK and to run the
correct protocol.
2 Register a callback scheme and configure the Configure the Info.plist.
3 Set Required and Optional AWController Delegate Callback Methods callback methods.
4 Set Keychain Access Group Entitlements to allow applications to share a single sign on session and
to share data.
n Use keychain access groups to share data between applications in the group.
n Enable keychain sharing for SDK-built applications that already share the same
AppIdentifierPrefix and the same keychain access group.
5 Configure an Create the AWSDKDefaultSettings.plist to customize the application with Workspace
ONE SDK for iOS (Swift) features.
6 Test the SDK-Built App the integration of your application with the Workspace ONE SDK for iOS
(Swift), including the delivery of profiles from the Workspace ONE UEM console to your application.
Initialize the Workspace ONE SDK for iOS (Swift)
Import the SDK and define initial values so that the SDK-built app can start, connect, and communicate
successful start up or start up errors.
Procedure
1 Unzip the Workspace ONE SDK DMG file.
2 Drag and drop the DMG framework file and the attached AWCMWrapper file into your Embedded
Binaries, which is on the General tab of your project settings.
If you add the framework files to only the Link Binary with Libraries, the application crashes. When
you add it to the Embedded Binaries, this action automatically adds the file to the Link Binary with
Libraries, too.
3 Register your callback scheme.
4 Import the Workspace ONE SDK module.
VMware, Inc.
6
5 Make your AppDelegate conform to the AWControllerDelegate protocol.
import AWSDK
class AppDelegate: UIResponder, UIApplicationDelegate, AWControllerDelegate {
6 In the AppDelegate, add the following code to initialize and start the SDK.
Do not call the start method in applicationWillEnterForeground or applicationDidBecomeActive.
These start methods result in inconsistent UI behavior.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
[UIApplicationLaunchOptionsKey: Any]?) -> Bool {
let awcontroller = AWController.clientInstance() awcontroller.callbackScheme = "myCallbackScheme"
awcontroller.delegate = self
awcontroller.start()
return true
}
7 In the AppDelegate, implement the listed method and code to enable the SDK to receive and handle
communication from other Workspace ONE UEM applications.
func application(_ application: UIApplication, open url: URL, options:
[UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
// `AWController.handleOpenURL` method will reconnect the SDK back to its previous state to
continue.
// If you are handling application specific URL schemes. Please make sure that the URL is not
intended for SDK Controller.
// An example way to perform this.
let sourceApplication: String? = options[UIApplicationOpenURLOptionsKey.sourceApplication]
let handedBySDKController = AWController.clientInstance().handleOpenURL(url,
fromApplication: sourceApplication) if handedBySDKController {
AWLogInfo("Handed over open URL to AWController")
// SDK Controller will continue with the result from Open URL.
return true
}
// Handle if this URL is for the Application.
return false
}
SDK for iOS (Swift)
VMware, Inc. 7
8 Implement the required delegate method controllerDidFinishInitialCheck.
func controllerDidFinishInitialCheck(error: NSError?) {
if error != nil {
AWLogError("Initial Check Done Error: \(error)")
return
}
AWLogInfo("SDK Initial Check Done!")
}
What to do next
You can add optional delegate methods that are described in Required and Optional AWController
Delegate Callback Methods .
Configure the Info.plist
Register a callback scheme for the Workspace ONE SDK for iOS (Swift) and configure the info.plist file to
receive a callback from the Workspace ONE Intelligent Hub for iOS or Workspace ONE.
Prerequisites
Do the steps in Initialize the Workspace ONE SDK for iOS (Swift).
Procedure
1 In Xcode, navigate to Supporting Files.
2 Select the file <YourAppName> > -Info.plist.
3 Navigate to the URL Types section.
If it does not exist, add it at the Information Property List root node of the PLIST.
4 Expand the URL Types section and add a URL Schemes entry.
5 Enter the desired callback scheme in the URL Schemes field.
6 Whitelist all Workspace ONE UEM anchor application schemes under the
LSApplicationQueriesSchemes entry in the Information Property List.
LSApplicationQueriesSchemes Array Item
Item 0 String airwatch
Item 1 String AWSSOBroker2
Item 2 String awws1enroll
7 If this application scans QR codes with the device camera, add permissions for
NSCameraUsageDescription.
Provide a description that devices prompt users to allow the application to enable this feature.
SDK for iOS (Swift)
VMware, Inc. 8
8 If this application uses FaceID, add permissions for NSFaceIDUsageDescription.
Provide a description that devices prompt users to allow the application to enable this feature.
Consider controlling the message users read. If you do not include a description, the iOS system
prompts users with native messages that might not align with the capabilities of the application.
Required and Optional AWController Delegate Callback
Methods
Ensure that you added the required initial-check method during initialization and use optional delegate
callback methods that are part of the AWController.
Table 2-1. Required Delegate Methods
Delegate Method Description
controllerDidFinishInitialCheck(Error error: NSError?) Called once the SDK finishes its setup.
Table 2-2. Optional Delegate Methods
Delegate Method Description
receivedProfiles(_ profiles: NSArray) Called when the configurations profiles are received from the
Workspace ONE UEM console.
AWController or the parameter in this callback can now access
the configurations profiles.
wipe() Called when the SDK has wiped all of its data.
The application wipes any of its application specific data.
lock() Called when the SDK has locked, user will need to unlock with
username/password, passcode, touch-id in order to access
application.
unlock() Called when the SDK has been unlocked by some form of
acceptable authentication (username/password, passcode,
touch-id).
stopNetworkActivity(_ networkActivityStatus:
NetworkActivityStatus)
Called to alert the application to stop its network activity due to
some restriction set by the admin's policies such as cellular data
connection disabled while roaming, if airplane mode is switched
on, SSID does not match what is on console, proxy failed, etc.
resumeNetworkActivity() Called to alert the application to resume its network activity
because it is now fine to do so based on the device's current
connectivity status and policies set by administrator.
userChanged() Called when the currently logged in user has changed to alert
the application of the change.
didReceiveEnrollmentStatus(_ enrollmentStatus:
EnrollmentStatus)
Called when the SDK has received the enrollment status of this
device from console. The application can now query the SDK for
the enrollment status using the DeviceInformationController
class after this point or use the EnrollmentStatus parameter
given in this delegate call.
SDK for iOS (Swift)
VMware, Inc. 9
Keychain Access Group Entitlements
Decide whether to enable or disable keychain sharing depending on what behavior you want to use in the
app. If you enable sharing, use the correct format so the system signs the app with the entitlement and so
apps can share data.
Enable or Disable Keychain Sharing
Enable keychain sharing entitlements to sign applications with a keychain access group.
Disable keychain sharing to not share data and to sign the application with another string.
Format of Entitlements
The format for keychain access group entitlements is \accessGroupName. The group names are defined
in a list and multiple applications have the same AppIdentifierPrefix to share data.
The AppIdentifierPrefix string associates to the bundle ID of the application. For applications to
share data, the applications in the group must share the same keychain access group. You create the
bundle ID in the Apple Developer portal and you associate the bundle ID with a prefix or group.
For information on keychain items and sharing on the Apple Developer site article Sharing Access to
Keychain Items Among a Collection of Apps at https://developer.apple.com/documentation/security/
keychain_services/keychain_items/sharing_access_to_keychain_items_among_a_collection_of_apps as
of December of 2018.
Table 2-3. Keychain Setting Decides what String Signs the App
Keychain sharing
enabled Application signed with the listed string
Yes With group names as AirWatchSDKTestAppAccessGroup1 and AirWatchSDKTestAppAccessGroup2,
the system signs the application with the prefix string.
n FZJQX8D5U8.AirWatchSDKTestAppGroup1
n FZJQX8D5U8.AirWatchSDKTestAppGroup2
No The system signs the application with the bundle ID.
FZJQX8D5U8.com.MyCompany.AirWatchSDKTestApp
For more information on the SDK and keychain enablement, see Tips to Troubleshoot Keychain
Enablement . For the procedure to enable keychain sharing for applications with the same prefix and
keychain access groups, see Enable Keychain Sharing for SDK-Built Applications.
Enable Keychain Sharing for SDK-Built Applications
Enable keychain sharing for SDK-built applications that already share the same AppIdentifierPrefix and
the same keychain access group so these apps can share data.
Procedure
1 In Xcode, select your application’s target and go to Capabilities.
2 Go to Keychain Sharing and turn it on.
SDK for iOS (Swift)
VMware, Inc. 10
3 Select the plus icon (+) and name the group as awsdk.
4 Drag the new access group to the top of the Keychain Groups list.
Tips to Troubleshoot Keychain Enablement
Keychain sharing does not work if it is not enabled, if the applications in a keychain access group do not
have the same AppIdentifierPrefix, or if the applications are in different groups.
Disabled Keychain Sharing
Problem - The SDK cannot initialize because the keychain-saves cannot happen.
Solution - Enable keychain sharing by signing the application with the keychain access group.
Dierent AppIdentifierPrefix
Problem - Applications in a keychain access group cannot share passcodes or data if they have different
prefixes. The system treats the different prefixes as separate clusters.
Solution - Edit the prefixes for applicable applications on the Apple Developer portal. However, before you
change prefixes, ensure you do not need the data stored with the older prefix. This older data is lost when
the prefix changes.
Dierent Keychain Access Groups
Problem - Applications with the same prefix cannot share passcodes or data if they are in different
keychain access groups. The system treats the different groups as separate clusters.
Solution - Ensure that the applicable keychain access groups have enabled keychain sharing.
Merging applications from different groups that use the same account and service names can result in
data collisions. Check for the listed situations to prevent collisions.
n The kSecAttrAccessGroup attribute is one of the required attribute that can uniquely identify the
item stored or retrieved from the keychain.
n All other attributes, for example kSecAttrAccount and kSecAttrService, that uniquely identify the
item stored and retrieved are the same.
n The kSecAttrAccessGroup attribute is not specified in the actual query to store and retrieve from the
keychain.
More Information
For information on how to sign the application for keychain sharing, see Keychain Access Group
Entitlements. For the procedure to enable keychain sharing for applications with the same prefix and
keychain access groups, see Enable Keychain Sharing for SDK-Built Applications.
See Apple documentation for more information on entitlements and keychains at the listed sites (as of
March 2018).
n https://developer.apple.com/library/content/technotes/tn2415/_index.html
SDK for iOS (Swift)
VMware, Inc. 11
n https://developer.apple.com/library/content/documentation/Security/Conceptual/
keychainServConcepts/02concepts/concepts.html
Cluster Session Management and Reduced Flip Behavior for SSO
in the Workspace ONE SDK for iOS (Swift)
An application built with Swift that uses the SDK does only flips to retrieve account information. It does
not flip to the anchor application to retrieve data, like environment information, and to lock and unlock
operations.
In the Workspace ONE SDK for iOS (Objective-C), applications needed to flip to the anchor application to
retrieve environment information, account details, and to perform all lock and unlock operations.
Cluster Session Management Explanation
The Workspace ONE SDK for iOS (Swift) includes a mechanism that uses the shared keychain for SDK
apps to communicate with other SDK apps on the device. This approach provides benefits from both
security and user experience perspectives.
SDK applications built by the same developer account and that are also in the same keychain group or
“cluster” can now share an app passcode and an SSO session without requiring a flip to the Workspace
ONE Intelligent Hub, Container, or Workspace ONE every time authentication is required.
However, applications on the same device built by different keychain groups cannot take advantage of
this passcode sharing capability. There are some scenarios that still require a flip to the Workspace ONE
Intelligent Hub or anchor app to obtain the server URL and other setup information. This particular flip
should only occur once per cluster of applications.
Create the AWSDKDefaultSettings.plist
Create a PLIST entitled AWSDKDefaultSettings so you can add SDK features to your application. You
use this PLIST to enable or disable many features that pertain to iOS or the Workspace ONE SDK.
To see what features are set in the AWSDKDefaultSettings.plist, see Chapter 3 SDK Payloads Reference,
Code and Console .
Procedure
1 In your Xcode project, create a bundle named AWSDKDefaults.
If iOS does not offer a non-unit testing bundle, add a macOS bundle and modify its build setting as an
iOS compatible. To do this, modify the BaseSDK to iOS.
2 Add the bundle to the Bundle Resources of your application.
3 Create a PLIST named AWSDKDefaultSettings.plist and put it in the AWSDKDefaults bundle.
What to do next
Review the default entries available to add to the PLIST file. See Entries to Set in the
AWSDKDefaultSettings.plist.
SDK for iOS (Swift)
VMware, Inc. 12
Entries to Set in the AWSDKDefaultSettings.plist
Use entries in the AWSDKDefaultSettings.plist to customize the application with Workspace ONE SDK for
iOS (Swift) features. Many of these entries require you to configure their counterparts in the SDK default
settings and policies section of the Workspace ONE UEM console.
Branding, Available Entries
Use the available entries, with the following structure, to add functionality to the application.
n Root (Dictionary)
n Branding (Dictionary)
• Colors (Dictionary)
• EnableBranding (Boolean = YES)
• PrimaryHighlight (Dictionary)
n Red (Number = 238)
n Green (Number = 139)
n Blue (Number = 48)
n Alpha (Number = 255)
• AppLogo_1x (String = logoFileName)
• AppLogo_2x (String = logoFileName)
• SplashLogo_1x (String = splashLogoFileName)
• SplashLogo_2x (String = splashLogoFileName)
QR Scan
Include NSCameraUsageDescription in the application info.plist file to enable the SDK to scan QR
codes with the device camera.
Provide a description that devices prompt users to allow the application to enable this feature.
FaceID
Include NSFaceIDUsageDescription in the application info.plist file to enable the SDK to use FaceID.
Provide a description that devices prompt users to allow the application to enable this feature. Consider
controlling the message users read. If you do not include a description, the iOS system prompts users
with native messages that might not align with the capabilities of the application.
Test the SDK-Built App
Test the integration of your application with the Workspace ONE SDK for iOS (Swift), including the
delivery of profiles from the Workspace ONE UEM console to your application.
SDK for iOS (Swift)
VMware, Inc. 13
Initialize the SDK in your application to set communication with the Workspace ONE UEM server and to
test the application.
Procedure
1 Enroll your test devices to the Workspace ONE UEM console to enable communication between
them.
The SDK does not currently support testing in a simulator.
2 Upload the SDK-built app or a placeholder application that has the same bundle ID as the testing
application.
a Create an empty application with the bundle ID of the testing-application to identify the
application.
b Upload the empty application to the console and assign a default or custom SDK profile to it.
3 Assign an SDK profile to the application.
If you do not assign a profile, the SDK does not initialize correctly.
This step enables the console to send commands to the application with the record.
4 Push the application to test devices. Save the application and assign it using the flexible deployment
feature.
Use devices for testing that are Workspace ONE UEM managed devices.
You do not have to repush the application every time you make a change.
Flexible deployment rules push the application to test devices with the app catalog.
5 Run your application in Xcode.
The console pushes the initialization data to the application when the application installs on test devices.
What to do next
After the application initializes, you can run the application as many times as you want to debug it.
SDK Stored Certificate Information
To troubleshoot your SDK-built application, use an AWController API to find and display the Workspace
ONE SDK stored certificate information. The API supports numerous certificate types and certificate
attributes to query.
SDK for iOS (Swift)
VMware, Inc. 14
API Example
Note Calling this API without waiting until the SDK calls initialcheckDone(_:) always fails with the
error InvalidOperation.ContainerLocked.
AWController.clientInstance().retrieveStoredCertificates { certificateMap, error) in
if let integratedAuthCert = certificateMap[CertificateUsageKey.identity].first {
let issuer: String? = integratedAuthCert.value(forCertificateAttribute: CertificateInfoKey.issuer)
let certOCSPRespondersList: [String]? = integratedAuthCert.value(forCertificateAttribute:
CertificateInfoKey.ocspResponderList)
...
}
if let magCert = certificateMap[CertificateUsageKey.magSigning].first {
let validFrom: Date? = magCert.value(forCertificateAttribute: CertificateInfoKey.startDate)
let validUntil: Date? = magCert.value(forCertificateAttribute: CertificateInfoKey.endDate)
...
}
}
Supported Certificate Types
// Following Are the Supported Certificate Types.
public class CertificateUsageKey: NSObject {
/// Certificate of this usage are used as identity for Integrated Authentication
public static let identity: String = "com.vmware.certificate.integrated-auth"
/// Certificate of this usage are used for signing requests for MAG Proxy
public static let magSigning: String = "com.vmware.certificate.mag-signing"
}
Supported Certificate Attributes to Query
///
/// Use these strings as keys for retrieving attributes and raw data of certificates
/// from AWController.storedCertificates() API
@objc(AWCertificateInfoKey)
public class CertificateInfoKey: NSObject {
/// Raw Certificate data in DER format
public static let rawCertificate: String = "exportCertificateData"
/// Return type of value - String?
public static let subjectName: String = "subjectName"
/// Return type of value - String?
public static let subjectUserID: String = "subjectUserID"
/// Return type of value - String?
public static let subjectIdentifier: String = "subjectIdentifier"
/// Return type of value - String?
public static let emailAddress: String = "emailAddress"
SDK for iOS (Swift)
VMware, Inc. 15
/// Return type of value - Data?
public static let serialNumber: String = "serialNumber"
/// Return type of value - String?
public static let commonName: String = "commonName"
/// Return type of value - String?
public static let issuer: String = "issuer"
/// Return type of value - String?
public static let algorithm: String = "algorithm"
/// Return type of value - Date?
public static let startDate: String = "startDate"
/// Return type of value - Date?
public static let endDate: String = "endDate"
/// Return type of value - String?
public static let subjectAlternativeName: String = "subjectAlternativeName"
/// Return type of value - String?
public static let keyUsage: String = "keyUsage"
/// Return type of value - String?
public static let extendedKeyUsage: String = "extendedKeyUsage"
/// Return type of value - String?
public static let universalPrincipalName: String = "universalPrincipalName"
/// Return type of value - [String]?
public static let ocspResponderList: String = "ocspResponderList"
}
SDK for iOS (Swift)
VMware, Inc. 16
SDK Payloads Reference, Code
and Console 3
Some features, also called payloads, require extra code in the application, entries in config files, and
settings in the console to work. Others only require, extra code, config entries, or a console setting.
Table 3-1. Workspace ONE SDK for iOS (Swift) Payloads and Needed Configurations
SDK Capability Add Code or Config Entries (Beyond AWController) Set in the Console
Force Token For App
Authentication
No Yes
Enable
This setting controls how the system allows
users to access SDK-built applications, either
initially or through a forgot- passcode
procedure. When enabled, the system forces
the user to generate an application token
through the Self- Service Portal (SSP) and
does not allow user name and password.
Authentication Yes Yes
n Enable
n Set a type.
SSO Yes
Enable keychain sharing.
Yes
Enable
Integrated
authentication
Yes
Use the challenge handler.
Yes
n Enable
n Enter allowed sites.
n Set an authentication option.
App tunnel proxy No Yes
n Enable
n Select a mode.
n Configure the proxy components of
the VMware Tunnel.
n If not using VMware Tunnel, ensure
the integration of the selected proxy
with your Workspace ONE UEM
deployment.
Data loss prevention
(DLP)
Yes
n Set the AWSDKDefault bundle and the
AWSDKDefaultSettings.plist.
n To use the third-party keyboards feature, implement
the shouldAllowExtensionPointIdentifier API in the
UIApplicationDelegate.
Yes
n Enable
n Set the supported restriction.
VMware, Inc. 17
Table 3-1. Workspace ONE SDK for iOS (Swift) Payloads and Needed Configurations
(continued)
SDK Capability Add Code or Config Entries (Beyond AWController) Set in the Console
Analytics Yes
n Set the AWDataSampler.
n Set the AnalyticsHelper.
n Decide to use the SDK or the Workspace ONE
Intelligent Hub for telecom data.
Yes
n Enable
n If the setting is Do Not Disturb, set
privacy.
Branding Yes
Add values to the AWSDKDefaultSettings.plist.
Yes
n Enable
n Set colors.
n Upload images.
Sample data and
MDM information
Yes
n Use the beacon.
The SDK sends the beacon but you can manually
send the beacon when desired.
n Query the DeviceInformationController singleton class.
No
Compromised
protection
No
Use code to check the status of devices with the
application.
Yes
Enable
Dynamic
Compromise
Detection
No
Have the app consume the supported SDK version.
No
Ensure that devices can access specified
URLs for rule updates.
Custom settings Yes
Use the AWCustomPayload object.
Yes
n Enable
n Enter code.
Geofencing No
Devices must use location services and have GPS.
Yes
n Enable
n Set the area.
Logging Yes
Add APIs for logging. See the sample applications for
examples.
Yes
n Enable
n Set the level.
n Set wi-fi.
Offline access No Yes
n Enable
n Set time allowed to be offline.
Encryption Yes
Use methods in the AWController to encrypt and decrypt
data.
No
However, the strength of the encryption
depends on the authentication method set in
the Workspace ONE UEM console.
SDK for iOS (Swift)
VMware, Inc. 18
Table 3-1. Workspace ONE SDK for iOS (Swift) Payloads and Needed Configurations
(continued)
SDK Capability Add Code or Config Entries (Beyond AWController) Set in the Console
SDK App
Compliance >
Application Version
No
Use the latest SDK frameworks.
Yes
n Enable
n Add the application identifier.
n Select an operator.
n Enter the applicable application version.
The console blocks non-compliant devices.
SDK App
Compliance >OS
Version
No
Use the latest SDK frameworks.
Yes
n Enable
n Select an operator.
n Select the OS version.
n Select an action. The console supports
the block and wipe actions.
Apple Push
Notifications
Yes
Add methods to AppDelegate.swift.
Yes
n Enable APNs in the app.
n Upload the production APNs certificates.
Certificates and
Credentials Payloads
Yes
Use APIs to fetch certificates, authenticate, and validate
the server trust.
Yes
Admin configures and adds certificates to the
console with an SDK profile.
This chapter includes the following topics:
n Authentication Type Payload Description
n Prerequisites to Use SSO
n Integrated Authentication and the Challenge Handler
n Changes to Active Directory Passwords
n Configure VMware Tunnel for App Tunneling
n Behavior of Copy and Paste for SDK-Built Applications
n Limits of DLP Copy and Paste
n Set Up the Bundle and PLIST for Copy and Paste
n Behavior of the Third-Party Keyboard Restriction in the Workspace ONE SDK for iOS (Swift)
n Use DLP to Control Links to Open in Workspace ONE Web and Workspace ONE Boxer
n Set Up the DataSampler Module for Analytics
n Use the VMware Workspace ONE SDK for iOS (Swift) Branding Payload to Add Logos and Primary
Highlight Colors
n Beacon Data Sent Upon Application Unlock or Sent Manually
n Certificate Pinning
SDK for iOS (Swift)
VMware, Inc. 19
n Check the Compromised Status of Devices with Compromised Protection
n Dynamic Compromise Detection Requirements
n Query Devices for MDM Information with DeviceInformationController
n Geofence Capabilities
n SDK Logging APIs for Levels
n Offline Access
n Custom Settings for the SDK
n Encrypt Data on Devices
n Enable and Code APNs in the Application
n APIs to Use Custom Certificates for Your SDK-Built Apps
Authentication Type Payload Description
Set access to your application with the authentication type paload. Use a local passcode, Workspace
ONE UEM credentials, or require no authentication.
Select an authentication type in the Workspace ONE UEM console and use the provided SDK helper
classes in your application.
Setting Description
Passcode Designates a local passcode requirement for the application.
Device users set their passcode on devices at the application level when they first access the
application.
Username and
Password
Requires users to authenticate to the application with their Workspace ONE UEM credentials.
Disabled Requires no authentication to access the application.
Authentication Type and SSO Setting Behaviors
You can use keychain sharing, the authentication type, and the single sign-on (SSO) option to make
access to your application persistent.
Keychain Access Group Required
You must have a shared space, a keychain access group, so that applications signed in the correct format
can share keychain entries. See Keychain Access Group Entitlements for information on the signing
format. See Tips to Troubleshoot Keychain Enablement for common issues with keychain sharing.
Enable Authentication Type and SSO
If you enable both authentication type and SSO, then users enter either their passcode or credentials
once. They do not have to reenter them until the SSO session ends.
SDK for iOS (Swift)
VMware, Inc. 20
Enable Authentication Type Without SSO
If you enable an authentication type without SSO, then users must enter a separate passcode or
credentials for each individual application.
Prerequisites to Use SSO
Workspace ONE UEM allows access to iOS applications with single sign on, however. To use SSO, set
console, application, and anchor application components and query the SSO status.
SSO Components
n Enable the SSO setting in the SDK default settings and policies in the Workspace ONE UEM console.
n Initialize the SDK in the AppDelegate.
n Ensure an anchor application is on devices like the Workspace ONE Intelligent Hub or Workspace
ONE. The anchor application deployment is part of the Workspace ONE UEM mobile device
management system.
Query the Current SSO Status
To query the SSO status of the iOS application, wait for the controllerDidFinishInitialCheck method to
finish. Look in the DeviceInformationController class for the ssoStatus property. If the
controllerDidFinishInitialCheck method is not finished, the SSO status returns as SSO disabled.
SSO Configurations and System Login Behavior for iOS
Applications
Workspace ONE UEM allows access to iOS applications with single sign on enabled in two phases.
Workspace ONE UEM checks the identity of the application user and then it secures access to the
application.
Application Access With SSO Enabled
The authentication process to an application with Workspace ONE UEM SSO enabled includes two
phases: accessing the app and securing persistent access.
1 Identify user for app access - The first phase ensures that the user's credentials are valid. The system
identifies the user first by silent login. If the silent login process fails, then the system uses a
configured, authentication system. Workspace ONE UEM supports username and password, token,
and SAML.
2 Secure persistent app access - The second phase grants the user access to the application and
keeps the session live with a recurring authentication process. Workspace ONE UEM supports
passcode, username and password, and no authentication (disabled).
SDK for iOS (Swift)
VMware, Inc. 21
Authentication Behavior By SSO Configuration
The SSO configuration controls the login behavior users experience when they access applications. The
authentication setting and the SSO setting affect the experience of accessing the application.
Table 3-2. Login Behavior for Users when Passcode is Set for SSO
Authentication Phase SSO Enabled SSO Disabled
Identify n Silent login: The system registers
credentials with the managed token
for MDM.
If silent login fails, the system moves
to the next identification process.
n Authenticate: The system identifies
credentials against a common
authentication system (username
and password, token, and SAML).
n Silent login: The system registers
credentials with the managed token
for MDM.
If silent login fails, the system moves
to the next identification process.
n Authenticate: The system identifies
credentials against a common
authentication system (username and
password, token, and SAML).
Secure n Prompt if passcode exists: The
system does not prompt for the
passcode if the session instance is
live.
n Prompt if passcode does not exist:
The system prompts users to create
a passcode.
n Session shared: The system shares
the session instance across
applications configured with
Workspace ONE UEM SSO
enabled.
n Prompt if passcode exists: The
system prompts users the application
passcodes.
n Prompt if passcode does not exist:
The system prompts users to create a
passcode.
n Session not shared: The system does
not share the session or the passcode
with other applications.
Table 3-3. Login Behavior for Users when Username and Password is Set for SSO
Authentication Phase SSO Enabled SSO Disabled
Identify n Silent login: The system registers
credentials with the managed token
for MDM.
If silent login fails, the system moves
to the next identification process.
n Authenticate: The system identifies
credentials against a common
authentication system (username
and password, token, and SAML).
n Silent login: The system registers
credentials with the managed token
for MDM.
If silent login fails, the system moves
to the next identification process.
n Authenticate: The system prompts for
application login credentials.
Secure n Prompt: The system does not
prompt for the login credentials if the
session instance is live.
n Session shared: The system shares
the session instance across
applications configured with
Workspace ONE UEM SSO
enabled.
n Prompt: The system prompts for the
login credentials for the application on
every access attempt.
n Session not shared: The system does
not share the session with other
applications.
SDK for iOS (Swift)
VMware, Inc. 22
Table 3-4. Login Behavior for Users when Disabled is Set for SSO
Authentication phase SSO enabled SSO disabled
Identify n Silent login: The system registers
credentials with the managed token
for MDM.
If silent login fails, the system moves
to the next identification process.
n Authenticate: The system identifies
credentials against a common
authentication system (username
and password, token, and SAML).
n Silent login: The system registers
credentials with the managed token
for MDM.
If silent login fails, the system moves
to the next identification process.
n Authenticate: The system prompts for
application login credentials.
Secure Prompt: The system does not prompt
users for authentication.
Prompt: The system does not prompt
users for authentication.
Integrated Authentication and the Challenge Handler
Use integrated authentication to pass single sign on (SSO) credentials or certificates to authenticate to
web sites like content repositories and wikis. Set the payload in the Workspace ONE UEM console and
add a list of allowed sites. Then use the challenge handler in your application to handle incoming
authentication challenges.
Challenge Handler Methods for Challenges
Find the challenge handler in the AWController class of the SDK. Inside the AWController, use the listed
methods to handle an incoming authentication challenge for connections made with NSURLConnection
and NSURLSession.
SDK for iOS (Swift)
VMware, Inc. 23
Table 3-5. Descriptions of Challenge Methods
Method Description
func canHandle(_ protectionSpace:
URLProtectionSpace, withError error: Error?)
-> Bool
Checks that the Workspace ONE SDKcan handle this type of authentication
challenge. The SDK makes several checks to determine that it can handle
challenges.
1 Is the Web site challenging for authentication on the list of allowed sites in
the SDK profile?
2 Is the challenge one of the supported types?
n Basic
n NTLM
n Client certificate
3 Does the SDK have a set of credentials to respond?
n Certificate
n User name and password
If all three of the criteria are met, then this method returns YES.
The SDK does not handle server trust, so your application must handle
NSURLAuthenticationMethodServerTrust.
func handleChallenge(forURLSessionChallenge
challenge: URLAuthenticationChallenge,
completionHandler: @escaping (_ disposition:
URLSession.AuthChallengeDisposition, _
credential: URLCredential) -> Void) -> Bool
Responds to the actual authentication challenge from a network call made
using NSURLSession.
This method is the same as the handleChallenge method, except the system
uses this method with calls made with NSURLSession. This call involves
using a completion block to handle authentication challenges.
Requirements for Integrated Authentication
For integrated authentication to work, communication between the allowed sites and the challenge
handler must use a 401 status code, specific authentication methods, and the correct credentials.
n The URL of the requested web site must match an entry in your list of Allowed Sites.
n The system must make the network call so that the process provides an
NSURLAuthenticationChallenge object.
n The web site must return a 401 status code that requests authentication with one of the listed
authentication methods.
n NSURLAuthenticationMethodBasic
n NSURLAuthenticationMethodNTLM
n NSURLAuthenticationMethodClientCertificate
n The challenge handler can only use the enrollment credentials of the user when attempting to
authenticate with a web site. If a web site requires a domain to log in, for example ACME\jdoe, and
users enrolled with a basic user name, like jdoe, then the authentication fails.
n For applications using WebView, use SDK's handleChallenge method in the URLSession's
challenge handler. Display the response on a UIWebView or a WKWebView. Do not use the SDK's
handleChallenge method directly inside WKWebView's challenge handler.
SDK for iOS (Swift)
VMware, Inc. 24
SCEP Support to Retrieve Certificates for Integrated
Authentication
The Workspace ONE SDK supports the SCEP protocol, with limitations, to retrieve certificates for
integrated authentication. To use SCEP certificates for your SDK-built application, ensure integrated
authentication is enabled and that SCEP is configured in the console as a certificate authority.
Supported SAN Information Types
The SDK fully supports the listed Subject Alternative Names (SAN) information types in certificate
attributes.
n dNSName
n ntPrincipalName
Note When you configure this information type, it displays as an entry nested under the otherName
attribute. Although otherName is not supported, ntPrincipalName is supported even as a nested entry
of otherName.
n rfc822Name
n uniformResourceIdentifier
Supported with Correct Format
The Workspace ONE SDK supports the listed SAN information types but you must use the correct format
or the SDK ignores them.
n iPAddress
n registeredID
Not Supported
The Workspace ONE SDK does not support the listed SAN information types. If you configure them, the
SCEP process fails.
n Custom
n directoryName
n ediPartyName
n GUID
n otherName
n x400Address
Methods for a Pending Status from the SCEP Certificate Authority
Use the AWController method to modify SCEP certificate fetches to account for when the SCEP
certificate authority returns a pending status for the fetch.
SDK for iOS (Swift)
VMware, Inc. 25
Pending Status of Certificate Fetches
Some configurations set the SCEP certificate authority to not issue the certificate until a request is
approved. In this scenario, the authority returns a pending status to the SDK. You can use the methods in
AWController to configure the retry logic and monitor the retry progress.
Ensure the Certificate Authority Server Handles Retry Requests
The Workspace ONE SDK retries the fetch request based on the parameters in the modified code or
using the default behavior (retries every 5 milliseconds for 10 tries). If a certificate authority server is not
configured to handle retry requests caused by the pending status, the fetch never completes.
Methods for Pending Status
Use the AWController to modify the retry timeout and maximum number of retry attempts when fetching
SCEP certificates. Also, use the SDK delegate method to notify the SDK-built application on the progress
of the pending SCEP certificate fetch.
SDK for iOS (Swift)
VMware, Inc. 26
Table 3-6. Pending Status Methods
Configuration Code Examples
Modify the retry timeout and maximum number of retry attempts. Modify the AWController.
public func setPendingCertificateRetry(timeout:
Double, maxAttempts: Int) -> Bool
Here is an example of code modifications that set the timeout
value to 10 seconds and the maximum number of retry attempts
to 8.
let success =
AWController.clientInstance.setPendingCertificat
eRetry(timeout: 10.0, maxAttempts: 8)
Note : If you do not configure the timeout and retry attempts,
then the timeout value defaults to 5 milliseconds and the
maximum number of retry attempts defaults to 10.
Use the delegate method for pending status notifications. Use a delegate method to notify about the pending status of the
fetch.
@objc(didFinishPollingForPendingCertificateIssue
d:error:)
optional public func
controllerDidFinishPollingForPendingCertificate(
certificateIssued: Bool, error: NSError?)
Here is an example of the delegate method for notification.
func
controllerDidFinishPollingForPendingCertificate(
certificateIssued: Bool, error: NSError?) {
// Application logic goes here
}
Table 3-7. Error Codes for Pending Status
Error Code Description
certificateIssuancePending The certificate is pending.
retryIntervalNotReached The timeout is not reached for retry. You can set in
setPendingCertificateRetry.
maximumAllowedAttemptsEllapsed The maximum attempts have been reached for polling. You can
set it in setPendingCertificateRetry.
Changes to Active Directory Passwords
Use an API to update the Workspace ONE SDK for iOS (Swift) credentials when there are Active
Directory password changes..
SDK for iOS (Swift)
VMware, Inc. 27
If an Active Directory (AD) password changes and becomes out of sync with the object account of the
SDK, use an API to update the SDK credentials. An example for using this API is for situations where the
password changed for access to sites controlled by integrated authentication configurations.
/// Swift
AWController.clientInstance().updateUserCredentials(with: { (success, error) in {
///insert completion handler code here
}
Find the new credentials in the SDK account object after the callback successfully returns.
Configure VMware Tunnel for App Tunneling
The proxy components of the VMware Tunnel provide a secure method for individual applications that use
the VMware Workspace ONE SDK to access corporate resources.
The Tunnel proxy component uses HTTPS tunneling to use a single port to filter traffic through an
encrypted HTTPS tunnel for connecting to internal sites such as SharePoint or a wiki. The Workspace
ONE SDK for iOS (Swift) provides app tunneling without adding code to the application. However, you
need to configure app tunneling in the Workspace ONE UEM console.
Note If users access an internal resource through a non-standard port (a port that is not port 80 or 443),
you must explicitly list the port number in the URL you enter in App Tunnel URLs. For example, if the
resource URL is data.company.com and it is accessed through port 7777, you must add
data.company.com:7777 in the App Tunnel URLs field.
Procedure
1 Navigate to Groups & Settings > All Settings > Settings & Policies > Security Policies >
AirWatch App Tunnel.
2 Enable the setting.
3 Select an app tunnel mode.
Select VMware Tunnel - Proxy if your company has this configured.
4 In the App Tunnel URLs field, enter the URLs that you do not want to tunnel.
n Enter no URLs and every URL goes through the VMware Tunnel.
n Enter one or more URLs and the system splits the traffic. This configures split tunneling. The
system does not send the URLs entered in this field through the VMware Tunnel. The system
does send all other URLs through t he VMware Tunnel.
App Tunneling Known Limitations and Other Considerations
Due to platform and other technical limitations, only network traffic made from certain network classes can
tunnel.
SDK for iOS (Swift)
VMware, Inc. 28
Table 3-8. Supported Network Classes
Network Class Supported
NSURLConnection Calls made with NSURLConnection tunnel. There is one
exception to this behavior. If calls are made synchronously on
the main thread, they do not tunnel.
NSURLSession Calls made using NSURLSession tunnel only on iOS 8+ devices
and depending on the configuration used. Default and
ephemeral configuration types tunnel. However, background
configuration types do not tunnel.
CFNetwork Most calls made using CFNetwork tunnel except for
CFSocketStream, which does not tunnel.
Table 3-9. Network Classes Not Supported
Network Class Not Supported
URLs that contain .local Requests with URLs containing .local do not tunnel.
Various Apple services on the device use this .local string
pattern. The SDK does not tunnel these requests through the
VMware Tunnel to avoid interfering with these services.
WKWebView Requests made with WKWebView do not tunnel so use
UIWebView.
Behavior of Copy and Paste for SDK-Built Applications
The copy and paste payloads, Enable Copy and Paste Out and Enable Copy and Paste Into, restrict
actions when set to No. They allow actions when set to Yes.
n Enable Copy and Paste Out - When you set Enable Copy and Paste Out to No, you can only
paste copied data from your SDK-built application out to other SDK-built applications.
n Enable Copy and Paste Into - When you set Enable Copy and Paste Into to No, you can only
paste copied data from other SDK-built applications into your SDK-built application.
Limits of DLP Copy and Paste
The copy and paste payloads for the Workspace ONE SDK for iOS (Swift) are limited by parameters, out
of process classes, SSO and DLP configurations, and keychain groups.
There are specific limitations with certain UI classes.
n UIWebView and WKWebView - You cannot copy images in DOC and PDF files loaded in UIWebView or
WKWebView due to a technical limitation.
n Out of Process Classes - The Workspace ONE SDK does not support copy-out and copy-in
restrictions in views that are out of process. For example, the feature does not work in the listed
views, and this list is not exhaustive.
n SFSafariViewController
SDK for iOS (Swift)
VMware, Inc. 29
n UIDocumentInteractionViewController
n QLPreviewController
n Other Limitations
n Two sets of SDK-built applications that have different SSO settings (for example, one is set with
SSO on and another with SSO off) cannot share the pasteboard.
n You cannot copy from an application which has no restriction (Enable Copy and Paste Out set
to Yes) and paste that content into a restricted application (Enable Copy and Paste Into set to
No).
n You cannot share a pasteboard between two or more sets of applications that are in different
keychain groups.
For example, VMware Workspace ONE productivity applications and custom SDK-built
applications cannot share the clipboard. However, multiple custom SDK-built applications from
the same developer that are in the same keychain group can share the clipboard.
Set Up the Bundle and PLIST for Copy and Paste
To control the copy and paste interaction between your SDK-built applications and non-SDK-built
applications, create a bundle and PLIST file, locally, and set the keys and values.
For details on creating the bundle and PLIST during initial setup, see Create the
AWSDKDefaultSettings.plist.
Procedure
1 Create a bundle named AWSDKDefaults if you did not create it during initial setup.
2 Create a PLIST named AWSDKDefaultSettings.plist and put it in the AWSDKDefaults bundle if you
did not do this during initial setup.
3 In the PLIST, create a Boolean named AWClipboardEnabled and set it to YES.
After you add the local flag, and your admin sets the default or custom SDK policies for these features in
the console, the SDK enforces the restriction. It enforces it across your application’s user interfaces that
use cut, copy, and paste in the listed classes and subclasses.
n UITextField
n UITextView
n UIWebView
n WKWebView
SDK for iOS (Swift)
VMware, Inc. 30
Behavior of the Third-Party Keyboard Restriction in the
Workspace ONE SDK for iOS (Swift)
Run the third-party keyboard restriction by starting the AWController and configuring the data loss
prevention setting in the Workspace ONE UEM console. This payload behaves depending on the most
restrictive setting.
Request your Workspace ONE UEM admin to configure the data loss prevention (DLP) menu item. Find
the console settings in Groups & Settings > All Settings > Apps > Settings and Policies > Security
Policies > Data Loss Prevention > Enable Third Party Keyboards.
When this feature is set to No, any third party keyboards used in the application are automatically
replaced with the native system keyboard.
SDK Behaves According to the Most Restrictive Implementation
If your application's code overrides the shouldAllowExtensionPointIdentifier delegate method, the
Workspace ONE SDK for iOS (Swift) honors the more restrictive implementation.
For example, if the SDK setting allows third party keyboards but your application forcibly returns no to
disallow custom keyboards, then custom keyboards are disallowed in the application. If the SDK setting
does not allow third party keyboards then the third party keyboard is not allowed regardless of your
applications implementation of the method.
Table 3-10. Third Party Keyboard Restriction Behavior Depends on Console Settings and
Code
Data Loss
Prevention
Setting
Enable Third Party
Keyboard Setting
Is shouldAllowExxtensionPointIdentifier
Implemented in the Application
Keyboard
Behavior
Disabled NA Implemented Third party keyboards behave depending on the
implementation of the delegate method.
Enabled Set to No. Implementation does not matter. Third party keyboards are not available.
Enabled Set to Yes. Implemented Third party keyboards are available.
Enabled Set to Yes. Implemented and returns yes. Third party keyboards are available.
Enabled Set to Yes. Implemented and returns no. Third party keyboards are not available.
Run the Application to See Expected Behaviors
When the Enable Third Party Keyboard setting is configured in the console, the SDK does not enforce
the restriction until the next time the user runs the application after the application retrieves the new SDK
profile.
SDK for iOS (Swift)
VMware, Inc. 31
Use DLP to Control Links to Open in Workspace ONE
Web and Workspace ONE Boxer
Configure applications built with the Workspace ONE SDK to open in the Workspace ONE Web and to
compose emails in Workspace ONE Boxer. This feature enables end users to use alternative systems
other than Safari and the Mail app. To develop this feature, create a bundle in your iOS application and
configure Workspace ONE UEM to enforce the behaviors in the bundle.
Configure both systems, the browser and email systems, for this feature to work. Perform the procedures
in the listed order.
1 Initial Set Up of the Bundle and PLIST.
For more information, see Initial Set Up of the Bundle and PLIST.
2 Enable Links for Workspace ONE Web.
For more information, see Enable Links for Workspace ONE Web.
3 Enable Links for Workspace ONE Boxer.
For more information, see Enable Links for Workspace ONE Boxer.
4 Contain Data to Workspace ONE Web.
For more information, see Contain Data to Workspace ONE Web.
Limitation With MFMailComposeViewController
If you use the MFMailComposeViewController scheme in your MessageUI framework, this functionality is
not supported. The system cannot specify how end users access your application when it is an
attachment in an email. End-users access the application with the Mail app and not Inbox.
SupportInformationController
The SupportInformationController class allows you to query for the email address and telephone
numbers for contacting enrollment support which you can display on the application UI.
Initial Set Up of the Bundle and PLIST
Perform these steps before you enable any links. Use this bundle and PLIST for both HTTP/HTTPS links
and MAILTO links.
Procedure
1 Create a bundle named AWSDKDefaults.
2 Create a PLIST named AWSDKDefaultSettings.plist and put it in the AWSDKDefaults bundle.
Enable Links for Workspace ONE Web
To enable the application to open HTTP / HTTPS links in the Workspace ONE Web, enable a few
dictionary and PLIST flags.
SDK for iOS (Swift)
VMware, Inc. 32
Procedure
1 Work in the AWSDKDefaults bundle.
2 Create a dictionary named AWURLSchemeConfiguration and put it in the
AWSDKDefaultSettings.plist.
3 Inside the AWURLSchemeConfiguration dictionary, create a new Boolean entry with the key name
enabled and set the Boolean value to Yes.
If you set the Boolean value to No, then the HTTP and HTTPS links open in Safari. If set to Yes, then
your SDK app opens in Workspace ONE Web.
Enable Links for Workspace ONE Boxer
To enable the application to open MAILTO links in Workspace ONE Boxer, enable a few dictionary and
PLIST flags.
Procedure
1 Work in the AWSDKDefaults bundle.
2 Create a dictionary named AWMailtoSchemeConfiguration and put it in the
AWSDKDefaultSettings.plist.
3 Configure the AWMailtoSchemeConfiguration dictionary, create a new Boolean entry with the key
name as enabled and set the Boolean value to Yes.
If you set the Boolean value as No, then MAILTO links open in the native mail. If set to Yes, then your
SDK app looks to see if you enabled data loss prevention in the SDK profile.
n DLP Enabled – The app opens in Workspace ONE Boxer.
n DLP Disabled – The app opens in the iOS Mail app.
Contain Data to Workspace ONE Web
Use the data loss prevention, DLP, settings in the Workspace ONE UEM default SDK profile to enforce
the application to use Workspace ONE Web andWorkspace ONE Boxer.
If you do not enable data loss prevention in the SDK policy, the application opens links in Safari and
composes email in the iOS Mail app.
Procedure
1 Navigate to Groups & Settings > All Settings > Apps > Settings and Policies > Security
Policies.
2 Select Enabled for Data Loss Prevention.
3 Disable the Enable Composing Email check box for the MAILTO links. If you do not disable this
option, the application opens from the Mail app and not from Inbox.
SDK for iOS (Swift)
VMware, Inc. 33
Disable the Default Blocker Screen
The Workspace ONE SDK displays a blocker screen to cover the application’s content when the
application is not active. When the app is in the foreground, the Workspace ONE SDK dismisses the
blocker screen.
You can disable this sceen and use your own custom backgroud blocker screen or use the Workspace
ONE SDK screen.
Procedure
1 Work in the AWSDKDefaults bundle.
2 Create a dictionary named AWBlockerViewEnableKey and put it in the AWSDKDefaultSettings.plist.
3 Configure the AWBlockerViewEnableKey dictionary, create a new Boolean entry with the key name
as enabled and set the Boolean value to No.
n If you set AWBlockerViewEnableKey to Nothen the Workspace ONE SDK disables the blocker
screen so that you can use your own blocker screen.
n If you set AWBlockerViewEnableKey to Yes then the Workspace ONE SDK uses its blocker
screen.
If AWBlockerViewEnableKey is empty, the Workspace ONE SDK displays its blocker screen.
Set Up the DataSampler Module for Analytics
The DataSampler module samples detailed device data and reports it back to the Workspace ONE UEM
console. Device details such as analytics, call logs, GPS location, and network adapters are all sampled
with the DataSampler.
Important For GPS sampling to function, ensure your application supports location tracking. For more
information, see Apple's documentation at https://developer.apple.com/documentation/corelocation.
The DataSampler samples and transmits on two different time intervals. Device samples remain on to the
disk and the system removes them after transmitted. This process allows the developer to sample
statistics multiple times before sending them to Workspace ONE UEM. Samples stored on the disk are
useful when a device does not have network connectivity.
AWDataSampler is a singleton object. There can only be one DataSampler for each process.
Configuration
These parameters are required to set up a DataSampler.
n sampleModules – Names the bitmask whose flags specify which modules to use.
n defaultSampleInterval – Specifies the time in seconds between DataSampler samples for all
modules by default.
SDK for iOS (Swift)
VMware, Inc. 34
n defaultTransmitInterval – Specifies the time in seconds between DataSampler transmissions
for all modules by default.
n traceLevel – Determines the error and information logging level of the DataSampler module when it
is running.
Modules Available for Sampling
These modules are available for sampling in the DataSampler.
n AWDataSamplerModuleSystem
n AWDataSamplerModuleAnalytics
n AWDataSamplerModuleGPS
n AWDataSamplerModuleNetworkData
n AWDataSamplerModuleNetworkAdapter
n AWDataSamplerModuleWLAN2Sample
Gather Telecom Data
Disable the AWDataSamplerModuleNetworkData mask if you gather telecom data using the Workspace
ONE Intelligent Hub. If you enable this mask for the SDK, then you receive duplicate data from the
Workspace ONE Intelligent Hub and from the SDK.
Set Do Not Disturb
You can use the SDK to set the do-not-disturb (DND) status on the Workspace ONE UEM server. You
must enable the DND policy in the Workspace ONE UEM console. You can find the policy at Groups &
Settings > All Settings > Devices & Users > General > Privacy > DO NOT DISTURB section.
The two relevant methods are fetchDeviceDNDStatus and setDeviceDNDStatus found in the
AWDeviceDNDStatus object.
Use AnalyticsHelper
The AnalyticsHelper is a singleton with a property and a function. Send your custom analytics event
from your application to the console with this process.
Procedure
1 Ask your admin to enable the Analytics setting in the SDK profile for the SDK-built application. This
setting is in the console at Groups & Settings > All Settings > Apps > Settings and Policies >
Settings > Analytics.
SDK for iOS (Swift)
VMware, Inc. 35
2 In the application, call the recordEvent method on the singleton after the
controllerDidFinishInitialCheck delegate callback returns.
func sendAnalytics() {
let analytics = AnalyticsHandler.sharedInstance
analytics.recordEvent(AWSDK.AnalyticsEvent.customEvent, eventName: "EVENT_NAME",
eventValue: "EVENT_VALUE", valueType: AWSDK.AnalyticsEventValueType.string)
}
After the system records the event, it saves the event in the SDK container for two hours. After the two
hours passes, the SDK sends analytics recorded to disk to the console the application re-starts.
What to do next
Locate the data in the console in Apps & Books > Applications > Logging > SDK Analytics.
Use the VMware Workspace ONE SDK for iOS (Swift)
Branding Payload to Add Logos and Primary Highlight
Colors
Use the branding payload to add logos and primary highlights to customize the look of the application.
Branding by Organization Group
Many organizations brand applications according to the applications assigned organization group in the
Workspace ONE UEM console. This technique is useful for updating the branding payload over the air
(without having to update the application) for time-sensitive events or marketing initiatives.
Access Branding Settings in the SDK
The branding payload is available after the controllerDidReceive(profiles: [Profile]) function is
called. Within the branding payload, it is possible to view the raw values set in the console. Use the listed
API.
let brandingPayload = AWController.clientInstance().sdkProfile()?.BrandingPayload
The values in AWBranding become set after controllerDidFinishInitialCheck. If a value is not set
in the console, then the system returns nil.
Add Values to AWSDKDefaultSettings.plist
You can add a primary highlight color to brand the buttons on the authentication screen. You can also add
two company logos (AppLogo and SplashLogo) within the Branding dictionary inside your
AWSDKDefaultSettings.plist.
n AppLogo - The SDK puts the AppLogo on all of the authentication screens.
SDK for iOS (Swift)
VMware, Inc. 36
n SplashLogo - The SDK puts the SplashLogo on the loading screen and on the second application
login screen.
SDK for iOS (Swift)
VMware, Inc. 37
Table 3-11. Available Branding Entries in the AWSDKDefaultSettings.plist
Entry Type
Branding Dictionary
Colors Dictionary
PrimaryHighlight String
AppLogo_1x String
AppLogo_2x String
SplashLogo_1x String
SplashLogo_2x String
Beacon Data Sent Upon Application Unlock or Sent
Manually
The beacon is a regular update sent from the VMware Workspace ONE SDK for iOS (Swift) to the
Workspace ONE UEM console. The SDK sends this data every time it is unlocked. You can also force the
beacon when you want data.
Beacon Location Configuration
To take advantage of the location functionality of the beacon, the host application registers itself as
needing location updates in the background.
In the info.plist file, set the UIBackgroundModes array with a value configured as location.
Beacon Update Contents
The beacon update contains the listed information.
Table 3-12. Contents in the Beacon Update
Type of Information Data
General n Device name
n Organizational group
n Application bundle identifier
Platform n Device operating system (Apple, iOS)
n Device operating system version
User n User email
n User full name
n User display name
Enrollment n Device enrolled
n Device unenrolled
n Device wipe pending
Compliance n Device compliance
n Application compliance
SDK for iOS (Swift)
VMware, Inc. 38
Send the Beacon Manually
Use an API to send the beacon manually.
let beaconTransmitter = SDKBeaconTransmitter.sharedTransmitter()
//To send immediately
beaconTransmitter.sendDeviceStatusBeacon(completion: SendBeaconCompletion?)
beaconTransmitter.sendBeacon(updatedAPNSToken: String, completion: SendBeaconCompletion?)
//To start a schedule of how frequenlty to send (If given time interval is less than 60, frequency
will default to 60)
public func startSendingDeviceStatusBeacon(transmitFrequency: TimeInterval = 60)
//To stop the sending the scheduled beacon
public func stopSendingDeviceStatusBeacon()
Certificate Pinning
Use certificate pinning to help prevent man-in-the-middle (MITM) attacks by enabling an additional layer
of trust between listed hosts and devices.
Certificate pinning requires no code. Just enable SSL pinning in the Workspace ONE UEM console and
upload your certificate.
Check the Compromised Status of Devices with
Compromised Protection
Workspace ONE UEM detects jailbroken devices and can wipe compromised devices if enabled in the
Workspace ONE UEM console.
Compromised protection requires no code unless you want to manually check the status of the device.
Check Compromised Protection Status
To check the status of a device directly in your application, whether the device is online or offline, call the
isCurrentDeviceCompromised() API from the DeviceInformationController singleton class.
//Swift
let deviceInfoController = DeviceInformationController.sharedController()
let compromisedStatus = deviceInfoController.isCurrentDeviceCompromised()
if compromisedStatus == true {
AWLogDebug("My device is jailbroken!")
}
Compliance and Compromised Protection
Compromised protection is a feature that allows the developer to check the SSO status and the jailbreak
status.
SDK for iOS (Swift)
VMware, Inc. 39
You can check the compromised status of the device directly in your application by calling the
isCurrentDeviceCompromised() API from the DeviceInformationController singleton.
let deviceInfoController = DeviceInformationController.sharedController()
let compromisedStatus = deviceInfoController.isCurrentDeviceCompromised()
if compromisedStatus == true {
AWLogInfo("My device is jailbroken! Oh no!")
}
Dynamic Compromise Detection Requirements
Dynamic compromise detection for iOS sets SDK-built apps to securely update the compromise detection
algorithm over-the-air. Apps that use this feature do not need to update or re-release after compromise
detection rule updates. To configure this feature, update to the supported SDK version and ensure that
devices can access specific URLs.
To use dynamic compromise detection, update the SDK version and ensure that devices can access
specific URLs.
n The SDK-built app must consume Workspace ONE SDK for iOS (Swift) v19.2.
n To receive the latest compromise detection rules, ensure that devices can connect to the listed URLs.
n api.na1.region.data.vmwservices.com
n discovery.awmdm.com
n signing.awmdm.com
If devices cannot access these URLs, they still get compromise detection but rules only update when
the SDK-built app consumes the latest SDK. This lapse in rule updates might result in false positives.
Query Devices for MDM Information with
DeviceInformationController
Use the DeviceInformationController singleton class to query devices for mobile device management
(MDM) information.
The class returns the listed MDM information.
n Enrollment status
n Compliance status
n Managed status
n Management type
n Organizational group name
n Organizational group ID
n Device services URL
SDK for iOS (Swift)
VMware, Inc. 40
n Single sign on status
n Compromised status
Requery Method
The method queries the console, and the console sends a query command to the device to collect certain
types of device information.
Geofence Capabilities
A geofence limits the use of devices to specific areas including corporate offices, school buildings, and
retail department stores. Geofence settings are configured within the default SDK profile and do not
require code.
The feature works on devices that run location services. To turn on the location services, the device must
be connected to either a cellular network, Wi-Fi, or the device must have integrated GPS capabilities. If a
device is in "Airplane Mode," the location services are deactivated, and geofencing stops working.
SDK Logging APIs for Levels
Workspace ONE UEM groups logging messages into categories to distinguish critical issues from normal
activities.
The Workspace ONE UEM console reports the messages that match the configured logging level plus
any logs with a higher critical status. For example, if you set the logging level to Warning, messages with
a Warning and Error level display in the Workspace ONE UEM console.
The SDK-built application collects logs over time and stores them locally on the device until another API
or command is invoked to transmit the logs.
Note When an enterprise wipe occurs, the console does not purge the log files. You can retrieve logs
after a device re-enrolls to determine what issues occurred in the last enrollment session to cause the
enterprise wipe.
Table 3-13. SDK Logging Level APIs and Level Descriptions
Level Logging API Description
Error AWLogError("{log message}") Records only errors. An error displays failures in processes such as a
failure to look up UIDs or an unsupported URL.
Warning AWLogWarning("{log message}") Records errors and warnings. A warning displays a possible issue with
processes such as bad response codes and invalid token authentications.
Information AWLogInfo("{log message}") Records a significant amount of data for informational purposes. An
information logging level displays general processes, warning, and error
messages.
Debug or Verbose AWLogVerbose("{log message}") Records all data to help with troubleshooting. This option is not available
for all functions.
SDK for iOS (Swift)
VMware, Inc. 41
SDK Logging APIs to Send to the Console
Use two ways to transmist SDK logs. The developer can manually trigger the transmission of SDK logs to
the Workspace ONE UEM console with APIs. The Workspace ONE UEM admin can use the View Logs
menu item to get logs for an application.
Developer APIs
n iOS (Swift) - AWContorller
public func sendLogDataWithCompletion( completion: @escaping ( success: Bool, _ error:
NSError?) -> Void)
n iOS (Objective-C) - AWLog
- (void)sendApplicationLogsWithCompletion:(void(^)(BOOL success, NSError *error))completion;
- (BOOL)hasAWLogs;
SDK Log Types
Workspace ONE UEM displays logs for applications that report application failures and that report
application-specific data. These logs integrate with the VMware Workspace ONE SDK so that you can
manage applications built by it.
Find logs for applications in Apps & Books > Analytics > App Logs.
Setting Description
Application Logs This type of log captures information about an application. You set the log level in the default SDK profiles
section, Groups & Settings > All Settings > Apps > Settings and Policies > Settings > Logging. You must
add code into the application to upload these logs to the Workspace ONE UEM console.
Crash Logs This type of log captures data from an application the next time the application runs after it crashes. These logs
are automatically collected and uploaded to the Workspace ONE UEM console without the need for extra code in
the SDK application.
Configure Logging for the Default SDK Profile
Use Logging so the system records data for applications the use the VMware Workspace ONE SDK
framework.
The Workspace ONE UEM system collects logs until the log file size reaches 200 MB for SaaS
environments. If the log size exceeds 200 MB, the system stops collecting logs. The Workspace ONE
UEM console notifies you when your application log size reaches 75% of 200 MB. To act on the
application log size, contact your Workspace ONE UEM Representative.
n Ask for an increase in your application log size.
n Ask for a purge of your application log. The system can purge logs older than two weeks.
Procedure
1 Navigate to Groups & Settings > All Settings > Apps > Settings and Policies > Settings.
SDK for iOS (Swift)
VMware, Inc. 42
2 Select Enabled for Logging.
3 Choose your Logging Level from a spectrum of recording frequency options.
4 Select Send logs over Wi-Fi only to prevent the transfer of data while roaming and to limit data
charges.
5 Save your settings.
Request Application Logs for SDK-Built Apps
Request applications logs for your SDK-built applications from the device record in the console.
Procedure
1 Navigate to Devices > List View and select the device.
2 Select the Apps tab, select the SDK-built app, and choose Request Logs.
The Request Logs button displays after you select the application.
3 Complete the settings in the Request Logs window. You can retrieve logs that are currently available
or you can select to capture a log type for a duration of time.
4 To retrieve the logs, navigate to Apps & Books > Applications > Logging > App Logs.
5 Find the log for the application with the App Name column and download the file.
Configure View Logs for Internal Applications
Use the View Logs feature to access available log files pertaining to applications that use the Workspace
ONE SDK framework. Log types include all logs, crash logs, and application logs. With this feature, you
can download or delete logs.
Filter options using the Log Type and Log Level menus so that you can find the type or amount of
information to research and troubleshoot applications that use the SDK framework.
Procedure
1 Navigate to Apps & Books > Applications > Native and select the Internal tab.
2 Select the application and then select More > View > Logs option from the actions menu.
3 Select desired options depending on if you want to act on specific devices (selected) or to act on all
devices (listed).
Setting Description
Download Selected Download selected logs with information pertaining to applications that use the
Workspace ONE SDK framework.
Download Listed Download all logs in all pages with information pertaining to applications that use
the Workspace ONE SDK framework.
SDK for iOS (Swift)
VMware, Inc. 43
Setting Description
Delete Selected Delete selected logs with information about applications that use the Workspace
ONE SDK framework.
Delete Listed Delete all logs in all pages with information about applications that use the
Workspace ONE SDK framework.
Oine Access
The offline access function allows access to the application when the device is not communicating with
the network. It also allows access to Workspace ONE UEM applications that use the SSO feature while
the device is offline.
Oine Behavior
The Workspace ONE SDK automatically parses the SDK profile and honors the offline access policy once
AWController is started. If you enable offline access and an end-user exceeds the time allowed offline,
then the SDK automatically presents a blocker view to prevent access into the application. The system
calls the lock method of the AWSDKDelegate so your application can act locally.
Custom Settings for the SDK
The VMware Workspace ONE SDK for iOS (Swift) allows you to define your own custom settings for your
application using an SDK profile.
You can paste raw text in the custom settings section, and the SDK makes this content available inside
the application using the AWCustomPayload object.
You can define an XML, JSON, key-value pairs, CSV, or plain text for your settings. Parse the raw text in
the application once it is received.
Encrypt Data on Devices
The VMware Workspace ONE SDK for iOS (Swift) offers the use of basic encrypt and decrypt methods to
operate on raw data that the system encrypts using the SDK’s internal encryption keys.
These methods are defined in the AWController.
Important Do not use these encryption methods on any mission critical data or data that you cannot
recover. Examples of unrecoverable data include no backup on a server or if the data cannot be re-
derived through other means. The encrypted key (and associated encrypted data) is lost in the event that
an end user deletes the application or if an enterprise wipe.
SDK for iOS (Swift)
VMware, Inc. 44
Prequisites
Before you call the encryption methods, ensure the AWControllerDelegate receives no errors.
n Swift -Applications must ensure that AWControllerDelegate receives the
controllerDidFinishInitialCheck(error: NSError?) callback with no errors before they call
the encryption methods.
n Objective-C - The AWControllerDelegate callback method is -
(void)initialCheckDoneWithError:(NSError * _Nullable)error;.
Encryption Strength and Authentication Mode
The strength of the encryption depends on the enabling of the authentication mode.
If you set authentication passcode or username and password, then the system derives the key used for
encryption from the passcode or username and passcode the user enters. The system keeps the key in
device volatile memory for additional security.
If you disable authentication, the system randomly generates the encryption key and persists it in device
storage.
Encrypt Data not Stored with Core Data
The Workspace ONE SDK for iOS (Swift) provides the ability to encrypt data that Core Data does not
store. These methods take in the data input and return back either the encrypted or decrypted data.
These methods are only used for the transformation of the data. The application developer is responsible
for the storage of the encrypted data.
n Encryption Method: Swif -
n public func encrypt(_ data: Data) throws -> Data
n public func decrypt(_ data: Data) throws -> Data
n Encryption Method: Objective-C
n (NSData * _Nullable)encrypt:(NSData * _Nonnull)data error:(NSError * _Nullable *
_Nullable)error SWIFT_WARN_UNUSED_RESULT;
n (NSData * _Nullable)decrypt:(NSData * _Nonnull)data error:(NSError * _Nullable *
_Nullable)error SWIFT_WARN_UNUSED_RESULT;
Error Codes Defined and Examples
The enum AWSDKCryptError defines the error codes for the error thrown by the methods.
n Encrypt
let controller = AWController.clientInstance()
let plainData: Data = .. //assign data to be encrypted
do {
let encryptedData = try controller.encrypt(plainData)
//save encryptedData for future use
SDK for iOS (Swift)
VMware, Inc. 45
//...
} catch let error {
print(" failed to encrypt data with error: \(String(describing: error))")
}
n Decrypt
let controller = AWController.clientInstance()
let encryptedData = ..//fetch data previously encrypted using Encrypt method above
do {
let decryptedData = try controller.decrypt(encryptedData)
//do something with decryptedData
//...
} catch let error {
print(" failed to encrypt data with error: \(String(describing: error))")
}
Enable and Code APNs in the Application
To use Apple push notifications in your SDK-built application and Workspace ONE UEM, enable the use
of APNs and add code to support push notifications.
Setting a token value to AWController initiates the call to the console because it sends the beacon.
Assign the token value to AWController only after the token value has changed.
Setting the token value to nil clears the token value from the console and you cannot use the token to
send push notifications.
Note The sample code is for reference and can be adjusted per the app requirements. See the sample
app for more examples of how the listed methods are used.
SDK for iOS (Swift)
VMware, Inc. 46
Procedure
1 Select Target and enable push notifications in capabilities. You see two checks in Push Notification.
2 Add import UserNotifications to the top of AppDelegate.swift.
3 Add applicable methods to the end of AppDelegate.swift.
func registerForPushNotifications() {
if #available(iOS 10.0, *){
UNUserNotificationCenter.current()
.requestAuthorization(options: [.alert, .sound, .badge] ) {
granted, error in
print(“Permission Granted\(granted)”)
guard granted else { return }
self.getNotificationSettings()
}
} else {
let notificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound],
categories: nil)
DispatchQueue.main.async {
UIApplication.shared.
registerUserNotificationSettings
(notificationSettings)
}
}
}
@available(iOS 10.0, *)
func getNotificationSettings() {
UNUserNotificationCenter.current()
.getNotificationSettings { settings in
print("Notification settings\(settings)")
guard settings.authorizationStatus ==
.authorized else { return }
SDK for iOS (Swift)
VMware, Inc. 47
DispatchQueue.main.async {
UIApplication.shared
.registerForRemoteNotifications()
}
}
}
func application(_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceTokn
deviceToken: Data) {
let tokenParts = deviceToken.map { data in
String(format: "%02.2hhx", data) }
let token = tokenParts.joined()
print("Device Token: \(token)")
let controller = AWController.clientInstance()
controller.APNSToken = token
}
func application(_ application: UIApplication,
didFailToRegisterForRemoteNotificationsWithError
error: Error) {
print("Failed to register: \(error)")
}
4 Add registerForPushNotifications() near the end of
application(_:didFinishLaunchingWithOptions:), and before return:.
Enable APNs in the Console
Use SDK-built applications to send Apple push notifications to applicable devices. Enable the SDK-built
app to use APNs.
This task assumes that the SDK-built app is already uploaded and managed in the Workspace ONE UEM
console. These apps are available in an app store and they use Production APNs certificates.
Prerequisites
Generate your production APNs certificates so you can upload the certificates to the Workspace ONE
UEM console. For details, visit the topic Registering Your App with APNs on the Apple Developer site.
Procedure
1 Navigate to Apps & Books > ApplicationsSDK-built app and choose Edit.
2 Select the Files tab and select Yes for Application Supports APNs.
3 Select Production for APNs Certificate.
4 Use Upload to add your certificates to the console as an APNs Production Certificate.
5 Select Save & Assign. Editing the assignment is optional and not necessary to finish this task. You
can Save and Publish from the assignment module.
SDK for iOS (Swift)
VMware, Inc. 48
APIs to Use Custom Certificates for Your SDK-Built Apps
The Workspace ONE SDK for iOS (Swift) has APIs to evaluate server trust and verify configured
certificates.
API to Validate Server Trust
n Declaration
func validate(serverTrust: SecTrust, trustStore: CertificatesTrustStore, strictness:
SSLTrustStrictness) -> Bool.
The admin configures trusted certificates as Credentials in the SDK profile. When the SDK starts, it
fetches custom anchors and SSL certificates configured by the admin and stores them securely as
configured.
While connecting to a network host, the app can receive a challenge. During this challenge, the app
can use an API to validate the server trust and can decide to allow or cancel the connection.
n Parameter Explanations - ServerTrust, TrustStore, and SSLTrustStrictness
n ServerTrust
Retrieve the SecTrust object from the ProtectionSpace given to the app for authentication by the
URLSession task. The API func validate(serverTrust: SecTrust, trustStore:
CertificatesTrustStore, strictness: SSLTrustStrictness) -> Bool copies the certificate
chain and policies for evaluation, so that the app can perform additional operations on the
SecTrust in its original form.
n TrustStore
The API func validate(serverTrust: SecTrust, trustStore: CertificatesTrustStore,
strictness: SSLTrustStrictness) -> Bool considers the TrustStore type while it evaluates the
ServerTrust. The API supports only deviceAndCustom and custom types for TrustStore.
If you configure the type as custom, the API uses only custom anchors or self-signed SSL
certificates (those anchors or certificates configured by the admin in a Credentials payload) to
evaluate trust. If your server uses intermediate certificate authorities, you must add the
intermediate certificate authorities in the Credentials payload.
If type is deviceAndCustom, the SDK uses system trust store combined with the configured
certificates to evaluate the ServerTrust.
Note You can use self-signed SSL certificates with or without any CA certificates by adding
them directly to the SDK Credentials payload.
n SSLTrustStrictness
SDK for iOS (Swift)
VMware, Inc. 49
The SDK uses SSLTrustStrictness to consider `recoverableTrustFailure` SecTrustResultType
as an end result, to be trusted or not trusted.
• If the value for strictness is strict, the SecTrustResultType end result is
recoverableTrustFailure and is not trusted.
• If the value for strictness is ignore, the SecTrustResultType end result is
recoverableTrustFailure and is trusted.
If the TrustStore is custom, the SDK forms a complete chain with the certificates from the
SecTrust and validates the chain. Validation is according to the policies set in the SecTrust. If
TrustStore is deviceAndCustomThe, the SDK forms the chain up to a certificate that is in the
trusted list.
n Certificates Considered for Server Trust Validation
n Root CA certificates
n Intermediate CA certificates
n SSL certificates
Upload public X509 certificates in DER or PEM format. The SDK does not consider certificates
uploaded with a private key for server trust evaluation.
API to Retrieve Configured Certificates
n Declaration
func retrieveStoredPublicCertificates(completion: (_ certificateMap: [String:
[PublicCertificate]]?, _ error: NSError?) -> Void)
n Parameter Explanation - Completion
The completion block is called with the configured certificates map. It returns an error if there is any
problem while retrieving the certificates.
The API returns a map. The keys are represented using the constants from AWCertificateUsageKey
class. Corresponding values are array of Public Certificate Objects. You can query certain x509
attributes from the PublicCertificate objects and verify the configuration.
@objc(AWCertificateUsageKey)
public class CertificateUsageKey: NSObject {
/// Certificate of Usage key to reflect Integrated Authentication
public static let integratedAuthIdentity: String
/// Certificate of Usage key to reflect Integrated Authentication
public static let uncategorizedIdentity: String
/// Certificate of this usage are used for signing requests for MAG Proxy
public static let magSigning: String
///Certificates of type SSL
public static let selfSignedSSLCerts: String
SDK for iOS (Swift)
VMware, Inc. 50
///Certificates of type Custom Anchors
public static let customTrustedAnchorCerts: String
/// SDK doesn't have specific usage for this type of certificates
public static let others: String
}
SDK for iOS (Swift)
VMware, Inc. 51
Delete Workspace ONE SDK
Data 4
Use the func destroyContainerData() method in the class WS1SDKContainerCleaner to delete
Workspace ONE SDK data from your Workspace ONE SDK-built app and apps that share the iOS
keychain with it.
Important You cannot recover data deleted by this method.
After calling the method, there is an error in SDK initialiaziation, Workspace ONE SDK for iOS (Swift)
must get restarted.
n Unsuccessful initialization results in the delegate callback func
controllerDidFinishInitialCheck(error: NSError?) getting called with a non-nil error.
n Successful initialization results in the delegate callback func
controllerDidFinishInitialCheck(error: NSError?) getting called with no error.
Quit and relaunch apps that share the iOS keychain with the SDK-built app to avoid undefined behavior.
Method Usage
let ws1SDKDataCleaner = WS1SDKContainerCleaner()
ws1SDKDataCleaner.destroyContainerData()
VMware, Inc.
52
VMware Workspace ONE SDK
for iOS (Swift) and the Apple
App Review 5
Deploy apps that use the Workspace ONE SDK for iOS (Swift) to the App Store without dependency on
other Workspace ONE UEMcomponents. The SDK includes a mode for your application for use during
the Apple App Review process.
This app review mode removes dependencies on the broker applications such as the Workspace ONE
Intelligent Hub for iOS, Container, and the Workspace ONE application. It also enables the app reviewer
to access the application without enrolling with Workspace ONE UEM.
Explanation of the Process
Build your application and incorporate the Workspace ONE SDK for iOS (Swift). Then, build a test
environment in Workspace ONE UEM and prepare the application for submission to the app review
process. For general steps in the process, see Steps to Configure App Review Mode.
Build a Test Environment in Workspace ONE UEM
Create a test environment in Workspace ONE UEM that you use only for this app review process. For
details on how to create this environment and how to upload your application to it, see Configure an App
Review Mode Testing Environment in the Workspace ONE UEM Console.
Identify the Server URL and Group ID
To help your application work for the review process without dependencies on other Workspace ONE
UEM components, follow the procedure in Declare the App Review Server and Group ID in the SDK
PLIST.
This chapter includes the following topics:
n Steps to Configure App Review Mode
n Configure an App Review Mode Testing Environment in the Workspace ONE UEM Console
n Declare the App Review Server and Group ID in the SDK PLIST
n Test the App Review Mode Testing Environment in the Workspace ONE UEM Console
n Build Script Information for App Store Submission
VMware, Inc.
53
Steps to Configure App Review Mode
Deploy apps that use the VMware Workspace ONE SDK for iOS (Swift) to the App Store without
dependency on other Workspace ONE UEM components. The SDK includes a mode for your application
for use during the Apple App Review process.
This app review mode removes dependencies on the broker applications such as the Workspace ONE
Intelligent Hub for iOS, VMware Container, and the Workspace ONE application. It also enables the app
reviewer to access the application without enrolling with Workspace ONE UEM.
Important Use this work flow only on applications built with the Workspace ONE SDK that you submit to
the App Store for review. Do not use this work flow for any other application development processes.
Also, do not use the process in a production environment. This process is only supported for use in a test
environment for applications you submit to Apple's App Review.
Procedure
1 Integrate the SDK with your application.
2 Configure the app review mode testing environment in the Workspace ONE UEM console, upload the
application IPA file, assign it an SDK profile, and deploy it to the test environment.
See Configure an App Review Mode Testing Environment in the Workspace ONE UEM Console.
3 Assign an app review mode server and a group ID to the SDK PLIST.
See Declare the App Review Server and Group ID in the SDK PLIST.
4 Test the IPA in the test environment.
See Test the App Review Mode Testing Environment in the Workspace ONE UEM Console.
5 Run the app store build script.
See Build Script Information for App Store Submission.
6 Submit your application for review to the Apple App Store ensuring to add the app review mode
server, group ID, and user credentials from the test environment to the submission.
Configure an App Review Mode Testing Environment in
the Workspace ONE UEM Console
With help from your admin, configure a testing environment in the Workspace ONE UEM console. Upload
your application to this environment so that the app reviewer can review your application without
dependencies on other Workspace ONE UEM components.
Prerequisites
n Integrate the Workspace ONE SDK for iOS (Swift) with your application.
n You need Workspace ONE UEM system admin permissions to configure these components. If you do
not have these permissions, ask your Workspace ONE UEM Admin for help.
SDK for iOS (Swift)
VMware, Inc. 54
n Ensure that you create a testing environment that hosts no production applications and components.
Use this app review mode environment only for the app review process.
n Configure all options in the app review organization group.
Procedure
1 Configure a special organization group for app review mode in the Workspace ONE UEM console.
Record the group ID for later entry to the SDK PLIST.
2 Configure an app review mode user with credentials in the Workspace ONE UEM console.
You give these credentials to the app reviewer so record the credentials.
3 Create a smart group and add the user to the group.
Workspace ONE UEM deploys applications based on assignment groups, specifically the smart
group type.
4 Configure the SDK profile.
Use the default SDK profile or a custom SDK profile. Whatever SDK profile you use, ensure that the
desired SDK features are enabled. Features to review are the Authentication Type, Single Sign On,
and the App Tunnel Mode.
5 Upload the application binary (IPA) to the internal application area or the public application area of the
Workspace ONE UEM console. Ensure that you assign the SDK profile to the application and assign
the test smart group to the application.
The bundle identifier must match the application submitted to the App Review process.
6 Disable the requirement for MDM enrollment so the app reviewer can access the application without
enrolling with MDM.
Although the setting are nested under the Content Locker, it applies to all applications. Improvements
to the user interface are planned for the future.
a Ensure you are in the app review mode organization group.
b Navigate to Groups & Settings > All Settings > Content > Applications > Content Locker.
c In the General area, disable Require MDM Enrollment.
d Select Save.
Declare the App Review Server and Group ID in the SDK
PLIST
To prepare to submit your application to the Apple App Review process, add the app review mode server
URL and the group ID. These strings allow the reviewer to review your application without the need for
other Workspace ONE UEM components.
Procedure
1 If you have not done so, in your Xcode project, create a bundle named AWSDKDefaults.
SDK for iOS (Swift)
VMware, Inc. 55
2 If the AWSDKDefaults bundle does not have a PLIST named AWSDKDefaultSettings.plist, create this
PLIST in the bundle.
3 Create a key in the PLIST with the data type string. Name this key com.vmware.air-
watch.enrollment.test-server-url.
This name is case sensitive.
4 Set the value of this key to the server URL of the Workspace ONE UEM environment you setup in
Configure an App Review Mode Testing Environment in the Workspace ONE UEM Console.
Ensure to meet these requirements for the URL.
n Include https:// before the URL.
n Ensure the URL is the exact device services server URL. Do not use the console or API server
URL.
n Do not include /deviceservices at the end of the URL. The SDK appends this automatically.
5 Create another key in the PLIST with the data type string. Name this key com.vmware.air-
watch.enrollment.test-org-group-id.
This name is case sensitive.
6 Set the value of this key to the group ID of the app review group you setup in Configure an App
Review Mode Testing Environment in the Workspace ONE UEM Console.
Test the App Review Mode Testing Environment in the
Workspace ONE UEM Console
Test that the IPA file, server URL, group ID, and user credentials work before you submit the application
for review.
Procedure
1 Attempt to run the app on a device without any previous app data.
This action ensures that stale URL and device information is not present on the device. It also
ensures there are no other Workspace ONE UEM apps on the device.
2 Enter the server URL and group ID when the app prompt for these options.
3 Enter the user credentials when prompted.
If the SDK permits you to continue without error and controllerDidFinishInitialCheck is called, the
test environment and components are successful.
Build Script Information for App Store Submission
This process requires a separate build script that you run before you submit the application for review.
SDK for iOS (Swift)
VMware, Inc. 56
Reason for the Special Script
Run the build script to strip the simulator architectures. The application fails the Apple App Review static
analysis if you do not run the script.
Access the Script
Use the script located on Stack Overflow, at https://stackoverflow.com/questions/30547283/submit-to-
app-store-issues-unsupported-architecture-x86/30866648#30866648 as of October, 2018, to strip the
non-app store related architectures from your application.
SDK for iOS (Swift)
VMware, Inc. 57
Migrate the Objective-C Version
to the Swift Version 6
To migrate to a version of the Workspace ONE SDK for iOS (Swift)Workspace ONE SDK for iOS (Swift),
remove the old SDK and add the current one to your environment.
See Component Changes in the VMware Workspace ONE SDK for iOS (Swift) for changes to make to
your project to prevent build errors.
Share Your Keychain
Share your keychain between the SDK applications so you can use all the SDK capabilities. See
Keychain Access Group Entitlements.
This chapter includes the following topics:
n Remove the Objective-C Version of the SDK
n Add the Swift Version of the SDK
n Component Changes in the VMware Workspace ONE SDK for iOS (Swift)
Remove the Objective-C Version of the SDK
Delete the listed Workspace ONE SDK for iOS (Swift)frameworks and libraries to remove the SDK.
Procedure
1 On the General tab in your project, delete the AWSDK.framework from both the Embedded
Binaries and Link Framework and Libraries areas.
2 Open the Build Phases tab in the project settings of your application.
3 Delete AWKit from your project.
4 Delete AWlocalization from your project.
Add the Swift Version of the SDK
Add Workspace ONE SDK for iOS (Swift) frameworks and edit the locations of the listed calls to migrate
SDK behaviors to the current version. If you do not edit the listed call locations, the UI behavior is
inconsistent with the previous SDK version.
VMware, Inc.
58
Procedure
1 Drag and drop the current AirWatchSDK framework and the AWCMWrapper file into your Link
Binary with Libraries step in the build phase section of your project settings.
2 Change the location of your StartSDK call. Call it in the didFinishLaunchingWithOptions method
that is inside your application delegate class.
In versions before the Workspace ONE SDK v17.x, you called awcontroller.start() within the
applicationDidBecomeActive method.
3 Build your project.
4 Resolve naming differences and API differences that changed in the new SDK causing build errors.
Component Changes in the VMware Workspace ONE SDK
for iOS (Swift)
If you migrate an older version of the SDK to install it, review the list of changed components. Update
names and locations of components to prevent or resolve build errors caused by the differences between
SDK versions.
Samples present the old version of the code followed by the current code.
SDK for iOS (Swift)
VMware, Inc. 59
Table 6-1. Workspace ONE SDK for iOS (Swift) Components with Examples of Objective-C
and Swift Code
Component Sample Code
AWController start
In the previous SDK you called
awcontroller.start() within the
applicationDidBecomeActive
method.
In the current SDK, start the SDK
within the
didFinishLaunchingWithOptions
method inside your application
delegate class.
You will get inconsistent UI
behaviors from the SDK if you do not
make this change.
///5.9.X Implementation
func applicationDidBecomeActive(_ application: UIApplication)
let awc = AWController.clientInstance()
awc.delegate = self
awc.callbackScheme = "myAppName"
awc.start()
}
///Swift version Implementation
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions:
[UIApplicationLaunchOptionsKey: Any]?) -> Bool {
let awc = AWController.clientInstance()
awc.delegate = self
awc.callbackScheme = "myAppName"
awc.start()
return true
}
CanhandleProtectionSpace
(Integrated Authentication)
Update the code for authentication
challenges and chain validation.
///5.9.X Implementation
try
AWController.clientInstance().canHandle(challenge.protectionsSpace)
///Swift version Implementation
try AWController.clientInstance().canHandle(protectionsSpace:
challenge.protectionsSpace )
AWLog singleton (Logging)
Use this instead of the AWController
to send logs.
///5.9.X Implementation
AWLog.sharedInstance().sendApplicationLogs(success, errorName)
///Swift version Implementation
AWController.clientInstance().sendLogDataWithCompletion
{ (success, error)
}
Network status
Update the front of the enum to
AWSDK.
///5.9.X Implementation
AWNetworkActivityStatus
///Swift version Implementation
AWSDK.NetworkActivityStatus
SDK for iOS (Swift)
VMware, Inc. 60
Table 6-1. Workspace ONE SDK for iOS (Swift) Components with Examples of Objective-C
and Swift Code (continued)
Component Sample Code
Profiles and profile payloads
Drop the AW from the front of
profiles.
///5.9.X Implementation
AWProfile
///Swift version Implementation
Profile
Custom settings
Access custom settings through
AWController instead of
AWCommanManager.
///5.9.X Implementation
AWCommandManager().sdkProfile().customPayload
///Swift version Implementation
AWController.clientInstance().sdkProfile()?.customPayload
Account object
The account object is now a property
on AWController instead of an
accessor method.
This property returns default, empty
values for SAML and token
enrollment.
///5.9.X Implementation
AWController.clientInstance().account()
///Swift version Implementation
AWController.clientInstance().account
User credentials
///5.9.X Implementation
AWController.clientInstance().updateUserCredentials(completions:
{ (success, error) in {
...
} )
///Swift version Implementation
AWController.clientInstance().updateUserCredentials(with:
{ (success, error) in {
...
})
OpenInURL calls
///5.9.X Implementation
AWController.clientInstance().handleOpen(url,
fromApplication: sourceApplication)
///Swift version Implementation
AWController.clientInstance().handleOpenURL(url,
fromApplication: sourceApplication)
SDK for iOS (Swift)
VMware, Inc. 61
Table 6-1. Workspace ONE SDK for iOS (Swift) Components with Examples of Objective-C
and Swift Code (continued)
Component Sample Code
DeviceInformationController
Replace
MDMInformationController with
DeviceInformationController.
NA
Manually load commands
Use an API on AWController to
force commands to reload instead of
using the command manager.
///5.9.X Implementation
AWCommandHandler.sharedHandler().loadCommands()
///Swift version Implementation
AWController.clientInstance().loadCommands()
SDK for iOS (Swift)
VMware, Inc. 62
