Guardian.swift (iOS)

Guardian is Auth0's multi-factor authentication (MFA) service that provides a simple, safe way for you to implement MFA.

Auth0 is an authentication broker that supports social identity providers as well as enterprise identity providers such as Active Directory, LDAP, Google Apps and Salesforce.

This SDK allows you to integrate Auth0's Guardian multi-factor service in your own app, transforming it in the second factor itself. Your users will get all the benefits of our frictionless multi-factor authentication from your app.

Requirements

iOS 10+ and Swift 4.1 is required in order to use Guardian.

Before getting started

To use this SDK you have to configure your tenant's Guardian service with your own push notification credentials, otherwise you would not receive any push notifications. Please read the docs about how to accomplish that.

Install

CocoaPods

Guardian.swift is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Guardian', '~> 1.4.2'

Carthage

In your Cartfile add this line

github "auth0/Guardian.swift" ~> 1.4.2

Usage

Guardian is the core of the SDK. To get things going you'll have to import the library:

import Guardian

Set the auth0 domain for your tenant:

let domain = "https://<tenant>.<locality>.auth0.com/appliance-mfa"

alternatively you can use the custom domain if you configured one:

let domain = "https://<custom>/appliance-mfa"

Enroll

An enrollment is a link between the second factor and an Auth0 account. When an account is enrolled you'll need it to provide the second factor required to verify the identity.

For an enrollment you need the following things, besides your Guardian Domain:

Enrollment Uri: The value encoded in the QR Code scanned from Guardian Web Widget or in your enrollment ticket sent to you, e.g. by email.
APNS Token: Apple APNS token for the device and MUST be a Stringcontaining the 64 bytes (expressed in hexadecimal format)
Signing & Verification Key: A RSA (Private/Public) key pair used to assert your identity with Auth0 Guardian

In case your app is not yet using push notifications or you're not familiar with it, you should check their docs.

after your have all of them, you can enroll your device

Guardian
        .enroll(forDomain: "{YOUR_GUARDIAN_DOMAIN}",
                usingUri: "{ENROLLMENT_URI}",
                notificationToken: "{APNS_TOKEN}",
                signingKey: signingKey,
                verificationKey: verificationKey
                )
        .start { result in
            switch result {
            case .success(let enrolledDevice):
                // success, we have the enrollment device data available
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

On success you'll obtain the enrollment information, that should be secured stored in your application. This information includes the enrollment identifier, and the token for Guardian API associated to your device for updating or deleting your enrollment.

Signing & Verification Keys

Guardian.swift provides a convenience class to generate a signing key

let signingKey = try DataRSAPrivateKey.new()

this key only exists in memory but you can obtain its Data representation and store securely e.g. in an encrypted SQLiteDB

// Store data
let data = signingKey.data
// performthe storage

// Load from Storage
let loadedKey = try DataRSAPrivateKey(data: data)

But if you just want to store inside iOS Keychain

let signingKey = try KeychainRSAPrivateKey.new(with: "com.myapp.mytag")

It will create it and store it automatically under the supplied tag, if you want to retrieve it using the tag

let signingKey = try KeychainRSAPrivateKey(tag: "com.myapp.mytag")

The tags should be unique since it's the identifier of each key inside iOS Keychain.

and for the verification key, we can just obtain it from any SigningKey like this

let verificationKey = try signingKey.verificationKey()

Allow a login request

Once you have the enrollment in place, you will receive a push notification every time the user has to validate his identity with MFA.

Guardian provides a method to parse the data received from APNs and return a Notification instance ready to be used.

if let notification = Guardian.notification(from: userInfo) {
    // we have received a Guardian push notification
}

Once you have the notification instance, you can easily allow the authentication request by using the allow method. You'll also need some information from the enrolled device that you obtained previously. In case you have more than one enrollment, you'll have to find the one that has the same id as the notification (the enrollmentId property).

When you have the information, device parameter is anything that implements the protocol AuthenticatedDevice

struct Authenticator: Guardian.AuthenticationDevice {
    let signingKey: SigningKey
    let localIdentifier: String
}

Local identifier is the local id of the device, by default on enroll UIDevice.current.identifierForVendor

Then just call

Guardian
        .authentication(forDomain: "{YOUR_GUARDIAN_DOMAIN}", device: device)
        .allow(notification: notification)
        .start { result in
            switch result {
            case .success:
                // the auth request was successfuly allowed
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

Reject a login request

To deny an authentication request just call reject instead. You can also send a reject reason if you want. The reject reason will be available in the guardian logs.

Guardian
        .authentication(forDomain: "{YOUR_GUARDIAN_DOMAIN}", device: device)
        .reject(notification: notification)
        // or reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // the auth request was successfuly rejected
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

Unenroll

If you want to delete an enrollment -for example if you want to disable MFA- you can make the following request:

Guardian
        .api(forDomain: "{YOUR_GUARDIAN_DOMAIN}")
        .device(forEnrollmentId: "{USER_ENROLLMENT_ID}", token: "{ENROLLMENT_DEVICE_TOKEN}")
        .delete()
        .start { result in
            switch result {
            case .success:
                // success, the enrollment was deleted
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }

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 account in Auth0

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.

auth0 / Guardian.swift

readme