Microsoft Tunnel for MAM iOS SDK developer guide (2023)

Article
01/27/2023
9 minutes to read

The Microsoft Tunnel for MAM iOS SDK developer guide is a resource for developers. It helps developers integrate and configure the SDK into an iOS/iPadOS app. For an overview of the Microsoft Tunnel for MAM, go to Microsoft Tunnel for MAM for iOS/iPadOS - Intune admin guide.

This guide covers different parts of the integration process in your Xcode app project, including installing the frameworks, configuring the info.plist file, build settings, key sharing, and implementing the SDK's delegate methods.

These components are critical in the development of an iOS/iPadOS app. Developers must understand how to navigate and configure the SDK components. If you're new to Xcode and iOS/iPadOS app development, then this guide can help. It provides an overview of where to find the different SDK components and how to use these elements in your app projects.

This feature applies to:

iOS/iPadOS

What's in the SDK Repository

The SDK repository includes the following frameworks. You'll add these frameworks to your app project in a later step:

crypto.xcframework
MCPCommon.xcframework
MCPCore.xcframework
MCPPluginUnencryptedFile.xcframework
MicrosoftTunnelApi.xcframework
MSTAPNextPluginSecurityOpenssl.xcframework
MSTAPNextPluginSwiftSupport.xcframework
MSTAPNextPluginVpnMicrosoftTunnel.xcframework
ssl.xcframework

Prerequisites

To use the Microsoft Tunnel for MAM iOS SDK, the following prerequisites are required:

A macOS computer with Xcode 14.0 or newer installed
Your line of business (LOB) iOS/iPadOS app must be targeted for iOS/iPadOS 14.0 or newer.
There are two GitHub SDKs you need to download and integrate with your iOS app in Xcode. Make sure the following projects build successfully before you continue with the Microsoft Tunnel for MAM iOS SDK:
1. Intune App SDK for iOS (opens a GitHub site): At a minimum, install the 16.1.1 version.
  At this site, also review the Microsoft License Terms Intune App SDK for iOS file.
  For your records, keep a copy of the license terms. By downloading and using the Microsoft Tunnel for MAM iOS SDK, you agree to the license terms. If you don't accept the license terms, then don't use the software.
2. Microsoft Authentication Library (MSAL) (opens a GitHub site): At a minimum, install the 1.2.3 version.
Install and set up the Microsoft Tunnel for MAM iOS SDK (public preview) (opens a GitHub site). This SDK is the focus of this article.
Important
Intune regularly releases updates to the Microsoft Tunnel for MAM iOS SDK. Regularly, check the Microsoft Tunnel for MAM iOS SDK for updates. Add these updates into your software development release cycle. You want to make sure your apps support the Microsoft Tunnel Gateway updates and feature enhancements.

How the Microsoft Tunnel for MAM iOS SDK works

The Tunnel for MAM iOS SDK enables iOS/iPadOS apps to establish an "in-app" VPN connection. The VPN connection only exists within the app.

To summarize, these in-app VPN connections are:

Discrete, not device-level VPN connections
Scoped only to the application network layer

When an app makes a network call, the SDK intercepts the network call and establishes the VPN connection. This in-app VPN connection isn't shown in the Settings app on the iOS/iPadOS device.

Architecture: Tunnel for MAM iOS SDK

The following image describes the flow from a managed app that's successfully integrated with Tunnel for MAM iOS SDK:

