Integrated Authentication Methods and Sample Code - iOS

Integrated Authentication is a VMware Workspace ONE SDK feature that allows the automatic passing of one’s credentials, such as a Username/Password or Certificate, to an endpoint that challenges for this authentication. By doing so, it is no longer necessary for the developer to manually handle the authentication into an endpoint. This can be used alongside tunnel proxy to access and automatically authenticate into internal endpoints.

With the iOS SDK, you can leverage the enrollment user’s Username and Password or Certificates (uploaded or via a template) to automatically authenticate into internal websites, such as content repositories (Sharepoint) etc.

Once Integrated Authentication is enabled in the default application settings or a custom SDK profile in your Workspace ONE Console, you must define a list of allowed sites, which are the only sites supported with Integrated Authentication.

On the application side, use the challenge handler component in the AWController class of the Workspace ONE SDK. Inside the AWController, use certain methods to handle an incoming authentication challenge for connections made with NSURLConnection and/or NSURLSession. Find the available methods in the following list:



(BOOL)canHandleProtectionSpace:(NSURLProtectionSpace*)protectionSpace withError:(NSError**)error

Description: Checks if the Workspace ONE SDK has the means to handle this type of authentication challenge. The SDK makes the following checks to determine if it can handle challenges:

  1. Is the website challenging for authentication on the list of allowed sites in the SDK profile?
  2. Is the challenge one of the supported types?:
    Client Certificate
  3. Does the SDK have a set of credentials to respond with?:
    Username and Password

If all 3 of the criteria are met, then this method will return YES.
Note: The SDK does not handle server trust, so your application needs to handle NSURLAuthenticationMethodServerTrust.




Description: Responds to the actual authentication challenge from a network call made using NSURLConnection.
It will return YES or NO depending on if it was able to respond to the authentication challenge.
The SDK’s canHandleProtectionSpace method in AWController should be called first to validate that the challenge is actually one that can be processed.



(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential

Description: Responds to the actual authentication challenge from a network call made using NSURLSession.
This method is the same as the handleChallenge method above, except this is used with calls made with NSURLSession. This call involves using a completion block to handle authentication challenges.




Description: Forces the SDK to fetch a new certificate.

The SDK automatically handles retrieving certificates initially during setup, after you call start in AWController. However, in the event you need to force the SDK to fetch a new certificate, use this method.
Ensure a certificate is properly configured in the Authentication and Credentials payload of the SDK profile. This method resolves issues with revoked and corrupt certificates.


Requirements for Integrated Authentication

  1. The URL of the requested website must match an entry in your list of Allowed Sites.
  2. The network call must be done to where an NSURLAuthenticationChallenge object is provided.
  3. The website must return a 401 status code requesting authentication with one of the following authentication
    • NSURLAuthenticationMethodBasic
    • NSURLAuthenticationMethodNTLM
    • NSURLAuthenticationMethodClientCertificate
  4. The challenge handler can only use the enrollment credentials of the user when attempting to authenticate with a website. If a website requires a domain, for example, ACME\jdoe, to log in, and your end user's enrolled with only a basic username, for example, jdoe, then the authentication will fail.
    Note: Content repositories use the saved enrollment credentials (which are encrypted and shared with all SSO apps). If the content repository requires a different password, the connecting app prompts the user for the password at the time of accessing the repository.

    Sample Code
    - (void)connection:(NSURLConnection *)connection 
          willSendRequestForAuthenticationChallenge:(NSURLAuthenticationChallenge *)
               if([[AWController clientInstance]
    canHandleProtectionSpace:challenge.protectionSpace withError:&error]){
                      if([[AWController clientInstance]
                            NSLog(@"Challenge handled successfully");
                            NSLog(@"Challenge could not be handled");
    // Let’s make sure that AWEnrollmentAccount returns // the user’s credentials.

    if([[AWController clientInstance] account].username == NULL){
          NSLog(“Unable to retrieve username, prompting username for updated credentials”);
    [[AWController clientInstance]
    ^(BOOL success, NSError *error){
          NSLog(@"==== Calling updateUserCredentialsWithCompletion");
          AWEnrollmentAccount *account = [[AWController clientInstance] account];
          NSString *username = account.username;
          NSString *password = account.password;
                NSLog(@"%@, %@", username, password);

The code above uses an NSURLConnection delegate method to automatically handle a 401 authentication challenge returned from an endpoint that expects a user’s enrollment credentials.

Integrated authentication requires that the AWEnrollmentAccount object not be NULL in order to automatically authenticate using enrollment credentials. If the authentication fails, check to make sure that user’s credentials are available. If the user account is NULL, prompt end user to enter credentials by calling updateUserCredentialsWithCompletion. This will allow an automatic Workspace ONE Login prompt to appear to allow users to enter their credentials.

Have more questions? Submit a request


Article is closed for comments.