Lock.swift
Auth0 是一个支持社交身份提供者以及 Active Directory、LDAP、Google Apps 和 Salesforce 等企业身份提供者的身份验证代理。
Lock 让您轻松地将 SSO 集成到您的应用程序中。您不用担心
- 拥有一个看起来专业且在任何设备上都能正确显示的登录对话框。
- 找到流行的社交提供者的正确图标。
- 解决企业用户的主域发现挑战（即：询问企业用户的电子邮件，并重定向到正确的企业身份提供者）。
- 实现标准登录协议（OpenID Connect / OAuth2 登录）
需要从 v1 迁移的帮助？请查看我们的 迁移指南。
目录
需求
- iOS 9+
- Xcode 12.x / 13.x
- Swift 4.x / 5.x
安装
Cocoapods
如果你使用Cocoapods，将以下行添加到你的Podfile文件中
pod "Lock", "~> 2.24"然后运行pod install。
有关Cocoapods的更多信息，请查看官方文档。
Carthage
如果你使用Carthage，将以下行添加到你的Cartfile文件中
github "auth0/Lock.swift" ~> 2.24然后运行carthage bootstrap --use-xcframeworks --platform iOS。
有关Carthage使用的更多信息，请查看官方文档。
SPM
如果你使用Swift Package Manager，请打开Xcode中的以下菜单项
文件 > 添加包...
在搜索或输入包URL搜索框中输入以下URL
https://github.com/auth0/Lock.swift.git
然后选择依赖规则并按'添加包。
有关SPM的更多信息，请查看官方文档。
用法
首先导入 Lock
import Lock然后在您的 AppDelegate.swift 中添加以下内容
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return Lock.resumeAuth(url, options: options)
}配置
为了使用 Lock，您需要提供 Auth0 客户端 ID 和域。
您可以在 Auth0 控制台中找到 Auth0 客户端 ID & 域 Auth0 控制台
Auth0.plist 文件
在您的应用程序包中，您可以添加一个名为 Auth0.plist 的 plist 文件，其中包含以下信息
<?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 通过数据库、社交和企业连接处理身份验证。
OIDC 兼容模式
强烈建议在 OIDC 兼容模式下使用此 SDK。启用此模式时，将强制 SDK 使用 Auth0 的当前身份验证管道，并防止其访问旧端点。默认情况下，此值是 false。
.withOptions {
$0.oidcConformant = true
}更多信息，请参阅 OIDC 采用指南。
要显示 Lock，请将以下代码片段添加到您的 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)重要：数据库连接认证
自2017年6月起，新客户端默认不再启用密码授权类型。如果您在Lock中使用数据库连接，则需要启用密码授权类型，请按照此指南操作。
指定连接
Lock会自动加载您的应用配置，如果您想覆盖此行为，可以手动指定要使用的连接。
在展示Lock之前，您可以告诉它应显示和用于认证用户的连接。您可以通过调用方法并传递一个闭包来指定连接。
添加数据库连接
.withConnections {
$0.database(name: "Username-Password-Authentication", requiresUsername: true)
}添加社交连接
.withConnections { connections in
connections.social(name: "facebook", style: .Facebook)
connections.social(name: "google-oauth2", style: .Google)
}添加企业连接
.withConnections { connections in
connections.enterprise(name: "customAD", domains: ["domain1.com", "domain2.com"])
connections.enterprise(name: "alternativeAD", domains: ["domain3.com"], style: .Microsoft)
}自定义域名
如果您正在使用自定义域名，则需要将configurationBaseURL设置为您的Auth0域名，以便Lock配置能正确读取。
.withOptions {
$0.configurationBase = "https://<YOUR DOMAIN>.auth0.com"
}日志记录
您可以轻松地开启/关闭日志记录功能
Lock
.classic()
.withOptions {
$0.logLevel = .all
$0.logHttpRequest = true
}样式锁定
样式锁定提供了许多样式选项，帮助您将品牌身份应用到样式锁定上。
iPad模态窗演示
在iPad上的演示将以模态窗弹出显示，您可以禁用此功能，使用全屏方式如下
.withStyle {
$0.modalPopup = false
}自定义您的头部和主要颜色
.withStyle {
$0.title = "Company LLC"
$0.logo = UIImage(named: "company_logo")
$0.primaryColor = UIColor(red: 0.6784, green: 0.5412, blue: 0.7333, alpha: 1.0)
}您可以在 Style.swift 中探索完整的样式选项集
自定义OAuth2连接的样式
.withStyle {
$0.oauth2["slack"] = AuthStyle(
name: "Slack",
color: UIColor(red: 0.4118, green: 0.8078, blue: 0.6588, alpha: 1.0),
withImage: UIImage(named: "ic_slack")
)
}无密码锁
Lock Passwordless通过无密码和社交连接处理身份验证。
无密码功能要求您的应用程序已启用无密码OTP授权类型。请查阅这篇文章获取更多信息。
要使用Lock中的无密码身份验证，您需要将其配置为设置为true的OIDC遵从模式。
OIDC兼容模式将强制使用Auth0当前的认证流程，并防止其访问遗留端点。默认情况下，此模式是禁用的。更多信息，请参阅OIDC采用指南。
要显示 Lock，请将以下代码片段添加到您的 UIViewController
Lock
.passwordless()
.withOptions {
$0.oidcConformant = true
}
.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)说明
- 无密码功能只能与一个连接搭配使用，并将优先使用电子邮件连接而不是短信连接。
无密码方法
当使用无密码Lock时，默认的passwordlessMethod是.code，它会向用户发送一次性密码以进行登录。如果您想使用通用链接，可以添加以下内容：
.withOptions {
$0.passwordlessMethod = .magicLink
}活动回调
如果您正在使用无密码Lock且已指定.magicLink选项向用户发送通用链接，则需要将以下内容添加到您的AppDelegate.swift：
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
return Lock.continueAuth(using: userActivity)
}添加无密码连接
短信
.withConnections {
$0.sms(name: "sms")
}电子邮件
.withConnections {
$0.email(name: "email")
}自定义选项
Lock 提供众多选项来自定义 Lock 的体验。
可关闭
允许用户关闭 Lock。默认情况下为 false。
.withOptions {
$0.closable = true
}服务条款
默认情况下，Lock 将使用 Auth0 的服务条款和隐私策略
.withOptions {
$0.termsOfService = "https://mycompany.com/terms"
$0.privacyPolicy = "https://mycompany.com/privacy"
}必须接受服务条款
数据库连接将需要明确接受服务条款
.withOptions {
$0.mustAcceptTerms = true
}显示服务条款
数据库连接将显示服务条款对话框。默认为 true。
.withOptions {
$0.showTerms = true
}注意：如果启用了 mustAcceptTerms 标志，则始终显示条款。
日志记录
- 日志级别：默认情况下为
.off，Syslog 日志级别得到支持。 - 记录HTTP请求：记录Auth0.swift API请求。默认情况下为
false - 日志输出：指定输出处理器，默认使用
print语句。
.withOptions {
$0.logLevel = .all
$0.logHttpRequest = true
$0.loggerOutput = CleanroomLockLogger()
}如上代码中，日志输出 已设置为使用 CleanroomLogger。这通常通过实现 日志输出 协议来实现。当然，您可以使用您最喜欢的日志库。
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)
}
}作用域
用于身份验证的作用域。默认为 openid。它不仅返回 访问令牌，还返回一个包含用户信息的 id_token，这是一个 JSON Web Token (JWT)。
.withOptions {
$0.scope = "openid name email picture"
}连接作用域
允许您使用逗号分隔的列表设置OAuth2/社交连接的提供者作用域。默认为空。
.withOptions {
$0.connectionScope = ["facebook": "user_friends,email"]数据库
- 允许：哪些数据库屏幕是可访问的，默认是启用所有屏幕，例如
.Login, .Signup, .ResetPassword - 初始屏幕：向用户提供的第一屏幕，默认是
.login。 - 用户名样式：指定登录所需的标识符类型。默认是
[.Username, .Email]。但请注意，此选项仅在您在 Auth0 控制台 中将 requires_username 标志设置为true时才激活。
.withOptions {
$0.allow = [.Login, .ResetPassword]
$0.initialScreen = .login
$0.usernameStyle = [.Username]
}自定义注册字段
在注册时，默认的信息要求是用户的 电子邮件 和 密码。您可以根据需要扩展数据捕获要求。
如果您想保存用户配置文件根目录中的属性值，请确保将 storage 参数设置为 .rootAttribute。只有子集的值可以以这种方式存储。可以添加到根配置文件的属性列表 这里。默认情况下，每个额外的注册字段都存储在用户的 user_metadata 对象中。
在注册过程中，您的应用可能需要分配用户未输入的值给用户的个人资料。《CustomTextField》的《hidden》属性可以防止注册字段显示给用户，从而允许您的应用为用户个人资料分配默认值。
.withOptions {
$0.customSignupFields = [
CustomTextField(name: "first_name", placeholder: "First Name", storage: .rootAttribute, icon: UIImage(named: "ic_person", bundle: Lock.bundle), contentType: .givenName),
CustomTextField(name: "last_name", placeholder: "Last Name", storage: .rootAttribute, icon: UIImage(named: "ic_person", bundle: Lock.bundle), contentType: .familyName),
CustomTextField(name: "referral_code", placeholder: "Referral Code", defaultValue: referralCode, hidden: true)
]
}注意：您必须指定与自定义文本字段一起使用的图标，并将其存储在应用的包中。
密码管理器
由于1Password扩展使用已弃用的方法，这可能导致您的应用被AppStore拒绝，因此自版本2.18起删除了此功能。当Apple在iOS 12中引入密码管理器到登录表单时，此功能已被取代。
以下选项已弃用
.withOptions {
$0.passwordManager.enabled = false
$0.passwordManager.appIdentifier = "www.myapp.com"
$0.passwordManager.displayName = "My App"
}您还可以安全地从应用的《Info.plist》中移除以下条目
<key>LSApplicationQueriesSchemes</key>
<array>
<string>org-appextension-feature-password-management</string>
</array>显示密码
默认情况下，在密码字段中显示显示密码图标以切换输入文本的可见性。您可以使用《allowShowPassword》选项来禁用此功能
.withOptions {
$0.allowShowPassword = false
}注意：如果提供了《密码管理器》，则《显示密码》功能将不可用。
企业
- enterpriseConnectionUsingActiveAuth：默认情况下，企业连接将使用Web身份验证。但是，您可以为哪些连接指定使用凭据身份验证并提示用户名和密码。
- activeDirectoryEmailAsUsername：在执行家庭领域发现（HRD）后，Lock请求您的企业凭据，例如Active Directory，它将尝试为您预先填写用户名。默认情况下，它将解析电子邮件的本部分并将其用作用户名，例如
[email protected]将为john.doe。如果您不希望这样，您可以将此标志打开，它将仅使用电子邮件地址。
.withOptions {
$0.activeDirectoryEmailAsUsername = true
$0.enterpriseConnectionUsingActiveAuth = ["enterprisedomain.com"]
}什么是Auth0？
Auth0帮助您
- 通过多种来源添加身份验证，例如：
- 通过更传统的
- 添加对
- 支持生成用于调用您的API和
- 分析用户如何、何时以及在哪里登录。
- 通过
创建免费Auth0账户
- 访问 Auth0 并点击
- 使用Google、GitHub或Microsoft账户登录。
问题报告
如果您发现了错误或需要请求新功能，请
作者
许可
本项目采用MIT许可。详细信息请见