Motivation​

Currently, developers building native applications that integrate with Okta typically rely on a browser-based, redirected authentication flow. While secure and effective, this approach has several drawbacks for native clients:

• Poor User Experience: Redirecting users out of the application to a system browser for sign-in creates a jarring and disconnected experience. It breaks the flow of the native application and can feel less polished and integrated.
• Limited UI Customization: The sign-in and MFA pages are hosted by Okta. Developers have limited control over the look and feel, making it difficult to create a seamless experience that matches their application's branding and design system.
• Infeasibility in Browser-less Environments: Many valid use-cases for authentication exist where a web browser is not available. This includes command-line interface (CLI) tools, IoT devices, and other "headless" systems. The browser-based flow is not a viable option for these platforms.

To work around these issues, developers might attempt to call Okta's low-level authentication APIs directly. This is a complex and error-prone process, requiring the developer to manually manage the authentication state machine, handle various MFA challenges, and ensure secure token handling.

This proposal seeks to address these problems by providing a high-level, stateful SDK specifically for Direct Authentication. This will empower developers to easily build custom, native authentication flows that provide a superior user experience, match their application's branding, and support a wider range of client types, all without needing to manage the underlying complexity of the authentication protocol.

Design objectives​

Authenticate users using Okta's Direct Authentication API, enabling native sign-in experiences supporting Multi-Factor Authentication (MFA).

This enables developers to build native sign-in workflows into their applications, while leveraging MFA to securely authenticate users, without the need to present a browser. Furthermore, this enables passwordless authentication scenarios by giving developers the power to choose which primary and secondary authentication factors to use when challenging a user for their credentials.

This library provides the classes and methods necessary to implement native sign-in, directed by the developer, to follow specific workflows to meet your application's user experience.

Proposed solution

This proposal outlines the design for a Kotlin Multiplatform library that provides the interfaces and methods necessary to implement native sign-in flows using Okta's Direct Authentication APIs. By using this library, developers can build fully customized and integrated sign-in experiences, including support for Multi-Factor Authentication (MFA), directly within their native applications.

The initial implementation of this multiplatform library will focus on delivering support for Android as the first target platform. This will allow us to build a robust foundation and gather feedback from the mobile development community. Following the successful launch on Android, the library will be extended to support Java, enabling its use in a wider range of desktop and server-side applications.

A hybrid approach that combines both imperative and reactive paradigms will be used. This will be achieved by exposing a StateFlow<DirectAuthenticationState> alongside the imperative start function. This allows developers to choose the pattern that best fits their platform's architecture and development style.

Detailed design​

The core of the library is designed around a central interface, DirectAuthenticationFlow, which is configured via a DirectAuthenticationFlowBuilder. The authentication process is modeled as a state machine, where each step returns a DirectAuthenticationState that informs the application of the next required action.

DirectAuthenticationFlow Interface​

The DirectAuthenticationFlow is the primary entry point for developers. It exposes a single start method to initiate the authentication process. Once started, the flow returns a DirectAuthenticationState. Upon receiving a DirectAuthenticationState.Authenticated state, the application is responsible for storing the returned Token object, for example by using Credential.store() from the AuthFoundation library.

The authenticationState property is a StateFlow that emits updates to the current state of the authentication process. This is ideal for applications that prefer a reactive programming model, allowing them to observe state changes and update the UI accordingly.

/**
 * The primary interface for interacting with the Okta Direct Authentication API.
 *
 * This interface defines the contract for initiating an authentication flow. An instance
 * of this interface can be created using the `DirectAuthenticationFlow.create` builder.
 */
interface DirectAuthenticationFlow {

    /**
     * Indicates authentication flow state.
     */
    val authenticationState: StateFlow<DirectAuthenticationState>

    /**
     * Starts the direct authentication flow with an initial factor.
     *
     * This is the entry point for authenticating a user. Depending on the server's policy
     * and the provided factor, the flow may complete in a single step or require
     * additional steps, such as providing a secondary factor.
     *
     * @param loginHint A hint to the authorization server about the user's identity,
     *  such as a username or email address.
     * @param primaryFactor The initial authentication factor to use (e.g., a [PrimaryFactor.Password]).
     * @return A [DirectAuthenticationState] of the flow after processing the initial factor
     */
    suspend fun start(loginHint: String, primaryFactor: PrimaryFactor): DirectAuthenticationState
}

DirectAuthenticationFlowBuilder​

To create an instance of DirectAuthenticationFlow, developers use a builder that provides a fluent API for configuration. The builder validates essential parameters such as issuerUrl and clientId at creation time to prevent runtime errors. Upon creation, all configured properties are collected into a DirectAuthenticationContext object, which encapsulates the configuration for the authentication session, as described in the Authentication Flow Context documentation. This context is then passed to the internal DirectAuthenticationFlow implementation.

/**
 * A builder used to configure and create an instance of [DirectAuthenticationFlow].
 *
 * This class provides a fluent API for setting the necessary parameters for the
 * Direct Authentication flow, such as the issuer URL, client ID, and scopes.
 *
 * An instance of this builder should be created using the [DirectAuthenticationFlow.create] factory method.
 */
class DirectAuthenticationFlowBuilder private constructor() {
    /**
     * The intended user action for the authentication flow.
     *
     * This parameter indicates what the user is trying to achieve with the authentication request.
     * For example, [DirectAuthenticationIntent.SIGN_IN] or [DirectAuthenticationIntent.RECOVERY].
     *
     * Defaults to [DirectAuthenticationIntent.SIGN_IN].
     */
    var directAuthenticationIntent = DirectAuthenticationIntent.SIGN_IN

    /**
     * The list of grant types the client application supports for the Direct Authentication flow.
     *
     * This list informs the authorization server about the authentication methods the client can handle,
     * such as passwords, OTP, or OOB (out-of-band) factors.
     */
    var supportedGrantType = listOf(
        GrantType.Password,
        GrantType.Oob,
        GrantType.Otp,
        GrantType.OobMfa,
        GrantType.OtpMfa,
        GrantType.WebAuthn,
        GrantType.WebAuthnMfa
    )

    /**
     * A list of Authentication Context Class Reference values.
     *
     * This OIDC parameter requests that the user be authenticated with a particular level of assurance.
     * The values are defined by the authorization server's policy.
     */
    var acrValues = listOf<String>()

