sdk/ios | XID

SDK Swift pour iOS et macOS utilisant ASWebAuthenticationSession, le fluxde code d'autorisation PKCE S256 et le stockage des jetons dans leKeychain.

Statut

L’état du package est Implémenté et vérifié localement. La suite de tests unitaires Swift réussit sur macOS pour le package iOS. Le comportement sur simulateur ou appareil et un aller-retour réel avec un IdP sur une instance XID en cours d’exécution restent à vérifier manuellement. Cette page documente le comportement implémenté; elle ne constitue pas une déclaration d’aptitude à la production.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

Prérequis

iOS 16+ / macOS 13+
Swift 5.9+ et Xcode 15+
Aucune dépendance tierce — utilise uniquement les frameworks système Apple

Installation

Ajoutez le package via Swift Package Manager dans Xcode (Fichier ->Ajouter des dépendances de package) ou directement dansPackage.swift :

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

Démarrage rapide

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)

API principale

Méthode	Description
`configure(options:)`	Initialiser avec issuer, clientId, redirectUri, scopes. À appeler avanttout autre.
`signIn(options:) async throws`	Ouvrir ASWebAuthenticationSession avec l’URL d’autorisation PKCE S256.Retourne lorsque la session du navigateur se termine.
`handleRedirect(url:) async throws -> XidSession`	Valider l’état OAuth, échanger le code d’autorisation au point determinaison de jeton, persister les jetons dans le Keychain et retournerune session.
`getSession() async throws -> XidSession?`	Retourner la session iOS actuelle non expirée; l’état du jeton expiré est effacé et la méthode retourne nil.
`getAccessToken(forceRefresh:) async throws -> String`	Retourner le jeton d’accès actuel non expiré. Le SDK rejette offline_access tant que DPoP n’est pas implémenté; l’expiration exige une nouvelle autorisation.
`signOut(callEndSession:) async throws`	Effacer les jetons Keychain. Passez true pour appeler le point determinaison end_session via le navigateur.
`setTokenStorage(_:) throws`	Remplacer le KeychainTokenStorage par défaut par une implémentationpersonnalisée de TokenStorageAdapter.

Adaptateur de stockage

Le stockage par défaut utilise le Keychain aveckSecAttrAccessibleAfterFirstUnlockThisDeviceOnly — les jetons nesont pas synchronisés sur le Keychain iCloud. Implémentez le protocoleTokenStorageAdapter pour utiliser une politique Keychaind’entreprise :

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())

Sécurité

Client public — aucun secret client stocké ni transmis.
PKCE S256 uniquement. Le serveur rejette la méthode plain challenge.
État OAuth aléatoire généré par requête ; validé lors de la redirectionpour prévenir le CSRF.
Le code_verifier PKCE est écrit dans le Keychain uniquement pendant leflux d’autorisation et supprimé immédiatement après l’échange de code.
ASWebAuthenticationSession lancée avec prefersEphemeralWebBrowserSession =true pour éviter de partager les cookies du navigateur entre applications.

Limites connues

La vérification des jetons d’identité ES256/RS256 adossée à JWKS, la validation du nonce et la déconnexion end_session sont implémentées et testées localement. Un aller-retour réel avec un IdP sur un appareil ou simulateur iOS reste requis avant le support L4.
Le comportement Keychain doit etre verifie avec un test Xcode sur appareil ou simulateur.