Onboarding, login, signIn flow

[azlekov]

Hello,

I'm considering some modern approaches for rewrite an old style app to KMM. I'm interested in few things particularly - deep links, onboarding and authentication across screens. I saw that there is documentation about the deep links (thanks for that) but can someone give me some guidelines, some pseudo code, sample or something about what should be the proper way implementing authentication with Decompose?

Other kits and libraries I saw, enforce to check on each screen and preserve the login state with a flag or something. Is there a central way let's say via the router aka. child stack?

Is Decompose flexible enough to handle session expiration for example?

All kinds of information are more than welcome! Thanks! 🙏

[arkivanov]

Hello and thanks for the question!

After quickly searching through GitHub, I found Lastik app which seems to have an auth feature. But I didn't deep dive into the implementation details. Maybe other folks could provide their examples?

what should be the proper way implementing authentication with Decompose?

I believe there couldn't be any single "proper" way of handling authentication. Decompose is very flexible and different developers may come up with different ideas specific for their projects.

Is there a central way let's say via the router aka. child stack?

The first idea is to utilize Custom ComponentContext. You could create some sort of AuthController and expose it from the custom AppComponentContext, so it would be available in all components automatically.

Overall, this highly depends on the exact requirements of your project. Maybe you could describe in more details what screens do you have and what is the logic behind handling the authentication?

[azlekov]

@arkivanov thanks for the quick response first.

The use case is a very common one. Onboarding with 3-4 screens with info and requesting set of permissions (this should be executed only the first time). After the onboarding we have phone sign in - enter phone screen then verify code screen (if is new user it should be able to fill some details and submit in additional screen) and from there on the user sees a bottom nav or rail depending on screen.

I have tabs with lists inside the bottom nav items, something like nested navigation but this shouldn't be a problem, right?

[arkivanov]

Sure, the navigation shouldn't be a problem, here is an approximate component hierarchy.

Root ┐
     ├ Onboarding ┐
     │            ├ Step1
     │            ├ Step2
     │            └ Step3
     ├ SignIn ┐
     │        ├ EnterPhone
     │        └ CodeVerification
     └ Main ┐
            ├ Feature1
            └ Feature2

What is logic behind the auth handling? Why do you need it globally available? Can credentials expire?

[azlekov]

@arkivanov I'm thinking how to organize everything so when user clicks on a deep link and it's not logged in, to go first trough the sign in process and then to continue with the deep link. This is what you mentioned about custom context I suppose?

If this can be handled on a top root level maybe I do not need it globally available.

[arkivanov]

Custom ComponentContext is only needed when you need to provide something to most of the components, e.g. this could be a http client, a logger, an analytics tracker, or auth handler. If all you need is "to go first through the sign in process and then to continue with the deep link", then most likely you don't need the custom ComponentContext.

Here is an example of component interfaces:

interface Onboarding

interface SignIn

interface Feature1

interface Feature2

interface Main {
    val childStack: Value<ChildStack<*, Child>>

    sealed interface Child {
        class Feature1Child(val component: Feature1) : Child
        class Feature2Child(val component: Feature2) : Child
    }
}

interface Root {
    val childStack: Value<ChildStack<*, Child>>

    sealed interface Child {
        class OnboardingChild(val component: Onboarding) : Child
        class SignInChild(val component: SignIn) : Child
        class MainChild(val component: Main) : Child
    }
}

interface SignInController {
    val isSignedIn: Boolean
}

Here is an example of implementations:

class RootComponent(
    componentContext: ComponentContext,
    signInController: SignInController,
    private val deepLink: String?,
) : Root, ComponentContext by componentContext {

    private val navigation = StackNavigation<Config>()

    private val stack =
        childStack(
            source = navigation,
            initialConfiguration = if (signInController.isSignedIn) Config.Main else Config.Onboarding,
            childFactory = ::child,
        )

    override val childStack: Value<ChildStack<*, Root.Child>> get() = stack

    private fun child(config: Config, componentContext: ComponentContext): Root.Child =
        when (config) {
            is Config.Onboarding -> Root.Child.OnboardingChild(onboarding(componentContext))
            is Config.SignIn -> Root.Child.SignInChild(signIn(componentContext))
            is Config.Main -> Root.Child.MainChild(main(componentContext))
        }

    private fun onboarding(componentContext: ComponentContext): Onboarding =
        OnboardingComponent(
            componentContext = componentContext,
            onFinished = { navigation.replaceCurrent(Config.SignIn) } // Switch to SignIn
        )

    private fun signIn(componentContext: ComponentContext): SignIn =
        SignInComponent(
            componentContext = componentContext,
            onFinished = { navigation.replaceCurrent(Config.Main) }, // Switch to Main
        )

    private fun main(componentContext: ComponentContext): Main =
        MainComponent(componentContext = componentContext, deepLink = deepLink)

    private sealed interface Config : Parcelable {
        @Parcelize
        object Onboarding : Config

        @Parcelize
        object SignIn : Config

        @Parcelize
        object Main : Config
    }
}

class MainComponent(
    componentContext: ComponentContext,
    deepLink: String?,
) : Main, ComponentContext by componentContext {

    private val navigation = StackNavigation<Config>()

    private val stack =
        childStack(
            source = navigation,
            initialStack = {
                when (deepLink) {
                    "feature1" -> listOf(Config.Feature1)
                    "feature2" -> listOf(Config.Feature2)
                    else -> listOf(Config.Feature1) // Default initial feature
                }
            },
            childFactory = ::child,
        )

    override val childStack: Value<ChildStack<*, Main.Child>> get() = stack

    private fun child(config: Config, componentContext: ComponentContext): Main.Child = TODO()

    private sealed interface Config : Parcelable {
        @Parcelize
        object Feature1 : Config

        @Parcelize
        object Feature2 : Config
    }
}

class OnboardingComponent(componentContext: ComponentContext, onFinished: () -> Unit) : Onboarding

class SignInComponent(componentContext: ComponentContext, onFinished: () -> Unit) : SignIn

class Feature1Component(componentContext: ComponentContext) : Feature1

class Feature2Component(componentContext: ComponentContext) : Feature2

[malliaridis]

I am working on a similar project and the first thing I started with was the authentication.

Since I wanted to integrate OAuth 2.0 with OIDC my structure looks as follow (registration and authenticated routes are not implemented yet).

In the example structure the components Root, Unauthenticated, Authenticated and Auth (which is the login) hold their own ChildStack. Auth->Main is the basic username and password authentication, DeviceCode is a flow that was a proof of concept and will be removed, and Google is the authentication flow with an identity provider (here limited to Google only).

My implementation uses Ktor (HttpClient) for getting the access token and passes it upwards once authenticated, so that I can get into the Authenticated route, which requires that token to operate. I plan to make use of a custom ComponentContext, something called like AuthenticatedComponentContext. There, I will store the access token and provide an authenticated GraphQL client for making further authenticated requests. I still have to figure out how well I can integrate tests with that custom component context, but so far I am positively amazed how easy the Decompose structure allows the integration of tests.

The onboarding you mentioned could be either part of the authenticated components or separate components, depending on how the onboarding will work / displayed. But I think separating them completely is a good idea in general, so that you follow the separation of concerns principle.

And about session / token expiration: I still haven't implemented that, but the clients I use support middlewares. If those are not enough I would probably try somehow to publish a label so that another component (like the Root) can redirect the user for reauthentication or token refresh. But I couldn't find any examples about the usage of labels and publishing labels for other components, but the documentation mentions that it is possible somehow.

[malliaridis]

This looks pretty similar to what I proposed earlier here

Yeah, I thought I post the graph as a confirmation that the structure works out quite well.

