Advanced Setup

This page covers more complex integration scenarios for the Solibo SDK.

Authentication Environments

The Solibo SDK supports three primary authentication environments:

Ideal for web applications. The SDK will use standard HTTP cookies for session management. This is the most secure option for browsers as it protects against XSS attacks by keeping tokens out of JavaScript memory.

Configuration:

  • authMode: COOKIE
  • userPoolId: Your Cognito User Pool ID.
  • clientId: Your Cognito Client ID.

2. App / CLI (Token-based)

Used for mobile apps (Android/iOS), desktop apps, or Node.js CLI tools. The SDK manages access and refresh tokens in memory or via a provided DeviceManager.

Configuration:

  • authMode: TOKEN
  • userPoolId: Your Cognito User Pool ID.
  • clientId: Your Cognito Client ID.

3. Machine-to-Machine (M2M)

For backend services, cron jobs, or any integration that doesn’t involve a user login. It uses the OAuth2 Client Credentials flow.

Configuration:

  • authMode: M2M
  • clientId: Your application’s client ID.
  • clientSecret: Your application’s client secret.
  • scopes: (Optional) A list of scopes required for the integration.

Advanced Configuration (Kotlin)

If you need more control, you can use the KotlinBuilder:

val sdk = SoliboSDK.create("USER_POOL_ID") {
    authMode = AuthMode.TOKEN
    clientId = "CLIENT_ID"
    httpClientConfig = {
        // Custom Ktor client configuration
    }
}

Platform Implementations (Kotlin)

When using the SDK on Android or iOS, you should provide platform-specific implementations for Fingerprinter and PushTokenProvider.

Android Fingerprinter

To use Cognito Advanced Security on Android, implement Fingerprinter using the AWS Cognito SDK’s UserContextDataProvider.

Dependencies (build.gradle.kts)

implementation("com.amazonaws:aws-android-sdk-cognitoauth:2.73.0")

Implementation

import android.content.Context
import com.amazonaws.cognito.clientcontext.data.UserContextDataProvider
import no.solibo.oss.sdk.auth.Fingerprinter

class AndroidFingerprinter(private val context: Context) : Fingerprinter {
    override fun print(username: String): String {
        return UserContextDataProvider.getInstance()
            .getEncodedContextData(context, username, "USER_POOL_ID", "CLIENT_ID")
            .replace("\n", "")
    }
}

iOS Fingerprinter (Swift)

For iOS, implement the SdkFingerprinter interface (exposed from the shared KMP module) using the AWS Cognito Identity Provider ASF SDK.

Dependencies (Swift Package Manager) Add AWSCognitoIdentityProviderASF to your project.

Implementation

import AWSCognitoIdentityProviderASF
import Shared // Your shared KMP module name

class iOSFingerprinter: SdkFingerprinter {
    func print(username: String) -> String {
        return AWSCognitoIdentityProviderASF.userContextData(
            "USER_POOL_ID",
            username: username,
            deviceId: nil,
            userPoolClientId: "CLIENT_ID"
        )!
    }
}

Push Token Provider

To support push notifications, you should provide an implementation that retrieves the device’s push token (e.g., from Firebase).

Android (Firebase)

Implementation

import com.google.firebase.messaging.FirebaseMessaging
import kotlinx.coroutines.tasks.await
import no.solibo.oss.sdk.auth.PushTokenProvider

class FirebasePushTokenProvider : PushTokenProvider {
    override suspend fun token(): String? {
        return runCatching {
            FirebaseMessaging.getInstance().token.await()
        }.getOrNull()
    }
}

iOS (Firebase/Swift)

Implementation

import FirebaseMessaging
import Shared

class iOSPushTokenProvider: SdkPushTokenProvider {
    func token() async throws -> String? {
        return await withCheckedContinuation { continuation in
            Messaging.messaging().token { token, error in
                continuation.resume(returning: token)
            }
        }
    }
}

Advanced Configuration (React / TypeScript)

In a React environment, you should also consider implementing a fingerprinter and a refreshFailureHandler for production use.

Web Fingerprinter

When running in a browser, you can use the Amazon Cognito Advanced Security JavaScript library to generate the context data.

const fingerprinter = {
  print: (username: string) => {
    // Requires AmazonCognitoAdvancedSecurityData to be loaded
    return (window as any).AmazonCognitoAdvancedSecurityData?.getData(
      username,
      'user-pool-id',
      'client-id'
    );
  },
};

Global Refresh Failure

The refreshFailureHandler allows you to define a global action when the authentication token cannot be refreshed (e.g., when the session has expired).

const refreshFailureHandler = {
  onRefreshFailure: () => {
    // Clear local session state and redirect to login
    localStorage.removeItem('user_session');
    window.location.href = '/auth/login';
  },
};

Customizing the Ktor Client (Kotlin)

The HomeApi uses Ktor’s HttpClient under the hood. While you can usually just use the factory methods, you can also provide a custom configured HttpClient if you need to add custom interceptors, logging, or other features.

Kotlin 

import io.ktor.client.HttpClient
import io.ktor.client.plugins.logging.Logging
import no.solibo.oss.sdk.SoliboSDK

val sdk = SoliboSDK.create("USER_POOL_ID") {
    httpClientConfig = {
        install(Logging)
    }
}

Error Handling

The SDK throws exceptions for non-successful API responses. You should wrap your calls in try-catch blocks.

Common Exceptions

  • RedirectException: Thrown when an API call is redirected (often used during authentication in COOKIE mode).
  • Exception: Standard exceptions for network errors, 404s, or 500s.
  • UnknownRefreshErrorException: Thrown when token refresh fails unexpectedly.

Solibo AS