    /**
     * The HTTP client executor used to make network requests.
     *
     * This allows consumers to provide a custom implementation for making HTTP requests,
     * such as one that integrates with their existing networking stack or adds custom
     * headers for logging or analytics.
     *
     * Defaults to an instance of [KtorHttpExecutor] which uses Ktor's HTTP client.
     */
    var apiExecutor: ApiExecutor = KtorHttpExecutor()

    /**
     * The logger used by the SDK to output diagnostic information.
     *
     * This allows consumers to integrate the SDK's logging with their application's
     * existing logging framework, such as Timber or a custom solution. It can also be
     * replaced with a mock implementation for testing purposes.
     *
     * Defaults to an instance of [AuthFoundationLoggerImpl] which logs to Android's Logcat.
     */
    var logger: AuthFoundationLogger = AuthFoundationLoggerImpl()

    /**
     * The clock used for time-sensitive operations.
     *
     * This defaults to a clock that returns the current time in epoch seconds.
     */
    var clock: OidcClock = OidcClock { System.currentTimeMillis() / 1000 }

    companion object {
        /**
         * Creates an instance of [DirectAuthenticationFlow] using the builder pattern.
         *
         * @param issuerUrl The base URL of the Authorization Server. This is the issuer URI for the authorization server that will be used for the flow. For example: `https://dev-123456.okta.com`.
         * @param clientId The client ID of the application. This ID is obtained from the Okta developer console when you register your application.
         * @param scope The OAuth 2.0 scopes the application is requesting. Scopes are used to specify what access privileges are being requested for access tokens. For example: `openid`, `profile`, `email`, and `offline_access`.
         * @param buildAction A lambda with a [DirectAuthenticationFlowBuilder] receiver to configure the flow's parameters.
         *
         * @return A [Result] containing the configured [DirectAuthenticationFlow] on success,
         * or an exception on failure.
         */
        fun create(
            issuerUrl: String,
            clientId: String,
            scope: List<String>,
            buildAction: (DirectAuthenticationFlowBuilder.() -> Unit)? = null,
        ): Result<DirectAuthenticationFlow> = runCatching {
            // TODO(https://oktainc.atlassian.net/browse/OKTA-10087 return the DirectAuthenticatorFlow implementation)
        }.getOrElse { Result.failure(it) }
    }
}

Network abstraction​

The SDK's networking layer is designed to be flexible and extensible through a set of defined interfaces, ensuring it can be adapted to various project requirements without being tied to a specific HTTP client library. This abstraction is centered around the ApiExecutor interface.

• ApiExecutor: This is the core of the network abstraction. It defines a single execute method that takes an ApiRequest and returns an ApiResponse. By providing a custom implementation of this interface, developers can integrate the SDK with their application's existing networking stack, whether it's based on Ktor, OkHttp or another library. This is particularly useful for sharing a single HTTP client instance, adding custom interceptors for logging or analytics, or managing advanced configurations like certificate pinning.

• ApiRequest Hierarchy: Instead of depending on a specific library's request builder, the SDK defines its own request interfaces:

  • ApiRequest: The base interface defining common elements like the URL, HTTP method, headers, and query parameters.
  • ApiFormRequest: An extension for requests with application/x-www-form-urlencoded bodies, which is standard for many OAuth 2.0 token exchanges. It includes a formParameters() method.
  • ApiRequestBody: An extension for requests with a raw body, such as application/json, providing the body as a ByteArray.

  The SDK internally constructs objects that implement these interfaces. The ApiExecutor implementation is then responsible for translating these abstract request definitions into a concrete HTTP request for its underlying client library.

• ApiResponse: This interface standardizes the representation of an HTTP response, providing access to the status code, headers, and raw body (ByteArray). This ensures that the SDK's internal logic can parse the response consistently, regardless of which HTTP client is used to perform the request.

By abstracting the entire request/response cycle, the DirectAuthenticationFlow remains completely decoupled from the underlying networking implementation. This design enhances flexibility, allowing developers to use the tools they are already familiar with, and dramatically improves testability by making it simple to provide a mock ApiExecutor to simulate various network responses and error conditions during unit testing.

/**
 * An interface for executing API requests.
 */
interface ApiExecutor {
    /**
     * Executes the given API request.
     *
     * @param request The [ApiRequest] to execute.
     * @return The [ApiResponse] containing the response from the API.
     */
    suspend fun execute(request: ApiRequest): ApiResponse
}

/**
 * A specification for an HTTP API request to be executed by an [ApiExecutor].
 *
 * This interface defines all the necessary components of a request, such as the
 * target URI, HTTP method, headers, and body.
 */
interface ApiRequest {
    /**
     * The HTTP method to be used for the request (e.g., GET, POST).
     *
     * @return The HTTP method as an [ApiRequestMethod].
     */
    fun method(): ApiRequestMethod

    /**
     * Returns a map of HTTP headers to be included with the request.
     *
     * @return A map of header names to their corresponding values.
     */
    fun headers(): Map<String, List<String>>

    /**
     * Returns the complete URL for the request, including the scheme, host, and path.
     *
     * @return The request URL as a string.
     */
    fun url(): String

    /**
     * Returns a map of URL query parameters to be appended to the request URI.
     *
     * @return A map of query parameters, or null if there are none.
     */
    fun query(): Map<String, String>? = null
}

/**
 * An extension of [ApiRequest] for requests that include form parameters in the body.
 */
interface ApiFormRequest : ApiRequest {
    /**
     * The MIME type of the request body (e.g., `application/x-www-form-urlencoded`).
     *
     * This is typically used for methods like POST or PUT to indicate the format of the body content.
     */
    fun contentType(): String

    /**
     * Returns a map of form parameters to be sent as the request body with a
     * `application/x-www-form-urlencoded` content type.
     *
     * This allows for multiple values per key, which will be encoded as repeated key-value pairs
     * in the request body (e.g., `key=value1&key=value2`).
     *
     * @return A map of form parameters, or null if there are none.
     */
    fun formParameters(): Map<String, List<String>>
}

/**
 * An extension of [ApiRequest] for requests that include a body.
 */
interface ApiRequestBody : ApiRequest {
    /**
     * The MIME type of the request body (e.g., `application/json`).
     *
     * This is typically used for methods like POST or PUT to indicate the format of the body content.
     */
    fun contentType(): String

    /**
     * Returns the body of the request as a byte array.
     *
     * This is typically used for methods like POST or PUT with content types like `application/json`.
     *
     * @return The request body, or null if the request has no body.
     */
    fun body(): ByteArray
}

