How to use single sign-on (SSO) and passcode with the AirWatch iOS SDK

In order to use the Single Sign On (SSO) feature, an SDK-enabled app must interact with the AirWatch Agent for handling authentication across multiple apps. Once initialized, the app can establish an SSO session with the Agent and delegate the handling of user authentication and SSO management to the Agent or AirWatch Container. Once a session is established in one app, all the other apps can share the same session, avoiding the need to authenticate or require a passcode for each individual app. 

The SSO functionality can also allow the application access to the AirWatch enrollment credentials for that device if necessary. When the SSO session expires, access to any SSO app requires the user to enter a passcode or username and password (depending on the authentication security policies set) and reinitialize the SSO session. The default settings or SDK profile also defines the maximum number of failed attempts. If the user exceeds this number, the session expires and the wipe delegate method invokes in the associated applications to signal the developer to remove local app data.

To implement the SDK, you must implement the code to initialize the SDK using AWController and calling Start from the clientInstance. Also make sure you implement the lock, unlock, and wipe methods, along with the other delegate methods of AWSDKDelegate inside your app delegate. See the iOS SDK Guide or the iOS SDK Implementation Walkthrough article for more information.

Once you upload the SDK application into the AirWatch Admin Console and assign an SDK profile or default settings with SSO enabled, the SDK automatically handles communication with the AirWatch Agent to manage the sessions.


Authentication Type

Authentication Type and SSO can work together or alone. If you enable an Authentication Type (passcode or username/password) without SSO, then users must enter a separate passcode or credentials for each individual application. If you enable both Authentication Type and SSO, then users enter either their passcode or credentials (whichever you configure as the Authentication Type) once and do not have to re-enter them until the SSO session terminates.




Designates a local passcode requirement for AirWatch applications or wrapped applications that have the default settings profile applied to them. Device users set their passcode on the device at the application level when they first access the application.

Username and Password

Requires a user to authenticate to AirWatch using the AirWatch credentials. Set these credentials when you add users in the Accounts area of the AirWatch Admin Console.


Requires no authentication to access the application.

To set up a passcode as the authentication type for use within your application, you can push down a custom SDK profile or use the default application settings set up in the Admin Console.


In order to use the default application settings, navigate to Groups & Settings > All Settings > Apps > Settings and Policies > Security Policies and set the Authentication Type to Passcode. 

Passcode Setting



Enable this option to require a local passcode requirement.

Authentication Timeout

Set the allowable time for access to applications before disallowing access due to inactivity. If SSO is enabled and the passcode times out, the SSO identity logs out of all AirWatch and configured corporate applications and resources.

Max Number of Failed Attempts

Set the maximum times a user can login with an incorrect passcode before having to authenticate and set a new passcode.

Passcode Mode

Set as Numeric or Alphanumeric.

Allow Simple Value

Set the passcode to allow simple strings. For example, allow strings like 1234 and 1111.

Min Passcode Length

Set the minimum number of characters for the passcode.

Min Number of Complex Characters (if Alphanumeric is selected)

Set the minimum number of complex characters for the passcode. For example, allow characters like [], @, and #.

Max Passcode Age (days)

Set the number of days the passcode remains valid before you must change it.

Passcode History

Set the number of passcodes the AirWatch Admin Console stores so that users cannot use recent passcodes.

Biometric Mode

Select the system used to authenticate for access. 

  • Enabled – Require users to access the application with their fingerprints or other biometric characteristics.

Note: You must configure a device passcode and TouchID/FaceID prior to using the application

  • Disabled – Require no use of biometric authentication systems to access the application.



Once a Passcode SDK policy is sent to your application, you will be asked to set up the passcode the next time you open your application or another AirWatch SDK-enabled application such as the AirWatch Agent, depending on whether or not SSO is also enabled. 



Single Sign On (SSO)

AirWatch's single sign on (SSO) feature allows end users to access all AirWatch apps, wrapped apps, and SDK-enabled apps with a single SSO Passcode without having to enter login credentials for each application. Using either the AirWatch Agent or the AirWatch Container as a "broker application", end users can authenticate once using either their normal credentials or an SSO Passcode and then gain access to other applications so long as the SSO session is active.


Enabling SSO

Enable SSO as part of the Security Policies that you configure to apply to all AirWatch apps, wrapped apps, and SDK- enabled apps using a Default SDK Profile. To enable SSO:

  1. Navigate to Groups & Settings > All Settings > Apps > Settings and Policies > Security Policies. 

  2. Set Single Sign On to Enabled to allow end users to access all AirWatch applications and maintain a persistent login. 

  3. Optionally set Authentication Type to Passcode and set the Passcode Mode to either Numeric or Alphanumeric to require an SSO Passcode on the device. If you enable SSO but do not enable an Authentication Type, end users will use their normal credentials (either directory service or AirWatch account) to authenticate, and an SSO Passcode will not exist. 


SSO Session

Once an end user authenticates with an application participating in SSO, a session establishes. The session is active until the Authentication Timeout defined in the SDK profile is reached or if the user manually locks the application.

Note: It is possible to retrieve the timeout value set in the authentication payload of the SDK profile using the AWAuthenticationPayload API and the passcodeTimeout setting. See below for an example.



Required Agent Settings

When using the Agent as a "broker application" for features such as single-sign on, ensure to configure the AirWatch Agent with the applicable SDK profile. If you are using the default SDK profile, ensure that the Agent is configured to use this profile. If you do not set the Agent to use the default SDK profile, then the system does not apply your configurations you set in the Settings and Policies section.


Setting the AirWatch Agent for Apple iOS

Configure the AirWatch Agent for Apple iOS to use the correct profile.

  1. Navigate to Groups & Settings > All Settings > Devices & Users > Apple > Apple iOS > Agent Settings. 

  2. Set the SDK Profile V2 option in the SDK PROFILE section to the default profile by selecting iOS Default Settings @ <Organization Group>.
  3. Save your settings.


Finishing Up

You should now be able to implement the functionality of forcing a user to authenticate with a passcode or their directory/basic user credentials in order to access your application (or any AirWatch application). For more information, please see the AirWatch iOS SDK Technical Implementation Guide.

Have more questions? Submit a request


Article is closed for comments.