A Swift & iOS framework to authenticate using Auth0 and with a Native Look & Feel
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Lock.swift

CircleCI Version License Platform Carthage compatible Swift 3.2

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

Lock makes it easy to integrate SSO in your app. You won't have to worry about:

  • Having a professional looking login dialog that displays well on any device.
  • Finding the right icons for popular social providers.
  • Solving the home realm discovery challenge with enterprise users (i.e.: asking the enterprise user the email, and redirecting to the right enterprise identity provider).
  • Implementing a standard sign in protocol (OpenID Connect / OAuth2 Login)

Need help migrating from v1? Please check our Migration Guide

Requirements

  • iOS 9 or later
  • Xcode 8.3+
  • Swift 3.2+

Install

CocoaPods

Add the following line to your Podfile:

pod "Lock", "~> 2.7"

Carthage

In your Cartfile add

github "auth0/Lock.swift" ~> 2.7

Usage

First import Lock

import Lock

Next in your AppDelegate.swift add the following:

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

Configuration

In order to use Lock you need to provide your Auth0 Client ID and Domain.

The Auth0 Client ID & Domain can be found in your Auth0 Dashboard

Auth0.plist file

In your application bundle you can add a plist file named Auth0.plist with the following information:

<?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>

Lock Classic

Lock Classic handles authentication using Database, Social & 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 the OIDC adoption guide.

To show Lock, add the following snippet in your UIViewController

Lock
    .classic()
    .withOptions {
        $0.closable = false
        $0.oidcConformant = true
    }
    .withStyle {
      $0.title = "Welcome to my App!"
    }
    .onAuth {
      print("Obtained credentials \($0)")
    }
    .onError {
      print("Failed with \($0)")
    }
    .onCancel {
      print("User cancelled")
    }
    .present(from: self)

Important: Database Connection Authentication

Since June 2017 new Clients no longer have the Password Grant Type* enabled by default. If you are using a Database Connection in Lock then you will need to enable the Password Grant Type, please follow this guide.

Specify Connections

Lock will automatically load your application configuration automatically, if you wish to override this behaviour you can manually specify which of your connections to use.

Before presenting Lock you can tell it what connections it should display and use to authenticate an user. You can do that by calling the method and supply a closure that can specify the connections.

Adding a Database connection
.withConnections {
    $0.database(name: "Username-Password-Authentication", requiresUsername: true)
}
Adding Social connections
.withConnections { connections in
    connections.social(name: "facebook", style: .Facebook)
    connections.social(name: "google-oauth2", style: .Google)
}
Adding Enterprise connections
.withConnections { connections in
    connections.enterprise(name: "customAD", domains: ["domain1.com", "domain2.com"])
    connections.enterprise(name: "alternativeAD", domains: ["domain3.com"], style: .Microsoft)
}

Custom Domains

If you are using Custom Domains, you will need to set the configurationBaseURL to your Auth0 Domain so the Lock configuration can be read correctly.

.withOptions {
   $0.configurationBase = "https://<YOUR DOMAIN>.auth0.com"
}

Logging

You can easily turn on/off logging capabilities.

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

Styling Lock

Lock provides many styling options to help you apply your own brand identity to Lock.

iPad Modal Presentation

iPad presentation is show in a modal popup, this can be disabled to use full screen as follows.

.withStyle {
  $0.modalPopup = false
}

Customize your header and primary color

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

You can explore the full range of styling options in Style.swift

Styling a custom OAuth2 connection

.withStyle {
  $0.oauth2["slack"] = AuthStyle(
      name: "Slack",
      color: UIColor(red: 0.4118, green: 0.8078, blue: 0.6588, alpha: 1.0),
      withImage: LazyImage(name: "ic_slack")
  )
}

Lock Passwordless

Lock Passwordless handles authentication using Passwordless & Social Connections.

The Passwordless feature requires your application to have the Resource Owner Legacy Grant Type enabled. Check this article for more information.

To show Lock, add the following snippet in your UIViewController

Lock
    .passwordless()
    .withOptions {
        $0.closable = false
    }
    .withStyle {
      $0.title = "Welcome to my App!"
    }
    .onAuth {
      print("Obtained credentials \($0)")
    }
    .onError {
      print("Failed with \($0)")
    }
    .onCancel {
      print("User cancelled")
    }
    .onPasswordless {
      print("Passwordless requested for \($0)")
    }
    .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)
}

Adding a Passwordless connection

SMS
.withConnections {
    $0.sms(name: "sms")
}
Email
.withConnections {
    $0.email(name: "email")
}

Customization options

Lock provides numerous options to customize the Lock experience.

Closable