/**
 * Represents the response from an HTTP API request executed by an [ApiExecutor].
 *
 * This interface provides access to all components of the response, including the
 * status code, headers, and body.
 */
interface ApiResponse {
    /** The HTTP status code from the server's response (e.g., 200 for OK). */
    val statusCode: Int

    /** The raw response body as a byte array, or null if there is no body. */
    val body: ByteArray?

    /** A map of all response headers. */
    val headers: Map<String, List<String>>

    /** The length of the response body in bytes, as reported by the `Content-Length` header. */
    val contentLength: Long

    /** The MIME type of the response body, as reported by the `Content-Type` header. */
    val contentType: String
}

Factors​

Authentication factors are represented by a sealed interface hierarchy, which maps directly to the PrimaryFactor, SecondaryFactor types in the reference API. This allows for a type-safe representation of the different authentication methods.

/**
 * Represents an authentication factor that can be used as a secondary factor in an MFA flow.
 * This excludes primary-only factors like passwords.
 */
sealed interface SecondaryFactor : PrimaryFactor

/**
 * Represents an authentication factor used in a Direct Authentication flow.
 *
 * Factors are categorized as either Primary or Secondary to support multi-stage
 * authentication workflows.
 */
sealed interface PrimaryFactor {
    /**
     * A password factor, which can only be used as a primary factor.
     *
     * @param password The user's password.
     */
    data class Password(val password: String) : PrimaryFactor

    /**
     * An OTP (One-Time Passcode) factor.
     *
     * @param passCode The one-time passcode provided by the user.
     */
    data class Otp(val passCode: String) : SecondaryFactor

    /**
     * An OOB (Out-of-Band) factor, such as a push notification.
     *
     * @param channel The channel through which the OOB challenge should be sent.
     */
    data class Oob(val channel: OobChannel) : SecondaryFactor

    /**
     * A WebAuthn factor, used for phishing-resistant authentication with hardware
     * authenticators or biometrics.
     */
    data object WebAuthn : SecondaryFactor
}

DirectAuthenticationState​

The DirectAuthenticationState sealed class represents the various states of the authentication flow. Each state corresponds to a specific step in the process, guiding the application on what action to take next.

/**
 * Represents the current state of a Direct Authentication flow.
 *
 * This sealed interface defines the possible outcomes after an authentication step. The flow can
 * either be complete, resulting in a [Authenticated] state, or require further user interaction,
 * such as in an [MfaRequired] state or [Continuation] state
 */
sealed interface DirectAuthenticationState {

    /**
     * The initial state of the authentication flow, before any action has been taken.
     */
    data object Idle : DirectAuthenticationState

    /**
     * The authentication flow has been canceled
     */
    data object Canceled : DirectAuthenticationState

    /**
     * This state indicates that the authentication process is still pending and awaiting user action.
     * Such as waiting for the user to complete an out-of-band (OOB) authentication step.
     *
     * @param timestamp The time in milliseconds when the authorization became pending.
     */
    class AuthorizationPending internal constructor(val timestamp: Long) : DirectAuthenticationState

    /**
     * This state indicates that the user has been authenticated and tokens have been issued.
     *
     * @param token The [Token] containing the access, refresh, and ID tokens.
     */
    class Authenticated internal constructor(val token: Token) : DirectAuthenticationState

    /**
     * The authentication flow requires an additional factor to complete.
     *
     * This state indicates that the user must perform a Multi-Factor Authentication (MFA)
     * step to proceed.
     *
     * @param context The [DirectAuthenticationContext] associated with this state.
     * @param mfaContext The context required to continue the MFA flow.
     */
    class MfaRequired internal constructor(
        private val context: DirectAuthenticationContext,
        internal val mfaContext: MfaContext
    ) : DirectAuthenticationState {
        /**
         * Continues the authentication flow with the selected MFA factor.
         *
         * @param secondaryFactor The secondary [SecondaryFactor] to use for MFA (e.g., [PrimaryFactor.Otp], [PrimaryFactor.WebAuthn], etc.).
         * @return The next [DirectAuthenticationState] in the flow.
         */
        suspend fun resume(secondaryFactor: SecondaryFactor): DirectAuthenticationState {
            TODO("Not yet implemented")
        }
    }

    /**
     * Represents a state where an out-of-band (OOB) challenge has been initiated, and the
     * client must poll to determine the result.
     *
     * This state occurs after initiating an OOB flow, such as sending a push notification to
     * Okta Verify. The client should use the [poll] method to check if the user has
     * completed the authentication step.
     *
     * @param context The [DirectAuthenticationContext] associated with this state.
     * @param pollContext The context required to poll for the OOB authentication result.
     */
    class OobAuthenticate internal constructor(
        private val context: DirectAuthenticationContext,
        internal val pollContext: PollContext
    ) : DirectAuthenticationState {
        /**
         * Polls the token endpoint to check the status of the OOB authentication.
         *
         * This method should be called periodically until the state transitions to [Authenticated]
         * or an error occurs.
         *
         * @return A [Result] containing the new [DirectAuthenticationState]. If the user has not
         * yet completed the action, the result will be a success containing [AuthorizationPending].
         */
        suspend fun poll(): DirectAuthenticationState {
            TODO("Not yet implemented")
        }
    }
}

DirectAuthenticationError​

The DirectAuthenticationError sealed class represents various error states that can occur during the direct authentication process. It provides detailed information about the nature of the error, distinguishing between internal SDK errors, API-specific errors, and OAuth2-specific errors.

/**
 * Represents the various error states of direct authentication.
 */
sealed class DirectAuthenticationError : DirectAuthenticationState {
    /**
     * Represents an internal error that occurred during the direct authentication process.
     * This is typically used for non-HTTP related errors caused by unexpected conditions such as network failures or JSON parsing issues.
     *
     * @param errorCode A string representing the specific error code.
     * @param description An optional description of the error.
     * @param throwable The [Throwable] that caused this error.
     */
    class InternalError internal constructor(
        val errorCode: String,
        val description: String? = null,
        val throwable: Throwable
    ) : DirectAuthenticationError()

    /**
     * Represents an HTTP error that occurred during the direct authentication process.
     *
     * @param error A string representing the error.
     * @param httpStatusCode The [HttpStatusCode] associated with this error.
     */
    sealed class HttpError(val httpStatusCode: HttpStatusCode) : DirectAuthenticationError() {

