Lock.swift: Configuration Options
There are numerous options to configure Lock's behavior listed below. In addition, there are also quite a few options available to alter Lock's appearance and style in the Style Customization Options page.
Configuring Lock's behavior
Configuration options can be added to your Lock initialization using withOptions
.
Lock
.classic()
.withOptions {
$0.closable = true
$0.usernameStyle = [.Username]
$0.allow = [.Login, .ResetPassword]
}
.present(from: self)
Was this helpful?
Behavior Options
closable
Allows Lock to be dismissed by the user. By default this is false
.
.withOptions {
$0.closable = true
}
Was this helpful?
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. See the documentation on Scopes for more information about authentication scopes.
.withOptions {
$0.scope = "openid name email picture"
}
Was this helpful?
Refresh Tokens
Specifying the offline_access
scope in your Lock options will allow a Refresh Token to be returned along with the access_token and the id_token. Refresh Tokens can be saved and used to acquire a new Access Token when the old one expires. For more information about using Refresh Tokens for Auth0 authentication, take a look at the reference documentation for the Auth0.Swift SDK, which you would use to implement Refresh Tokens, or at the Swift Quickstart Guide, which provides a comprehensive example of use of Auth0 in Swift development, including the management of Refresh Tokens.
termsOfService
By default Lock will use Auth0's Terms of Service and Privacy Policy, but other URLs can be filled in to link to other terms and policies.
.withOptions {
$0.termsOfService = "https://mycompany.com/terms"
$0.privacyPolicy = "https://mycompany.com/privacy"
}
Was this helpful?
Show Terms of Service
Database connections display the Terms of Service dialog. Default is true
. Note that the Terms of Service will always be shown if the mustAcceptTerms
flag is enabled.
.withOptions {
$0.showTerms = true
}
Was this helpful?
Require users to accept the Terms of Service
Database connection require explicit acceptance of the Terms of Service.
.withOptions {
$0.mustAcceptTerms = true
}
Was this helpful?
Web Authentication Options
leeway
Clock skew used for ID token validation. It expands the time window in which the ID token will still be considered valid, to account for the difference between server time and client time. By default is 60000 milliseconds (60 seconds).
.withOptions {
$0.leeway = 30000 // 30 seconds
}
Was this helpful?
maxAge
Allowable elapsed time (in milliseconds) since the user last authenticated. Used for ID token validation. If set, the ID token will contain an auth_time
claim with the authentication timestamp. Defaults to nil
.
.withOptions {
$0.maxAge = 86400000 // 1 day
}
Was this helpful?
Database options
allow
Which database screens will be accessible, the default is enable all screens such as .Login, .Signup, .ResetPassword
.
.withOptions {
$0.allow = [.Login, .ResetPassword]
}
Was this helpful?
initialScreen
The first screen to present to the user. The default is .Login
, other options include .Signup
and ResetPassword
.
.withOptions {
$0.initialScreen = .Login
}
Was this helpful?
usernameStyle
Specify the type of identifier the login will require. The default is either: [.Username, .Email]
, but it can also accept [.Username]
or [.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.usernameStyle = [.Username]
}
Was this helpful?
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. Capturing additional signup fields here will store them in the user_metadata
, which you can read more about in Metadata. Note that you must specify the icon to use with your custom text field.
.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))
]
}
Was this helpful?
You can also specify icons from other bundles, such as in the following example: CustomTextField(name: "slack_handle", placeholder: "Slack Handle", icon: LazyImage(name: "ic_slack", bundle: Bundle(identifier: "CustomBundle")))
Enterprise Options
There are also configuration options specific to Enterprise connections:
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.
.withOptions {
$0.enterpriseConnectionUsingActiveAuth = ["enterprisedomain.com"]
}
Was this helpful?
activeDirectoryEmailAsUsername
When in credential authentication mode, should the user require their email as an identifier? The default is false
, and instead requires a username.
.withOptions {
$0.activeDirectoryEmailAsUsername = true
}
Was this helpful?
Logging Options
Lock provides options to easily turn on and off logging capabilities, as well as adjust other logging related settings.
logLevel
By default this is .off
, Syslog logging levels are supported.
.withOptions {
$0.logLevel = .all
}
Was this helpful?
logHttpRequest
Whether or not to log Auth0.swift API requests. By default this is false
.
.withOptions {
$0.logHttpRequest = true
}
Was this helpful?
loggerOutput
Specify logger output handler, by default this uses the print
statement.
.withOptions {
$0.loggerOutput = CleanroomLockLogger()
}
Was this helpful?
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. Below is an example of usage handling logger output with 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)
}
}
Was this helpful?