🔐 Mastering Local Authentication

Secure your app with Face ID and Touch ID! Complete guide from biometric auth to password replacement.

⭐ Difficulty: ⭐ ⏱️ Est. Time: 30min 📂 System & Network

✨ Local Authentication is?

Local Authentication is a framework that authenticates users using Face ID, Touch ID, or device passcode. It provides safe and convenient authentication for login, payment authorization, and accessing sensitive information. All biometric data is processed on-device only and never sent to a server.

📦 Key Features

Feature Overview

✅ Face ID / Touch ID authentication
✅ Device passcode authentication
✅ Check biometric availability
✅ Handle authentication failure and retry
✅ Custom authentication UI
✅ Password fallback authentication

🔍 Checking Biometric Availability

BiometryCheck.swift

import LocalAuthentication

func checkBiometryAvailability() -> (Bool, String) {
    let context = LAContext()
    var error: NSError?

    // Check if biometric authentication is available
    let canEvaluate = context.canEvaluatePolicy(
        .deviceOwnerAuthenticationWithBiometrics,
        error: &error
    )

    if canEvaluate {
        // Check biometric type
        switch context.biometryType {
        case .faceID:
            return (true, "Face ID available")
        case .touchID:
            return (true, "Touch ID available")
        case .opticID:
            return (true, "Optic ID available")
        case .none:
            return (false, "Biometrics not supported")
        @unknown default:
            return (false, "Unknown type")
        }
    } else {
        // Error handling
        if let error = error {
            switch LAError.Code(rawValue: error.code) {
            case .biometryNotEnrolled:
                return (false, "Biometrics not enrolled")
            case .biometryNotAvailable:
                return (false, "Biometrics not supported")
            case .passcodeNotSet:
                return (false, "Device passcode not set")
            default:
                return (false, error.localizedDescription)
            }
        }
        return (false, "Unknown error")
    }
}

// Usage example
let (available, message) = checkBiometryAvailability()
print(message)  // "Face ID available"

🔐 Basic Biometric Authentication

BasicAuth.swift

import LocalAuthentication

func authenticateUser() async -> Bool {
    let context = LAContext()
    var error: NSError?

    // Check if biometric authentication is available
    guard context.canEvaluatePolicy(
        .deviceOwnerAuthenticationWithBiometrics,
        error: &error
    ) else {
        print("biometric authentication 불가: \(error?.localizedDescription ?? "")")
        return false
    }

    do {
        // Authentication 시도
        let success = try await context.evaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            localizedReason: "앱에 로그인하려면 인증이 필요합니다"
        )
        return success
    } catch let error {
        // Authentication failed 처리
        if let laError = error as? LAError {
            switch laError.code {
            case .authenticationFailed:
                print("Authentication failed (얼굴/지문 불일치)")
            case .userCancel:
                print("사용자가 취소함")
            case .userFallback:
                print("enter password 선택")
            case .systemCancel:
                print("시스템이 취소 (앱 전환 등)")
            case .biometryLockout:
                print("너무 많은 시도로 잠김")
            default:
                print("인증 Error: \(laError.localizedDescription)")
            }
        }
        return false
    }
}

// Usage example
let authenticated = await authenticateUser()
if authenticated {
    print("로그인 성공!")
}

🔑 Device Passcode Authentication

PasscodeAuth.swift

import LocalAuthentication

func authenticateWithPasscode() async -> Bool {
    let context = LAContext()

    // 생체 Authentication failed 시 기기 enter passcode 허용
    context.localizedFallbackTitle = "enter passcode"

    do {
        let success = try await context.evaluatePolicy(
            .deviceOwnerAuthentication,  // biometric authentication + 기기 암호
            localizedReason: "계정에 접근하려면 인증하세요"
        )
        return success
    } catch {
        print("Authentication failed: \(error.localizedDescription)")
        return false
    }
}

// Custom 취소 버튼 텍스트
func authenticateWithCustomButton() async -> Bool {
    let context = LAContext()
    context.localizedCancelTitle = "나중에"
    context.localizedFallbackTitle = "Password로 로그인"

    do {
        return try await context.evaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            localizedReason: "민감한 정보에 접근합니다"
        )
    } catch {
        return false
    }
}

📱 SwiftUI Integration

AuthView.swift

import SwiftUI
import LocalAuthentication

struct AuthenticationView: View {
    @State private var isAuthenticated = false
    @State private var showError = false
    @State private var errorMessage = ""