        /**
         * An API-specific error that occurred during the direct authentication process.
         *
         * https://developer.okta.com/docs/reference/api/error-codes/
         *
         * @param errorCode A string representing the specific error code.
         * @param errorSummary An optional summary of the error.
         * @param errorLink An optional link to more information about the error.
         * @param errorId An optional unique identifier for the error instance.
         * @param errorCauses An optional list of causes for the error.
         * @param httpStatusCode The [HttpStatusCode] associated with this error.
         */
        class ApiError(
            val errorCode: String,
            val errorSummary: String?,
            val errorLink: String?,
            val errorId: String?,
            val errorCauses: List<String>?,
            httpStatusCode: HttpStatusCode,
        ) : HttpError(httpStatusCode)

        /**
         * An OAuth2-specific error that occurred during the direct authentication process.
         *
         * https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
         *
         * @param error A string representing the error.
         * @param errorDescription An optional description of the error.
         * @param httpStatusCode The [HttpStatusCode] associated with this error.
         */
        class Oauth2Error(
            val error: String,
            httpStatusCode: HttpStatusCode,
            val errorDescription: String?,
        ) : HttpError(httpStatusCode)
    }
}

DirectAuthenticationErrorCode​

The DirectAuthenticationErrorCode enum defines specific error codes used within the Direct Authentication flow. These codes help in identifying the exact nature of an authentication error, including custom codes for MFA requirements and standard OAuth2 error codes.

/**
 * Error codes specific to Direct Authentication.
 */
internal enum class DirectAuthenticationErrorCode(val code: String) {
    MFA_REQUIRED("mfa_required"), // Custom error code for MFA requirement
    AUTHORIZATION_PENDING("authorization_pending"), // Custom error code for authorization pending

    // following are standard OAuth2 error codes https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
    ACCESS_DENIED("access_denied"),
    INVALID_GRANT("invalid_grant"),
    INVALID_REQUEST("invalid_request"),
    INVALID_SCOPE("invalid_scope"),
    INVALID_CLIENT("invalid_client"),
    UNAUTHORIZED_CLIENT("unauthorized_client"),
    UNSUPPORTED_GRANT_TYPE("unsupported_grant_type"),
    UNSUPPORTED_RESPONSE_TYPE("unsupported_response_type"),
    TEMPORARILY_UNAVAILABLE("temporarily_unavailable"),
    SERVER_ERROR("server_error")
}

Continuation​

The Continuation sealed class is a specialized DirectAuthenticationState that represents points in the authentication flow where the process is paused, awaiting further client-side action. This is common in flows that require more than a simple data entry, such as interacting with platform APIs (like WebAuthn) or handling out-of-band (OOB) verification. Each subclass of Continuation provides a proceed function, which the application calls to continue the flow after the required action is completed.

/**
 * Represents a state in the Direct Authentication flow where further action is required to proceed.
 *
 * This is a special type of [DirectAuthenticationState] that indicates the flow is paused,
 * pending input from the user or another client-side process.
 *
 * @param context The [DirectAuthenticationContext] associated with this state.
 * @param mfaContext An optional context for MFA flows, which may be present if the continuation
 * is part of a multi-factor sequence.
 */
sealed class Continuation(
    private val context: DirectAuthenticationContext,
    private val mfaContext: MfaContext? = null
) : DirectAuthenticationState {
    /**
     * A continuation that requires a WebAuthn (passkey) challenge to be completed.
     *
     * This state provides the necessary challenge data to interact with the platform's
     * WebAuthn/passkey APIs.
     *
     * @param challengeData The challenge data from the server, to be passed to the platform's WebAuthn API.
     * @param context The [DirectAuthenticationContext] associated with this state.
     * @param mfaContext An optional context for MFA flows.
     */
    class WebAuthn internal constructor(
        val challengeData: String,
        context: DirectAuthenticationContext,
        mfaContext: MfaContext? = null
    ) : Continuation(context, mfaContext) {
        /**
         * Proceeds with the authentication flow with the response from the WebAuthn/passkey ceremony.
         *
         * @param authenticationResponseJson The JSON response from the platform's WebAuthn API.
         * @return The next [DirectAuthenticationState] in the flow.
         */
        suspend fun proceed(authenticationResponseJson: String): Result<DirectAuthenticationState> {
            TODO("Not yet implemented")
        }
    }

    /**
     * A continuation that requires the user to enter a code, such as an OTP from an
     * authenticator app or a code sent via email/SMS.
     *
     * @param bindingContext Internal context required to continue the flow.
     * @param context The [DirectAuthenticationContext] associated with this state.
     * @param mfaContext An optional context for MFA flows.
     */
    class Prompt internal constructor(
        private val bindingContext: BindingContext,
        context: DirectAuthenticationContext,
        mfaContext: MfaContext? = null
    ) : Continuation(context, mfaContext) {
        /**
         * Proceeds with the authentication flow with the user-provided code.
         *
         * @param code The one-time code entered by the user.
         * @return The next [DirectAuthenticationState] in the flow.
         */
        suspend fun proceed(code: String): Result<DirectAuthenticationState> {
            TODO("Not yet implemented")
        }
    }

    /**
     * A continuation for an out-of-band (OOB) flow, where authentication happens on another device.
     *
     * This state is common for flows like "Okta Verify Push" where the user approves a prompt
     * on their phone.
     *
     * @param bindingContext Internal context required to continue the flow.
     * @param context The [DirectAuthenticationContext] associated with this state.
     * @param mfaContext An optional context for MFA flows.
     */
    class Transfer internal constructor(
        private val bindingContext: BindingContext,
        context: DirectAuthenticationContext,
        mfaContext: MfaContext? = null
    ) : Continuation(context, mfaContext) {
        /**
         * A code that can be displayed to the user to link devices or verify the transaction.
         */
        val bindingCode = bindingContext.bindingCode

        /**
         * Proceeds with the authentication flow by polling the server to check the status of the
         * out-of-band authentication.
         *
         * @return The next [DirectAuthenticationState] in the flow, which will typically be
         * [DirectAuthenticationState.Authenticated] once the user has approved the OOB prompt.
         */
        suspend fun proceed(): Result<DirectAuthenticationState> {
            TODO("Not yet implemented")
        }
    }
}

Example usage​

Here is a simplified example of how a developer might use the Direct Authentication SDK to implement a custom sign-in flow in an Android application using a imperative style. This example assumes the existence of UI components to collect user input and display messages.

// Create the DirectAuthenticationFlow instance using the builder
val flow = DirectAuthenticationFlowBuilder.create {
    issuerUrl = "https://example.com"
    clientId = "client-id"
    scope = listOf("openid", "profile", "email")
}.getOrThrow()