Allows Lock to be dismissed by the user. By default this is false.

.withOptions {
    $0.closable = true
}

Terms of Service

By default Lock will use Auth0's Terms of Service and Privacy Policy

.withOptions {
    $0.termsOfService = "https://mycompany.com/terms"
    $0.privacyPolicy = "https://mycompany.com/privacy"
}

Must accept Terms of Service

Database connection will require explicit acceptance of terms of service

.withOptions {
    $0.mustAcceptTerms = true
}

Logging

  • logLevel: By default this is .off, Syslog logging levels are supported.
  • logHttpRequest: Log Auth0.swift API requests. By default this is false
  • loggerOutput: Specify output handler, by default this uses the print statement.
.withOptions {
    $0.logLevel = .all
    $0.logHttpRequest = true
    $0.loggerOutput = CleanroomLockLogger()
}

In the code above, the loggerOutput has been set to use CleanroomLogger. This can typically be achieved by implementing the loggerOutput protocol. You can of course use your favorite logger library.

class CleanroomLockLogger: LoggerOutput {
  func message(_ message: String, level: LoggerLevel, filename: String, line: Int) {
    let channel: LogChannel?
    switch level {
    case .debug:
        channel = Log.debug
    case .error:
        channel = Log.error
    case .info:
        channel = Log.info
    case .verbose:
        channel = Log.verbose
    case .warn:
        channel = Log.warning
    default:
        channel = nil
    }
    channel?.message(message, filePath: filename, fileLine: line)
  }
}

Scope

Scope used for authentication. By default is openid. It will return not only the access_token, but also an id_token which is a JSON Web Token (JWT) containing user information.

.withOptions {
  $0.scope = "openid name email picture"
}

Connection Scope

Allows you to set provider scopes for oauth2/social connections with a comma separated list. By default is empty.

.withOptions {
  $0.connectionScope = ["facebook": "user_friends,email"]

Database

  • allow: Which database screens will be accessible, the default is enable all screens e.g. .Login, .Signup, .ResetPassword
  • initialScreen: The first screen to present to the user, the default is .login.
  • usernameStyle: Specify the type of identifier the login will require. The default is either [.Username, .Email]. However it's important to note that this option is only active if you have set the requires_username flag to true in your Auth0 Dashboard
.withOptions {
  $0.allow = [.Login, .ResetPassword]
  $0.initialScreen = .login
  $0.usernameStyle = [.Username]
}

Custom Signup Fields

When signing up the default information requirements are the user's email and password. You can expand your data capture requirements as needed.

.withOptions {
  $0.customSignupFields = [
    CustomTextField(name: "first_name", placeholder: "First Name", icon: LazyImage(name: "ic_person", bundle: Lock.bundle)),
    CustomTextField(name: "last_name", placeholder: "Last Name", icon: LazyImage(name: "ic_person", bundle: Lock.bundle))
  ]
}

Note: You must specify the icon to use with your custom text field and store it in your App's bundle.

Password Manager

By default password manager support using 1Password is enabled for database connections, although you will still need 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>

If your Info.plist is not shown in this format, you can Right Click on Info.plist in Xcode and then select Open As / Source Code.

If you see the following debug error:

canOpenURL: failed for URL: "org-appextension-feature-password-management://" - error: "This app is not allowed to query for scheme org-appextension-feature-password-management"

This is normal and expected behavior when there is no app that can open a custom URL. In this case when the 1Password app is not installed. Unfortunately, the message can be a little confusing but it is coming from iOS itself.

Show Password

By default a show password icon is shown in password fields to toggle visibility of the input text. You can disable this using the allowShowPassword option.

.withOptions {
    $0.allowShowPassword = false
}

Note: Show password will not be available if the [Password Manager](#Password Manager) is available.

Enterprise

  • enterpriseConnectionUsingActiveAuth: By default Enterprise connections will use Web Authentication. However you can specify which connections will alternatively use credential authentication and prompt for a username and password.
  • activeDirectoryEmailAsUsername: When Lock request your enterprise credentials after performing Home Realm Discovery (HRD), e.g. for Active Directory, it will try to prefill the username for you. By default it will parse the email's local part and use that as the username, e.g. john.doe@auth0.com will be john.doe. If you don't want that you can turn on this flag and it will just use the email address.
.withOptions {
  $0.activeDirectoryEmailAsUsername = true
  $0.enterpriseConnectionUsingActiveAuth = ["enterprisedomain.com"]
}

What is Auth0?

Auth0 helps you to:

Create a free account in Auth0

  1. Go to Auth0 and click Sign Up.
  2. Use Google, GitHub or Microsoft Account to login.

Issue Reporting

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.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.