---

Passage

Passage is a Kotlin Multiplatform library designed to simplify authentication flows across Android and iOS platforms. Built on Firebase Authentication, Passage abstracts common operations and provides composable APIs to manage authentication using popular providers like Google, Apple, and Email/Password.

Be sure to show your support by starring ⭐️ this repository, and feel free to contribute if you're interested!

---

🌟 Features

• Firebase Authentication: Powered by Firebase for robust and secure authentication.
• Gatekeeper (Provider) Support: Google, Apple, Email/Password.
• Extensible Configuration: Customize authentication flows with platform-specific settings.
• Email actions: Send email actions for password resets or verifying a user's email.

---

🚀 Used in production

Alarmee powers notifications in real-world apps:

• KMPShip — a Kotlin Multiplatform boilerplate to build mobile apps faster.
• Bloomeo — a personal finance app.

---

🎯 Concept

Passage uses Firebase Authentication as the backbone for secure and reliable user identity management. It abstracts the complexity of integrating with Firebase's SDKs on multiple platforms, providing a unified API for developers.

Passage abstracts the authentication flow into three main components:

1. Passage: The entry point for managing authentication flows.
2. Gatekeepers: Providers like Google, Apple, and Email/Password, which handle specific authentication mechanisms.
3. Entrants: Users who have successfully authenticated and gained access.

---

🛠️ Installation

In your settings.gradle.kts file, add Maven Central to your repositories:

repositories {
    mavenCentral()
}

Then add Passage dependency to your module:

• With version catalog, open libs.versions.toml:

[versions]
passage = "1.0.0" // Check latest version

[libraries]
passage = { group = "io.github.tweener", name = "passage", version.ref = "passage" }

Then in your module build.gradle.kts add:

dependencies {
    implementation(libs.passage)
}

• Without version catalog, in your module build.gradle.kts add:

dependencies {
    val passage_version = "1.0.0" // Check latest version

    implementation("io.github.tweener:passage:$passage_version")
}

The latest version is:

---

🔧 Configuration

1. Create a Passage

First, you need to create an instance of Passage for each platform:

• 🤖 Android

  Create an instance of PassageAndroid passing an Application-based Context:

val passage: Passage = PassageAndroid(applicationContext = context)

• 🍎 iOS

  Create an instance of PassageIos:

val passage: Passage = PassageIos()

2. Configure Passage

Provide a list of the desired gatekeepers (authentication providers) to configure:

val gatekeeperConfigurations = listOf(
    GoogleGatekeeperConfiguration(
        serverClientId = "your-google-server-client-id",
        android = GoogleGatekeeperAndroidConfiguration(
            filterByAuthorizedAccounts = false,
            autoSelectEnabled = true,
            maxRetries = 3
        )
    ),
    AppleGatekeeperConfiguration(),
    EmailPasswordGatekeeperConfiguration()
)

For example, if you only want to use the Google Gatekeeper, simply provide the GoogleGatekeeperConfiguration like this:

val gatekeeperConfigurations = listOf(
    GoogleGatekeeperConfiguration(
        serverClientId = "your-google-server-client-id",
        android = GoogleGatekeeperAndroidConfiguration(
            filterByAuthorizedAccounts = false,
            autoSelectEnabled = true,
            maxRetries = 3
        )
    ),
)

Important

Replace your-google-server-client-id with your actual Google serverClientId.

3. Initialize Passage

Initialize Passage in your common module entry point:

passage.initialize(gatekeepersConfiguration = gatekeepersConfiguration)

Note

If your app already uses Firebase, you can pass the existing Firebase instance to Passage to reuse it and prevent reinitializing Firebase unnecessarily:

passage.initialize(
    gatekeepersConfiguration = gatekeepersConfiguration,
    firebaseAuth = Firebase.Auth,
)

4. Bind Passage to the current view

When using Google gatekeeper on Android, you must now call bindToView() in Passage before performing any authentication operations. This ensures that Passage can access the Activity-based context needed to display the Google Sign-In UI.

@Composable
fun MyApp() {
    val passage = { inject Passage }

    passage.initialize(...)

    passage.bindtoView() // <- Add this line when using Google gatekeeper on Android
}

---

🧑‍💻 Usage

1. Authenticate a user

Use the provider-specific methods to authenticate users.

Google Authentication

Passage#authenticateWithGoogle() authenticates a user via Google Sign-In. If the user does not already exist, a new account will be created automatically.

val result = passage.authenticateWithGoogle()
result.fold(
    onSuccess = { entrant -> Log.d("Passage", "Welcome, ${entrant.displayName}") },
    onFailure = { error -> Log.e("Passage", "Authentication failed", error) }
)

Apple Authentication

Passage#authenticateWithApple() authenticates a user via Apple Sign-In. If the user does not already exist, a new account will be created automatically.

val result = passage.authenticateWithApple()
// Handle result similarly

Email/Password Authentication

a. Create a user:

Creating a user with email & password will automatically authenticate the user upon successful account creation.

val result = passage.createUserWithEmailAndPassword(PassageEmailAuthParams(email, password))
// Handle result similarly

b. Authenticate a user:

val result = passage.authenticateWithEmailAndPassword(PassageEmailAuthParams(email, password))
// Handle result similarly