// Start the authentication flow with the user's login and password
flow.start(
    loginHint = "fake.user@okta.com",
    primaryFactor = PrimaryFactor.Password("SuperSecretPassword")
).also { initialStatus ->
    // Recursively handle all intermediate steps until a Success status or exception thrown.
    runCatching { resolveAuthStatus(initialStatus) }
        .onSuccess { completedStatus ->
            val token = completedStatus.token
            // Credential.store(token) // Store tokens securely
            // Proceed with authenticated actions
        }.onFailure {
            // Handle errors (e.g., network issues, invalid credentials)
            println("Authentication failed: ${it.message}")
        }
}

// A tail-recursive function to handle the authentication flow until a terminal state is reached.
// Such as Authenticated, Canceled or DirectAuthenticationError.
// Recursively handles MFA requirements and continuations.
private tailrec suspend fun resolveAuthStatus(authStatus: DirectAuthenticationState): DirectAuthenticationState {
    return when (authStatus) {
        is DirectAuthenticationState.Authenticated, is DirectAuthenticationState.Canceled, is DirectAuthenticationError -> {
            // Base case. Authenticated, Canceled or error
            authStatus
        }

        is DirectAuthenticationState.MfaRequired -> {
            // MFA is required, handle the MFA context
            // Ask the user to choose a factor. Here we automatically choose an OTP factor for demonstration.
            resolveAuthStatus(authStatus.resume(PrimaryFactor.Otp("123456")))
        }

        is DirectAuthenticationState.OobAuthenticate -> {
            // Prompt the user to complete an out-of-band action. For Okta Verify, show the bindingCode. Resume will poll the server for status.
            resolveAuthStatus(authStatus.poll())
        }

        is Continuation.Prompt -> {
            // Prompt the user for a code. Here we automatically provide a code for demonstration.
            resolveAuthStatus(authStatus.proceed("123456").getOrThrow())
        }

        is Continuation.Transfer -> {
            // Prompt the user to complete an out-of-band action. For Okta Verify, show the bindingCode. Resume will poll the server for status.
            resolveAuthStatus(authStatus.proceed().getOrThrow())
        }

        is Continuation.WebAuthn -> {
            // Invoke the platform's WebAuthn API with the challengeData. For demonstration, we simulate a WebAuthn response.
            resolveAuthStatus(authStatus.proceed("authenticationResponseJson").getOrThrow())
        }
    }
}

Alternatively, developers can choose to use a reactive style by collecting the authenticationState flow. This approach is well-suited for applications that leverage reactive programming paradigms, such as those using Jetpack Compose or other state-driven UI frameworks. In this example, we launch a coroutine to collect state changes and handle them accordingly.

 val flow = DirectAuthenticationFlowBuilder.create(
    issuerUrl = "https://example.com",
    clientId = "client-id",
    scope = listOf("openid", "profile", "email")
).getOrThrow()

// Launch a coroutine to collect state changes from the flow.
val job = launch {
    flow.authenticationState.collect {
        handleAuthStatus(it)
    }
}

// Start the flow, which will emit the initial status to the collector.
flow.start("name", PrimaryFactor.Password("secret"))

// job.cancel()

private suspend fun handleAuthStatus(authStatus: DirectAuthenticationState) {
    when (authStatus) {
        is DirectAuthenticationState.Authenticated -> {
            // Authentication is complete. You can access the token here.
            authStatus.token
        }

        is DirectAuthenticationState.MfaRequired -> {
            // Ask the user to choose a factor. Here we automatically choose an OTP factor for demonstration.
            authStatus.resume(PrimaryFactor.Otp("123456"))
        }

        is DirectAuthenticationState.OobAuthenticate -> {
            // Prompt the user to complete an out-of-band action and continue. Resume will poll the server for status.
            authStatus.poll()
        }
        else -> { /* Handle other states like Idle, Canceled, AuthorizationPending, or Errors */
        }
    }
}

Example Sequence Diagram​

The following sequence diagrams are simplified for clarity. In a real-world scenario, additional error handling, logging, and edge cases would need to be considered. Handling of polling intervals is not shown for brevity.

Sequence Push OOB MFA flow​

Sequence OTP MFA flow​

The following sequence diagram illustrates a multi-factor authentication flow where the user first authenticates with a password and is then prompted for a second factor. In this example, the application provides a One-Time Passcode (OTP).

Sequence Okta Verify push with number challenge flow​

The following sequence diagram illustrates a multi-factor authentication flow where the user first authenticates with a password and is then prompted for a second factor. In this example, the application provides an out-of-band (OOB) verification method, such as Okta Verify Push with a binding code(number challenge). This flow initiates the second factor by calling the /challenge endpoint, unlike the OTP example which calls /token directly. The /challenge endpoint is optional and is used when the client needs the server to drive the next step, such as sending a push notification. If the client can determine the next factor on its own (for example, by prompting the user for an OTP), it can bypass this step and call /token directly with the factor details.

Implications on adoption​

This library introduces a new, additive capability for building native authentication experiences. It does not introduce any breaking changes to existing functionalities, such as browser-based redirect flows. Developers can continue to use existing authentication methods without any impact. The primary implication for developers choosing to adopt the Direct Authentication flow is that they assume full responsibility for building and maintaining the user interface for the entire authentication process. This includes screens for username/password entry, multi-factor authentication (MFA) challenges, and account recovery steps. While this provides complete control over the user experience and branding, it requires a more significant development effort compared to redirect-based flows where the UI is hosted by Okta.

More information about the advantages and disadvantages of using this library can be found at the following: https://developer.okta.com/docs/concepts/direct-authentication/

Future directions​

The following are potential enhancements and directions for the Direct Authentication SDK after its initial release.

• Multiplatform Expansion: The initial implementation will target Android. Future work could extend support to other platforms, including JVM for server-side and desktop applications. Based on developer demand, this could be further expanded to include JavaScript (for web clients) and native iOS/macOS targets.

• AuthFoundation Evolution: Supporting a broader set of platforms will require evolving the underlying auth-foundation library to be fully multiplatform. This may involve refactoring some of its core interfaces to be more flexible and abstract away platform-specific dependencies, ensuring a consistent and reusable architecture across all supported environments.

• New Authenticators: The SDK is designed to be extensible. As new authentication methods become available or are prioritized by Okta, support for additional factors can be seamlessly integrated into the existing Factor and Continuation models.

