adyen/adyen-authentication-ios

⚙️ Installation

The SDK can be integrated via CocoaPods, Carthage, Swift Package Manager, or manual installation.

CocoaPods

1. Add the following line to your Podfile:

``ruby pod 'AdyenAuthentication' ``

Carthage

Note: Carthage is no longer actively maintained and is not recommended for new projects. Prefer Swift Package Manager if possible.

1. Add the following to your Cartfile:

``text github "adyen/adyen-authentication-ios" ``

1. Link the generated framework with your target as described in Carthage’s guide.

Swift Package Manager (Recommended)

1. Follow Apple’s guide on Adding Package Dependencies to Your App.
2. Use the repository URL:

https://github.com/Adyen/adyen-authentication-ios

Requirements:

• Swift 5.7+
• Xcode 16+
• iOS 14 or later for DeviceCheck
• iOS 16 or later for passkeys.

XCFramework Installation

Dynamic xcFramework

1. Drag XCFramework/Dynamic/AdyenAuthentication.xcframework into the Frameworks, Libraries, and Embedded Content section of your app target.
2. Choose “Copy items if needed.”

Static xcFramework

1. Drag XCFramework/Static/AdyenAuthentication.xcframework into the Frameworks, Libraries, and Embedded Content section.
2. Ensure the framework is not embedded.

📱 Supported App Targets

| Authentication Method | iOS App | App Extension | Documentation | | :--- | :---: | :---: | :--- | | DeviceCheck | ✅ Supported | ❌ Not Supported | App Attest | | Passkeys | ✅ Supported | ⚠️ Conditional | ASAuthorizationController |

For App Extensions, Passkeys require ASAuthorizationControllerPresentationContextProviding.

🔑 Prerequisites

Before using the AdyenAuthentication SDK, configure your Xcode project with the required Apple capabilities.

| Authentication Method | Required Capability | Documentation | |-----------------------|---------------------|---------------| | DeviceCheck | DeviceCheck + App Attest | Preparing to Use the App Attest Service | | Passkeys | Associated Domains | Supporting Passkeys |

DeviceCheck

1. Enable App Attest capability in your app target.
2. Add the following to your .entitlements file:

``xml <key>com.apple.developer.devicecheck.appattest-environment</key> <string>production</string> ``

Use production for live environments. For sandbox testing, configure appropriately.

Passkeys

1. Enable Associated Domains capability.
2. Add your domain using the webcredentials service:

`` webcredentials:your-domain.com ``

Ensure your relyingPartyIdentifier in code matches the associated domain declared here.

🧩 Usage

Initialization Options

You can initialize the SDK in one of two mutually exclusive ways:

1. Using DeviceCheck APIs

let configuration = AuthenticationService.Configuration(
    localizedRegistrationReason: "Biometric use explanation for registration.",
    localizedAuthenticationReason: "Biometric use explanation for authentication.",
    appleTeamIdentifier: "YOUR_APPLE_TEAM_ID"
)
let authenticationService = AuthenticationService(configuration: configuration)

Ensure the App Attest capability and App Attest entitlement are configured.

2. Using Apple Passkeys

let configuration = AuthenticationService.PassKeyConfiguration(
    relyingPartyIdentifier: "your-domain.com",
    displayName: "Your App Name",
    consecutiveApprovalCancellationsLimit: 3 // Optional: refer AdyenAuthenticationError.consecutiveCancellationOnApproval
)
let authenticationService = AuthenticationService(passKeyConfiguration: configuration)

Ensure the Associated Domains capability is enabled and your webcredentials entry matches the relying party domain.

Checking Device Support

do {
    let deviceSupportPayload = try authenticationService.checkSupport()
    // Send this payload to your backend for validation.
} catch {
    print("Device not supported: \(error)") // `AdyenAuthenticationError` if not supported.  
}

If successful, checkSupport() returns a Base64 URL-encoded payload describing device capabilities.

Registering and Authenticating

Check Registration Status

do {
    let isDeviceRegistered = try await authenticationService.isDeviceRegistered(withAuthenticationInput: backendInput) /*The opaque string sdk input*/
} catch error {
    // refer: `AdyenAuthenticationError` for the type of errors.
}

Register Device

do {
    let sdkOutput = try await authenticationService.register(withRegistrationInput: backendInput) /*The opaque string sdk input*/
} catch error {
    // refer: `AdyenAuthenticationError` for the type of errors.
}

Authenticate User

do {
    let sdkOutput = try await authenticationService.authenticate(withAuthenticationInput: backendInput) /*The opaque string sdk input*/
} catch error {
    // refer: `AdyenAuthenticationError` for the type of errors.
}

🧠 Error Handling

Common AuthenticationService.Error cases includes:

• .userCancelled // User cancelled authentication
• .deviceOwnerAuthenticationFailure // Indicates that device owner authentication failed.

For more such errors refer to the source documentation.

🧩 Support

If you encounter a bug or have a feature request, open an issue. For other questions, contact Adyen Support.

🔒 See Also

• Reporting security issues
• Security best practices
• Data security at Adyen

📜 License

This SDK is available under the Apache License, Version 2.0. See the LICENSE file for details.

Package Metadata

Repository: adyen/adyen-authentication-ios

Default branch: main

README: README.md