    var body: some View {
        VStack(spacing: 20) {
            if isAuthenticated {
                // Authentication 후 화면
                VStack(spacing: 16) {
                    Image(systemName: "checkmark.circle.fill")
                        .font(.system(size: 80))
                        .foregroundStyle(.green)

                    Text("Authentication successful")
                        .font(.title)
                        .bold()

                    Text("안전하게 로그인되었습니다")
                        .foregroundStyle(.secondary)

                    Button("로그아웃") {
                        isAuthenticated = false
                    }
                    .buttonStyle(.borderedProminent)
                }
            } else {
                // 로그인 화면
                VStack(spacing: 16) {
                    Image(systemName: "faceid")
                        .font(.system(size: 80))
                        .foregroundStyle(.blue)

                    Text("생체 Authentication required")
                        .font(.title)
                        .bold()

                    Text("Face ID로 안전하게 로그인하세요")
                        .foregroundStyle(.secondary)

                    Button("인증하기") {
                        Task {
                            await authenticate()
                        }
                    }
                    .buttonStyle(.borderedProminent)
                }
            }
        }
        .padding()
        .alert("Authentication failed", isPresented: $showError) {
            Button("OK", role: .cancel) { }
        } message: {
            Text(errorMessage)
        }
        .onAppear {
            // App 시작 시 자동 인증 시도
            Task {
                await authenticate()
            }
        }
    }

    func authenticate() async {
        let context = LAContext()
        var error: NSError?

        guard context.canEvaluatePolicy(
            .deviceOwnerAuthentication,
            error: &error
        ) else {
            errorMessage = error?.localizedDescription ?? "인증 불가"
            showError = true
            return
        }

        do {
            let success = try await context.evaluatePolicy(
                .deviceOwnerAuthentication,
                localizedReason: "앱 접근을 for 인증이 필요합니다"
            )

            await MainActor.run {
                isAuthenticated = success
            }
        } catch let error {
            await MainActor.run {
                errorMessage = error.localizedDescription
                showError = true
            }
        }
    }
}

🔒 Practical Example: Protecting Sensitive Data

SecureDataView.swift

import SwiftUI
import LocalAuthentication

struct SecureDataView: View {
    @State private var isUnlocked = false
    @State private var sensitiveData = "****-****-****-1234"

    var body: some View {
        List {
            Section("계좌 정보") {
                HStack {
                    Text("계좌번호")
                    Spacer()
                    Text(isUnlocked ? "1234-5678-9012-3456" : "****-****-****-3456")
                        .font(.system(.body, design: .monospaced))
                }

                HStack {
                    Text("잔액")
                    Spacer()
                    Text(isUnlocked ? "1,234,567원" : "*******원")
                }
            }

            Section {
                Button(isUnlocked ? "정보 숨기기" : "정보 보기") {
                    if isUnlocked {
                        isUnlocked = false
                    } else {
                        Task {
                            await authenticate()
                        }
                    }
                }
            }
        }
        .navigationTitle("내 계좌")
    }

    func authenticate() async {
        let context = LAContext()

        do {
            let success = try await context.evaluatePolicy(
                .deviceOwnerAuthentication,
                localizedReason: "민감한 계좌 정보를 보려면 인증하세요"
            )

            if success {
                await MainActor.run {
                    withAnimation {
                        isUnlocked = true
                    }
                }
            }
        } catch {
            print("Authentication failed")
        }
    }
}

⏱️ Reusing Authentication Context

ContextReuse.swift

import LocalAuthentication

class AuthenticationManager {
    private let context = LAContext()

    init() {
        // Authentication 유효 시간 설정 (기본 10초)
        context.touchIDAuthenticationAllowableReuseDuration = 30  // 30초
    }

    func authenticate(reason: String) async -> Bool {
        do {
            // 30초 내 재인증 시 biometric authentication 생략
            return try await context.evaluatePolicy(
                .deviceOwnerAuthenticationWithBiometrics,
                localizedReason: reason
            )
        } catch {
            return false
        }
    }

    func invalidate() {
        // 컨텍스트 무효화 (즉시 재Authentication required)
        context.invalidate()
    }
}

// Usage example
let authManager = AuthenticationManager()

// 첫 인증 (생체 Authentication required)
let success1 = await authManager.authenticate(reason: "결제 승인")

// 30초 내 재인증 (biometric authentication 생략)
let success2 = await authManager.authenticate(reason: "추가 결제")

// 로그아웃 시 컨텍스트 무효화
authManager.invalidate()

🎯 Advanced Features: Domain State

DomainState.swift

import LocalAuthentication

class BiometricStateMonitor {
    private var domainState: Data?