• Integration with OAuth2Client: To simplify configuration for developers already using the auth-foundation library, the DirectAuthenticationFlowBuilder could be enhanced to accept an OAuth2Client instance. This would allow the builder to automatically populate common parameters like clientId, scope, and issuerUrl from the existing client, reducing boilerplate code and ensuring consistency across different authentication-related components of an application.

Alternatives considered​

The design of DirectAuthenticationFlow intentionally combines elements from both imperative and reactive programming paradigms to offer developers flexibility. Several alternative approaches were considered:

• Purely Imperative (suspend functions only): An API could be designed using only suspend functions, where each function call blocks (asynchronously) and returns the next state.

  • Pros: Simple to understand for developers familiar with sequential code. Follows a clear request-response pattern.
  • Cons: This model is less suitable for modern, state-driven UI frameworks (like Jetpack Compose or SwiftUI) which are designed to react to streams of data. Managing UI updates would require more manual, imperative code from the developer. It also makes handling background state changes (like from a polling operation) more complex to propagate to the UI.

• Purely Reactive (StateFlow only): The API could be designed to expose only a StateFlow and functions to submit actions (e.g., submitFactor(factor)). The result of an action would only be observable through the flow.

  • Pros: Aligns perfectly with reactive UI patterns. All state changes are handled through a single, consistent mechanism.
  • Cons: This can make handling the result of a specific, one-off action more complex. For example, the result of the initial start call (which might fail due to a simple configuration error) would be delivered asynchronously through the flow, which can be unintuitive. It mixes immediate validation feedback with asynchronous state transitions.

• Chosen Hybrid Approach: The proposed design uses an imperative start function that returns an initial state directly, providing immediate feedback. Subsequent state changes can then be observed through the authenticationState StateFlow.

  • Pros: It offers the best of both worlds. The imperative start call is natural for initiating an action and getting a direct result. The StateFlow is ideal for observing the subsequent, asynchronous state transitions in a reactive way, fitting well with modern UI development.
  • Cons: Developers need to be comfortable with both suspend functions and Flow, which adds a slight learning curve compared to a single-paradigm approach.

By providing both an imperative entry point and a reactive state stream, the SDK empowers developers to choose the pattern that best fits their application's architecture while promoting best practices for modern native development.

Alignment with Reference Architecture​

The KMP implementation, while heavily influenced by the original Apple (Swift) reference architecture, introduces several key differences to provide a more idiomatic and type-safe experience for Kotlin developers. The core concepts remain consistent, but the execution and developer interaction have been tailored to the strengths of the Kotlin language and its ecosystem.

Key Architectural Differences:​

Analysis of the differences​

The KMP (Kotlin) implementation of Okta's Direct Authentication is a Kotlin variation of the original Apple (Swift) design. It embraces modern Kotlin features to offer a type-safe, thread-safe, and developer-friendly experience.

While the fundamental authentication flows and concepts are aligned, the KMP SDK is not a direct port. It has been redesigned to be idiomatic for the Kotlin ecosystem, prioritizing:

• Type Safety: The state machine design in the KMP version is inherently safer, reducing the possibility of runtime errors by leveraging Kotlin's strong type system.
• Modern Asynchronicity: The use of coroutines and suspend functions aligns with current best practices in Kotlin development, leading to cleaner and more manageable asynchronous code.
• Reactive Architecture: The adoption of StateFlow makes the KMP SDK a natural fit for modern, declarative UI frameworks, simplifying state management for the developer.

In essence, the KMP implementation takes the core principles of the Apple reference architecture and refines them to follow Kotlin patterns, resulting in an SDK that feels native to the Kotlin language and provides a more streamlined and secure development experience.

In-depth analysis of the differences​

Here is a detailed analysis of the differences between the OktaDirectAuth Apple (Swift) and KMP (Kotlin) implementations, focusing on the networking layer and state mutability.

Networking Layer​

KMP (Kotlin) Implementation:

The KMP implementation uses the Ktor client for handling HTTP requests. This is a modern, multiplatform networking library from JetBrains that allows for a single networking implementation to be shared across all target platforms.

• KtorHttpExecutor: This class is responsible for executing API requests. It creates and configures a Ktor HttpClient with plugins for timeouts, cookies, and caching. It's designed to be extensible, allowing developers to provide their own pre-configured Ktor client if needed.
• DirectAuth...Request: These classes represent the individual API requests. They define the endpoint, HTTP method, headers, and body of the request. This creates a clean separation between the definition of a request and its execution.

Apple (Swift) Implementation:

The Swift implementation abstracts the networking layer into a separate AuthFoundation framework. The OktaDirectAuth module itself does not contain any code for making network calls.

• APIRequest protocol: Request objects, such as OOBAuthenticateRequest, conform to the APIRequest protocol from the AuthFoundation framework. This protocol defines the properties of a request (URL, HTTP method, parameters, etc.).
• AuthFoundation: This framework is responsible for taking the APIRequest object, executing the network call ( likely using URLSession internally), and decoding the response. This approach decouples the authentication logic from the underlying networking implementation.

Comparison:

State Mutability​

KMP (Kotlin) Implementation:

The KMP implementation uses a reactive, unidirectional data flow model for state management, which is idiomatic for modern Kotlin applications.

• DirectAuthenticationState: This is a sealed interface that represents all possible states of the authentication flow (e.g., Idle, Authenticated, MfaRequired). Using a sealed interface ensures that all possible states are known at compile time.
• StateFlow: The DirectAuthenticationFlowImpl class uses a MutableStateFlow to hold the current DirectAuthenticationState. It exposes this as an immutable StateFlow to clients. This allows clients (such as a UI layer) to observe the state and react to changes automatically.
• Immutability: The DirectAuthenticationState objects are immutable. State transitions are handled by creating a new state object and updating the StateFlow.

Apple (Swift) Implementation:

The Swift implementation uses Swift's modern concurrency features, specifically actors, to manage state in a thread-safe manner.

• Status enum: Similar to the KMP implementation, the Swift code defines a Status enum to represent the different states of the flow (e.g., success, mfaRequired).
• DirectAuthenticationFlow actor: The main DirectAuthenticationFlow class is an actor. This ensures that all access to its internal mutable state (such as the _context property which holds the current Status) is synchronized and free of data races.
• State Updates: State is updated by calling async functions on the actor (e.g., start, resume). These functions return the new Status upon completion. Additionally, a delegate protocol ( DirectAuthenticationFlowDelegate) is used to notify listeners of state changes.

