Docs

Lock v1 for iOS and macOS

Versionv1

This document covers an outdated version of Lock for iOS. We recommend you to upgrade to v2

Auth0 is an authentication broker that supports social identity providers as well as enterprise identity providers such as Active Directory, LDAP, G Suite and Salesforce.

Key features

  • Integrates your iOS app with Auth0 (OS X coming soon).
  • Provides a elegant native UI to log in your users.
  • Provides support for Social Providers (Facebook, Twitter, and so on), Enterprise Providers (AD, LDAP, and so on) and Username & Password authentication.
  • Provides the ability to do Single Sign-on (SSO) with 2 or more mobile apps, similar to Facebook and Messenger apps.
  • 1Password integration using the iOS 8 Extension.

Check out the Lock.swift repository on GitHub.

Requirements

iOS 7+. If you need to use our SDK with an earlier version, use the previous SDK pod Auth0Client, or see the old-sdk branch of the Lock.iOS-OSX repo.

Installation

Lock is available through CocoaPods. To install it, simply add the following line to your Podfile:

Then, in your project's Info.plist file, add the following string entries:

  • Auth0ClientId: The client ID of your Auth0 application.
  • Auth0Domain: Your Auth0 account domain.

For example: plist

You can find these values in your Application Settings in the Auth0 dashboard.

You will also need to register a Custom URL type with a custom scheme in the following format:

a0{Your Client ID}

For example, if your Client ID is Exe6ccNagokLH7mBmzFejP, the custom scheme would be a0Exe6ccNagokLH7mBmzFejP.

Before you can begin using Lock, you will need to import Lock into your codebase.

If you are working in Objective-C, import this header when you need to use Lock's classes:

The same applies if you are working in Swift and Lock is included as a static library. In this case, the header must also be included in your Objective-C Bridging Header.

If you need help creating the Objective-C Bridging Header, see: Swift and Objective-C in the Same Project.

If you are working in Swift with Lock included as an framework, just include the module in your Swift files like this:

Now you can initialize A0Lock (which handles authentication) and keep it in your AppDelegate as a strong property.

You can store A0Lock in a different location as long as you keep it alive as long as it is needed.

This examples creates A0Lock inside -application:didFinishLaunchingWithOptions:

Objective C:

Swift:

Then call this method:

Objective C:

Swift:

Lastly, you will need to handle the already registered custom scheme in your AppDelegate. To do so, override the -application:openURL:sourceApplication:annotation: method and add the following line:

Objective C:

Swift:

This call is required to be able to return to your application when authenticating with Safari, or with native integration with Facebook or Twitter. This call checks the URL and handles those that have the custom scheme.

Usage

Email/password, enterprise, and social provider authentication

A0LockViewController will handle email/password, enterprise, and social provider authentication based on the connections enabled on your application in the Auth0 Dashboard.

First, instantiate A0LockViewController and register the authentication callback that will receive the authenticated user's credentials. Then present it as a modal view controller:

Objective C

Swift

You will see the Lock native login screen:

Lock-iOS

By default, all social authentication will be done using Safari. If you want native integration, see: Lock iOS: Native Social Authentication.

Close Lock UI

You can add a Close button to Lock UI. For this to function, you will need to set the closable property to allow the A0AuthenticationViewController to be dismissed. The default value is NO.

If you want to handle the closing event, you will need to add the onUserDismissBlock block which will be called when the user dismisses the Login screen only if the closable property is set to YES.

Objective C

Swift

Sign-up

There are different approaches to implement Sign-up functionality:

  1. You can add or hide the Sign Up button in Lock UI by setting the disableSignUp property which will hide the Sign Up button when set to YES. The default value is NO.

  2. Another approach is to use the A0LockSignUpViewController directly:

Objective-C

Swift

  1. A third option is to create your own sign up viewController to implement the sign-up logic with one of the A0APIClient methods:

Your viewController should also implement the A0LockEventDelegate methods:

After implementing your viewController, you will need to return it in a customSignUp block of A0LockViewController. The default value for this block is nil.

Objective-C:

Swift:

Automatic login after sign-up

After a successful sign-up, the user can be logged in automatically using the loginAfterSignUp property. If loginAfterSignUp is set to YES, A0AuthenticationViewController will attempt to log in the user . Otherwise, it will call onAuthenticationBlock with both parameters set to nil. The default value of loginAfterSignUp is YES.

Disclaimer View

If you want to show a disclaimer for your app, you will need to set signUpDisclaimerView. This view will appear at the bottom of the sign-up screen.

Logout

To log out a user, call clearSessions for A0Lock. This method removes all stored sessions of any IdP in your application.

  • If the user has logged in using Safari, their sessions will not be cleared.
  • If you stored the credentials in the keychain, you need to clear them there as well.

Objective-C

Swift

WebView

When authenticating with a social connection, you can choose between using Safari or the embedded webView. To use embedded webView, set the useWebView property to YES. The default value is YES.

Objective-C

Swift

Additional Information

See the Swift and Objective-C example apps.

For more information on how to use Lock with Swift, see: Lock iOS: Using Swift.

For more information on Lock for CocoaPods, see the Lock documentation in CocoaDocs.

Further reading