Auth0.swift

Swift toolkit that lets you communicate efficiently with many of the Auth0 API functions and enables you to seamlessly integrate the Auth0 login.

Important Notice

Behaviour changes in iOS 13 related to Web Authentication require that developers using Xcode 11 with this library must compile using Swift 5.x. This should be the default setting applied when updating, unless it has been manually set. However, we recommend checking that this value is set correctly.

Table of Contents

• Requirements
• Installation
• Getting Started
• Next Steps
• What is Auth0?
• Create a Free Auth0 Account
• Issue Reporting
• Author
• License

Requirements

• iOS 9+ / macOS 10.11+ / tvOS 9.0+ / watchOS 2.0+
• Xcode 10.x / 11.x
• Swift 4.x / 5.x

Installation

Cocoapods

If you are using Cocoapods, add this line to your Podfile:

pod 'Auth0', '~> 1.26'

Then run pod install.

For more information on Cocoapods, check their official documentation.

Carthage

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

github "auth0/Auth0.swift" ~> 1.26

Then run carthage bootstrap.

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

Upgrade Notes

If you are using the clearSession method in iOS 11+, you will need to ensure that the Callback URL has been added to the Allowed Logout URLs section of your application in the Auth0 Dashboard.

Getting Started

Authentication with Universal Login (iOS / macOS 10.15+)

1. Import Auth0 into your project.

import Auth0

2. 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 under Application / Settings / Advanced / OAuth. For more information please check the OIDC Conformant Authentication Adoption Guide.

3. Allow Auth0 to handle authentication callbacks. In your AppDelegate.swift, add the following:

iOS

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

macOS

func application(_ application: NSApplication, open urls: [URL]) {
    Auth0.resumeAuth(urls)
}

Configuration

In order to use Auth0 you need to provide your Auth0 ClientId and Domain.

Auth0 ClientId & Domain can be found in your Auth0 Dashboard.

Adding Auth0 Credentials

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>

Configure Callback URLs (iOS / macOS)

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 on Info.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

Next Steps

Learning Resources

Check out the iOS Swift QuickStart Guide to find out more about the Auth0.swift toolkit and explore our tutorials and sample projects.

Common Tasks

Retrieve user information

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

Renew user credentials

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

Disable Single Sign On (iOS 13+ / macOS)

Add the useEphemeralSession() method to the chain to disable SSO on iOS 13+ and macOS. This way the system will not display the consent popup that otherwise shows up when SSO is enabled. It has no effect on older versions of iOS.

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

Credentials Management Utility (iOS / macOS / tvOS)

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 Credentials

Store user credentials securely in the KeyChain.

credentialsManager.store(credentials: credentials)

Retrieve stored 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.

credentialsManager.credentials { error, credentials in
    guard error == nil, let credentials = credentials else { 
        return print("Failed with \(error)") 
    }
    print("Obtained credentials: \(credentials)")
}

Clearing credentials and revoking refresh tokens

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

Biometric authentication

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

Native Social Login

Sign in With Apple

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.

Facebook Login

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.

Authentication API (iOS / macOS / tvOS)

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 Application 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 and password, otherwise Auth0 Dashboard will take care of activating both when Password is enabled.

Login with database connection (via Realm)

Auth0
    .authentication()
    .login(
        usernameOrEmail: "[email protected]",
        password: "secret-password",
        realm: "Username-Password-Authentication",
        scope: "openid")
     .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 or http://auth0.com/oauth/grant-type/password-realm.

Sign Up with database connection

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

Custom Domains

If you are using the Custom Domains feature and need to use 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")

Management API (Users)

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.

Link an account

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

Logging

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.

What is Auth0?

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.

Create a Free Auth0 Account

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

Author

Auth0

License

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