sdk/ios | XID

Swift SDK for iOS and macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage.

Status

Package status is Implemented and verified locally. The Swift unit-test suite passes on macOS for the iOS package. Simulator or device behavior and a real IdP round-trip on a running XID instance remain pending manual verification. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Requirements

iOS 16+ / macOS 13+
Swift 5.9+ and Xcode 15+
No third-party dependencies — uses Apple system frameworks only

Installation

Add the package via Swift Package Manager in Xcode (File -> Add Package Dependencies) or directly in Package.swift:

// Package.swift
dependencies: [
    .package(path: "../xid/sdk/ios"),
],
targets: [
    .target(name: "YourApp", dependencies: [.product(name: "Xid", package: "ios")]),
]

Quick start

import Xid

// 1. Configure in @main App.init. offline_access is rejected until DPoP is implemented.
Xid.shared.configure(options: XidConfiguration(
    issuer: URL(string: "https://xid.dev")!,
    clientId: "your_client_id",
    redirectUri: URL(string: "com.example.app://auth/callback")!,
    scopes: ["openid", "profile", "email"]
))

// 2. Sign in (opens ASWebAuthenticationSession)
try await Xid.shared.signIn()

// 3. Handle redirect in SceneDelegate
let session = try await Xid.shared.handleRedirect(url: callbackUrl)

// 4. Read the current unexpired session. Expiry requires reauthorization.
if let session = try await Xid.shared.getSession() {
    let token = try await Xid.shared.getAccessToken()
}

// 5. Clear local state and optionally call end_session.
try await Xid.shared.signOut(callEndSession: true)

Core API

Method	Description
`configure(options:)`	Initialize with issuer, clientId, redirectUri, scopes. Call before all others.
`signIn(options:) async throws`	Open ASWebAuthenticationSession with PKCE S256 authorization URL. Returns when the browser session ends.
`handleRedirect(url:) async throws -> XidSession`	Validate OAuth state, exchange authorization code at the token endpoint, persist tokens to Keychain, and return a session.
`getSession() async throws -> XidSession?`	Return the current unexpired iOS session; expired token state is cleared and the method returns nil.
`getAccessToken(forceRefresh:) async throws -> String`	Return the current unexpired access token. The SDK rejects offline_access until DPoP is implemented; expiry requires reauthorization.
`signOut(callEndSession:) async throws`	Clear Keychain tokens. Pass true to call the end_session endpoint via the browser.
`setTokenStorage(_:) throws`	Replace the default KeychainTokenStorage with a custom TokenStorageAdapter implementation.

Storage adapter

The default storage uses Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly — tokens are not synced to iCloud Keychain. Implement the TokenStorageAdapter protocol to use an enterprise Keychain policy:

struct EnterpriseKeychain: TokenStorageAdapter {
    func save(key: String, value: String) throws { /* ... */ }
    func load(key: String) throws -> String? { /* ... */ }
    func delete(key: String) throws { /* ... */ }
}
try Xid.shared.setTokenStorage(EnterpriseKeychain())

Security

Public client — no client secret stored or transmitted.
PKCE S256 only. Server rejects plain challenge method.
Random OAuth state generated per request; validated on redirect to prevent CSRF.
PKCE code_verifier written to Keychain only for the duration of the authorization flow and deleted immediately after the code exchange.
ASWebAuthenticationSession launched with prefersEphemeralWebBrowserSession = true to avoid sharing browser cookies across apps.

Known limitations

JWKS-backed ES256/RS256 ID token verification, nonce validation, and end_session logout are implemented and locally tested. A real IdP round-trip on an iOS device or simulator is still required before L4 support.
Keychain behavior must be verified in an Xcode device or simulator test run.