BlackBerry Dynamics
Runtime library for macOS applications
from the application developer portal
Static Public Member Functions

GDURLLoadingSystem Class Reference

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

#import <GDURLLoadingSystem.h>

List of all members.

Static Public Member Functions

Detailed 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 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 for application developers.
    • 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 developer website for details of this flag.

Additional features are made available, using the NSURLCache(GDURLCache) subclass.

See also:
GDMac, for BlackBerry Dynamics authorization
Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.
System administration tasks for application developers.
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.

  1. 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.)
  2. Implement a connection::willSendRequestForAuthenticationChallenge callback.
  3. 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
     (NSURLAuthenticationChallenge *)challenge
         [[challenge protectionSpace] authenticationMethod] !=
     ) {
         // Reject anything that is not NTLM, i.e. reject Negotiate.
         [[challenge sender]
     else {
         NSURLCredential* cred =

         [[challenge sender] useCredential:cred
See also:
NSURLConnectionDelegate protocol reference on the developer website.

Member Function Documentation

+ (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 for application developers.

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

+ (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 (GDMac) function.

+ (BOOL) isSecureCommunicationEnabled

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

YES if access is enabled.
NO otherwise.
See also:
+ enableSecureCommunication
+ disableSecureCommunication
+ (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.

Class object.

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