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 Ivanti server administrator uses the results to troubleshoot AppTunnel configuration for the app.
An AppTunnel diagnostic API is also available for .NET projects. See "How to include the .NET C# binding in your .NET project" in Developing AppConnect apps with .NET.
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 Ivanti EPMM
-diagnoseTunnelingForURL:resultHandler: parameters
The following table describes the parameters that you pass 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:
|
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:
|
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:
|
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.
|
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 Ivanti 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 This result shows the bytes as they are received, not the total number of bytes. |
AppTunnel configuration troubleshooting checklist for Ivanti EPMM
If an app is not successfully tunneling to its app server, check the following in the Ivanti EPMM Admin Portal:
|
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:
|
||||||||||||
|
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 Ivanti EPMM.
|
||||||||||||
|
Settings > Sentry |
Make sure the Standalone Sentry is configured for AppTunnel for the app:
|
||||||||||||
|
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:
|