Email Link Sign-in Authentication

a. Send the sign-in link email:

You can send an email with a sign-in link to the user's email adress:

val result = passage.sendSignInLinkToEmail(
    params = PassageSignInLinkToEmailParams(
        email = userEmail, // Ask the user for its email address
        url = "https://passagesample.page.link/action/sign_in_link_email",
        iosParams = PassageSignInLinkToEmailIosParams(bundleId = "com.tweener.passage.sample"),
        androidParams = PassageSignInLinkToEmailAndroidParams(
            packageName = "com.tweener.passage.sample",
            installIfNotAvailable = true,
            minimumVersion = "1.0",
        ),
        canHandleCodeInApp = true,
    )
)
result.fold(
    onSuccess = { entrant -> Log.d("Passage", "An email has been sent to the user with a sign-in link.") },
    onFailure = { error -> Log.e("Passage", "Couldn't send the email", error) }
)

b. Verify sign-in link and authenticate the user:

Once the user clicks on this link from the email, it will redirect to your app and automatically sign-in the user:

passage.handleSignInLinkToEmail(email = "{Your email address}", emailLink = it.link)
    .onSuccess { entrant = it } // User is sucessfully signed-in
    .onFailure { println("Couldn't sign-in the user, error: ${it.message}") }

2. Sign Out or Reauthenticate

passage.signOut()

passage.reauthenticateWithGoogle()
passage.reauthenticateWithApple()
passage.reauthenticateWithEmailAndPassword(params)

3. Email actions

You may need to send emails to the user for a password reset if the user forgot their password for instance, or for verifying the user's email address when creating an account.

Important

Passage uses Firebase Dynamic Links to send emails containing universal links. Follow the documentation to configure your app with Firebase Dynamic Links (you don't need to add Firebase Dynamic Links SDK to your app).

To handle universal links, additional configuration is required for each platform:

🤖 Android

In your activity configured to be open when a universal link is clicked:

class MainActivity : ComponentActivity() {

    private val passage = providePassage()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        handleUniversalLink(intent = intent)

        // ...
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)

        handleUniversalLink(intent = intent)

        // ...
    }

    private fun handleUniversalLink(intent: Intent) {
        intent.data?.let {
            passage.handleUrl(url = it.toString())
        }
    }
}

🍎 iOS

Create a class PassageHelper in your iosMain module:

class PassageHelper {

    private val passage = providePassage()

    fun handle(url: String): Boolean =
        passage.handleUrl(url = url)

}

Then, in your AppDelegate, add the following lines:

class AppDelegate : NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {

    // ...

    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let url = userActivity.webpageURL {
            if (PassageHelper().handle(url: url.absoluteString)) {
                print("Handled by Passage")
            }

            return true
        }
        
        print("No valid URL in user activity.")
        return false
    }
}

Passage exposes a universalLinkToHandle StateFlow, which you can use to be notified when a new unviersal link has been clicked and validated by Passage:

val link = passage.universalLinkToHandle.collectAsStateWithLifecycle()

LaunchedEffect(link.value) {
    link.value?.let {
        println("Universal link handled for mode: ${it.mode} with continueUrl: ${it.continueUrl}")
        passage.onLinkHandled() // Important: call 'onLinkHandled()' to let Passage know the link has been handled and can update the authentication state
    }
}

a. Send an email for verifying a user's email

If you want to reinforce authentication, you can send the user an email to verify its email address:

val result = passage.sendEmailVerification(
    params = PassageEmailVerificationParams(
        url = "https://passagesample.page.link/action/email_verified",
        iosParams = PassageEmailVerificationIosParams(bundleId = "com.tweener.passage.sample"),
        androidParams = PassageEmailVerificationAndroidParams(
            packageName = "com.tweener.passage.sample",
            installIfNotAvailable = true,
            minimumVersion = "1.0",
        ),
        canHandleCodeInApp = true,
    )
)
result.fold(
    onSuccess = { entrant -> Log.d("Passage", "An email has been sent to the user to verify its email address.") },
    onFailure = { error -> Log.e("Passage", "Couldn't send the email", error) }
)

b. Send an email for a password reset

If you want to reinforce authentication, you can send the user an email to verify its email address:

val result = passage.sendPasswordResetEmail(
    params = PassageForgotPasswordParams(
        email = passage.getCurrentUser()!!.email,
        url = "https://passagesample.page.link/action/password_reset",
        iosParams = PassageForgotPasswordIosParams(bundleId = "com.tweener.passage.sample"),
        androidParams = PassageForgotPasswordAndroidParams(
            packageName = "com.tweener.passage.sample",
            installIfNotAvailable = true,
            minimumVersion = "1.0",
        ),
        canHandleCodeInApp = true,
    )
)
result.fold(
    onSuccess = { entrant -> Log.d("Passage", "An email has been sent to the user to reset its password.") },
    onFailure = { error -> Log.e("Passage", "Couldn't send the email", error) }
)

---

🤝 Contributing

We love your input and welcome any contributions! Please read our contribution guidelines before submitting a pull request.

---

🙏 Credits

• Logo by Freeicons

---

📜 Licence

Passage is licensed under the Apache-2.0.