Spezi Access Guard

Allows developers to easily guard a SwiftUI view with an access code or biometrics.


4-digit Numeric Access Code	Face ID with Access Code Fallback

Overview

The Access Guard module allows developers to guard a SwiftUI view with an access code or biometrics and allows users to set or reset their access codes.

For more information, please refer to the API documentation.

Setup

1. Add Spezi Access Guard as a Dependency

First, you will need to add the SpeziAccessGuard Swift package to your app in Xcode or Swift package.

2. Register the Access Guard Module

Important

If your application is not yet configured to use Spezi, follow the Spezi setup article to set up the core Spezi infrastructure.

You can configure the AccessGuardModule in the SpeziAppDelegate as follows.

Access Code

In the example below, we configure the AccessGuardModule with one access guard that uses an access code and is identified by ExampleIdentifier. The codeOptions property defines the type of code used, which in this case is a 4-digit numeric code. The timeout property defines when the view should be locked based on the time the scene is not in the foreground, in seconds.

import Spezi
import SpeziAccessGuard


class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            AccessGuardModule(
                [
                    .code(identifier: "ExampleIdentifier", codeOptions: .fourDigitNumeric, timeout: 15 * 60)
                ]
            )
        }
    }
}

Biometric with Access Code Fallback

The AccessGuardModule can also be configured with an access guard that uses either Face ID or Touch ID, if the user has one of these enabled on their device (see Face ID or Touch ID for more information). This is shown in the example below. If biometrics are not available or biometric authentication fails, the user will be asked to enter their access code instead.

import Spezi
import SpeziAccessGuard


class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            AccessGuardModule(
                [
                    .biometric(identifier: "ExampleIdentifier", codeOptions: .fourDigitNumeric, timeout: 15 * 60)
                ]
            )
        }
    }
}

Fixed Code

The AccessGuardModule can also be configured with a fixed code passed as a string. This is shown in the example below.

import Spezi
import SpeziAccessGuard


class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            AccessGuardModule(
                [
                    .fixed(identifier: "ExampleIdentifier", code: "1234", codeOptions: .fourDigitNumeric, timeout: 15 * 60)
                ]
            )
        }
    }
}

Multiple Guards

The AccessGuardModule can also be configured with multiple access guards that use different mechanisms, as shown below. In this example, we create both a biometric-based access guard and an access guard with a fixed code that can be used on different views in the application. Each access guard must have a unique identifier.

import Spezi
import SpeziAccessGuard


class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            AccessGuardModule(
                [
                    .biometric(identifier: "ExampleIdentifier"),
                    .fixed(identifier: "ExampleFixedIdentifier", code: "1234")
                ]
            )
        }
    }
}

Note

You can learn more about a Module in the Spezi documentation.

3. Configure target properties

To ensure that your application has the necessary permissions for biometrics, follow the steps below to configure the target properties within your Xcode project:

Open your project settings in Xcode by selecting PROJECT_NAME > TARGET_NAME > Info tab.
Add a key named Privacy - Face ID Usage Description to the Custom iOS Target Properties (the Info.plist file) and provide a string value that describes why your application needs access to Face ID.

This entry is mandatory for apps that utilize biometrics. Failing to provide it will result in your app being unable to access these features.

Examples

Setting an Access Code

Using SetAccessGuard, we can create a view that allows the user to set their access code. This step must be done before access guards can be used to guard a SwiftUI view, with the exception of an access guard that uses a fixed code. (Note that the access guard will be automatically unlocked after the passcode is set until it is locked or times out.)

import SpeziAccessGuard

struct SetAccessCode: View {
    var body: some View {
        SetAccessGuard(identifier: "ExampleIdentifier")
    }
}

Guarding Access to a SwiftUI View

Now, we can use the AccessGuarded view to guard access to a SwiftUI view with an access code.

import SpeziAccessGuard

struct ProtectedContent: View {    
    var body: some View {
        AccessGuarded("ExampleIdentifier") {
            Text("Secured content...")
        }
    }
}

Locking an Access Guard

The access guard will lock automatically when it times out. However, we can also lock an access guard directly using the lock(identifier:) method. Here, we add a toolbar item with a button that will lock the access guard.

struct ProtectedContent: View {
    @Environment(AccessGuard.self) private var accessGuard
    
    var body: some View {
        AccessGuarded("ExampleIdentifier") {
            Text("Secured content...")
        }
        .toolbar {
            ToolbarItem {
                Button("Lock Access Guard") {
                    try? accessGuard.lock(identifier: "ExampleIdentifier")
                }
            }
        }
    }
}

Resetting an Access Guard

To remove the access code and all information from an access guard, we can use the resetAccessCode(for:) method. Here, we add a toolbar item with a button that will reset the access guard.

struct ProtectedContent: View {
    @Environment(AccessGuard.self) private var accessGuard
    
    var body: some View {
        AccessGuarded("ExampleIdentifier") {
            Text("Secured content...")
        }
        .toolbar {
            ToolbarItem {
                Button("Reset Access Guard") {
                    try? accessGuard.resetAccessCode(for: "ExampleIdentifier")
                }
            }
        }
    }
}