Comparison:

Acknowledgments​

• Alex Nachbaur, for her work on the okta-client-swift SDK, which served as a reference point for this design.
• Rajdeep Nanua, for his work on the AuthFoundation library, which provides the foundational components for this SDK.

Motivation​

The WebAuthenticationUI framework library was named during the initial development of the Client SDK, when only Swift and Kotlin were planned, and it was specifically targeting native application environments. It was also named to indicate its use as a UI-facing library. However, the SDK's modularization into logical layers has been refined since then, and encompasses not only UI-facing environments, but integration into other more abstact application development frameworks.

Another motivation is the upcoming support for Passkeys / WebAuthn, which could result in developers confusing the WebAuthenticationUI library with WebAuthn.

Fundamentally, the names of these framework libraries should represent the technology or framework being used. Web-redirect sign-in ultimately will always be web-based, so naming the library after "WebAuthentication" is redundant.

As a result, a clearer name should be adopted to address these problems.

Design objectives​

1. Select a new name that more clearly represents the developer's use-case.
2. Ensure the name can be consistently applied across all relevant environments.
3. Pave the way for Passkey/WebAuthn libraries.

Proposed solution

The name this proposal recommends is: BrowserAuthentication. There are several reasons this name is chosen:

• This more specifically indicates that a browser itself will be used to enable user sign-in.
• The UI suffix is dropped as it's redundant.
• The name is generic enough that it can apply to both Apple/Android environments, native desktop applications, and potentially even Javascript environments (particularly within hybrid environments like React Native and Electron).

Detailed design​

The library targets / names should be changed from WebAuthenticationUI to BrowserAuthentication, with the WebAuthentication class also adopting the name BrowserAuthentication. Compilers should be able to disambiguate the namespace from the class name, but in languages where that isn't possible another name can be considered for the class.

Implications on adoption​

• This change would necessitate a major Semver version change, since this would represent a breaking API update (e.g. library/namespace names do not often support deprecation attributes in most languages).
  • In languages that support deprecation markers or type aliases, the class name itself can include these to simplify developer migration.
• Documentation and sample app updates would be necessary, to ensure the changes can be easily adopted by developers.
• Package managers may need to be updated explicitly to communicate the deprecation of the old framework names to developers.

Alternatives considered​

Alternative names were considered, but within discussions among the Okta SDK engineers, this seemed to be the clearest and most platform-agnostic name that best communicated the library's intended purpose.

We also considered not making any changes, and leaving the name as-is. But with our future roadmap plans for expanding support for the Client SDKs to more languages and platforms, this seems like the perfect time to rename this library: the scope is currently limited to two platforms (Swift and Kotlin), but over time this will become increasingly difficult to change.

Motivation​

Swift has been incrementally introducing new concurrency features to the language which protects developers from a variety of hard-to-diagnose runtime errors. Many of these features were only available if a developer opted-in to those features. With the release of Swift 6, these optional features are enabled by default, which has a huge impact on developers.

More importantly, these language features make it significantly easier for developers to fix a variety of runtime problems, such as data races, preventing concurrent access to shared mutable state, and many other tricky edge-cases.

The Okta Client SDK has been stable for a long time, but recent updates to Swift and Apple's platforms caused rare threading issues to become much more common, negatively impacting users and introducing tricky race conditions. This is most prevalent in the race conditions around the default credential property.

This SDK was originally built around completion blocks, with support for Swift Concurrency async functions added as optional wrappers around those block-based APIs. This was because Swift Concurrency was fairly new at the time, and wasn't available to all supported versions of iOS. As a result, actor isolation context and task inheritance won't work with the SDK's current architecture.

To that end, the Okta Client SDK is being updated to fully support Swift 6 concurrency features, will harden its underlying foundations to leverage modern language capabilities, and to eliminate entire classes of runtime multithreading safety issues.

Design objectives​

1. Adopt new Swift 6 language features
2. Maintain backwards compatibility with Swift 5.10
3. Enable future development to easily use new language fatures
4. Maintain an optimal Developer Experience for users of the SDK

Detailed design

Ultimately Swift 6 language compatibility is a secondary concern to the concerns around data races and thread safety. To support this, the SDK should:

1. Update existing APIs and types to limit the surface area for mutable properties, changing common objects to value types, etc.
2. Update classes, structs, and other data types to conform to the Sendable protocol, explicitly identifying which objects can safely transit isolation contexts.
3. Adopt Swift Concurrency (e.g. async/await) and Task Inheritance to ensure proper actor isolation across context boundaries.
4. Adopt Actor types for highly-asynchronous components (e.g. Token Storage, Authentication Flows, etc) to guarantee serialized access to shared state across the system.
5. Explicitly mark commonly-used properties and functions as nonisolated, implementing other thread safety features (like locks or semaphores) to prevent all APIs requiring async access.

To support Swift 6 Complete Concurrency Checking, a lot of small changes needed to be made, such as marking types as conforming to Sendable, marking blocks as @Sendable, and updating other libraries to adapt to changes in interfaces defined in AuthFoundation.

Limit mutable API surface area​

Several sections of the API feature mutable state, or state spread across different properties. For example, additionalHttpHeaders on the OAuth2Client is defined as a var, or Authentication Flows which contains a variety of mutable properties which change throughout the authentication flow (such as authenticationUrl, device authorization flow verification data, etc). Not only do these mutable properties pose problems for data race safety, but they highlight problems in consistency across a variety of APIs.

To limit the scope of these mutable properties, Authentication Flows should all include a required Context type which can contain all developer-assigned customizations during an individual sign-in session, but can also contain any in-progress state that may change throughout the sign in operation.

public protocol AuthenticationFlow {
    associatedtype Context: AuthenticationContext

    var context: Context? { get }
    var isAuthenticating: Bool { get }

    // Other common properties / functions
}

public protocol AuthenticationContext: ProvidesOAuth2Parameters {
    // Common properties / functions applicable to all context types
    var acrValues: [String]? { get }
}

Not only can this restrict the mutable values to context and isAuthenticating, but it also can simplify how authentication values can pass from flows and OAuth2Client configuration to their accompanying requests.

The ProvidesOAuth2Parameters protocol can be updated to be more expressive, allowing a flow and its context to supply information to the request based on the type of request being performed.

public protocol ProvidesOAuth2Parameters {
    func parameters(for category: OAuth2APIRequestCategory) -> [String: any APIRequestArgument]?
}