Upon initial launch of the app, a connection is made using the Microsoft Tunnel for MAM SDK for iOS.
The tunnel gets a device authentication token from Azure AD.
See Also
Use Microsoft Tunnel VPN with iOS/iPad devices that don't enroll with Microsoft Intune CreateSSH - Free Premium Xray Shadowsocks gRPC France 3 Days
If the device signed in to another MAM enabled app, such as Outlook, Edge, or Microsoft 365 mobile app, then the device may already have an Azure AD authentication token. If a valid authentication token already exists, then the existing token is used.
A TCP Connect happens, which is a TLS Handshake between the token and the tunnel server.
If UDP is enabled on the Microsoft Tunnel Gateway, then a data-channel connection using DTLS is made. If UDP is disabled, then TCP establishes the data channel to Tunnel gateway.
For more information, go to the TCP and UDP notes in the Microsoft Tunnel overview - architecture.
When the mobile app makes a connection to an on-premises corporate resource:
1. A Microsoft Tunnel for MAM API requests to connect to the company resource.
2. An encrypted web request is created and sent to the corporate resource.

Xcode Tasks

This section lists and describes the Xcode tasks you must complete, including:

Add the frameworks and libraries
Review and update the following features:
- info.plist file
- Build settings
- Keychain sharing
Use the samples to update the Xcode AppDelegate project and add a Microsoft Tunnel delegate file

Step 1 - Add the frameworks and libraries

The following frameworks include the necessary APIs and delegate methods for communicating with the Intune Microsoft Tunnel Gateway. They implement the Microsoft Tunnel VPN features within the app.

To enable the Tunnel for MAM iOS SDK, use the following steps:

Download and extract the Tunnel for MAM iOS SDK to a folder on a macOS computer. This task is also listed in the Prerequisites.
Copy the following nine frameworks to the Xcode app project frameworks folder:
- crypto.xcframework
- MCPCommon.xcframework
- MCPCore.xcframework
- MCPPluginUnencryptedFile.xcframework
- MicrosoftTunnelApi.xcframework
- MSTAPNextPluginSecurityOpenssl.xcframework
- MSTAPNextPluginSwiftSupport.xcframework
- MSTAPNextPluginVpnMicrosoftTunnel.xcframework
- ssl.xcframework
In the Xcode project, select your app project > Add files. In the following example, files are added to an app project called “Flash Chat”:
In PROJECT > TARGETS, select Build Phases > Embed Frameworks. Add (+) all nine frameworks:
The following example shows all nine frameworks added:
In PROJECT > TARGETS, select Build Phases > Link Binary with Libraries. In the list, only the MicrosoftTunnelApi.xcframework framework should be added. If other frameworks are listed, remove them using the minus (-):

Step 2 - Update the `info.plist` file

In the info.plist for the Xcode app project, confirm the following settings:

Bundle ID: Make sure the same Bundle ID listed in the Azure AD App registration for the iOS mobile app is the same Bundle ID in your app project:
To check the Bundle ID:
1. Go to PROJECT > TARGETS > General.
2. Select Identity > Bundle Identifier:
URL Types: In PROJECT > TARGETS, select Info.
In URL Types, confirm the $(PRODUCT_BUNDLE_IDENTIFIER) variable is there. When you integrated the Intune App SDK for iOS with your app project (a required prerequisite), this variable should have been created.
If the variable isn't there, then you need to add it:
1. Using the Intune App SDK for iOS (a required prerequisite), create an info.plist Array property and name it Queried URL Schemes.
  Add the string items listed in the Intune App SDK for iOS developer guide – Step 5. This step creates the Intune MAM SDK URL schemes.
  The following example shows the info.plist using Queried URL Schemes:
2. Add the $(PRODUCT_BUNDLE_IDENTIFIER) variable.
  The following example shows the $(PRODUCT_BUNDLE_IDENTIFIER) variable in URL Types:
IntuneMAMSettings: Confirm the following MSAL settings are configured with the appropriate Azure AD app registration values:
1. Go to PROJECT > TARGETS > Info.
2. Select IntuneMAMSettings. Confirm your settings:
  - ADALAuthority: Enter the Azure AD tenant ID, like https://login.microsoftonline.com/USE_YOUR_ Directory (tenant) ID.
  - ADALClientId: Enter the application client ID.
  - ADALRedirectUri: Enter msauth.$(PRODUCT_BUNDLE_IDENTIFIER):/auth.
