Manage access across the firewall via the URL Loading System. More...

#import <BlackBerryDynamics/GD/GDURLLoadingSystem.h>

Description

BlackBerry Dynamics applications can utilize the native URL Loading System to communicate with servers that are behind the enterprise firewall. Communication across the enterprise firewall utilizes the BlackBerry Dynamics proxy infrastructure, which is secure.

Access across the firewall is enabled in the URL Loading System by default, when authorization of the application succeeds. The application can subsequently disable and enable access. If the application's or the user's authorization is withdrawn, access is implicitly disabled for the duration of the withdrawal.

Access across the firewall utilizes the BlackBerry Dynamics proxy infrastructure. The BlackBerry Dynamics SDK includes a class that interfaces with the infrastructure. The interfacing class is also compatible to be registered as a URL handler in the URL Loading System. Enabling and disabling access across the firewall actually registers and de-registers the interfacing class. This means that, when access is disabled, the default URL Loading System handlers will service any URL requests.

Note that synchronous request calls shouldn't be made from the main application thread.

When access is enabled, the normal URL Loading System classes can be used to communicate with servers that are behind the firewall, using standard Internet protocols. For an overview, see the URL Session Programming Guide on the apple.com developer website.

Note the following details.

Only the HTTP and HTTPS schemes are ever handled by the BlackBerry Dynamics runtime. FTP and other schemes are never handled, and hence cannot be used to access resources that are behind the enterprise firewall.
Enterprise servers that are not listed in the management console cannot be accessed, unless they are accessible from the Internet.
Authorization credentials are supported with the following notes.
NSURLAuthenticationMethodHTTPBasic is supported.
NSURLAuthenticationMethodDefault is treated as NSURLAuthenticationMethodHTTPBasic.
NSURLAuthenticationMethodHTTPDigest is supported.
NSURLAuthenticationMethodNTLM is supported, specifically: NTLMv1, NTLMv2, and NTLM2 Session.
NSURLAuthenticationMethodNegotiate is supported for Kerberos version 5.
When Kerberos authentication is in use, note the following.
- Credentials are initially taken in the same way as other credentials, with the same specified persistence.
- The credentials will be a username in the form user@realm, and a password.
- The credentials are used to request Kerberos tickets, which are stored.
- The stored Kerberos tickets are then used to authenticate the user on any site that supports Kerberos authentication. So long as the ticket continues to be accepted, there is no need for credentials to be supplied again, and no authentication challenge.
- This continues until a site does not accept the stored ticket (e.g. the ticket has expired and cannot be renewed).
- The Kerberos realm must be accessible. Usually, this means that the Kerberos realm must be listed as an Additional Server in the enterprise management console. See System administration tasks.
- Kerberos delegation can be allowed or disallowed. See GDCacheController::kerberosAllowDelegation:.
Authorization credentials are persisted as per the NSURLCredentialPersistence flag of NSURLCredential:
NSURLCredentialPersistenceNone credential is used for this connection only
NSURLCredentialPersistenceForSession credential is persisted in memory
NSURLCredentialPersistencePermanent treated as NSURLCredentialPersistenceForSession
The BlackBerry Dynamics secure store is utilized, as follows.
- Browser cookies are persisted in the secure store. See HTTP Cookie Handling below.
- The default store is not used to cache retrieved files. Instead, a separate secure cache is used.
- Kerberos tickets are persisted in the secure store.
General access to these secure stores by the application is not supported, but see GDCacheController.
Data communication does not go via the proxy specified in the native settings of the device or computer, if any.
The value YES is assumed for the setAllowsCellularAccess flag. See the NSMutableURLRequest class reference on the apple.com developer website for details of this flag.

Additional features are made available, using the NSMutableURLRequest(GDNET) category, and the NSURLCache(GDURLCache) subclass.

See also: GDiOS, for BlackBerry Dynamics authorization; Background Execution; Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.; System administration tasks.; GDNetUtility; NSURLSession Support

Multiple Authentication Methods

An HTTP server may support multiple authentication methods. For example, a server could support both NTLM and Kerberos authentication. By default, the BlackBerry Dynamics runtime handles this by selecting the first authentication method presented.

The application can implement its own handling for multiple authentication methods, as follows.

Deprecated:: The GDRejectAuthSupport key in Info.plist is deprecated and will be removed in a future release. It is no longer required.

Add a new row to the application's Info.plist file:
- Key: GDRejectAuthSupport
- Type: Boolean
- Value: YES
(In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The setting just made should appear there.)
Implement a connection::willSendRequestForAuthenticationChallenge callback.
In the application code for the callback, call the rejectProtectionSpaceAndContinueWithChallenge function, where necessary.

The following code snippet illustrates a simple implementation of the callback mentioned in the above.

