Skip to content

Latest commit

 

History

History
257 lines (193 loc) · 8.7 KB

MIGRATION.md

File metadata and controls

257 lines (193 loc) · 8.7 KB
Raw

Migrating from Lock iOS 1 to 2

Lock 2.0 is the latest major release of Lock iOS-OSX, Lock provides a simple way to integrate Auth0 into existing projects and provide the frictionless login and signup experience that you want for your app. Lock provides extensive authentication options and customizable UI for your users to use to authenticate with your app.

This guide is provided in order to ease the transition of existing applications using Lock 1.x to the latest APIs.

Requirements

  • iOS 9.0+
  • Xcode 8.3+
  • Swift 3.2+

Objective-C Support

Lock v2 cannot be used from Objective-C since it's public API relies in Swift features and that makes them unavailable in ObjC codebase.

If you are willing to have some Swift code in your existing application you can follow this guide on how to mix Objective-C and Swift and then use Lock v2 from the Swift files.

If that's not an option we recommend sticking with Lock v1 or using Auth0.swift to build your own Lock

Benefits of Upgrading

  • Complete Swift 3 Compatibility: The new version includes the adoption of the new API Design Guidelines.
  • Improved UI: having a professional looking login box that displays well on any device.
  • Extensive configuration: lock provides improved configuration options to help customize the experience to your users needs.
  • Safari controller for web-based Auth: Following Google's recent ban of WebView based auth, Lock (and Auth0.swift) will always use SFSafariViewController when web auth is needed.
  • API Authorization support: Adds support for Auth0 API Authorization

Changes from v1

Lock 2.0 has adopted all the new Swift 3 changes and conventions, including the new API Design Guidelines. Because of this, almost every API in Lock has been modified in some way. So we're going to attempt to identify the most common usage and how they have changed to help you get started with Lock 2.0.

Integration with your Application

Lock needs to be notified for some of your application state changes and some events/notifications your application receives from the OS. You can do all these things in the AppDelegate

Application finished launching

In Lock v1 you'd add the following

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
	A0Lock.sharedLock().applicationLaunchedWithOptions(launchOptions)
	//Your code
	return true
}

but in Lock v2 is no longer required.

Application is asked to open URL

In Lock v1 you'd add the following

func application(application: UIApplication, openURL url: NSURL, sourceApplication: String?, annotation: AnyObject?) -> Bool {
    return A0Lock.shared().handle(url, sourceApplication: sourceApplication)
}

and in Lock v2 you need to

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool {
  return Lock.resumeAuth(url, options: options)
}

Application is asked to continue a User Activity

If you are using Lock passwordless and have specified the .magicLink option to send the user a universal link then you will need to add the following to your AppDelegate.swift:

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    return Lock.continueAuth(using: userActivity)
}

Usage

Lock by default will handle Email/Password, Enterprise & Social authentication based on your Application's connections enabled in your Auth0 Dashboard.

Auth0 credentials

Like in v1, in your application bundle you can add a plist file named Auth0.plist with the following format

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>ClientId</key>
  <string>{YOUR_CLIENT_ID}</string>
  <key>Domain</key>
  <string>{YOUR_DOMAIN}</string>
</dict>
</plist>

and it will load your Auth0 credentials, and if you prefer you can specify your credentials when showing Lock v2 like

Lock
    .classic(clientId: "{YOUR_CLIENT_ID}", domain: "{YOUR_DOMAIN}")

Classic mode (Database, Enterprise & Social authentication)

In v1 to show Lock from a UIViewController you'd add the following code

let lock = A0Lock.shared()
let controller = lock.newLockViewController()
controller.onAuthenticationBlock = {(profile, token) in
    // Do something with token & profile. e.g.: save them.
    // Lock will not save the Token and the profile for you.
    // And dismiss the UIViewController.
    self.dismissViewController(animated: true, completion: nil)
}
lock.present(controller, from: self)

and in v2 it can be changed for the following

Lock
    .classic()
    .onAuth { credentials in
      print("Authenticated!")
    }
    .present(from: self)

so in the onAuth callback you'd only receive the credentials of the user when the authentication is successful.

In contrast with Lock v1, now Lock will dismiss itself so there is no need to call dismissViewController(animated:, completion:) in any of the callbacks.

In the case you need to know about the errors or signup there are the corresponding onError and onSignUp callbacks to be notified.

Lock
    .classic()
    .onAuth { credentials in
      print("Authenticated!")
    }
    .onSignUp { email, attributes in
      print("New user with email \(email)!")
    }
    .onError { error in
      print("Failed with error \(error.localizedString)")
    }
    .present(from: self)

The callback onSignUp is only called when the login after signup is disabled

Passwordless mode (Email & SMS connections)

In v1 to show Lock Passwordless from a UIViewController you'd need to use either:

Email

let lock = A0Lock.shared()
let controller: A0EmailLockViewController = lock.newEmailViewController()
controller.useMagicLink = true
controller.onAuthenticationBlock = { (profile, token) in
    // Do something with token & profile. e.g.: save them.
    // Lock will not save the Token and the profile for you.
    // And dismiss the UIViewController.
    self.dismiss(animated: true, completion: nil)
}
lock.presentEmailController(controller, from: self)

SMS

let lock = A0Lock.shared()
let controller: A0SMSLockViewController = lock.newSMSViewController()
controller.useMagicLink = true
controller.onAuthenticationBlock = { (profile, token) in
    // Do something with token & profile. e.g.: save them.
    // Lock will not save the Token and the profile for you.
    // And dismiss the UIViewController.
    self.dismiss(animated: true, completion: nil)
}
lock.presentSMSController(controller, from: self)

In V2 both email and sms now use the same method:

Lock
    .passwordless()
    .onAuth { credentials in
      print("Authenticated!")
    }
    .present(from: self)

Notes:

  • Passwordless can only be used with a single connection and will prioritize the use of email connections over sms.
  • The audience option is not available in Passwordless.

Configuration Options

If you needed to tweak Lock behaviour using it's options in v1 you'd do something like

let controller = A0Lock.shared().newLockViewController()
controller?.closable = true
controller?.connections = ["facebook", "github", "my-database"]

in Lock v2 you can do it all before presenting Lock by calling

Lock
    .withOptions { options in
      options.closable = true
      options.allowedConnections = ["facebook", "github", "my-database"]
    }
    // continue configuring and then present Lock

UI Customizations

In v1 all UI customizations were performed using the A0Theme object where you'd do something like

let theme = A0Theme()
theme.register(.blue, forKey: A0ThemeTitleTextColor)
A0Theme.sharedInstance().register(theme)

in Lock v2 the UI customization is done using the withStyle function

Lock
    .classic()
    .withStyle { style in
      style.titleColor = .blue
    }
    // other customizations
    .present(from: self)

In the Roadmap

  • Native Authentication with third party SDKs (Facebook, Google, Twitter)
  • 1Password support
  • Secure Token storage and automatic token refresh
  • Remember me like feature using TouchID
  • Universal Link support for browser based Auth
  • Improved UI Styling
  • Bundle more i18n translation in Lock.framework