Swift toolkit that lets you communicate efficiently with many of the Auth0 API functions and enables you to seamlessly integrate the Auth0 login.
- Requirements
- Installation
- Getting Started
- Next Steps
- What is Auth0?
- Create a Free Auth0 Account
- Issue Reporting
- Author
- License
- iOS 9+ / macOS 10.11+ / tvOS 9.0+ / watchOS 2.0+
- Xcode 12.x / 13.x
- Swift 4.x / 5.x
If you are using Cocoapods, add this line to your Podfile
:
pod 'Auth0', '~> 1.38'
Then run pod install
.
For more information on Cocoapods, check their official documentation.
If you are using Carthage, add the following line to your Cartfile
:
github "auth0/Auth0.swift" ~> 1.38
Then run carthage bootstrap --use-xcframeworks
.
For more information about Carthage usage, check their official documentation.
If you are using the Swift Package Manager, open the following menu item in Xcode:
File > Add Packages...
In the Search or Enter Package URL search box enter this url:
https://github.com/auth0/Auth0.swift.git
Then select the dependency rule and press Add Package.
For further reference on SPM, check its official documentation.
- Import Auth0 into your project.
import Auth0
- Present the Universal Login page.
Auth0
.webAuth()
.audience("https://YOUR_AUTH0_DOMAIN/userinfo")
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
This snippet sets the
audience
to ensure OIDC compliant responses, this can also be achieved by enabling the OIDC Conformant switch in your Auth0 dashboard underApplication / Settings / Advanced / OAuth
.
- If your app targets iOS <11, allow Auth0 to handle authentication callbacks (otherwise, skip this step). In your
AppDelegate.swift
, add the following:
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any]) -> Bool {
return Auth0.resumeAuth(url)
}
In order to use Auth0 you need to provide your Auth0 ClientId and Domain.
Auth0 ClientId & Domain can be found in your Auth0 Dashboard.
In your application bundle 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_AUTH0_CLIENT_ID</string>
<key>Domain</key>
<string>YOUR_AUTH0_DOMAIN</string>
</dict>
</plist>
As an alternative, you can pass the ClientId & Domain programmatically.
// When using Universal Login
Auth0.webAuth(clientId: "YOUR_AUTH0_CLIENT_ID", domain: "YOUR_AUTH0_DOMAIN")
// When using the Authentication API
Auth0.authentication(clientId: "YOUR_AUTH0_CLIENT_ID", domain: "YOUR_AUTH0_DOMAIN")
Callback URLs are the URLs that Auth0 invokes after the authentication process. Auth0 routes your application back to this URL and appends additional parameters to it, including a token. Since callback URLs can be manipulated, you will need to add your callback URL to the Allowed Callback URLsย field in the Auth0 Dashboard. This will enable Auth0 to recognize these URLs as valid. If omitted, authentication will not be successful.
In your application's Info.plist
file, register your iOS / macOS Bundle Identifer as a custom scheme.
<!-- Info.plist -->
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>None</string>
<key>CFBundleURLName</key>
<string>auth0</string>
<key>CFBundleURLSchemes</key>
<array>
<string>YOUR_BUNDLE_IDENTIFIER</string>
</array>
</dict>
</array>
If your
Info.plist
is not shown in this format, you can Right Click onInfo.plist
in Xcode and then select Open As / Source Code.
Finally, go to your Auth0 Dashboard and make sure that your application's Allowed Callback URLs field contains the following entry:
YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback
e.g. If your bundle identifier was com.company.myapp
and your Auth0 domain was company.auth0.com
, then this value would be:
com.company.myapp://company.auth0.com/ios/com.company.myapp/callback
Check out the iOS Swift QuickStart Guide to find out more about the Auth0.swift toolkit and explore our tutorials and sample projects.
Auth0
.authentication()
.userInfo(withAccessToken: accessToken)
.start { result in
switch result {
case .success(let profile):
print("User Profile: \(profile)")
case .failure(let error):
print("Failed with \(error)")
}
}
Use a Refresh Token to renew user credentials. It's recommended that you read and understand the refresh token process before implementing.
Auth0
.authentication()
.renew(withRefreshToken: refreshToken)
.start { result in
switch result {
case .success(let credentials):
print("Obtained new credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
You can make users land directly on the Signup page instead of the Login page by specifying the "screen_hint": "signup"
parameter when performing Web Authentication. Note that this can be combined with "prompt": "login"
, which indicates whether you want to always show the authentication page or you want to skip if there's an existing session.
Parameters | No existing session | Existing session |
---|---|---|
no extra parameters | Shows the login page | Redirects to the callback url |
"screen_hint": "signup" |
Shows the signup page | Redirects to the callback url |
"prompt": "login" |
Shows the login page | Shows the login page |
"prompt": "login", "screen_hint": "signup" |
Shows the signup page | Shows the signup page |
Auth0
.webAuth()
.parameters(["screen_hint": "signup"])
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
The
screen_hint
parameter can only be used with the New Universal Login Experience, not the Classic Experience.
This SDK uses ASWebAuthenticationSession
under the hood to perform Web Authentication on iOS 12+ and macOS. It is Apple's current API for performing web-based authentication. By default, ASWebAuthenticationSession
will store the Web Authentication cookies in Safari's shared cookie jar. This makes Single Sign On (SSO) possible, but it also means that ASWebAuthenticationSession
will prompt the user for consent.
To suppress the alert box, add the useEphemeralSession()
method to the chain. Doing so will make the SDK configure ASWebAuthenticationSession
with prefersEphemeralWebBrowserSession
enabled. This will disable SSO, but will also not display the consent alert that otherwise shows up when SSO is enabled.
prefersEphemeralWebBrowserSession
is only available on iOS 13+ and macOS, souseEphemeralSession()
will have no effect on older versions of iOS. For more information onprefersEphemeralBrowserSession
, check its documentation.
Auth0
.webAuth()
.audience("https://YOUR_AUTH0_DOMAIN/userinfo")
.useEphemeralSession()
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
If you're using useEphemeralSession()
, you do not need to call clearSession()
to perform logout as there will be no cookies to remove. Just deleting the credentials will suffice.
The credentials manager utility provides a convenience to securely store and retrieve the user's credentials from the Keychain.
let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
Store user credentials securely in the Keychain.
credentialsManager.store(credentials: credentials)
Credentials will automatically be renewed (if expired) using the refresh token. The scope offline_access
is required to ensure the refresh token is returned.
This method is not thread-safe, so if you're using Refresh Token Rotation you should avoid calling this method concurrently (might result in more than one renew request being fired, and only the first one will succeed). Note that this will also happen if you call this method repeatedly from the same thread, so we recommend using a queue to ensure that only one request can be in flight at any given time.
credentialsManager.credentials { error, credentials in
guard error == nil, let credentials = credentials else {
return print("Failed with \(error)")
}
print("Obtained credentials: \(credentials)")
}
Credentials can be cleared by using the clear
function, which clears credentials from the Keychain.
let didClear = credentialsManager.clear()
In addition, credentials can be cleared and the refresh token revoked using a single call to revoke
. This function will attempt to revoke the current refresh token stored by the credential manager and then clear credentials from the Keychain. If revoking the token results in an error, then the credentials are not cleared:
credentialsManager.revoke { error in
guard error == nil else {
return print("Failed to revoke refresh token: \(error)")
}
print("Success")
}
You can enable an additional level of user authentication before retrieving credentials using the biometric authentication supported by your device e.g. Face ID or Touch ID.
credentialsManager.enableBiometrics(withTitle: "Touch to Login")
If needed, you are able to specify specific LAPolicy
to be used - i.e. you might want to support FaceID, but allow fallback to pin code.
credentialsManager.enableBiometrics(withTitle: "Touch or enter pincode to Login", evaluationPolicy: .deviceOwnerAuthentication)
If you've added the Sign In with Apple flow to your app, you can use the string value from the authorizationCode
property obtained after a successful Apple authentication to perform a token exchange for Auth0 tokens.
Auth0
.authentication()
.login(appleAuthorizationCode: authCode)
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
Find out more about Setting up Sign in with Apple with Auth0.
If you've added the Facebook Login flow to your app, after a successful Faceboook authentication you can request a Session Access Token and the Facebook user profile, and use them to perform a token exchange for Auth0 tokens.
Auth0
.authentication()
.login(facebookSessionAccessToken: sessionAccessToken, profile: profile)
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
Find out more about Setting up Facebook Login with Auth0.
Organizations is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) applications.
Using Organizations, you can:
- Represent teams, business customers, partner companies, or any logical grouping of users that should have different ways of accessing your applications, as organizations.
- Manage their membership in a variety of ways, including user invitation.
- Configure branded, federated login flows for each organization.
- Implement role-based access control, such that users can have different roles when authenticating in the context of different organizations.
- Build administration capabilities into your products, using Organizations APIs, so that those businesses can manage their own organizations.
Note that Organizations is currently only available to customers on our Enterprise and Startup subscription plans.
Auth0.webAuth()
.organization(organizationId)
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
To accept organization invitations your app needs to support Universal Links. Tapping on the invitation link should open your app (invitations links are https
only).
When your app gets opened by an invitation link, grab the invitation URL and pass it to .invitationURL()
:
if let url = URLContexts.first?.url {
// You need to wait for the app to enter the foreground before launching WebAuth
_ = NotificationCenter.default.publisher(for: UIApplication.didBecomeActiveNotification)
.subscribe(on: DispatchQueue.main)
.prefix(1)
.sink { _ in
Auth0.webAuth()
.invitationURL(url)
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
}
}
The Authentication API exposes AuthN/AuthZ functionality of Auth0, as well as the supported identity protocols like OpenID Connect, OAuth 2.0, and SAML. We recommend using Universal Login but if you wish to build your own UI, you can use our API endpoints to do so. However, some Auth flows (grant types) are disabled by default so you must enable them via your Auth0 Dashboard as explained in Update Grant Types.
These are the required Grant Types that needs to be enabled in your application:
- Password: For login with username/password using a realm (or connection name). If you set the grants via API you should activate both
http://auth0.com/oauth/grant-type/password-realm
andpassword
, otherwise Auth0 Dashboard will take care of activating both whenPassword
is enabled.
Auth0
.authentication()
.login(usernameOrEmail: "[email protected]",
password: "secret-password",
realm: "Username-Password-Authentication",
scope: "openid profile")
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error):
print("Failed with \(error)")
}
}
This requires
Password
Grant orhttp://auth0.com/oauth/grant-type/password-realm
.
Auth0
.authentication()
.createUser(email: "[email protected]",
password: "secret-password",
connection: "Username-Password-Authentication",
userMetadata: ["first_name": "First", "last_name": "Last"])
.start { result in
switch result {
case .success(let user):
print("User Signed up: \(user)")
case .failure(let error):
print("Failed with \(error)")
}
}
You can request more information about a user's profile and manage the user's metadata by accessing the Auth0 Management API. For security reasons native mobile applications are restricted to a subset of User based functionality.
You can find a detailed guide in this iOS Swift QuickStart.
Auth0
.users(token: idToken)
.link("user identifier", withOtherUserToken: "another user token")
.start { result in
switch result {
case .success(let userInfo):
print("User: \(userInfo)")
case .failure(let error):
print("Failed with \(error)")
}
}
If you are using Custom Domains and need to call an Auth0 endpoint
such as /userinfo
, please use the Auth0 domain specified for your Application in the Auth0 Dashboard.
Example: .audience("https://YOUR_AUTH0_DOMAIN/userinfo")
Users of Auth0 Private Cloud with Custom Domains still on the legacy behavior need to specify a custom issuer to match the Auth0 domain before starting the authentication. Otherwise, the ID Token validation will fail.
Example: .issuer("https://YOUR_AUTH0_DOMAIN/")
If you are using the Bot Detection feature and performing database login/signup via the Authentication API, you need to handle the isVerificationRequired
error. It indicates that the request was flagged as suspicious and an additional verification step is necessary to log the user in. That verification step is web-based, so you need to use Universal Login to complete it.
let email = "[email protected]"
let realm = "Username-Password-Authentication"
let scope = "openid profile"
Auth0
.authentication()
.login(usernameOrEmail: email,
password: "secret-password",
realm: realm,
scope: scope)
.start { result in
switch result {
case .success(let credentials):
print("Obtained credentials: \(credentials)")
case .failure(let error as AuthenticationError) where error.isVerificationRequired:
DispatchQueue.main.async {
Auth0
.webAuth()
.connection(realm)
.scope(scope)
.useEphemeralSession()
// โ๐ผ Otherwise a session cookie will remain
.parameters(["login_hint": email])
// โ๐ผ So the user doesn't have to type it again
.start { result in
// Handle result
}
}
case .failure(let error):
print("Failed with \(error)")
}
}
In the case of signup, you can add an additional parameter to make the user land directly on the signup page.
.parameters(["login_hint": email, "screen_hint": "signup"])
Check out how to set up Universal Login in the Getting Started section.
You don't need to handle this error if you're using the deprecated login methods.
To enable Auth0.swift to log HTTP request and OAuth2 flow for debugging you can call the following method in either WebAuth
, Authentication
or Users
object:
var auth0 = Auth0.authentication()
auth0.logging(enabled: true)
Then for a OAuth2 authentication you'll see something similar to the following:
Safari: https://samples.auth0.com/authorize?.....
URL: com.auth0.myapp://samples.auth0.com/ios/com.auth0.MyApp/callback?...
POST https://samples.auth0.com/oauth/token HTTP/1.1
Content-Type: application/json
{"code":"...","client_id":"...","grant_type":"authorization_code","redirect_uri":"com.auth0.MyApp:\/\/samples.auth0.com\/ios\/com.auth0.MyApp\/callback","code_verifier":"..."}
HTTP/1.1 200
Pragma: no-cache
Content-Type: application/json
Strict-Transport-Security: max-age=3600
Date: Thu, 09 Jun 2016 19:04:39 GMT
Content-Length: 57
Cache-Control: no-cache
Connection: keep-alive
{"access_token":"...","token_type":"Bearer"}
Set this flag only when DEBUGGING to avoid leaking user's credentials in the device log.
Auth0 helps you to:
- Add authentication with multiple sources, either social identity providers such as Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce (amongst others), or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS, or any SAML Identity Provider.
- Add authentication through more traditional username/password databases.
- Add support for linking different user accounts with the same user.
- Support for generating signed JSON Web Tokens to call your APIs and flow the user identity securely.
- Analytics of how, when, and where users are logging in.
- Pull data from other sources and add it to the user profile through JavaScript rules.
- Go to Auth0 and click Sign Up.
- Use Google, GitHub, or Microsoft Account to login.
If you have found a bug or to request a feature, please raise an issue. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
This project is licensed under the MIT license. See the LICENSE file for more info.