Using Passwordless on iOS with TouchID

This feature is disabled for new tenants as of June 8th 2017. Any tenant created after that date won't have the necessary legacy grant types to use Touch ID. This document is offered as reference for older implementations.

For an alternative approach, using the Credentials Manager utility in Auth0.swift, refer to Touch ID Authentication.

Authenticate users with Touch ID

A feature specific to iOS is the support for Touch ID, which allows users to authenticate with their fingerprint (biometric authentication).

During sign-up, the library will generate a key pair on the device, create a user in Auth0, and register the public key for the user:

The private key is stored in the keystore of the device. Each time a user initiates authentication with a valid fingerprint, Touch ID retrieves the private key from the keystore, creates a token, signs it with the private key and sends it to Auth0. Auth0 then returns an id_token, the user profile and, optionally, a refresh_token.

You can use Touch ID with an iPhone 5s or later, an iPad Air 2, or an iPad mini 3 or later.


Using the Auth0 Lock

The Lock is a widget that allows you to easily integrate Auth0's Passwordless Authentication into your iOS applications.

After installing and configuring Lock.iOS-OSX you will be able to use Lock as follows.

A0Lock *lock = ... //Fetch Lock instance from where you stored it
A0TouchIDLockViewController *controller = [lock newTouchIDViewController];
controller.onAuthenticationBlock = ^(A0UserProfile *profile, A0Token *token) {
    // Your user is now authenticated with Auth0
    // You'd probably want to store somewhere safe the tokens stored in "token" parameter
    [self dismissViewControllerAnimated:YES completion:nil];
[lock presentTouchIDController:controller fromController:self];

Using your own UI

If you choose to build your own UI, you must install our TouchIDAuth library to handle the features specific to Touch ID.

Begin by signing up a user in a Database Connection:

A0Lock *lock = ... //Fetch Lock instance from where you stored it
A0APIClient *client = [lock apiClient];
A0AuthParameters *params = [A0AuthParameters newDefaultParams];
params[A0ParameterConnection] = kAuth0ConnectionType; // Or your configured DB connection

[client signUpWithUsername:username
                   success:^(A0UserProfile *profile, A0Token *token) {
                      [self loginTouchIDWithToken:token.idToken];
                   } failure:^(NSError *error){
                      // Handle failure

You can generate a random password to avoid asking the user for one at this time. The user can change it later.

Once the user has signed up, use the idToken to register the public key for the user.

First, you will need a place to store an Auth0 API client with the token until you register the key, and a place to store the TouchID component:

@property (strong, nonatomic) A0UserAPIClient *userClient;
@property (strong, nonatomic) A0TouchIDAuthentication *authentication;

Now implement the following method to perform TouchID authentication:

- (void)loginTouchIDWithToken:(NSString *)token;

Then create and store the API client:

A0Lock *lock = ... //Fetch Lock instance from where you stored it
self.userClient = [lock newUserAPIClientWithIdToken:token.idToken];

Now configure the TouchID Authentication component:

NSString *device = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
NSString *userId = profile.userId;

A0TouchIDAuthentication *authentication = [[A0TouchIDAuthentication alloc] init];
authentication.registerPublicKey = ^(NSData *pubKey, A0RegisterCompletionBlock completed, A0ErrorBlock errored) {
    void(^registerBlock)() = ^{
        [self.userClient registerPublicKey:pubKey device:device user:userId success:^{
        } failure:^(NSError *error) {
    [self.userClient removePublicKeyOfDevice:device user:userId success:^{
    } failure:^(NSError *error) {

authentication.jwtPayload = ^{
    return @{
             @"iss": userId,
             @"device": device,

authentication.authenticate = ^(NSString *jwt, A0ErrorBlock block) {
    A0AuthParameters *parameters = [A0AuthParameters newWithDictionary:@{      
       A0ParameterConnection: @"{NAME_OF_MY_DB_CONNECTION}",
       A0ScopeProfile: @"openid name email nickname"

    [client loginWithIdToken:jwt deviceName:deviceName parameters:parameters success:^(A0UserProfile *profile, A0Token *token) {
        // User is authenticated with Auth0 & Touch ID
    } failure:^(NSError *error){
authentication.onError = ^(NSError *error) {
    // Handle authentication error

self.authentication = authentication;

Then, to begin authentication, add this line:

[self.authentication start];