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.

Requirements

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

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.

Installation

Carthage

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

github "auth0/Auth0.swift" ~> 1.18

Then run carthage bootstrap.

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

Cocoapods

If you are using Cocoapods, add these lines to your Podfile:

use_frameworks!
pod 'Auth0', '~> 1.18'

Then run pod install.

For further reference on Cocoapods, 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 hosted login page (iOS Only)

Import Auth0 into your project.

import Auth0

Present the hosted 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 this documentation.

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

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

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

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

Credentials Management Utility (iOS Only)

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

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

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()
    .tokenExchange(withAppleAuthorizationCode: 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.

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 our Hosted Login Page 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 will need to enable them via your Auth0 Dashboard as explained in this guide.

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: "support@auth0.com",
        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: "support@auth0.com",
        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 authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont 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

Go to Auth0 and click Sign Up.
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.

andrewfoghel/Auth0.swift