- (void)connection:
    (NSURLConnection *)connection
willSendRequestForAuthenticationChallenge:
    (NSURLAuthenticationChallenge *)challenge
{
    if(
        [[challenge protectionSpace] authenticationMethod] !=
        NSURLAuthenticationMethodNTLM
    ) {
        // Reject anything that is not NTLM, i.e. reject Negotiate.
        [[challenge sender]
            rejectProtectionSpaceAndContinueWithChallenge:challenge];
    }
    else {
        NSURLCredential* cred =
            [NSURLCredentialcredentialWithUser:@"abc"
                                      password:@"abc"
                                   persistence:NSURLCredentialPersistenceForSession];
 
        [[challenge sender] useCredential:cred
               forAuthenticationChallenge:challenge];
    }
}

See also: NSURLConnectionDelegate protocol reference on the apple.com developer website.

HTTP Cookie Handling

By default, HTTP cookies received through BlackBerry Dynamics secure communication are handled automatically:

Set-cookie: headers that are received as part of an HTTP response are processed and then added to subsequent matching requests.
Persistent cookies are written to cookie storage in the BlackBerry Dynamics secure store.

The BlackBerry Dynamics cookie store persists between executions of the application, and if the mobile device is switched off. The contents of the store can be managed with the native NSHTTPCookieStorage programming interface, and so can non-persistent cookies received through BlackBerry Dynamics secure communication.

Automatic handling of HTTP cookies received through BlackBerry Dynamics secure communication can be switched off, as follows.

For communication that goes via the GDURLLoadingSystem, such as NSURLSession and NSURLConnection, call the setHTTPShouldHandleCookies: method of the associated NSMutableURLRequest instance.

See also: NSHttpCookieStorage class reference on the apple.com developer website.; NSMutableURLRequest class reference on the apple.com developer website.

Class Methods
(void)	+ enableSecureCommunication
	Enable access across the enterprise firewall via the URL Loading System. More...

(void)	+ disableSecureCommunication
	Disable access across the enterprise firewall via the URL Loading System. More...

(BOOL)	+ isSecureCommunicationEnabled
	Check whether access across the enterprise firewall via the URL Loading System is enabled. More...

(Class)	+ getProtocolClass
	Custom protocol class. More...

Properties
BOOL	supportWKWebView
	Configure WKWebView instances for BlackBerry Dynamics (class property). More...

Method Documentation

◆ enableSecureCommunication

+ (void) enableSecureCommunication

Call this function to enable, or re-enable access across the enterprise firewall via the URL Loading System.

Access across the enterprise firewall is provided by the BlackBerry Dynamics proxy infrastructure. Only servers that have been specifically listed in the enterprise management console are accessible. See System administration tasks.

Access is enabled by default during authorization processing, which is initiated by the authorize (GDiOS) function. The enableSecureCommunication function need only be called if access was disabled after authorization, see the disableSecureCommunication function, below.

◆ disableSecureCommunication

+ (void) disableSecureCommunication

Call this function to disable access across the enterprise firewall via the URL Loading System.

Access can be re-enabled using the enableSecureCommunication function. Access will also be re-enabled during authorization processing, which is initiated by the authorize (GDiOS) function.

Calling this function has no impact on access across the firewall using GDHttpRequest (deprecated).

◆ isSecureCommunicationEnabled

+ (BOOL) isSecureCommunicationEnabled

Call this function to check whether access across the enterprise firewall via the URL Loading System is enabled.

Returns: YES if access is enabled.; NO otherwise.

See also: + enableSecureCommunication; + disableSecureCommunication

◆ getProtocolClass

+ (Class) getProtocolClass

This function returns an object that is suitable to be included in an NSURLSessionConfiguration protocolClasses list.

Note that isn't generally necessary for the application code to manipulate the protocol classes list in a session configuration. This is because the BlackBerry Dynamics runtime configures the list automatically. This function is provided for completeness.

Returns: Class object.

Property Documentation

◆ supportWKWebView

- (BOOL) supportWKWebView

readwritenonatomicassign

The BlackBerry Dynamics runtime checks this property when the application code creates a WKWebView instance.

If YES, the new instance will be configured for BlackBerry Dynamics support. HTTP requests made from the instance may utilize the BlackBerry Dynamics proxy infrastructure. The instance will use the BlackBerry Dynamics secure store to cache data.
If NO, the new instance won't be configured for BlackBerry Dynamics.

The runtime sets this property to YES when authorization processing completes with success. Set this property, if required, before creating a WKWebView instance.

Setting this property doesn't change the configuration of WKWebView instances that are already running.

This is a class property.

The documentation for this class was generated from the following file:

GDURLLoadingSystem.h