AppTunnel diagnostic API details

The AppTunnel diagnostic API provides troubleshooting information for an app’s use of AppTunnel with HTTP/S tunneling. Typically, you add a user interface, such as a menu item, to invoke a diagnostic run for tunneling to a specified URL. Your app then displays or logs the results of the diagnostic run. The MobileIron server administrator uses the results to troubleshoot AppTunnel configuration for the app.

NOTE: An AppTunnel diagnostic API is also available for Xamarin projects. See "How to include the Xamarin C# binding in your Xamarin project" in Developing AppConnect Apps with Xamarin .

The AppTunnel diagnostic API provides the following AppTunnel information:

• Whether the device received any AppTunnel rules
• Whether the URL requested matched an AppTunnel rule
• Whether a valid pinned Standalone Sentry server certificate is available for tunneling. This is the certificate that devices use to know that the Sentry used for AppTunnel is a trusted server.
• Whether a valid client identity is available. This client identity is used to authenticate the app to the Sentry.
• Whether the Sentry is reachable
• The HTTP/S status code returned from the backend server
• Whether AppTunnel is blocked
• Whether the device received data from the backend server
• Whether the backend server redirected the URL request
• Whether the backend server issued an authentication challenge

The API is defined in the Networking category of the AppConnect interface, in the header file AppConnect+Networking.h.

Running an AppTunnel diagnostic

To run an AppTunnel diagnostic, use the following method:

-(NSInteger)diagnoseTunnelingForURL:(NSURL *)url
              resultHandler:(void (^)(ACTunnelingDiagnosticResult *result,
                                      NSInteger runID)) resultHandler;

The method -diagnoseTunnelingForURL:resultHandler: makes successive calls to the resulthandler block as it progresses through the diagnostic run for the specified URL. Each call to the resulthandler block contains information about processing the URL for tunneling. When the diagnostic run is complete, -diagnoseTunnelingForURL:resultHandler: makes a final call to the resulthandler block, passing it nil for the result.

IMPORTANT: The URL request must have no side effects, such as modifying data on the server. This requirement is because if the URL request is successful, the destination server receives the request, but your app does not receive the response.

For example, the following code snippets (one for Objective-C and one for Swift):

• Passes a URL from a text field.
• Passes an in-line block to log the results of the diagnostic run.

Objective-C example

[[AppConnect sharedInstance] diagnoseTunnelingForURL:
	        [NSURL URLWithString:self.urlField.text]
                resultHandler:^(ACTunnelingDiagnosticResult *result, NSInteger runID) {
                                               
         if (result) {
                NSLog(@"Diagnostic run %I result %@: %@", runID, 
                            result.successful?@"Success":@"FAILURE", 
                            result.resultDescription);
         } else {
                NSLog(@"Diagnostic run %@I ended", runID);
         }
 }];

Swift example

AppConnect.sharedInstance()?.diagnoseTunneling (
	for: URL(string: self.urlField.text)!, 
	     resultHandler: { (result, runID) in
 
		if (nil != result) {
 
			print("Diagnostic run \(runID) result \(result!.isSuccessful ? "Success" :
				"FAILURE"):  \(result!.description)")
        	}
		else {
			print("Diagnostic run \(runID) ended")
		}
 	}
    )
}

For more information, continue to:

• -diagnoseTunnelingForURL:resultHandler: parameters
• -diagnoseTunnelingForURL:resultHandler: return value
• The result handler for diagnostic runs
• The ACTunnelingDiagnosticResult class
• The ACTunnelingDiagnosticResultCode enumeration
• AppTunnel configuration troubleshooting checklist for MobileIron Core

-diagnoseTunnelingForURL:resultHandler: parameters

The following table describes the parameters that you pass to
-diagnoseTunnelingForURL:resultHandler:.

 

Table 1. Parameters passed to -diagnoseTunnelingForURL:resultHandler

Parameter

Description

url

An NSURL object specifying the URL to diagnose.

resultHandler

A callback block that you define. It is called successive times with each result as the diagnostic run progresses.

-diagnoseTunnelingForURL:resultHandler: return value

The method -diagnoseTunnelingForURL:resultHandler: returns an NSInteger value. The value is the same as the value of the runID parameter returned to the resulthandler block. The runID is a unique number assigned by each diagnostic run. The runID parameter is useful for distinguishing different runs of the AppTunnel diagnostic.

For each call to -diagnoseTunnelingForURL:resultHandler:, you pass:

• a URL
• a resulthandler block

The runID associates the results passed back in the resulthandler block with the URL being diagnosed.

The result handler for diagnostic runs

