Architecture

The ZKsync SSO consists of three components that work together to offer a seamless experience for both developers and users.

ZKsync SSO Developer SDK

The Developer SDK is a client-side library that developers can integrate into their applications with minimal effort. It handles authentication and session management with the spend limit controls, allowing developers to enhance security and streamline the user experience, without dealing with complex wallet and key management infrastructure.

Features:

• Authentication: Enables users to authenticate using passkeys, supporting PIN or biometric methods like Face ID and fingerprint recognition.
• Session and Spend Limit Management: Allows applications to manage user sessions with specific spend limits, enhancing security by restricting the scope and usage of session keys.

Platforms:

• Web SDK: Available now, implemented in JavaScript for web applications.
• React Native SDK: For React Native applications
• Swift SDK: For iOS applications (coming soon).
• Kotlin SDK: For Android applications (coming soon).

SDK Modalities

There are two general approaches to creating and signing transactions with passkeys: web-based using an auth server and embedded. The React Native SDKs currently only support the embedded modality, while the web SDK supports both.

Auth Server modality

The Auth Server is a single-page-application provided by ZKsync as a public good that facilitates key aspects of the authentication process. It acts as a non-custodial intermediary between the client application and the ZKsync chain, handling:

• Passkey Creation: Assists in generating and managing user passkeys for secure authentication.
• Session Settings: Manages user sessions, including session keys with their associated permissions/spend limits.
• Transaction Signatures: Facilitates the signing of transactions.

This component ensures that sensitive operations are handled securely and efficiently without exposing private keys or requiring users to manage complex cryptographic details. Hosting this on a trusted domain allows for multiple applications to easily interoperate, while storing data on-chain for the full benefits of decentralization.

Embedded modality

The Embedded modality integrates passkey functionality directly into applications, leveraging native platform infrastructure. This approach eliminates the need for an auth server intermediary, as the application itself handles passkey creation and management. Each platform implements this through its native security frameworks:

• Web:
  • Passkeys are created and stored directly in the browser using the WebAuthn API
  • The application's domain serves as the origin for passkey creation and authentication
  • Supports both embedded and auth server modalities
• iOS:
  • Utilizes native AuthenticationServices framework for passkey management
  • Passkeys are stored securely in the iOS Keychain
  • Requires app-to-web association through associated domains
  • Bundle identifier (e.g., com.example.Example) is linked to a server domain via webcredentials in entitlements
  • Enables seamless passkey usage across both native app and browser contexts
• Android:
  • Leverages the Credential Manager API for passkey management
  • Passkeys are stored securely in Google Play Services
  • Requires Digital Asset Links verification to associate app package name with domain
  • Supports WebAuthn-compatible domain association
  • Enables cross-context passkey usage between app and browser

Smart Contracts

A set of smart contracts deployed on the ZKsync chain manage accounts, passkeys, and sessions. These contracts form the on-chain backbone of the ZKsync SSO system.

• SsoAccount. Implements the ZKSync modular account standard, allowing for extensible smart account functionalities.
• AAFactory. A factory contract used to deploy new user accounts on the chain efficiently.
• SessionKeyValidator. Manages session keys with specific spend limits, enhancing security by restricting their scope and usage.
• WebAuthnModule. Handles authentication using WebAuthn standards, enabling passkey-based authentication methods.
• Account Proxies. Each user account is an upgradable proxy contract for the ZKsync smart-sign-on implemention.

Diagram