When you integrated the Intune App SDK for iOS with your app project (a required prerequisite), these settings should have been configured.
If these settings aren't configured, then you need to configure them. To create the IntuneMAMSettings info.plist Dictionary property and associated Microsoft Authentication Library strings, follow the Intune App SDK for iOS (a required prerequisite) developer guide at Configure MSAL settings for Intune App SDK guidance.
The following example shows these values configured:

Step 3 - Turn off Bitcode

Go to PROJECT > TARGETS > Build settings.
Select Build options > Enable Bitcode.
Select No.

Step 4 - Add keychain sharing

Keychain sharing may or not be present in the app project. If it's not there, add it:

Go to PROJECT > TARGETS > Signing & Capabilities.
Select Keychain sharing.
In the Keychain Groups list, add (+) com.microsoft.workplacejoin.

Step 5 - Integrate the SDK with your app

✔️ Use the TunnelMAMTestApp2.xcproject sample app.

Depending on the LOB app and its implementation/intended purpose, the use of the MicrosoftTunnelApi may vary. There are some core functionalities to know as you're integrating the SDK with your app:

All interactions with the Microsoft Tunnel for MAM iOS SDK are handled through a MicrosoftTunnelAPI singleton object.
The MicrosoftTunnelAPI object interacts with the app using a delegate that implements a MicrosoftTunnelDelegate interface.

To understand how to write the Microsoft Tunnel delegate and how to initialize the MicrosoftTunnelAPI, use the Microsoft Tunnel for MAM iOS SDK sample apps (opens a GitHub site).

In the sample apps, the Xcode project AppDelegate shows:

How to handle MSAL URL callbacks
How to start the enrollment and initialization process required for Tunnel

To get started, open the TunnelMAMTestApp2.xcproject sample app, and look at the AppDelegate & MicrosoftTunnelDelegate in the app project.

Sample apps

✔️ Download at Microsoft Tunnel for MAM iOS SDK sample apps (opens a GitHub site).

These sample apps can help you get started and cover different scenarios.

MicrosoftTunnelAPI methods

The MicrosoftTunnelAPI includes the following methods:

Initialize – Checks and sets the VPN configurations, sets up logging, and sets up the MicrosoftTunnelAPI instance.
Connect – Gets the MicrosoftTunnelAPI instance and enables network traffic interception. If the API is uninitialized, an error is shown.
Disconnect - Gets the MicrosoftTunnelAPI instance and disables network traffic interception. If the API is uninitialized, an error is shown.
onTokenRequired – Optional. If your app already integrates with either IntuneMAM or MSAL, you'll need to implement this onTokenRequired method. This method uses the IntuneMAMSettings and MSAL to get a valid authentication token to connect to the Microsoft Tunnel Gateway.
Logging – There are some different logging classes, denoted by k. For example, kLoggingClassConnect creates logging output in the Xcode console. These logging config keys can be added to the delegate config. There are some examples of these logging classes in the sample apps.
- kLoggingClassInternal
- kLoggingClassConnect
- kLoggingClassPacket
- kLoggingClassSocket
- kLoggingClassHttp
- kLoggingClassIntune
- kLoggingClassMobileAccess
- kLoggingSeverityDebug
- kLoggingSeverityInfo
- kLoggingSeverityWarn
- kLoggingSeverityMinor
- kLoggingSeverityMajor
- kLoggingSeverityCrit

Warning

Don't use debug keys in deployed apps. The keys can log and show user identifiable information and security data.

Logging on iOS/iPadOS LOB apps

Integrating the SDK doesn't automatically enable logging. The developer must add the appropriate code to implement the logging delegate framework and make the appropriate logging calls. The specific implementation varies depending on the SDK and the developer's requirements.

The developer should:

Make sure they don't include any customer identifiable or end-user personal data in their logging. They must comply with privacy regulations.
Consult and work with the organization's company/organization privacy team. The privacy team can provide guidance on the appropriate data that can be logged and the appropriate ways of handling sensitive data.