In the resulthandler block, put the logic to handle the successive results of a diagnostic run. For example, log the values of the properties of the result parameter.

The resulthandler block has the following parameters:

 

Table 2. resultHandler block parameters

Parameter

Description

result

An ACTunnelingDiagnosticResult object returned with each callback to the result handler.

When the diagnostic run is complete, -diagnoseTunnelingForURL:resultHandler: makes a final call to the resulthandler block, passing it nil for the result.

runID

A variable to contain the ID that associates the returned result with a URL. The runID is a unique number assigned by each diagnostic run. The runID parameter is useful for distinguishing different runs of the AppTunnel diagnostic.

For each call to -diagnoseTunnelingForURL:resultHandler:, you pass:

• a URL
• a resulthandler block

 

The runID associates the results passed back in the resulthandler block with the URL being diagnosed.

The ACTunnelingDiagnosticResult class

The ACTunnelingDiagnosticResult class represents one of the results of a diagnostic run. The result handler receives an instance of the ACTunnelingDiagnosticResult class.

The object has these properties:

 

Table 3. ACTunnelingDiagnosticResult properties

Property

Description

resultCode

A ACTunnelingDiagnosticResultCode value.

successful

YES if the result was successful. Otherwise, NO.

timestamp

An NSDate object containing the timestamp for when the result occurred.

resultDescription

A description of the result.

Important: These descriptions are for readability only, and possibly will change in future releases. Do not depend on these strings for programmatic decisions. Use the resultCode.

The ACTunnelingDiagnosticResultCode enumeration

The ACTunnelingDiagnosticResultCode enumeration values are returned in each result of a diagnostic run. Not all values are returned with each run, and some values can be returned more than once in each run. For example, if a URL request is redirected more than once, ACTDR_REDIRECT is returned more than once.

The enumeration values fall into these categories:

 

Table 4. ACTunnelingDiagnosticResultCode enumeration values

Category

Description

Diagnostic run life cycle codes

Status of diagnostic run’s progress.

Policy integrity codes

Information about the AppTunnel policy data for the app on the device.

Certificate challenges codes

 

Whether using the available certificates is successful.

Networking codes

 

Whether the Standalone Sentry is reachable.

Connection result codes

Information about the HTTP/S connection

The following table provides:

• the enumeration’s values
• a description of each value
• the values of the successful and resultDescription properties in the ACTunnelingDiagnosticResult object.
IMPORTANT: These resultDescription strings are for readability only, and possibly will change in future releases. Do not depend on these strings for programmatic decisions. Use the resultCode.

Table 5. ACTunnelingDiagnosticResult object descriptions for each result code

Value

Details

Diagnostic run life cycle codes

ACTDR_RUN_STARTED

The run started properly.

successful: Always YES.

resultDescription:

Diagnostic run started. Requesting (URL)

ACTDR_REDIRECT

The server redirected to a new URL.

successful: Always YES.

resultDescription:

Redirected by server to new URL (url)

ACTDR_COMPLETED

Indicates whether the diagnostic run completed successfully.

successful: YES if completed without an error. Otherwise NO.

resultDescription:

Session completed normally

or

Session completed with error: (error)

ACTDR_ABORT_UNSUPPORTED_AUTH

The diagnostic run ended because the server issued an authentication challenge, such as basic authentication. This challenge is normally handled by the app, so the diagnostic run cannot continue. Typically, if the diagnostic run gets to this result, AppTunnel is working.

successful: Always YES.

resultDescription:

Server issued an auth challenge type that the diagnostic does not support. Aborting the diagnostic and the auth challenge. Auth challenge type is (auth type)

Policy integrity codes, evaluating AppTunnel policy information for the app on the device

ACTDR_RULE_MATCH

Indicates whether the URL matches an AppTunnel rule. If the URL redirects, another result with this code is returned for the redirection URL.

successful: YES if matched. Otherwise NO.

resultDescription:

Request matches a tunneling rule so it will be tunneled.

or

Request does not match a tunneling rule so it will not be tunneled.

or

AppTunnel policy has no tunneling rules.

ACTDR_POLICY_SERVER_CERT

Indicates whether a valid pinned Sentry certificate is available for tunneling. This is the certificate that the AppConnect Library in the app uses to know that the Sentry used for AppTunnel is a trusted server.

Note different Sentrys can provide tunneling for different URL requests. Each Sentry has its own pinned certificate.

successful: YES if the certificate is valid. Otherwise NO.

resultDescription:

Server certificate in the AppTunnel policy is valid.

or

Server certificate in the AppTunnel policy is invalid. It may have expired.

or

No server certificate was found in the AppTunnel policy.

