TouchIDAuth provides a default implementation for a passwordless login flow using TouchID and JWT.
The flow is represented in the following graph:
- Validate the user presence using TouchID
- Check if the user has a key pair
- Generate a key pair
- Register the Public Key for the user.
- Generate a JWT and signs it with the Private Key using RS256
- Authenticate the user with the signed JWT.
The library requires iOS 8+ and a device with TouchID.
TouchIDAuth is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "TouchIDAuth"
In your Cartfile add the following
github "auth0/TouchIDAuth"
To run the example project, clone the repo, and run pod install
from the Example directory first.
And then in A0ViewController add your IP address or hostname for the mock server URL:
#define kBaseURL @"http://mymac.local:3000"
To run the mock server, go to the folder TouchIDAuthServer and run the following commands:
npm install
node app.js
First you'll need to instantiate it
A0TouchIDAuthentication *authentication = [[A0TouchIDAuthentication alloc] init];
Then you need to configure a couple of callbacks that will be called during the authentication flow. There are three callbacks, registerPublicKey
, jwtPayload
and authenticate
.
The callback registerPublicKey
will handle the registration of the public key against an API and must call completionBlock
on success in order to continue with the flow (or errorBlock
if it fails). For example:
authentication.registerPublicKey = ^(NSData *pubKey, A0RegisterCompletionBlock completionBlock, A0ErrorBlock errorBlock) {
AFHTTPRequestOperationManager *manager = [[AFHTTPRequestOperationManager alloc] initWithBaseURL:baseURL];
//Configure AFHTTPRequestOperationManager
[manager POST:@"/pubkey" parameters:params success:^(AFHTTPRequestOperation *operation, id responseObject) {
completionBlock();
} failure:^(AFHTTPRequestOperation *operation, NSError *error) {
errorBlock(error);
}];
};
};
The callback jwtPayload
is called before generating the JWT in order to provide the JWT payload needed by your API endpoint. For example:
authentication.jwtPayload = ^{
return @{
@"iss": @"Issuer",
@"custom_key": @"value",
};
};
The callback authenticate
will receive the signed JWT and will need to authenticate against your API endpoint. For example:
authentication.authenticate = ^(NSString *jwt, A0ErrorBlock errorBlock) {
NSDictionary *params = @{
@"jwt": jwt,
};
AFHTTPRequestOperationManager *manager = [[AFHTTPRequestOperationManager alloc] initWithBaseURL:baseURL];
//Configure AFHTTPRequestOperationManager
[manager POST:@"/login" parameters:params success:^(AFHTTPRequestOperation *operation, id responseObject) {
NSLog(@"Logged in!!!");
} failure:^(AFHTTPRequestOperation *operation, NSError *error) {
errorBlock(error);
}];
};
There is an extra callback onError
that will be called whenever an error ocurrs while executing the Auth flow:
authentication.onError = ^(NSError *error) {
NSLog(@"ERROR %@", error);
};
At last, call the following method to start the authentication flow:
[authentication start];
Before calling
start
, it's recommended to check if TouchID is enabled in the device calling the method isTouchIDAuthenticationAvailable.
##API
###A0TouchIDAuthentication
####A0TouchIDAuthentication#registerPublicKey
@property (copy, nonatomic) void(^registerPublicKey)(NSData *pubKey, A0RegisterCompletionBlock completionBlock, A0ErrorBlock errorBlock);
Block to handle public key registration with an API Endpoint. It will receive 3 parameters: publicKey, completionBlock and errorBlock. The public key is formatted as a RSA public key.
####A0TouchIDAuthentication#jwtPayload
@property (copy, nonatomic) NSDictionary *(^jwtPayload)();
Block to return the paylod for the JWT to be signed by the device. It will be called each time a JWT needs to be generated and signed. By default A0TouchIDAuth
will include iat
, exp
(30 sec) and sub
(Public Key fingerprint) claims but you can override them or add more entries to the payload.
####A0TouchIDAuthentication#authenticate
@property (copy, nonatomic) void(^authenticate)(NSString *jwt, A0ErrorBlock errorBlock);
Block called with the signed JWT to authenticate against an API ednpoint.
####A0TouchIDAuthentication#onError
@property (copy, nonatomic) void(^onError)(NSError *error);
Block called when an error occurred during the Authentication flow.
####A0TouchIDAuthentication#localizedTouchIDMessage
@property (copy, nonatomic) NSString *localizedTouchIDMessage;
Localized message displayed in TouchID prompt.
####A0TouchIDAuthentication#start
- (void)start;
Starts the TouchID authentication flow. It will fail automatically if isTouchIDAuthenticationAvailable
returns NO
.
####A0TouchIDAuthentication#isTouchIDAuthenticationAvailable
- (BOOL)isTouchIDAuthenticationAvailable;
Check if TouchID is supported by the device and configured.
####A0TouchIDAuthentication#reset
- (void)reset;
Reset TouchID authentication info stored in the device.
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
Auth0 helps you to:
- Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
- Add authentication through more traditional username/password databases.
- Add support for linking different user accounts with the same user.
- Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
- Analytics of how, when and where users are logging in.
- Pull data from other sources and add it to the user profile, through JavaScript rules.
- Go to Auth0 and click Sign Up.
- Use Google, GitHub or Microsoft Account to login.
TouchIDAuth is available under the MIT license. See the LICENSE file for more info.