Guardian.swift iOS SDK

Guardian.swift allows you to integrate Auth0's Guardian multi-factor service in your own iOS app, transforming it into the second factor itself. Your users will get all the benefits of our frictionless multi-factor authentication from your app. To learn more, read Getting Started with Apple Push Notification Service.

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

• 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. To learn more, read Configure Push Notifications for MFA.

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

pod 'Guardian', '~> 1.1.0'

Add this line to your Cartfile:

github "auth0/Guardian.swift" ~> 1.1.0

1. Go to Dashboard > Security > Multi-factor Auth.

   

2. Toggle Push Notification on to enable it.

3. Configure push notifications.

Guardian is the core of the SDK. To use the SDK, import the library:

import Guardian

Then you'll need the Auth0 Guardian domain for your account:

let domain = "{YOUR_ACCOUNT_NAME}.guardian.auth0.com"

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. If your app is not yet using push notifications or you're not familiar with it, see Apple Push Notification Service Overview for details.

For an enrollment you need the following information, besides your Guardian domain:

After you have the information, you can enroll your device:

Guardian
        .enroll(forDomain: "{yourGuardianDomain}",
                usingUri: "{enrollmentUri}",
                notificationToken: "{apnsToken}",
                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.

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 in, for example, an encrypted SQLiteDB:

// Store data
let data = signingKey.data
// perform the 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")

The above example creates a key and stores it automatically under the supplied tag. If you want to retrieve it, you can use the tag:

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

For the verification key, we can just obtain it from any SigningKey, for example:

let verificationKey = try signingKey.verificationKey()

Once you have the enrollment in place, you will receive a push notification every time the user has to validate their 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: notificationPayload) {
    // 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: "{yourGuardianDomain}", 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
            }
        }

To deny an authentication request call reject instead. You can also send an optional reject reason. The reject reason will appear in the Guardian logs.

Guardian
        .authentication(forDomain: "{yourGuardianDomain}", 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
            }
        }

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

Guardian
        .api(forDomain: "{yourGuardianDomain}")
        .device(forEnrollmentId: "{userEnrollmentId}", token: "{enrollmentDeviceToken}")
        .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
            }
        }