I would keep Labels internal in each feature/module and just use normal callbacks to notify parents.

So it would probably make sense then to add the middleware to the client I use in the Authenticated component and when an 401 Unauthorized response is received it is handled directly by the parent of all authenticated components.

[arkivanov]

Yep, sounds reasonable.

[azlekov]

Many thanks! 🙏

Still I'm a bit noobie here, so I need to play around with the things you all said.
I'm using GraphQL as well and fortunately after the sign in I can refresh the token for some time. I will have issues only with users which are not using the app for a long time and the refresh token expires because of inactivity. @malliaridis may I ask if you can share some parts of code, maybe pseudo similar to the great explanation of @arkivanov above? If no possible, do not worry. I'm just trying to take a leap on the learning curve from Android XML, iOS Storyboard development to the declarative Multiplatform one.

Just one more question - your idea of separation was to separate the onboarding but on which level? Under Unauthenticated or next to it? Whenever I need to show the onboarding can be tracked with a combination of settings + authentication state.

Thanks again I was wondering between D-KMP or Decompose but I'm going for Decompose🥇

[malliaridis]

My code wouldn't differ much from what @arkivanov posted. My samples would include just more nesting and further navigation stacks in child components, but the implementation is everywhere the same. The only "big difference" would be the custom context I would use:

// Use default component context, since unauthenticated
class SignInComponent(componentContext: ComponentContext, onFinished: () -> Unit) : SignIn

// Use custom component context that has an authenticated apolloClient and a callback function for handling 401 responses
class OnboardingComponent(componentContext: AuthenticatedComponentContext, onFinished: () -> Unit) : Onboarding

class Feature1Component(componentContext: AuthenticatedComponentContext) : Feature1

class Feature2Component(componentContext: AuthenticatedComponentContext) : Feature2

The AuthenticatedComponentContext provides an apolloClient:

interface AuthenticatedComponentContext : ComponentContext {

    /**
     * An authenticated client for making GraphQL requests with Apollo.
     */
    val apolloClient: ApolloClient
}

/**
 * A default authenticated component context that can be sued to make requests to a backend.
 */
class DefaultAuthenticatedComponentContext(
    componentContext: ComponentContext,
    accessToken: String,
    onUnauthorized: () -> Unit
) : AuthenticatedComponentContext, ComponentContext by componentContext {

    override val apolloClient: ApolloClient = ApolloClient.Builder()
        .serverUrl("${BuildKonfig.backendUrl}/graphql")
        .addHttpHeader("apikey", BuildKonfig.backendApiKey)
        .addHttpHeader("Authorization", "Bearer $accessToken")
        .addHttpInterceptor(UnauthorizedInterceptor(onUnauthorized))
        .build()
}

internal class UnauthorizedInterceptor(private val onUnauthorized: () -> Unit): HttpInterceptor {
    override suspend fun intercept(
        request: HttpRequest,
        chain: HttpInterceptorChain
    ): HttpResponse {
        val response = chain.proceed(request)
        if (response.statusCode == 401) onUnauthorized()

        return response
    }
}

Implementation follows the instructions from Custom ComponentContext. You also have to provide custom implementation (see instructions mentioned before) for childStack to be able to initialize child stack with custom context.

I haven't tested it yet, so I can't guarantee yet that it will work as expected. The onFinish callback function in SignIn returns in my case an Output object that contains the access token. I followed the examples from the Todo-App here.

About the onboarding: it depends on when you gonna show the onboarding and what you need there. If you have an onboarding that asks the user for inserting some profile data for example, then I would place it in the authenticated route so that you can directly store user data as the authenticated user and link the data with the account that has been created moments ago. I would probably place it somewhere next to the Home component of my example and provide an own navigation stack (in case it contains multiple child components). The onboarding would also use the custom component context AuthenticatedComponentContext.

[azlekov]

Many thanks @malliaridis! Time to get my hands dirty.