Lock v2 for iOS

This reference guide will show you how to implement the Lock user interface, and give you the details on configuring and customizing Lock in order to use it as the UI for your authentication needs. However, if you'd like to learn how to do more with Auth0 and Swift, such as how to save, call and refresh access tokens, get user profile info, and more, check out the Auth0.Swift SDK. Or, take a look at the Swift QuickStart to walk through complete examples and see options, both for using Lock as the interface, and for using a custom interface.

Requirements

  • iOS 9 or later
  • Xcode 8
  • Swift 3.0

Install

Carthage

If you are using Carthage, add the following lines to your Cartfile:

github "auth0/Lock.swift" ~> 2.0
github "auth0/Auth0.swift" ~> 1.0

Then run carthage bootstrap.

For more information about Carthage usage, check their official documentation.

Cocoapods

If you are using Cocoapods, add these lines to your Podfile:

use_frameworks!
pod 'Lock', '~> 2.0'
pod 'Auth0', '~> 1.0'

Then, run pod install.

For further reference on Cocoapods, check their official documentation.

Setup

Integrate with your Application

Lock needs to be notified when the application is asked to open a URL. You can do this in the AppDelegate file.

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

Import Lock

Import Lock wherever you'll need it

import Lock

Auth0 Credentials

In order to use Lock you need to provide your Auth0 Client Id and Domain, which can be found in your Auth0 Dashboard, under your Client's settings.

In your application bundle you can add a plist file named Auth0.plist that will include your credentials 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_AUTH0_DOMAIN</string>
</dict>
</plist>

Implementation of Lock Classic

Lock Classic handles authentication using Database, Social, and Enterprise connections.

OIDC Conformant Mode

It is strongly encouraged that this SDK be used in OIDC Conformant mode. When this mode is enabled, it will force the SDK to use Auth0's current authentication pipeline and will prevent it from reaching legacy endpoints. By default this is false

.withOptions {
    $0.oidcConformant = true
}

For more information, please see our Introduction to OIDC Conformant Authentication and the OIDC adoption guide.

To show Lock, add the following snippet in your UIViewController.

Lock
    .classic()
    // withConnections, withOptions, withStyle, etc
    .withOptions {
      $0.oidcConformant = true
      $0.scope = "openid profile"
    }
    .onAuth { credentials in
      // Let's save our credentials.accessToken value
    }
    .present(from: self)

Use Auth0.Swift Library to access user profile

To access user profile information, you will need to use the Auth0.Swift library:

guard let accessToken = credentials.accessToken else { return }
Auth0
    .authentication()
    .userInfo(withAccessToken: accessToken)
    .start { result in
        switch result {
        case .success(let profile):
            // You've got a UserProfile object
        case .failure(let error):
            // You've got an error
        }
}

Check out the Auth0.Swift Library Documentation for more information about its uses.

Specify Connections

Lock will automatically load the connections configured for your client. If you wish to override the default behavior, you can manually specify which connections it should display to users as authentication options. This can be done by calling the method and supplying a closure that can specify the connection(s).

Adding a database connection:

.withConnections {
    connections.database(name: "Username-Password-Authentication", requiresUsername: true)
}

Adding multiple social connections:

.withConnections {
    connections.social(name: "facebook", style: .Facebook)
    connections.social(name: "google-oauth2", style: .Google)
}

Styling and Customization

Lock provides many styling options to help you apply your own brand identity to Lock using withStyle. For example, changing the primary color and header text of your Lock widget:

Customize your title, logo, and primary color

.withStyle {
  $0.title = "Company LLC"
  $0.logo = LazyImage(named: "company_logo")
  $0.primaryColor = UIColor(red: 0.6784, green: 0.5412, blue: 0.7333, alpha: 1.0)
}

You can see the complete set of styling options to alter the appearance of Lock for your app in the Customization Guide.

Configuration Options

There are numerous options to configure Lock's behavior. Below is an example of Lock configured to allow it to be closable, to limit it to only usernames (and not emails), and to only show the Login and Reset Password screens.

Lock
  .classic()
  .withOptions {
    $0.closable = true
    $0.usernameStyle = [.Username]
    $0.allow = [.Login, .ResetPassword]
  }

You can see the complete set of behavior configuration options to alter the way Lock works for your app in the Configuration Guide.

Password Manager Support

By default, password manager support using 1Password is enabled for database connections. 1Password support will still require the user to have the 1Password app installed for the option to be visible in the login and signup screens. You can disable 1Password support using the enabled property of the passwordManager.

.withOptions {
    $0.passwordManager.enabled = false
}

By default the appIdentifier will be set to the app's bundle identifier and the displayName will be set to the app's display name. You can customize these as follows:

.withOptions {
    $0.passwordManager.appIdentifier = "www.myapp.com"
    $0.passwordManager.displayName = "My App"
}

You will need to add the following to your app's info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>org-appextension-feature-password-management</string>
</array>

Lock Passwordless

Passwordless on native platforms is disabled by default for new tenants as of 8 June 2017. If you would like this feature enabled, please contact support to discuss your use case. See Client Grant Types for more information. Alternatively, you can use Lock Passwordless on Auth0's Hosted Login Page.

Lock Passwordless handles passwordless authentication using email and sms connections.

To show Lock, add the following snippet in your UIViewController.

Lock
    .passwordless()
    // withConnections, withOptions, withStyle, etc
    .onAuth { credentials in
      // Save the Credentials object
    }
    .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.

Passwordless Method

When using Lock Passwordless the default passwordlessMethod is .code which sends the user a one time passcode to login. If you want to use Universal Links you can add the following:

.withOptions {
    $0.passwordlessMethod = .magicLink
}

Activity callback

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)
}

Logging

Lock provides options to easily turn on and off logging capabilities, as well as adjust other logging related settings. The example below displays logging turned on, but take a look at the Behavior Configuration Options page for more information about logs in Lock for iOS v2.

Lock
    .classic()
    .withOptions {
        $0.logLevel = .all
        $0.logHttpRequest = true
    }

Future roadmap of Lock v2 for iOS

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

Next Steps