Instructions for

User sign out flow (local app)

Sample code

Configuration updates

There are no additional configuration changes needed to implement this use case.

Summary of steps

You can sign a user out of your app by revoking their tokens or deleting their credentials. See Implement token cleanup.

Also, if you have an active Okta browser session, you need to end the session. See End the Okta browser session.

Best practices and considerations

Do both when applicable: Local token cleanup and browser end-session are separate concerns. Handle both for a complete sign-out flow.
Revoke before remove: Always attempt revoke() before remove(). If the revoke fails, you should still still remove the token to ensure that the sign-out flow occurs.
Multiple accounts: If your app supports multiple profiles/tenants, iterate over all credentials during the sign-out flow.
Logout redirect URI: If you end the browser session, ensure that logout_redirect_uri is configured in Okta.plist and your URL scheme handler is implemented.
Handle errors gracefully: Network errors can occur when revoking tokens. Consider falling back to local deletion if revocation fails.
Clear app state: After signing out, ensure you clear any cached user data and reset your app's UI state.
Background operations: Token revocation is an async operation. Ensure that you handle it appropriately in your UI flow to avoid blocking the user experience.

Integration steps

The following code examples show you how to set up the user sign-out flow.

Implement token cleanup

The new SDK provides several methods to clean up tokens, depending on your use case:

Credential.revoke(): Revokes all available tokens from the authorization server. It works like the revoke(type:) method but with a default type of .all. As a result, it loops through all tokens calling revoke() on each of them in parallel.
- Note: The SDK keeps the token in storage so that you can refresh it to get a new access token. However, if the token is no longer usable, the SDK removes the token from storage. For example, if you revoke a refresh token and the associated access token is revoked.
Credential.revoke(type:): Revokes a specific token type (access token, refresh token, or device secret) from the authorization server. See Revoke tokens (opens new window).
- Notes:
  - If you revoke an access token, the associated refresh token or device secret isn’t revoked.
  - If you revoke a refresh token, the associated access token is revoked.
  - Keeps the token in storage so that you can refresh it to get a new access token. However, if the token is no longer usable, the SDK removes the token from storage. For example, if you revoke a refresh token and the associated access token is revoked.
Credential.remove(): Clears the in-memory reference to the token and removes it from storage.
- Note: The SDK doesn’t revoke the token from the authorization server, so it can still be used.

When implementing your code, consider the following items:

Always revoke all tokens: It’s always best to revoke all tokens. If the revoke fails, investigate the cause of the failure instead of removing the tokens from storage. For example, the failure could be due to a temporary network issue. In that case, it's better to try to revoke again to avoid a potential credential leak.
Multiple accounts: If your app allows users to switch between multiple accounts or tenants, keep the following items in mind:
- Credential storage: The SDK can store multiple user credentials securely. If the credential that the default property points to is removed, default is set to nil. As a result, assigning the default property, even to nil, doesn't remove a credential from storage.
- Default credentials: The Credential.default property can be used to determine which account is active. Switch the active user by assigning a different stored credential to the Credential.default property.
- Sign-out scope: When a user signs out, you typically only want to sign out the active user. If you want to remove all stored sessions, you need to iterate over all stored credentials and revoke or remove each one.

Example token cleanup code

The following code example shows you how to implement local token clean-up as part of the user sign-out flow:

import AuthFoundation

@MainActor
func signOutLocally() async {
    guard let credential = Credential.default else { return }

    do {
        // Revoke refresh/access tokens server-side (the safest approach).
        // The SDK's 'revoke' typically also removes the tokens from local storage upon success.
        try await credential.revoke()

        // If 'revoke()' succeeds, we're done. Navigate to the signed-out page.

    } catch {
        // If 'revoke()' fails (for example, due to a temporary network issue or invalid token).
        // Log the server-side revocation error but always continue to clear local state.
        // Log the error: print("Server-side revocation failed: \(error)")

        do {
            // Remove tokens and user state from local secure storage. This is essential for a proper sign-out, even if the server-side call failed.
            try await credential.remove()

            // Local removal succeeded. Navigate to signed-out page.

        } catch {
            // Handle/log if local storage removal also fails. This is rare but possible.
            // Handle/remove fallback, if needed.
            // Log the error: print("Local removal failed: \(error)")
        }
    }
}

Example switch between user accounts code

The following code example shows you how to switch between user accounts:

func switchDefaultAccount(to userEmail: String) throws {
    // Retrieve the credential object for the target account using its email address.

    guard let newCredential = try Credential.find(where: { meta in
        meta.preferredUsername == userEmail
    }) else {
        throw AccountError.credentialNotFound(account.username)
    }

    // Set the retrieved credential as the new default.
    // This immediately makes this account the active user (Credential.default).
    Credential.default = newCredential

    print("Switched active user to: \(newCredential.preferredUsername ?? "Unknown User")")

    // The app can now update to use the new default credential, or may be automatically updated in response to the Notification.Name.defaultCredentialChanged notification..
}

End the Okta browser session (optional)

You don’t need to end the Okta browser session if either of the following are true:

Your app uses DirectAuth (opens new window). That is, there isn’t a browser session.
You signed in with BrowserSignIn.shared?.ephemeralSession = true. That is, there are no persistent cookies.

Example end browser session code

import BrowserSignin
@MainActor
func signOutFromBrowser() async throws {
    guard let credential = Credential.default else {
        return
    }

    // Ends Okta browser session (opens auth session and returns to your logout_redirect_uri)
    do {
        // This revokes tokens and ends the Okta browser session
        try await BrowserSignin.shared?.signOut(token: credential.token)
    } catch {
        // If there's no browser session or a callback mismatch, log and continue
    }

    // Note: This revokes the token but does not remove it from storage. You still need to delete the credentials.
    try? credential.remove()
}