ACTDR_POLICY_CLIENT_IDENTITY

Indicates whether a valid client identity is available. This client identity is used to authenticate the app to the Sentry.

successful: YES if the client identity is valid. Otherwise NO.

resultDescription:

Client identity in the AppTunnel policy appears to be valid.

or

Client certificate in the AppTunnel policy is invalid. It may have expired.

or

No client identity in the AppTunnel policy.

Certificate challenges codes, indicating whether using the certificates is successful

ACTDR_SEND_CLIENT_CERT

Indicates whether the app successfully authenticated the app to the Sentry using the available client identity.

successful: YES if authentication to the Sentry succeeded. Otherwise NO.

resultDescription:

Authenticated with client identity

ACTDR_EVALUATE_SENTRY_CERT

Indicates whether the Sentry passed evaluation using the pinned Sentry certificate. This is the certificate that the AppConnect Library in the app uses to know that the Sentry used for AppTunnel is a trusted server.

successful: YES if the certificate is trusted. Otherwise NO.

resultDescription:

Server certificate passed all evaluation

or

Server certificate was not trusted. The trust result was (trust result)

Networking codes

ACTDR_DNSLOOKUP_SENTRY

Indicates whether a DNS lookup for the Sentry has succeeded.

successful: YES if the lookup succeeded. Otherwise NO.

resultDescription:

DNS resolution of the Sentry <Sentry hostname> succeeded

or

DNS resolution of the Sentry <Sentry hostname> failed

Connection result codes

ACTDR_RESPONSE

Indicates that the server returned an HTTP status code. The value of the HTTP status code is in the resultDescription.

successful: YES for HTTP status codes 1xx, 2xx, or 3xx. NO for 4xx and 5xx.

resultDescription:

Received HTTP status code (code)

or

AppTunnel is blocked.

Note The Following:  

• Some HTTP status codes are handled and consumed by iOS, and therefore do not generate a callback to the result handler.
• Blocking AppTunnel blocks access to web sites configured to use AppTunnel. The MobileIron administrator can block AppTunnel for a device through a manual action or an automatic action triggered by a security violation on the device.

ACTDR_RECEIVED_DATA

Indicates that data was received from the backend server in the HTTP/S response.

successful: Always YES.

resultDescription:

Received (bytes) bytes of data

NOTE: This result shows the bytes as they are received, not the total number of bytes.

AppTunnel configuration troubleshooting checklist for MobileIron Core

If an app is not successfully tunneling to its app server, check the following in the MobileIron Core Admin Portal:

 

Table 6. AppTunnel configuration troubleshooting checklist for MobileIron Core

Admin Portal location

Troubleshooting actions

Settings > Preferences

Under Additional Products, make sure you have enabled the appropriate features.

Make sure you have selected Enable App Tunnel for third-party and in-house apps, if you are using AppTunnel for any app besides Docs@Work.

Policies & Configs > Policies

AppConnect global policy

Check the AppConnect global policy configuration:

1. In the AppConnect field, make sure you have selected Enabled.
2. Make sure AppConnect global policy is applied to a label belonging to the device. If you are using the default AppConnect global policy, this step is not necessary.
3. If you do not create an AppConnect container policy for the app, select Authorize for Apps without an AppConnect container policy.

Settings > Sentry

Make sure the Standalone Sentry is configured with a certificate that devices use to know that the Sentry used for AppTunnel is a trusted server.

To view the Sentry certificate in the Admin Portal for MobileIron Core.

1. Go to Settings > Sentry.
2. Find the line for the appropriate Sentry.
3. Click View Certificate.

Settings > Sentry

Make sure the Standalone Sentry is configured for AppTunnel for the app:

1. Make sure Enable AppTunnel is selected.
2. In Device Authentication Configuration, make sure the correct, valid Trusted Root Certificate is uploaded.
3. In AppTunnel Configuration, make sure you have configured the Services.

Policies & Configs > Configurations

AppConnect container policy

Check the AppConnect container policy for the app. Make sure it is applied to a label belonging to the device.

You do not need an AppConnect container policy if the AppConnect global policy selects Authorize for Apps without an AppConnect container policy.

Policies & Configs > Configurations

AppConnect app configuration

Check the AppConnect app configuration for the app:

1. Make sure the AppTunnel Rules point to the intended Sentry and service.
2. For Identity Certificate, make sure you have selected the correct certificate, issued from the trusted root Certificate Authority indicated by the Trusted Root Certificate uploaded to the Sentry.
3. Make sure the certificate has not expired and that its initial validity date is in the past.
4. Make sure AppConnect app configuration is applied to a label belonging to the device.