How to perform Tunneling and Integrated Authentication with the Android SDK


1. In order to redirect your application's traffic to an AirWatch supported proxy such as the AirWatch Tunnel, you can use the following AirWatch networking classes:

  • AWWebView
  • AWUrlConnection
  • AWWebViewClient
  • AWHttpClient (Deprecated)

2. Each one of these classes is an extension of their respective base Android networking class (e.g. AWHTTPClient is a subclass of DefaultHttpClient). No additional logic is needed to handle the tunneling of a network request from your internal application.

3. It is recommend to extend your networking Activity class from GatewayBaseActivity class. You can override following method from GatewayBaseActivity to check for the status of proxy. proxyStatus value 3 means proxy is fully initialized and above mentioned network classes are ready to tunnel the networking traffic via AIrWatch Tunnel proxy.

public void proxyStatusUpdated(int proxyStatus) {
Logger.e(TAG,"Current proxy status is "+proxyStatus);

4. Please refer to the or classes in the sample app for examples on how to use these, or see the brief example below:


private void invokeWebView(){
AWWebView awWebView = (AWWebView) findViewById(;
private void httpUrlConnectionHandler() {

NtlmHttpURLConnection ntlmHttpURLConnection = null;
try {
// Create a trust manager that does not validate certificate chains
URL url =new URL(SITE_URL);
//decorate any httpurlconnection to get base and ntlm auth.
ntlmHttpURLConnection = new NtlmHttpURLConnection((HttpsURLConnection) AWUrlConnection.openConnection(url));
final int responseCode = ntlmHttpURLConnection.getResponseCode();
Logger.e(TAG ,"Response code is"+responseCode);

if (responseCode == HttpURLConnection.HTTP_OK){
mResponse = IOUtils.toString(ntlmHttpURLConnection.getInputStream());
} catch (Exception e) {
Logger.e(TAG, e);
}finally {


Integrated Authentication

Integrated Authentication is an SDK feature that allows the automatic passing of one’s credentials, such as a Client 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.

Android SDK supports integrated authentication for following type of authentication challenges. You can leverage SDK's integrated authentication to automatically authenticate into websites, such as content repositories (Sharepoint) or wikis:

1. Basic 


3. Certificate 

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. 

Make sure to select "use enrollment credentials" option to handle Basic/NTLM type challenge. To handle certificate based challenge, either upload the certificate or define the CA in the Credentials payload of the SDK Profile assigned to the application in the AirWatch Admin Console.

The authentication logic is handled automatically by the AirWatch classes and no additional code level changes are required. 


Handling Enrollment credential update:

1. SDK caches the enrollment username/password in a secure location and these credentials are used to handle the authentication challenge to achieve the Integrated Authentication.

2. However, developer must take care of the condition when user credentials are changed in either the Active directory or in AirWatch (for basic accounts).

3. Following is the logic to handle credential change while using various AW Networking classes:


  •  When the authentication challenge is received AWWebView will try to authenticate using the cached enrollment credentials.
  • Since enrollment credentials are updated in the backend, this will fail and a popup will appear requesting user to enter the username/password.
  • AWWebView will try to validate these credentials with your AD, if the response from the user matches the response from the AD then cached credentials will be updated. Post this AWWebView will use the updated credentials to handle the server challenge.
  • In case when user response doesn't match with the AD response while validating the cached credentials, cached credentials won't be updated but AWWebView will anyway try to handle the server challenge using the credentials entered by user.



  •  While using API(s) other then AWWebView developer must manually check for failed authentication and call the relevant API to validate and update the cached credential.
  • As an example, we have created an activity to cover this logic.
  • Please find the attached files called and update_user_credential.xml
  • To use this code snippet : 

1. Drop the Activity class under src.
2. Drop the layout xml file under layouts
3. Make sure to register the activity under the Manifest.

  • Check for your server response when AWURLConnection tries perform Integrated Auth. If a 401 is received, call UpdateUserCredentialActivity: 
  • final int responseCode = ntlmHttpURLConnection.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_UNAUTHORIZED){
    runOnUiThread(new Runnable() {
    public void run() {
    Intent intent = new Intent(YourActivity.this,UpdateUserCredentialsActivity.class);
  • UpdateUserCredentialActivity will:

1. Request User to Enter their updated credential.
2. Validate the entered credentials with your AD. (using validateCredential API)
3. If user response matches with AD response, it will update the local cached credential. (using updateEnrollmentCredential API)

  • Programmatically request user to force close and relaunch the app.
  • In next attempt Integrated Authentication using AWUrlConnection should be successful.
  • Please note that attached code is for instructional purpose only to explain the logic. Developers are expected to use the mentioned APIs and attain this same logic which caters to their specific use cases.
Have more questions? Submit a request


Article is closed for comments.