Manage credentials using the Okta Client SDK

Securely manage your tokens using the Okta Swift Client SDK, which provides a robust token management system designed to handle complex scenarios.

---

Learning outcomes

• Store credentials.
• Retrieve and work with credentials, including the default credentials.
• Refresh user tokens.
• Remove credentials.

What you need

The Okta Swift Client SDK configured for your app (opens new window)

---

About credential management using the Okta Client SDK

The primary goal of using authentication APIs is to receive credentials that allow your users to interact with your app. If you don’t have some way to save and retrieve those credentials for later use, your users need to sign into your app every time.

After the user (or other identity) is authenticated within an app, you must manage the token's lifecycle:

• Store it in a secure manner
• Retrieve the correct credential for the user from storage
• Use it to perform requests on behalf of the user
• Ensure that it's correctly refreshed as required
• Remove it after reaching expiration or a direct deletion request

The Okta Client SDK provides a robust token management system that's designed to handle complex scenarios, such as multi-threaded access and data race conditions. This allows you to focus on your app's features rather than building a complex token management system from scratch.

Core components of the token management system

The SDK's token management system is built on a few key components that work together to provide a seamless and secure developer experience.

• Credential: This is the main convenience class for interacting with tokens. It acts as a runtime wrapper for a Token object, exposing simplified methods for the entire token lifecycle. Each Credential instance is uniquely tied to a corresponding Token.
• Token: An immutable data object that represents the full set of OAuth 2.0 tokens (access token, refresh token, ID token) that your app receives from the authorization server. This object persists across app launches to keep your user signed in.

Store credentials

After a user successfully signs in to your app, you receive a Token object. The first step is to securely store it:

• How it works: Use the static Credential.store() function. This saves the token to secure storage and returns a Credential object for you to work with.
• Developer-assigned tags: You can add optional tags (metadata) during storage. These tags are useful for querying and managing multiple credentials later. For example, you could tag tokens based on user roles or the service they are for.
• Security access control settings: You can also specify a custom list of security access control flags. Use the flags to configure how the token is stored in the keychain, and if biometrics are required. If omitted, the default options are used, which your app can override. See store(_:tags:security:) - Discussion (opens new window).

Swift example: Store a token

try Credential.store(token,
                     tags: ["displayName": "My User"],
                     security: [
                         .accessibility(.afterFirstUnlock),
                         .accessControl(.biometryAny),
                         .accessGroup("com.example.myApp.shared")
                     ])

Manage the default credentials

If you have a single-user app, the use of "default" credentials simplifies the development process a lot:

• The default can either be explicitly set or implicitly assigned when the first token is stored.
• It's possible to retain the credential object and can pass it around throughout your app. However, it’s often convenient to have singleton access to this common object.
• Use the default type property to access the default credential, for example, to check if a user is already signed in when the app starts.
• The Credential class broadcasts a notification whenever the default credential is set or removed. You can listen for this event to dynamically update your UI, such as transitioning from a sign-in screen to a signed-in view.

Swift example: Check for a default user on app load

// On app launch, check for a default credential
if let credential = Credential.default {
  // User is signed in. Proceed to the main app view.
  showUserProfile(credential);
} else {
  // No default user. Show the sign-in screen.
  showLoginScreen();
}

// Listen for changes to the default credential
NotificationCenter.default.addObserver(forName: .defaultCredentialChanged,
                                       object: nil,
                                       queue: nil) { notification in
    if let credential = notification.object as? Credential {
        print("Default credential has changed to: \(credential.id)")
        // Update UI with new user info
    } else {
        print("User signed out, default credential removed.")
        // Update UI to show signed-out state
    }
}

Manage multiple credentials

The SDK is designed to support multi-user scenarios by allowing you to store and query multiple credentials simultaneously.

Swift example: Find credentials by ID

You can identify all tokens by unique IDs that are automatically assigned to them. This can be seen in the id (opens new window), and through the id (opens new window) property. This identifier may be used with the with(id:prompt:authenticationContext:) (opens new window) function.

The list of all stored IDs is available through the allIDs (opens new window) static property.

if let credential = try Credential.with(id: serviceTokenId) {
    // Do something with the credential
}

Swift example: Find credentials by developer-assigned tags

When storing tokens, the store(_:tags:security:) (opens new window) function accepts an optional collection of tags you can use to identify the purpose of different tokens.

The find(where:prompt:authenticationContext:) (opens new window) function allows you to query tokens based on those tags later.

Furthermore, those tags can later be updated by changing the credential’s tags (opens new window) property.

try Credential.store(token: newToken, tags: ["service": "purchase"])

// Later ...

if let credential = try Credential.find(where: { $0.tags["service"] == "purchase" }).first {
    // Use the credential
}

Swift example: Find credentials by ID Token claims

If a token contains a valid idToken (opens new window), the claims it represents are available within the find(where:prompt:authenticationContext:) (opens new window) expression. Both the SDK's JWT type and the find function support the access of ID token claims. See HasClaims (opens new window).

let userCredentials = try Credential.find { metadata in
    metadata.subject == "jane.doe@example.com"
}

Refresh user tokens

Access tokens are short-lived for security reasons. The Swift Client SDK simplifies the process of using long-lived refresh tokens to get new access tokens without requiring the user to sign in again. See Refreshing and Revoking Tokens (opens new window).

• refresh(): Immediately refreshes the token.
• refreshIfNeeded(): A smarter function that only refreshes the token if it's expired or is about to expire within a defined grace interval.
• authorize(request:): Authorizes an outgoing network request, refreshing the token if needed. Automatically attaches the appropriate HTTP Authorization headers to the outgoing request. This is the recommended approach to manage token expiration before making an API call.

Swift example: Refresh a token

func makeAuthenticatedApiRequest(credential: Credential, url: URL, data: [String: Any]) async -> Any {
    do {
        // Create a URLRequest representing the HTTP request
        var request = URLRequest(url: url)
        request.httpBody = try? JSONSerialization.data(withJSONObject: data, options: [])

        // Authorize the request with the tokens from the given credential
        await credential.authorize(&request)

        // Perform the request and return the data from it
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONSerialization.jsonObject(with: data)
    } catch {
        print("API request failed. User may need to re-authenticate. \(error)")

        showLoginScreen();
    }
}

Implement token cleanup

The SDK for Swift provides several methods to sign a user out of your app, 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.

See User sign-out flow (local app).

Swift example: Secure your sign-out flow

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)")
        }
    }
}

Swift example: 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..
}

Best practices

Here are some key recommendations for secure token management:

• Use short-lived access tokens. See Refresh the access and ID tokens.
• Use and rotate refresh tokens. See Refresh token rotation.
• Always revoke tokens when a user signs out of Okta. See Revoke tokens.
• Register a custom domain URL for your Okta org to unlock branding capabilities and simplify session management. See Customize domain and email address.
• To mitigate risk and ensure proper access token usage:
  • Configure APIs with specific authorization server audiences, for example, api.company.com/product1 instead of the base api.company.com. See Create an authorization server.
  • Use granular scopes, for example, com.okta.product1.admin instead of a generic administrator scope. See Create scopes.