    func saveBiometricState() {
        let context = LAContext()
        var error: NSError?

        guard context.canEvaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            error: &error
        ) else {
            return
        }

        // 현재 biometric authentication save state
        domainState = context.evaluatedPolicyDomainState
        UserDefaults.standard.set(domainState, forKey: "BiometricState")
    }

    func hasBiometricChanged() -> Bool {
        let context = LAContext()
        var error: NSError?

        guard context.canEvaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            error: &error
        ) else {
            return true
        }

        // Save된 상태와 비교
        guard let savedState = UserDefaults.standard.data(forKey: "BiometricState") else {
            return true
        }

        let currentState = context.evaluatedPolicyDomainState
        return savedState != currentState
    }

    func handleBiometricChange() {
        if hasBiometricChanged() {
            print("⚠️ biometric authentication 정보가 변경되었습니다!")
            print("보안을 for 다시 로그인do it.")

            // App 데이터 초기화 or 재로그인 요구
            logoutUser()
            saveBiometricState()
        }
    }

    func logoutUser() {
        // 로그아웃 로직
        UserDefaults.standard.set(false, forKey: "IsLoggedIn")
    }
}

// Usage example
let monitor = BiometricStateMonitor()
monitor.saveBiometricState()  // 로그인 시

// App 시작 시 확인
monitor.handleBiometricChange()

💡 HIG Guidelines

HIG Recommendations

✅ DO
1. 명확한 이유 제공
   - "결제를 승인하려면 Face ID가 필요합니다"
   - 사용자에게 왜 인증이 필요한지 명확히 설명

2. 대체 수단 제공
   - 생체 Authentication failed 시 기기 암호 허용
   - .deviceOwnerAuthentication 정책 사용

3. 적절한 타이밍
   - 민감한 작업 직전에만 요청
   - 너무 자주 요청하지 않기

4. Error handling
   - Authentication failed 시 명확한 피드백
   - Retry 옵션 제공

❌ DON'T
1. 앱 시작마다 인증 요구 (불If needed)
2. 생체 데이터를 서버로 전송
3. 인증 없이도 기본 기능은 available하게
4. "Touch ID"라고 명시 (기기별로 다름)

🔧 Practical Tips

Real-World Patterns

import LocalAuthentication

// 1. 인증 헬퍼 클래스
class BiometricAuth {
    static let shared = BiometricAuth()
    private init() {}

    var biometricType: LABiometryType {
        let context = LAContext()
        _ = context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
        return context.biometryType
    }

    var biometricName: String {
        switch biometricType {
        case .faceID: return "Face ID"
        case .touchID: return "Touch ID"
        case .opticID: return "Optic ID"
        case .none: return "biometric authentication"
        @unknown default: return "biometric authentication"
        }
    }

    func authenticate(reason: String) async throws -> Bool {
        let context = LAContext()
        return try await context.evaluatePolicy(
            .deviceOwnerAuthentication,
            localizedReason: reason
        )
    }
}

// 2. SwiftUI에서 사용
struct SettingsView: View {
    @AppStorage("useBiometric") private var useBiometric = false

    var body: some View {
        Form {
            Section("보안") {
                Toggle("\(BiometricAuth.shared.biometricName) 사용", isOn: $useBiometric)
            }
        }
    }
}

// 3. 결제 승인 예시
func processPayment(amount: Int) async -> Bool {
    do {
        let authenticated = try await BiometricAuth.shared.authenticate(
            reason: "\(amount)원 결제를 승인하시겠습니까?"
        )

        if authenticated {
            // 결제 처리
            await performPaymentTransaction(amount)
            return true
        }
    } catch {
        print("결제 취소됨")
    }
    return false
}

func performPaymentTransaction(_ amount: Int) async {
    // 실제 결제 API 호출
}

🔐 Info.plist Configuration

Info.plist

<!-- Face ID 사용 시 필수 -->
<key>NSFaceIDUsageDescription</key>
<string>안전한 로그인을 for Face ID is used</string>

<!-- or 한국어로 -->
<key>NSFaceIDUsageDescription</key>
<string>계정 보안을 for Face ID 인증이 필요합니다</string>

💡 Local Authentication 핵심
✅ all 생체 데이터는 기기 내에서만 처리
✅ Secure Enclave에 안전하게 저장
✅ 생체 Authentication failed 시 기기 암호 대체 수단 제공
✅ 앱은 Authentication successful/실패만 확인 가능
✅ 실제 생체 데이터는 앱에서 접근 불가

📦 Learning Resources

📎 Apple Official Resources

📘 Documentation 🎬 WWDC Sessions