How to perform integrated authentication with the iOS SDK

Integrated Authentication is an 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 tunneling 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 websites, such as content repositories (Sharepoint) or wikis.

 

Once Integrated Authentication is enabled in the default application settings or a custom SDK profile in your AirWatch Admin 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 AirWatch 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:

 

Method

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

 

Description: Checks if the AirWatch 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?: 

Basic
NTLM
Client Certificate

3. Does the SDK have a set of credentials to respond with?:

Certificate
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.

 

Method:

(BOOL)handleChallenge:(NSURLAuthenticationChallenge*)challenge

  

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.

 

Method

-(BOOL)handleChallengeForURLSessionChallenge:
(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential
*credential))completionHandler;

 

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.

 

Method:

 -(void)fetchNewCertificatesWithError:(NSError**)error

 

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

Methods:

  • 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 *)
      challenge{
            NSError*error;
           
            if([[AWController clientInstance]
canHandleProtectionSpace:challenge.protectionSpace withError:&error]){
                 
                  if([[AWController clientInstance]
handleChallenge:challenge]){
                        NSLog(@"Challenge handled successfully");
                  }else{
                        NSLog(@"Challenge could not be handled");
                  }
            }else{
// 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]
      updateUserCredentialsWithCompletion:
^(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 AirWatch Login prompt to appear to allow users to enter their credentials.

Have more questions? Submit a request

0 Comments

Article is closed for comments.