public enum OAuth2APIRequestCategory {
    case configuration
    case authorization
    case token
    case resource
    case other
}

For example, in the context for AuthorizationCodeFlow, this can be used to ensure PKCE data, state, and other values can be supplied at the correct stage of the flow.

func parameters(for category: OAuth2APIRequestCategory) -> [String: any APIRequestArgument]? {
  // Allow the developer to supply arbitrary values
  // to pass through to outgoing requests.
  var result = additionalParameters ?? [:]

  switch category {
  case .authorization:
    result["state"] = state
    result["response_type"] = "code"

    if let nonce = nonce {
      result["nonce"] = nonce
    }

    if let pkce = pkce {
      result["code_challenge"] = pkce.codeChallenge
      result["code_challenge_method"] = pkce.method
    }

    // Other values ...
      
  case .token:
    if let pkce = pkce {
      result["code_verifier"] = pkce.codeVerifier
    }
    
  case .configuration, .resource, .other:
    // No special values needed in these requests
    break
  }
  
  return result
}

Adopt Sendable in classes / types​

In order to use strict concurrency checking, objects need to conform to the Sendable protocol (including blocks/closures which need to apply the @Sendable attribute) to indicate they're safe to be used or sent across isolation contexts. Adding conformances to this protocol automatically enfores a number of compilation checks which will require code changes to comply with these new checks.

Wherever possible, using immutable properties or value types to enable implicit conformance, but there will be times where more explicit handling of Sendable checks will be neccessary. In those cases, it may be necessary to utilize locks or semaphores where appropriate to ensure objects can be sendable.

Use async/await and Tasks​

Much of Swift's new concurrency features center around async operations, as well as the use of Tasks. Unlike Grand Central Dispatch (GCD) and the use of blocks within Dispatch Queues, Tasks establish an inherited relationship between asynchronous operations which not only can pass along priority information, but can enable task cancellation that can propagate across multiple operations.

This will be a prerequisite for adopting any of these other concurrency features so this context can be maintained between operations.

To better understand how this will play out in the real world, consider the following example:

1. A user clicks a "Sign In" button in their application, which triggers an event within the @MainActor.
2. The WebAuthentication.shared property is accessed which loads the Okta.plist configuration, implicitly creates an instance of the WebAuthentication class, and creates the appropriate OAuth2Client as well as the flows used for sign-in and -out.
3. The start() async throws -> Token function is called, which performs a series of steps necessary to create an authorization URL.
   1. The OAuth2Client performs a request to fetch the client's /.well-known/openid-configuration endpoint.
   2. The authorize URL is fetched, PKCE data is generated, and a URL is formed.
   3. A delegate function is called to allow the developer's application to alter the URL before being opened.
   4. An instance of ASWebAuthenticationSession is initiated with the authorize URL, and is presented to the user.
4. The browser session returns the resulting redirect URI, which the SDK consumes, validates the response data, and extracts the authorization code.
5. This code is sent to the AuthorizationCodeFlow instance within the WebAuthentication object, and is used against the /token endpoint to request a token.
6. In parallel to the token request, the /keys endpoint is fetched to proactively load the JWK keyset the authoriation server is using.
7. Once both request responses are received, the tokens are validated and returned to the developer.

This workflow involves a number of asynchronous operations initiated by a user, many of which may be canceled for a variety of reasons. If completion blocks are used to trigger any of these steps, the information about task priority, the relationship between the tasks, and the cancellation of any of those operations is impossible to determine.

Use Actors where neccessary​

Actors are a relatively new capabiity within the Swift language. These are reference types, similar to classes, except there are several key differences that make them distinct from classes.

Actors guarantee serial access to callers, ensuring that mutations are isolated and aren't susceptable to race conditions. This comes at the cost of requiring all accesses to their isolated members (from outside the actor itself, or its global context) to be asynchronous, including properties. This negatively affects the developer experience (DX), so actors should only be used within isolated areas that are seldom used directly by consumers of the SDK, and that could benefit from data race saftey.

The areas that should be focused on are:

• Token Storage / Credential subsystem
• Authentication Flows
• Async conveniences / internals

Token Storage​

Given that the main concerns that precipitated these updates are related to token storage, and handling of the default token, this is the area that should be given the most attention.

Since a number of classes and protocols interact to form the token storage system, it makes sense to ensure that these classes can easily coordinate with one-another without unneccessary async operations across isolation contexts. As a result, this area should share a common custom global context to ensure they all share the same serial executor, and to simplify the way callers can coordinate with that isolation context.

Authentication Flows​

Authentication Flows are by their very nature asynchronous operations the user interacts with. Furthermore, the main access points (the start and resume functions) are already async functions. To simplify matters, the AuthenticationFlow protocol can ensure only actors can conform to that protocol.

Any other property on authentication flows beyond start and resume should do their best to remain nonisolated either by being immutable properties referencing Sendable value types, or should utilize semaphores to ensure the async interactions with the actor's isolation context can be safely serialized to the caller.

Optimize Developer Experience w/nonisolated properties & functions​

As mentioned in the previous section, ensuring an optimal developer experience (DX) is important, and requiring all interactions with SDK APIs to be async would hurt the development experience and could even introduce additional bugs through improper use of these APIs by developers.

Therefore common patterns should be adopted to consistently, and safely, enable synchronous access to objects and classes, while maintaining thread safety. Additionally, interactions with delegates should either consistently dispatch to the @MainActor, or should safely inherit the caller's isolation context, to limit the number of unneccessary synchronizations across threads.

Implications on adoption

There are some risks in adopting Swift 6 which should be carefully avoided to reduce the negative impact on the developer experience, and to ensure quick adoption.

• Avoid leaking too many async operations to developers, preserving synchronous APIs wherever possible.
• Provide completion wrappers for async operations for developers who haven't yet adopted Swift Concurrency, or who are using the SDK from synchronous contexts (e.g. SwiftUI action blocks).
• Limit the use of actors to areas not commonly used directly by developers, or in areas that are already asynchronous (using nonisolated in areas that don't require complete async operations, like immutable properties or initializers).
• Ensure task cancellation is supported, and that task priority inheritance works as expected.
• Try to avoid crossing isolation contexts unneccessarily, inheriting actor contexts appropriately.

Future directions​

By using Actors and Swift 6 concurrency, this sets the stage to adopt new Swift features more easily in the future. This can also simplify tighter integration with other Apple frameworks like SwiftUI, to provide more developer conveniences and to simplify customer deployments.