Session Management — Expert Decisions
Expert decision frameworks for session management choices. Claude knows Keychain basics and OAuth concepts — this skill provides judgment calls for security levels, refresh strategies, and cleanup requirements.
Decision Trees
Token Storage Strategy
Where should you store authentication tokens?
├─ Access token (short-lived, <1hr)
│ └─ Keychain with kSecAttrAccessibleAfterFirstUnlock
│ Available after first unlock, survives restart
│
├─ Refresh token (long-lived)
│ └─ Keychain with kSecAttrAccessibleWhenUnlockedThisDeviceOnly
│ More secure, device-bound, requires unlock
│
├─ Session ID (server-side session)
│ └─ Keychain with kSecAttrAccessibleAfterFirstUnlock
│ Needs to work for background refreshes
│
├─ Temporary auth code (OAuth flow)
│ └─ Memory only (no persistence)
│ Used once, discarded immediately
│
└─ Remember me preference
└─ UserDefaults (not sensitive)
Just a boolean, not a credential
The trap: Storing tokens in UserDefaults. It's unencrypted, backed up to iCloud, and readable by jailbroken devices.
Token Refresh Architecture
How should you handle token refresh?
├─ Simple app, few API calls
│ └─ Refresh on 401 response
│ Reactive: refresh when expired
│
├─ Frequent API calls
│ └─ Proactive refresh before expiration
│ Schedule refresh 5 min before exp
│
├─ Real-time features (WebSocket)
│ └─ Background refresh + reconnect
│ Maintain connection continuity
│
├─ Offline-first app
│ └─ Longer token lifetime + retry queue
│ Queue requests when offline
│
└─ High-security app
└─ Short tokens + frequent refresh
Minimize exposure window
Multi-Session Architecture
How many sessions does your app support?
├─ Single device, single account
│ └─ Simple SessionManager singleton
│ Replace tokens on new login
│
├─ Single device, multiple accounts (switching)
│ └─ Account-keyed Keychain storage
│ Keychain items per account ID
│ Active account pointer
│
├─ Multiple devices, single account
│ └─ Server-side session management
│ Device tokens registered with server
│ Remote logout capability
│
└─ Multiple devices, multiple accounts
└─ Full session registry
Server tracks all device-account pairs
Cross-device session visibility
Logout Cleanup Scope
What needs clearing on logout?
├─ Always clear
│ └─ Tokens (Keychain)
│ └─ User object (memory)
│ └─ Authenticated state
│
├─ Usually clear
│ └─ URL cache (cached API responses)
│ └─ HTTP cookies
│ └─ User preferences tied to account
│
├─ Consider clearing
│ └─ Downloaded files (if user-specific)
│ └─ Core Data (if user-specific)
│ └─ Image cache (if contains private content)
│
└─ Usually keep
└─ App preferences (theme, language)
└─ Onboarding completion state
└─ Device registration
NEVER Do
Token Storage
NEVER store tokens in UserDefaults:
// ❌ Unencrypted, backed up, exposed on jailbreak
UserDefaults.standard.set(accessToken, forKey: "accessToken")
UserDefaults.standard.set(refreshToken, forKey: "refreshToken")
// ✅ Use Keychain
try KeychainHelper.shared.save(accessToken, service: "auth", account: "accessToken")
try KeychainHelper.shared.save(refreshToken, service: "auth", account: "refreshToken")
NEVER log or print tokens:
// ❌ Tokens in console logs — security disaster
print("Token: \(accessToken)")
Logger.debug("Refresh token: \(refreshToken)")
// ✅ Log safely
Logger.debug("Token refreshed successfully") // No token content
Logger.debug("Token length: \(accessToken.count)") // Metadata only
NEVER hardcode secrets:
// ❌ Secrets in binary — extractable
let clientSecret = "abc123xyz789"
let apiKey = "sk-live-xxxxx"
// ✅ Use environment or server
// Fetch from server during OAuth flow
// Or use Info.plist with .gitignore for dev keys
let clientId = Bundle.main.infoDictionary?["CLIENT_ID"] as? String
Token Refresh
NEVER retry refresh infinitely:
// ❌ Infinite loop if refresh token is invalid
func refreshToken() async throws {
do {
let response = try await API.refresh(token: refreshToken)
storeTokens(response)
} catch {
try await refreshToken() // Recursive retry — infinite loop!
}
}
// ✅ Limited retries with backoff, then logout
func refreshToken(attempt: Int = 0) async throws {
guard attempt < 3 else {
await MainActor.run { logout() }
throw SessionError.refreshFailed
}
do {
let response = try await API.refresh(token: refreshToken)
storeTokens(response)
} catch {
try await Task.sleep(nanoseconds: UInt64(pow(2.0, Double(attempt))) * 1_000_000_000)
try await refreshToken(attempt: attempt + 1)
}
}
NEVER refresh on every request:
// ❌ Unnecessary API calls
func makeRequest(_ endpoint: Endpoint) async throws -> Data {
try await refreshAccessToken() // Refresh EVERY request!
return try await performRequest(endpoint)
}
// ✅ Refresh only when needed (expired or 401)
func makeRequest(_ endpoint: Endpoint) async throws -> Data {
if isTokenExpired() {
try await refreshAccessToken()
}
let (data, response) = try await performRequest(endpoint)
if (response as? HTTPURLResponse)?.statusCode == 401 {
try await refreshAccessToken()
return try await performRequest(endpoint).0
}
return data
}
Logout
NEVER forget to clear sensitive data:
// ❌ Partial cleanup — tokens still accessible
func logout() {
currentUser = nil
isAuthenticated = false
// Forgot to clear Keychain tokens!
}
// ✅ Complete cleanup
func logout() {
// Clear tokens
KeychainHelper.shared.deleteAll(service: keychainService)
// Clear memory
currentUser = nil
isAuthenticated = false
// Clear caches
URLCache.shared.removeAllCachedResponses()
// Clear cookies
HTTPCookieStorage.shared.removeCookies(since: .distantPast)
// Clear UserDefaults user data
let userKeys = ["userId", "userEmail", "userPreferences"]
userKeys.forEach { UserDefaults.standard.removeObject(forKey: $0) }
}
NEVER leave background tasks running after logout:
// ❌ Background refresh continues for logged-out user
func logout() {
clearTokens()
currentUser = nil
// Background refresh timer still running!
}
// ✅ Cancel all background work
func logout() {
// Cancel scheduled tasks
sessionRefreshTask?.cancel()
sessionRefreshTask = nil
// Cancel any pending requests
URLSession.shared.getAllTasks { tasks in
tasks.forEach { $0.cancel() }
}
// Clear data
clearTokens()
currentUser = nil
}
Keychain Security
NEVER use wrong accessibility level:
// ❌ Too permissive — accessible even when locked
kSecAttrAccessibleAlways // Deprecated and insecure!
kSecAttrAccessibleAlwaysThisDeviceOnly // Still too permissive
// ✅ Appropriate accessibility
// For tokens that need background access:
kSecAttrAccessibleAfterFirstUnlock
// For highly sensitive data (biometric):
kSecAttrAccessibleWhenUnlockedThisDeviceOnly
NEVER ignore Keychain errors:
// ❌ Silent failure — user appears logged out
func getToken() -> String? {
let query = [...]
var result: AnyObject?
SecItemCopyMatching(query as CFDictionary, &result) // Ignoring status!
return result as? String
}
// ✅ Handle errors properly
func getToken() throws -> String? {
let query = [...]
var result: AnyObject?
let status = SecItemCopyMatching(query as CFDictionary, &result)
switch status {
case errSecSuccess:
guard let data = result as? Data,
let token = String(data: data, encoding: .utf8) else {
throw KeychainError.invalidData
}
return token
case errSecItemNotFound:
return nil // No token stored
default:
throw KeychainError.unableToRetrieve(status: status)
}
}
Essential Patterns
Secure SessionManager
@MainActor
final class SessionManager: ObservableObject {
static let shared = SessionManager()
@Published private(set) var isAuthenticated = false
@Published private(set) var currentUser: User?
private let keychainService = "com.app.auth"
private var refreshTask: Task<Void, Never>?
private init() {
restoreSession()
}
// MARK: - Authentication
func login(email: String, password: String) async throws {
let response = try await AuthAPI.login(email: email, password: password)
try storeTokens(access: response.accessToken, refresh: response.refreshToken)
currentUser = response.user
isAuthenticated = true
scheduleTokenRefresh()
}
func logout() {
// Cancel background work
refreshTask?.cancel()
refreshTask = nil
// Clear Keychain
KeychainHelper.shared.deleteAll(service: keychainService)
// Clear state
currentUser = nil
isAuthenticated = false
// Clear caches
URLCache.shared.removeAllCachedResponses()
HTTPCookieStorage.shared.removeCookies(since: .distantPast)
}
// MARK: - Token Management
func getAccessToken() -> String? {
KeychainHelper.shared.read(service: keychainService, account: "accessToken")
}
func refreshAccessToken() async throws {
guard let refreshToken = KeychainHelper.shared.read(
service: keychainService, account: "refreshToken"
) else {
throw SessionError.noRefreshToken
}
let response = try await AuthAPI.refresh(token: refreshToken)
try storeTokens(access: response.accessToken, refresh: response.refreshToken)
}
// MARK: - Private
private func storeTokens(access: String, refresh: String) throws {
try KeychainHelper.shared.save(access, service: keychainService, account: "accessToken")
try KeychainHelper.shared.save(refresh, service: keychainService, account: "refreshToken")
}
private func restoreSession() {
guard let _ = getAccessToken() else { return }
isAuthenticated = true
Task { try? await loadUserProfile() }
}
private func scheduleTokenRefresh() {
refreshTask?.cancel()
refreshTask = Task {
while !Task.isCancelled {
// Refresh 5 minutes before expiration
try? await Task.sleep(nanoseconds: 55 * 60 * 1_000_000_000) // 55 min
guard !Task.isCancelled else { return }
do {
try await refreshAccessToken()
} catch {
await MainActor.run { logout() }
return
}
}
}
}
}
Secure KeychainHelper
final class KeychainHelper {
static let shared = KeychainHelper()
private init() {}
func save(_ value: String, service: String, account: String) throws {
guard let data = value.data(using: .utf8) else {
throw KeychainError.invalidData
}
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrService as String: service,
kSecAttrAccount as String: account,
kSecValueData as String: data,
kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock
]
// Delete existing
SecItemDelete(query as CFDictionary)
// Add new
let status = SecItemAdd(query as CFDictionary, nil)
guard status == errSecSuccess else {
throw KeychainError.saveFailed(status: status)
}
}
func read(service: String, account: String) -> String? {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrService as String: service,
kSecAttrAccount as String: account,
kSecReturnData as String: true,
kSecMatchLimit as String: kSecMatchLimitOne
]
var result: AnyObject?
let status = SecItemCopyMatching(query as CFDictionary, &result)
guard status == errSecSuccess,
let data = result as? Data,
let string = String(data: data, encoding: .utf8) else {
return nil
}
return string
}
func delete(service: String, account: String) {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrService as String: service,
kSecAttrAccount as String: account
]
SecItemDelete(query as CFDictionary)
}
func deleteAll(service: String) {
let query: [String: Any] = [
kSecClass as String: kSecClassGenericPassword,
kSecAttrService as String: service
]
SecItemDelete(query as CFDictionary)
}
}
enum KeychainError: LocalizedError {
case invalidData
case saveFailed(status: OSStatus)
case readFailed(status: OSStatus)
var errorDescription: String? {
switch self {
case .invalidData: return "Invalid data format"
case .saveFailed(let status): return "Keychain save failed: \(status)"
case .readFailed(let status): return "Keychain read failed: \(status)"
}
}
}
Auto-Retry Network Client
actor NetworkClient {
private let sessionManager: SessionManager
init(sessionManager: SessionManager = .shared) {
self.sessionManager = sessionManager
}
func request<T: Decodable>(_ endpoint: Endpoint) async throws -> T {
var request = try endpoint.asURLRequest()
// Add token
if let token = await sessionManager.getAccessToken() {
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
}
let (data, response) = try await URLSession.shared.data(for: request)
// Handle 401 with retry
if let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 401 {
try await sessionManager.refreshAccessToken()
// Retry with new token
if let newToken = await sessionManager.getAccessToken() {
request.setValue("Bearer \(newToken)", forHTTPHeaderField: "Authorization")
let (retryData, _) = try await URLSession.shared.data(for: request)
return try JSONDecoder().decode(T.self, from: retryData)
}
}
return try JSONDecoder().decode(T.self, from: data)
}
}
Quick Reference
Keychain Accessibility Levels
| Level | When Accessible | Use For | |-------|-----------------|---------| | WhenUnlocked | Device unlocked | Foreground-only tokens | | AfterFirstUnlock | After first unlock | Background refresh tokens | | WhenUnlockedThisDeviceOnly | Unlocked, no backup | Highly sensitive data | | WhenPasscodeSetThisDeviceOnly | Passcode set | Biometric-protected |
Logout Cleanup Checklist
| Data | Storage | Clear On Logout? | |------|---------|------------------| | Access token | Keychain | ✅ Always | | Refresh token | Keychain | ✅ Always | | User profile | Memory | ✅ Always | | API cache | URLCache | ✅ Usually | | Cookies | HTTPCookieStorage | ✅ Usually | | User preferences | UserDefaults | ⚠️ Maybe | | Downloaded files | FileManager | ⚠️ If user-specific | | App settings | UserDefaults | ❌ Usually keep |
Token Refresh Strategies
| Strategy | When to Use | Implementation | |----------|-------------|----------------| | On 401 | Simple apps | Retry after refresh | | Proactive | Frequent API calls | Timer before expiration | | Background | Real-time features | BGAppRefreshTask |
Red Flags
| Smell | Problem | Fix | |-------|---------|-----| | Tokens in UserDefaults | Unencrypted storage | Use Keychain | | Logging token values | Security exposure | Log metadata only | | Infinite refresh retry | DoS on invalid token | Limited retries + logout | | Refresh on every request | Unnecessary API calls | Check expiration first | | Partial logout cleanup | Data leakage | Clear all sensitive data | | Ignoring Keychain errors | Silent failures | Handle status codes | | kSecAttrAccessibleAlways | Too permissive | Use AfterFirstUnlock | | Background tasks after logout | Stale operations | Cancel on logout |