Overview

This project will create a client Android application that talks to a restful server to handle Passkey authentication. You will have to test on a physical Android device. CredentialManager will not work on an Android emulator.

Setting up the Project

Create a new project in Android Studio. I'm using Kotlin and Jetpack Compose for the UI. Jetpack Compose isn't required, but it made the job a lot easier for me. Also, I'm using retrofit for networking and Moshi for serializing JSON to and from the server endpoints.

Creating a Simple Login Screen

Once you've created the bones of a project, we'll start with a basic login screen UI. I'm going to hand the reins off to Jetpack Compose from MainActivity, use a view model, and I'm also keeping an instance of my PasskeyManager class in the activity. More on that later.

class MainActivity : ComponentActivity() {

    private val viewModel: MainViewModel by viewModels()
    private val passkeyManager = PasskeyManager(this)

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

        enableEdgeToEdge()
        setContent {
            PasskeysAndroidTheme {
                PasskeyApp(viewModel)
            }
        }

        setupViewModel()
    }

    private fun setupViewModel() {

    }
}

@Preview(showBackground = true)
@Composable
fun MainPreview() {
    PasskeysAndroidTheme {
        PasskeyApp(viewModel = MainViewModel())
    }
}

Later, we're going to use setupViewModel to implement a couple lamdbas in the view model for creating and validating passkeys. PasskeyManager holds an instance of Android's CredentialManager class that handles passkeys and it needs a context. It's a no-no to pass an actvity context into a view model, so I'm working around that this way. If you're a seasoned Android developer, you've probably got a solution in your back pocket that's better than mine. I've also got a preview here to show the UI for the only screen in this app.

Here's the start of the MainViewModel class. I'm also including a LoginStatus enum here. For this tutorial, I'm using this to keep track of where we are in the flow and to help with debugging. I'm also showing a snackbar for key events along the way.

enum class LoginStatus(var displayString: String) {
    SIGN_UP_IN_PROGRESS("Sign up in progress..."),
    SIGN_UP_SUCCESS("Signed up successfully!"),
    SIGN_UP_FAILED("Sign up failed"),
    LOGIN_IN_PROGRESS("Logging in..."),
    LOGIN_SUCCESS("Logged in!"),
    LOGIN_FAILED("Login failed"),
    LOGGED_OUT("Logged out")
}

class MainViewModel : ViewModel() {

    var loginStatus = mutableStateOf(LoginStatus.LOGGED_OUT)
    var username = mutableStateOf("")
    var snackbarHostState = SnackbarHostState()

    var createPasskey: (userId: String, payload: String) -> Unit = { _, _ -> }
    var validateCredential: (username: String, request: GetCredentialRequest) -> Unit = { _, _ -> }

    suspend fun showSnackbar(status: LoginStatus, errorMessage: String? = null) {
        val message = status.displayString + (errorMessage ?: "")
        snackbarHostState.showSnackbar(message)
    }

    private val moshi: Moshi = Moshi.Builder()
        .add(KotlinJsonAdapterFactory())
        .build()
}

The PasskeyApp composable holds the Scaffold for the Jetpack Compose UI. It's pretty simple:

@Composable
fun PasskeyApp(
    viewModel: MainViewModel
) {
    val coroutineScope = rememberCoroutineScope()

    Scaffold(
        snackbarHost = {
            SnackbarHost(hostState = viewModel.snackbarHostState)
        },
        modifier = Modifier.fillMaxSize()
    ) { innerPadding ->
        LoginView(
            viewModel = viewModel,
            onLogin = {
                coroutineScope.launch {
                    viewModel.onLoginButtonTapped()
                }
            },
            onSignUp = {
                coroutineScope.launch {
                    viewModel.onSignUpButtonTapped()
                }
            },
            modifier = Modifier.padding(innerPadding)
        )
    }
}

Setting up Networking

Like most Android projects, I'm using Retrofit for handling network requests. I have set up a pretty basic interface:

interface ApiInterface {
    companion object {
        private val BASE_URL = "https://942e-2600-1700-3e41-88b0-147b-69e-2c32-ee33.ngrok-free.app"

        fun retrofit(): Retrofit {
            val moshi = Moshi.Builder().build()
            return Retrofit.Builder()
                .baseUrl(BASE_URL)
                .addConverterFactory(MoshiConverterFactory.create(moshi))
                .client(okHttpClient())
                .build()
        }

        private fun okHttpClient(): OkHttpClient {
            val loggingInterceptor = HttpLoggingInterceptor()
            loggingInterceptor.level = HttpLoggingInterceptor.Level.BODY

            return OkHttpClient.Builder()
                .addInterceptor(DefaultHeaderInterceptor())
                .addInterceptor(loggingInterceptor)
                .build()
        }
    }
}

class DefaultHeaderInterceptor() : Interceptor {
    override fun intercept(chain: Interceptor.Chain): okhttp3.Response {
        var request = chain.request()
            .newBuilder()
            .addHeader("Accept", "application/json")
            .addHeader("Content-Type", "application/json")
            .build()

        return chain.proceed(request)
    }
}

Quick rundown on what's happening above, I'm building an instance of Retrofit and setting it up with Moshi. I'm also setting up an OkHttpClient with logging, as well as an interceptor that will add a set of headers to all of my requests. I'm also using a BASE_URL value that will change each time my ngrok address changes. For this tutorial, you're going to want something that allows you to connect to your local Passkey server from a physical Android device. ngrok can help with that.

A Quick Note about ngrok

ngrok is a tool that creates an http or https endpoint and routes the traffic to your local machine. You're going to need this to make calls to your local server during testing. You can download ngrok for free here. Once you get it set up, all you have to do is run ./ngrok http 8080 in Terminal and you'll be able to connect to your local server with the URL it provides. The https version of the URL will be your relying party, and the base URL for connecting to your backend server. Don't forget to update those values if you turn ngrok off and back on again, because the URL will change.

Setting up a Few Kotlin Extensions

Since we'll do lots of base 64 url safe encoding, here's an extension I'm using in several places:

fun String.base64UrlEncoded(): String {
    return Base64.encodeToString(
        this.encodeToByteArray(),
        Base64.NO_WRAP or Base64.URL_SAFE or Base64.NO_PADDING
    )
}

I've also got these Moshi functions for converting to and from JSON:

// [Moshi] extension to transform an object to json
inline fun <reified T> Moshi.objectToJson(data: T): String =
    adapter(T::class.java).toJson(data)

// [Moshi] extension to transform json to an object
inline fun <reified T> Moshi.jsonToObject(json: String): T? =
    adapter(T::class.java).fromJson(json)

PasskeyManager and CredentialManager

This project uses Android's CredentialManager for handling the Passkey flow. CredentialManager requires an activity context. I'm trying to have some separation of concerns and not put all of this Passkey handling code in the activity, so I created a PasskeyManager class to encapsulate it in one place.

Here's a basic outline of the PasskeyManager class:

class PasskeyManager(val activity: ComponentActivity) {

    var credentialManager = CredentialManager.create(context = activity)

    private val moshi: Moshi = Moshi.Builder()
        .add(KotlinJsonAdapterFactory())
        .build()

    @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
    suspend fun createPasskey(
        userId: String,
        requestJson: String,
        preferImmediatelyAvailableCredentials: Boolean
    ): Boolean {
        return false
    }
}

private suspend fun handlePasskeyRegistrationResult(
        userId: String, 
        result: CreateCredentialResponse
    ): Boolean {
        return false
}

suspend fun validateCredential(
        username: String,
        request: GetCredentialRequest
    ): Boolean {
        return false
}

private suspend fun handleSignInResult(
        username: String,
        result: GetCredentialResponse
    ): Boolean {
        return false
}

Creating a Passkey

Before we can log in with a Passkey on our Android device, we've got to create one. If you're building on my vapor Passkey server article, you can enter any username or email address or whatever into the TextField and tap the Sign Up button. That's going to call onSignUpButtonTapped in our view model. Here's the implementation for that. The first thing that has to happen is making a call to our Passkey server.

I'll show the whole LoginAPI now, but for now we're focused on the signUp function. It makes a call to the /signup endpoint and passes a username param from our text field:

interface LoginApi {
    @GET("/signup")
    suspend fun signUp(
        @Query("username") username: String
    ) : Response<ChallengeResponse>

    @POST("/makeCredential")
    suspend fun makeCredential(
        @Query("userId") userId: String,
        @Body postBody: MakeCredentialPostBody
    ) : Response<Unit>

    @GET("/authenticate")
    suspend fun login(
        @Query("username") username: String
    ) : Response<PublicKeyCredentialRequestOptions>

    @POST("/authenticate")
    suspend fun authenticate(
        @Query("username") username: String,
        @Body postBody: PublicKeyCredentialBody
    ) : Response<Unit>

    companion object {
        fun retrofit(): LoginApi {
            return ApiInterface.retrofit().create(LoginApi::class.java)
        }
    }
}

Here's the implementation of onSignUpButtonTapped in the view model:

suspend fun onSignUpButtonTapped() {
    showSnackbar(LoginStatus.SIGN_UP_IN_PROGRESS)

    // 1. Make a call to the sign up endpoint
    val response = LoginApi.retrofit().signUp(username.value)


    if (response.isSuccessful) {
        Log.i("", "got a response: $response")

        response.body()?.let { challengeResponse ->

            // 2. Base64 url encode the userId and challenge
            val userIdEncoded = challengeResponse.userId.base64UrlEncoded()
            val challengeEncoded = challengeResponse.challenge.challenge.base64UrlEncoded()

            val user = challengeResponse.challenge.user
            user.id = userIdEncoded

            // 3. Build a PublicKeyCredentialCreationOptions and convert it to JSON
            val creationOptions = PublicKeyCredentialCreationOptions(
                rp = challengeResponse.challenge.relyingParty,
                user = user,
                challenge = challengeEncoded,
                pubKeyCredParams = challengeResponse.challenge.params,
                timeout = challengeResponse.challenge.timeout,
                attestation = challengeResponse.challenge.attestation,
                excludeCredentials = listOf()
            )

            val json = moshi.objectToJson(creationOptions)
            Log.i("", "creationOptions json: $json")

            // 4. Ready to create our Passkey using Android's CredentialManager
            createPasskey(
                challengeResponse.userId,
                moshi.objectToJson(creationOptions)
            )
        } ?: run {
            showSnackbar(LoginStatus.SIGN_UP_FAILED)
        }
    } else {
        val errorMessage = response.errorBody().toString()
        Log.e("", "got an error: $errorMessage")
        showSnackbar(
            status = LoginStatus.SIGN_UP_FAILED,
            errorMessage = errorMessage
        )
    }
}

Here's a breakdown of what's happening above. It looks like a lot, but it's not that bad:

1. As mentioned above, we make a call to our server's sign up endpoint. This will create our new user in the system (if it doesn't already exist), and send back a challenge.

2. We need to Base64 url encode the challenge. This is a common theme throughout a Passkey implementation. Everything gets Base64 url encoded.

3. We build up a PublicKeyCredentialCreationOptions, which holds the details that are needed to create our Passkey. We're also using Moshi to convert this object to JSON.

4. The JSON object, along with our user's id, gets sent off to the createPasskey function, which will use CredentialManager to build a Passkey for Android.

Here's the implementation for PublicKeyCredentialCreationOptions:

@JsonClass(generateAdapter = true)
data class PublicKeyCredentialCreationOptions(
    val rp: RelyingParty,
    val user: AuthUser,
    val challenge: String,
    val pubKeyCredParams: List<PublicKeyCredParams>,
    val timeout: Int,
    val attestation: String,
    val excludeCredentials: List<String>
)

Earlier, we created a setupViewModel function in MainActivity. It's time to add our implementation for createPasskey there, so the view model can call it:

private fun setupViewModel() {
    viewModel.createPasskey = { userId, payload ->
        lifecycleScope.launch {
            val result = passkeyManager.createPasskey(
                userId = userId,
                requestJson = payload,
                preferImmediatelyAvailableCredentials = true
            )

            if (result) {
                viewModel.showSnackbar(LoginStatus.SIGN_UP_SUCCESS)
            } else {
                viewModel.showSnackbar(LoginStatus.SIGN_UP_FAILED)
            }
        }
    }
}

We're really only doing this here because CredentialManager needs a context. Trying to have some kind of encapsulation, I'm using a PasskeyManager class to hold an instance of CredentialManager and the code for managing Passkey registration and authentication. Here's our createPasskey implementation:

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
suspend fun createPasskey(
    userId: String,
    requestJson: String,
    preferImmediatelyAvailableCredentials: Boolean
): Boolean {
    Log.i("", "ready to create public key credentials with: $requestJson")

    val createPublicKeyCredentialRequest = CreatePublicKeyCredentialRequest(
        // Contains the request in JSON format. Uses the standard WebAuthn web JSON spec.
        requestJson = requestJson,
        // Defines whether you prefer to use only immediately available credentials,
        // not hybrid credentials, to fulfill this request. This value is false by default.
        preferImmediatelyAvailableCredentials = preferImmediatelyAvailableCredentials,
    )

    // Execute CreateCredentialRequest asynchronously to register credentials
    // for a user account. Handle success and failure cases with the result and
    // exceptions, respectively.
    try {
        val result = credentialManager.createCredential(
            context = activity,
            request = createPublicKeyCredentialRequest
        )

        return handlePasskeyRegistrationResult(userId, result)
    } catch (e : CreateCredentialException) {
        Log.e("", "failed to create a credential: $e")

        return false
    }
}

At this point, the Android OS will bring up a dialog to create a Passkey and gives back a result. Let's handle that:

private suspend fun handlePasskeyRegistrationResult(
    userId: String,
    result: CreateCredentialResponse
): Boolean {
    (result as? CreatePublicKeyCredentialResponse)?.let {

        // 1. Use Moshi to decode the registration response
        val createCredentialObject = moshi.jsonToObject<CreateCredential>(it.registrationResponseJson)
        Log.i("", "here's the registrationResponseJson: ${it.registrationResponseJson}")

        // 2. Generate a JSON payload to send the Passkey to the server
        createCredentialObject?.payload()?.let { payload ->
            Log.i("", "credentialPayload: $payload")

            val response = LoginApi.retrofit().makeCredential(userId = userId, postBody = payload)
            if (response.isSuccessful) {
                Log.i("", "got makeCredential response: $response")
                return true
            } else {
                val error = response.errorBody().toString()
                Log.e("", "got an error: $error")
                return false
            }
        } ?: run {
            return false
        }
    } ?: run {
        return false
    }
}

Buckle Up, It's About to Get Weird

I'm going to share the CreateCredential class and its payload function next. The authenticator data that we need to pass along contains a byte array with binary data and a number of flags. Worlds collide here, as Android is not quite following the rules on the format of these flags, and the Swift library is not flexible in handling that. So we've got to tap into the authenticator data before it gets sent and make sure everything lines up. In my experience, the Android-generated data says it's including extension data (the ED flag), but doesn't actually include any. Android also includes attestation data, but doesn't set the AT flag. The WebAuthn library isn’t having that, and the whole thing fails.

I don't think I would have figured this part out without ChatGPT, and probably would have given up. I'll share what I came up with that works, and feel free to use, edit, and dig into it on your own:

@JsonClass(generateAdapter = true)
data class CreateCredential(
    val id: String,
    val rawId: String,
    val authenticatorAttachment: String,
    val type: String,
    val response: CreateCredentialInnerResponse
) {
    fun payload(): MakeCredentialPostBody {
        val cborMap = decodedCBOR
        var authenticatorData = cborMap["authData"].GetByteString().clone()

        val flags = authenticatorData[32].toInt() and 0xFF
        Log.d("WebAuthn", "Original Flags Byte: 0x${flags.toString(16).uppercase()} (Binary: ${flags.toString(2).padStart(8, '0')})")
        Log.d("WebAuthn", "Original Authenticator Data Length: ${authenticatorData.size}")

        // ✅ Always clear ED (`0x80`)
        authenticatorData[32] = (authenticatorData[32].toInt() and 0x7F).toByte() // `0x7F` = `01111111`

        // ✅ If extra bytes exist (authenticatorData > 37), set `AT = true`
        if (authenticatorData.size > 37) {
            authenticatorData[32] = (authenticatorData[32].toInt() or 0x40).toByte() // `0x40` = `01000000`
        }

        val fixedFlags = authenticatorData[32].toInt() and 0xFF
        Log.d("WebAuthn", "Fixed Flags Byte: 0x${fixedFlags.toString(16).uppercase()} (Binary: ${fixedFlags.toString(2).padStart(8, '0')})")
        Log.d("WebAuthn", "Final Authenticator Data Length: ${authenticatorData.size}")

        val modifiedCborMap = CBORObject.NewMap()
        modifiedCborMap["fmt"] = cborMap["fmt"]
        modifiedCborMap["attStmt"] = cborMap["attStmt"]
        modifiedCborMap["authData"] = CBORObject.FromObject(authenticatorData)

        val modifiedCborBytes = modifiedCborMap.EncodeToBytes()
        val newAttestationObject = Base64.encodeToString(modifiedCborBytes, Base64.NO_WRAP or Base64.URL_SAFE or Base64.NO_PADDING)

        val credentialPayload = MakeCredentialPostBody(
            id = id,
            rawId = rawId,
            authenticatorAttachment = authenticatorAttachment,
            type = type,
            response = MakeCredentialResponseParam(
                attestationObject = newAttestationObject,
                clientDataJSON = response.clientDataJSON
            )
        )

        return credentialPayload
    }
}

@JsonClass(generateAdapter = true)
data class CreateCredentialInnerResponse(
    val attestationObject: String,
    val clientDataJSON: String
)

@JsonClass(generateAdapter = true)
data class MakeCredentialPostBody(
    val id: String,
    val rawId: String,
    val authenticatorAttachment: String,
    val type: String,
    val response: MakeCredentialResponseParam
)

@JsonClass(generateAdapter = true)
data class MakeCredentialResponseParam(
    val attestationObject: String,
    val clientDataJSON: String
)

This code basically takes the credential data apart and puts it back together as JSON, for sending to the Passkey server.

Back to PasskeyManager

Back in PasskeyManager's handlePasskeyRegistrationResult, we have to send this payload to our server's /makeCredential endpoint. If that succeeds, we've successfully created a Passkey, saved it on the server, and it can be used to log in.

Signing In

When the user taps the Log in button, we'll trigger onLoginButtonTapped in the view model:

suspend fun onLoginButtonTapped() {
    showSnackbar(LoginStatus.LOGIN_IN_PROGRESS)

    val username = username.value

    // 1. Call our login endpoint
    val response = LoginApi.retrofit().login(username)
    if (response.isSuccessful) {
        Log.i("", "got an auth response: $response")

        response.body()?.let { credentialOptions ->
            // 2. Parse the response and prepare for sending to CredentialManager
            val responseJson = moshi.objectToJson(credentialOptions)
            val jsonObject = JSONObject(responseJson)
            val challenge = jsonObject.getString("challenge")
            jsonObject.put("challenge", challenge.base64UrlEncoded())

            val newRequestJson = jsonObject.toString()
            val getPublicKeyCredentialOption = GetPublicKeyCredentialOption(
                requestJson = newRequestJson
            )

            val getPasswordOption = GetPasswordOption()
            val credentialRequest = GetCredentialRequest(
                listOf(getPasswordOption, getPublicKeyCredentialOption)
            )

            // 3. Use CredentialManager to validate the credentials
            validateCredential(username, credentialRequest)
        } ?: run {
            Log.e("", "something went wrong at login")
            showSnackbar(status = LoginStatus.LOGIN_FAILED)
        }
    } else {
        val errorMessage = response.errorBody().toString()
        val responseCode = response.code()
        val displayMessage = "got a $responseCode, error: $errorMessage"

        Log.e("", "got a $responseCode,  error: $errorMessage")
        showSnackbar(
            status = LoginStatus.LOGIN_FAILED,
            errorMessage = displayMessage
        )
    }
}

Here's what this code does:

1. Makes a call to the server's /authenticate endpoint, sending the username. The server looks up to see if that user exists, and sends back a challenge.

2. We need to Base64 url encode the challenge, and put that JSON into a GetPublicKeyCredentialOption class. This is a class Android provides. We then stick that into a GetCredentialRequest.

3. And off to CredentialManager it goes for validation.

Back in MainActivity, we need to provide our implementation of validateCredential to the view model. This gives us a path to interact with PasskeyManager. So add this to setupViewModels:

private fun setupViewModel() {

    ...

    viewModel.validateCredential = { username, request ->
        lifecycleScope.launch {
            val result = passkeyManager.validateCredential(
                username = username,
                request = request
            )

            if (result) {
                viewModel.showSnackbar(LoginStatus.LOGIN_SUCCESS)
            } else {
                viewModel.showSnackbar(LoginStatus.LOGIN_FAILED)
            }
        }
    }
}

Now we can implement PasskeyManager's validateCredential function:

suspend fun validateCredential(
    username: String,
    request: GetCredentialRequest
): Boolean {
    try {
        val result = credentialManager.getCredential(
            context = activity,
            request = request
        )
        return handleSignInResult(username, result)
    } catch (e: GetCredentialException) {
        Log.e("", "got a credential exception: $e")
        return false
    }
}

private suspend fun handleSignInResult(
    username: String,
    result: GetCredentialResponse
): Boolean {
    val credential = result.credential

    when (credential) {
        is PublicKeyCredential -> {
            val responseJson = credential.authenticationResponseJson
            Log.i("", "got responseJson: $responseJson")
            val createCredentialObject = moshi.jsonToObject<PublicKeyCredentialBody>(responseJson)?.let {
                val response = LoginApi.retrofit().authenticate(username, it.payload)
                if (response.isSuccessful) {
                    Log.i("", "authenticate response: $response")
                    return true
                } else {
                    val error = response.errorBody().toString()
                    Log.e("", "got an error: $error")
                    // TODO: could throw an error?
                    return false
                }
            }
        }
        is PasswordCredential -> {
            val username = credential.id
            val password = credential.password
            Log.i("", "got a PasswordCredential")
            return false
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e("", "Unexpected type of credential")
            return false
        }
    }

    return false
}

Above, we make our call to CredentialManager's getCredential, and then handle the result. We really only care about the public key credential for the purposes of this project since we're concerned with Passkeys. From the user's perspective, they'll receieve a system prompt for biometrics, and if everything goes well you'll get a success and credential data.

We build up a POST payload from the credential, and send that to our /authenticate endpoint that receives a POST body.

Here's the implementation for PublicKeyCredentialBody:

@JsonClass(generateAdapter = true)
data class PublicKeyCredentialBody(
    val id: String,
    val rawId: String,
    val type: String,
    val authenticatorAttachment: String,
    val response: PublicKeyCredentialResponse
) {
    val payload: PublicKeyCredentialBody
        get() {
            val something = response.decodedAuthenticatorData
            Log.i("", "what actually gets sent: ${response.authenticatorData.unsignedBase64Encoded()}")
            return PublicKeyCredentialBody(
                id = id,
                rawId = rawId,
                type = type,
                authenticatorAttachment = authenticatorAttachment,
                response = PublicKeyCredentialResponse(
                    clientDataJSON = response.clientDataJSON,
                    authenticatorData = response.authenticatorData,
                    userHandle = response.userHandle.base64UrlEncoded(),
                    signature = response.signature
                )
            )
        }
}

@JsonClass(generateAdapter = true)
data class PublicKeyCredentialResponse(
    val clientDataJSON: String,
    val authenticatorData: String,
    val userHandle: String,
    val signature: String
)

You should get a 200 success back from the server. If so, the user has successfully logged in. In a real application, you'll want to give the user a token at this point. They'll include that token in subsequent calls to your backend endpoints. I'll leave the rest of that exercise up to you.

Conclusion

If you've made it this far, congrats! You're ready to fire up ngrok in a terminal, use the generated url as your relying party on your vapor server and Android application, and test it out!

If you got here first, here are the other 2 articles in this series:

• Build a WebAuthn Passkey server in Swift with Vapor

• Build an iOS client application that uses Passkeys

Overview

This project will create a client iOS application that talks to a restful server to handle Passkey authentication.

Setting up the Project

Create a new Xcode project. When prompted, you can use either SwiftUI or UIKit. My UI code example is SwiftUI for simplicity, but the meat of this article is the Passkey related code, and that will work great with either UI framework.

Creating a Simple Login Screen

Once you've created the bones of a project, we'll start with a basic login screen UI. This isn't the best it could be, but gets the job done:

import SwiftUI

struct LoginView: View {

    @StateObject var authService = AuthService()

    @State private var emailAddress = ""
    @State private var loginStatus = ""
    @State private var isLoading = false
    @FocusState private var isTextFieldFocused: Bool

    var body: some View {
        ZStack {
            VStack {

                Spacer()

                TextField("Email Address", text: $emailAddress)
                    .focused($isTextFieldFocused)
                    .autocorrectionDisabled()
                    .autocapitalization(.none)
                    .textContentType(.emailAddress)
                    .onSubmit {
                        isTextFieldFocused = false
                    }
                    .padding()
                    .frame(maxWidth: .infinity)
                    .frame(height: 44)
                    .border(.separator, width: 1)
                    .padding()

                Text(authService.authStatus.displayMessage)

                Spacer()

                VStack(spacing: 20) {
                    Button {
                        signUp()
                    } label: {
                        Text("Sign Up")
                    }
                    .frame(maxWidth: .infinity)
                    .frame(height: 50)
                    .foregroundColor(.white)
                    .background(.blue)
                    .padding(.horizontal)

                    Button {
                        login()
                    } label: {
                        Text("Log In")
                    }
                    .frame(maxWidth: .infinity)
                    .frame(height: 50)
                    .foregroundColor(.white)
                    .background(Color(.systemCyan))
                    .padding(.horizontal)
                    .padding(.bottom)
                }
            }

            if isLoading {
                ProgressView()
            }
        }
        .alert(authService.authErrorTitle,
               isPresented: $authService.isShowingAuthError, actions: {
            Button("Ok", role: .cancel) { }
        }, message: {
            Text(authService.authErrorMessage)
        })
    }

    private func signUp() {
        Task {
            await authService.signUp(username: emailAddress)
        }
    }

    private func login() {
        Task {
            await authService.login(username: emailAddress)
        }
    }
}

#Preview {
    LoginView()
}

Here's a quick run down on the screen:

• There is a TextField for username/email input. I'm also using a FocusState so the keyboard will be dismissed when the return button is tapped since the buttons are at the bottom of the screen and will be covered up

• I've also got a Text label in the mix that gets updated with a status as we progress through the flow

• This screen can also show an error alert if anything goes wrong.

A Quick Note about ngrok

ngrok is a tool that creates an http or https endpoint and routes the traffic to your local machine. You're going to need this to make calls to your local server during testing. You can download ngrok for free here. Once you get it set up, all you have to do is run ./ngrok http 8080 in Terminal and you'll be able to connect to your local server with the URL it provides. The https version of the URL will be your relying party, and the base URL for connecting to your backend server. Don't forget to update those values if you turn ngrok off and back on again, because the URL will change.

Setting up an Associated Domain

Once you have ngrok running, you'll need to use that https url in a couple places in your Xcode project. Open your project file, select your app's target and select the Signing & Capabilties tab. Add an Associated Domains capability, and then add a domain like this:

webcredentials:7c42-2600-1700-3e41-88b0-b052-7126-dc42-525f.ngrok-free.app?mode=developer

When you've got a real url set up and are ready for production, you'll remove the ?mode=developer part, but it's going to allow us to reach our url for testing purposes. Here's a link if you'd like to read more about supporting associated domains on iOS.

We're also going to use the ngrok url as our relying party in AuthService, which is coming up next. Also note, each time you kill and restart ngrok, you're going to need to update both places in your iOS code with the new url. You'll also need to update the environment variables on your Vapor server and run it again.

Setting up AuthService

Before we get into the heavy lifting, here's an enum I created to help keep track of progress as the app moves through the steps of Passkey creation and login. We'll display the status in the Text label on the login screen.

enum AuthStatus: Equatable, Hashable {
    case signUpInProgress
    case signUpSuccess
    case loginInProgress
    case loginSuccess
    case loggedOut

    var displayMessage: String {
        switch self {
        case .signUpInProgress:     "Sign up in progress..."
        case .signUpSuccess:        "Signed up successfully"
        case .loginInProgress:      "Logging in..."
        case .loginSuccess:         "Logged in!"
        case .loggedOut:            "Logged out"
        }
    }
}

We can start with this basic outline of the file:

// 1. Class setup
@MainActor
class AuthService: NSObject, ObservableObject {

    enum PasskeyError: Error {
        case signup
        case login
    }

    // 2. Relying party url created by ngrok
    static let relyingParty = "7c42-2600-1700-3e41-88b0-b052-7126-dc42-525f.ngrok-free.app"

    // 3. Published properties for the LoginView
    @Published var authErrorTitle = ""
    @Published var authErrorMessage = ""
    @Published var isShowingAuthError = false
    @Published var authStatus = AuthStatus.loggedOut

    private var username = ""
    private var userId = ""
    private var preferImmediatelyAvailableCredentials = true

    // MARK: - Sign Up / Registration

    func signUp(username: String) async {
        authStatus = .signUpInProgress
    }

    // MARK: - Log in

    func login(username: String) async {
        authStatus = .loginInProgress
        self.username = username
    }
}

This is just a basic outline of a file. I'll give a quick overview and then we'll start implementing everything:

1. I'm using ObservableObject and publishing some values to be observed by the UI. If you're targeting iOS 17 and up, you can use the @Observable macro instead. Everything in this article will work with iOS 16+ since that's what I'm supporting in my apps at the time of writing.

2. Here's our relying party, using the domain created for us by ngrok. You'll eventually replace this with your real url in a production app

3. We're publishing some properties that will drive the UI

You can also see I've got some placeholder functions for the overall purpose of AuthService, which is handling sign ups (Passkey creation), and logging in with an existing passkey.

Making Calls to the Passkey Server

You can use your preferred method for making API calls, but if you just want to get this all working, here's my code for making GET and POST requests. It's a simplified version of what I've been using for years, and for our purposes now, it'll just work. This code takes a generic type T and decodes the response from the server into that type, or throws an error.

//
//  URLSession+Example.swift
//  PasskeyClient
//

import Foundation

enum SessionError: Error {
    case badResponse
    case requestFailed(String)
}

/// Object to represent empty response bodies from API calls that conform to Decodable.
public struct EmptyResponse: Decodable { }

extension URLSession {
    func get<T: Decodable>(endpoint: String,
                           queryParams: [String: String] = [:],
                           decodingType: T.Type) async throws -> T {
        var request = request(endpoint: endpoint, queryParams: queryParams)
        request.httpMethod = "GET"
        return try await fetchAndDecode(request: request)
    }

    @discardableResult
    func post<T: Decodable>(endpoint: String,
                            queryParams: [String: String] = [:],
                            postBody: Data,
                            decodingType: T.Type) async throws -> T {
        var request = request(endpoint: endpoint, queryParams: queryParams)
        request.httpMethod = "POST"
        request.httpBody = postBody
        return try await fetchAndDecode(request: request)
    }

    private func request(endpoint: String,
                         queryParams: [String: String]) -> URLRequest {
        let baseUrlString = "https://\(AuthService.relyingParty)"
        let baseUrl = URL(string: baseUrlString)!
        let fullUrl = URL(string: endpoint, relativeTo: baseUrl)!
        var request = URLRequest(url: fullUrl)

        if !queryParams.isEmpty {
            if let url = request.url {
                if var components = URLComponents(url: url, resolvingAgainstBaseURL: true) {
                    let queryItems = queryParams.compactMap { URLQueryItem(name: $0.key, value: $0.value) }
                    components.queryItems = queryItems
                    if let newURL = components.url {
                        request = URLRequest(url: newURL)
                    }
                }
            }
        }

        defaultHeaders.forEach { request.addValue($0.value, forHTTPHeaderField: $0.key) }
        return request
    }

    private func fetchAndDecode<T: Decodable>(request: URLRequest) async throws -> T {
        let (data, response) = try await data(for: request)

        guard let response = response as? HTTPURLResponse else {
            throw SessionError.badResponse
        }

        switch response.statusCode {
        case (200...299):
            var data = data
            if data.isEmpty {
                data = "{}".data(using: .utf8) ?? Data()
            }

            return try JSONDecoder().decode(T.self, from: data)

        default:
            let errorMessage = String(data: data, encoding: .utf8) ?? ""
            throw SessionError.requestFailed(errorMessage)
        }
    }

    private var defaultHeaders: [String: String] {
        return [
            "Content-Type": "application/json",
            "Accept": "application/json"
        ]
    }
}

Creating a Passkey

First we've got to create a Passkey. If you're building on my vapor Passkey server article, you can enter any username or email address or whatever into the TextField and tap the Sign Up button. It's going to call this function in AuthService:

func signUp(username: String) async {
        authStatus = .signUpInProgress

        do {
            // 1. Generate a challenge
            let challengeResponse = try await URLSession.shared.get(endpoint: "/signup",
                                                                    queryParams: ["username": username],
                                                                    decodingType: ChallengeResponse.self)

            // 2. Save the userId -- we'll need it later                                                                    
            userId = challengeResponse.userId

            // 3. Trigger iOS to prompt the user to create a Passkey
            try startSignUpAuthorization(with: challengeResponse)
        } catch {
            // 4. Something went wrong, kick the error up to the UI
            authErrorTitle = "Sign Up Error"
            authErrorMessage = "\(error)"
            isShowingAuthError = true
        }
    }

Here's what we're adding to the login function:

1. We've got to call our first server endpoint with the username supplied by the user. The server will make sure a Passkey doesn't already exist for this user, create a challenge, and save it to the database. That challenge and the user's id will be returned to us. In a production app, you'd already have a user and user id, but this is a simplified flow focusing on the Passkey parts.

2. Save the userId locally, because we're going to need it again later in the process.

3. Here we start the flow in iOS that's going to prompt the user to create a Passkey. For most users, they'll get a prompt to allow the Passkey and be presented with a Face ID authentication (see screenshot below).

4. If anything goes wrong, we're going to bubble the error state back up to the UI so you know what's going on.

The ChallengeResponse struct

Here's how ChallengeResponse is built. I'm using CustomStringConvertible to generate a nicer log output for debugging.

struct ChallengeResponse: Decodable, CustomStringConvertible {
    let challenge: Challenge
    let userId: String

    var description: String {
        return """
            challenge: \(challenge)
            userId: \(userId)
        """
    }
}

struct Challenge: Decodable, CustomStringConvertible {
    let attestation: String
    let challenge: String
    let params: [PublicKeyCredParams]
    let relyingParty: RelyingParty
    let timeout: Int
    let user: AuthUser

    var description: String {
        return """
            attestation: \(attestation)
            challenge: \(challenge)
            params: \(params)
            relyingParty: \(relyingParty)
            timeout: \(timeout)
            user: \(user)
        """
    }

    enum CodingKeys: String, CodingKey {
        case attestation
        case challenge
        case params = "pubKeyCredParams"
        case relyingParty = "rp"
        case timeout
        case user
    }
}

struct PublicKeyCredParams: Decodable, CustomStringConvertible {
    let alg: Int
    let type: String

    var description: String {
        return "alg: \(alg), type: \(type)"
    }
}

struct RelyingParty: Decodable, CustomStringConvertible {
    let id: String
    let name: String

    var description: String {
        return "id: \(id), name: \(name)"
    }
}

struct AuthUser: Decodable, CustomStringConvertible {
    let displayName: String
    let id: String
    let name: String

    var description: String {
        return "id: \(id), name: \(name), displayName: \(displayName)"
    }
}

Generating a Passkey on iOS with ASAuthorizationController

/Users/jday/Documents/WhiteRockStudios/blog/passkeys/iOS screenshots/iOS allow Face ID.png

/Users/jday/Documents/WhiteRockStudios/blog/passkeys/iOS screenshots/iOS save Passkey.png

Once you've got ChallengeResponse and its properties set up, we're ready to continue. From step 3 above, we call startSignUpAuthorization and pass in our newly created challenge. We're going to create a request and pass that into ASAuthorizationController. This will bring up the system Passkey screen in the screenshot above. This will prompt the user to allow biometrics and use them to create a Passkey. Most users at this point will see Face ID, but Touch ID would also work. Once that is finished, we'll get a callback from ASAuthorizationControllerDelegate, which AuthService must conform to and implement.

Note: You can enable biometrics in the iOS Simulator with the enroll option in the Features > Face ID menu. You'll see that you can also complete Face ID prompts here (and there's a handy keyboard shortcut).

Let's walk through startSignUpAuthorization first:

private func startSignUpAuthorization(with challenge: ChallengeResponse) throws {
    guard let challengeData = challenge.challenge.challenge.data(using: .utf8),
          let userIdData = challenge.challenge.user.id.data(using: .utf8) else {

        throw PasskeyError.signup
    }

    // 1. Create the request using our relying party and challenge data
    let platformProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(
            relyingPartyIdentifier: AuthService.relyingParty)
    let assertionKeyRequest = platformProvider.createCredentialRegistrationRequest(challenge: challengeData,
                                                                                   name: challenge.challenge.user.name,
                                                                                   userID: userIdData)

    // 2. Establish AuthController as the delegate and send the request to create a Passkey
    let authController = ASAuthorizationController(authorizationRequests: [assertionKeyRequest])
    authController.delegate = self
    authController.presentationContextProvider = self
    authController.performRequests()
}

So what exactly is going on above?

1. After guarding to make sure we've got all the challenge data inputs required, we create an assertion request using the AuthenticationServices framework in iOS.

2. The request gets passed to ASAuthorizationController to prompt the user to allow the Passkey to be created. Our AuthService class will be the controller's delegate to handle the result. We also provide a presentation context. At the end of your file, add the below chunk of code.

extension AuthService: ASAuthorizationControllerPresentationContextProviding {
    func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {
        ASPresentationAnchor()
    }
}

Ok, back to the ASAuthorizationControllerDelegate conformance. You'll need to implement the two functions below. One is for error handling, and the other handles the actual responses from ASAuthorizationController. The same delegate callback function handles registration, signing in (credential assertion), and also other types of login like Sign in with Apple. Here's the first step in getting this implementation ready:

extension AuthService: ASAuthorizationControllerDelegate {
    func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) {
        print("\(#function) error: \(error)")
    }

    func authorizationController(controller: ASAuthorizationController,
                                 didCompleteWithAuthorization authorization: ASAuthorization) {
        switch authorization.credential {
        case let credentialRegistration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
            print("\(#function) got a credential registration: \(credentialRegistration)")

            Task {
                do {
                    try await makeCredential(userId: userId,
                                             registration: credentialRegistration)
                } catch {
                    authErrorTitle = "Error Registering Credentials"
                    authErrorMessage = "Unable to register at this time. Reason: \(error)"
                    isShowingAuthError = true
                }
            }

        case let credentialAssertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
            // we are not ready for this yet
            break

       case let credential as ASPasswordCredential:
             // Handle other authentication cases, such as Sign in with Apple. We are not doing anything with this.
             print("\(#function) got a password credential: \(credential)")

        default:
            print("something went wrong: \(authorization)")
        }
    }
}

All we're really doing above is making sure the controller is handling a credential registration request, by making sure the authorization credential is of type ASAuthorizationPlatformPublicKeyCredentialRegistration. If so, we're going to take that credential registration and send it to our server in the makeCredential function. There, we'll create a POST request and send that up to our /makeCredential endpoint. If all goes well there, we've completed the registration process and can now use our Passkey to sign in. Here's what that implementation looks like:

private func makeCredential(userId: String,
                                registration: ASAuthorizationPlatformPublicKeyCredentialRegistration) async throws {
    self.userId = userId

    guard let attestationObject = registration.rawAttestationObject else {
            authErrorTitle = "Login Error"
            authErrorMessage = "Unable to find attestation object"
            isShowingAuthError = true
        return
    }

    let payload = attestationPayload(userId: userId,
                                     registration: registration,
                                     attestation: attestationObject)
    try await URLSession.shared.post(endpoint: "/makeCredential",
                                     queryParams: ["userId": userId],
                                     postBody: JSONSerialization.data(withJSONObject: payload),
                                     decodingType: EmptyResponse.self)

    authStatus = .signUpSuccess
}

private func attestationPayload(userId: String,
                                registration: ASAuthorizationPlatformPublicKeyCredentialRegistration,
                                attestation: Data) -> [String: Any] {

    let clientDataJSON = registration.rawClientDataJSON
    let credentialID = registration.credentialID

    return [
        "rawId": credentialID.base64EncodedString(),
        "id": registration.credentialID.base64URLEncode(),
        "authenticatorAttachment": "platform", // Optional parameter
        "clientExtensionResults": [String: Any](), // Optional parameter
        "type": "public-key",
        "response": [
            "attestationObject": attestation.base64EncodedString(),
            "clientDataJSON": clientDataJSON.base64EncodedString()
        ],
        userId: userId
    ]
}

So what's going on here? We're basically just building a POST payload out of the credential response we got back from ASAuthenticationController and sending that to the server. It returns as empty 200 response if everything goes well. The attestationPayload function builds up that payload, making sure all of the fields are encoded correctly. As mentioned before, there's heavy use of base64 and base64 url encoded strings in the WebAuthn flow. If you're interested in learning more about how WebAuthn works, you can really just google any of those terms or ask your favorite LLM, and go as deep into the details as you'd like.

A quick note about ASPresenationAnchor above

There's no need to provide a window or try to hook into your UI somehow. Other implementations you'll find online here are often misunderstood and overcomplicated. By just calling ASPresentationAnchor(), iOS will do the right thing.

Signing in with a Passkey

Now we're ready to use the Log In button in our iOS app, and validate our newly created Passkey. Our button calls AuthService.login, which gets implemented like this:

func login(username: String) async {
    authStatus = .loginInProgress
    self.username = username

    do {
        let options = try await URLSession.shared.get(endpoint: "/authenticate",
                                                      queryParams: ["username": username],
                                                      decodingType: PublicKeyCredentialRequestOptions.self)

        if let challengeData = options.challenge.data(using: .utf8) {
            initiateLogin(challenge: challengeData)
        } else {
            authErrorTitle = "Error Logging In"
            authErrorMessage = "Things are not working."
            isShowingAuthError = true
        }
    } catch {
        authErrorTitle = "Login Error"
        authErrorMessage = "\(error)"
        isShowingAuthError = true
    }
}

Pretty straightforward here, we're making a GET call to our server's /authenticate endpoint to retreive challenge data for a Passkey login. We're going to pass that challenge to our initiateLogin function which is going to interact with ASAuthorizationController again. Before we get there, here is the model class structure for PublicKeyCredentialRequestOptions:

struct PublicKeyCredentialRequestOptions: Decodable {
    /// A base64encoded string.
    let challenge: String

    let timeout: UInt32?
    let rpId: String?
    let allowCredentials: [PublicKeyCredentialDescriptor]?
    let userVerification: UserVerificationRequirement?
}

struct PublicKeyCredentialDescriptor: Decodable {
    let id: String
    let type: String
    let transports: [String]
}

public enum UserVerificationRequirement: String, Decodable {
    /// The auth server requires user verification and will fail if the user wasn't verified
    case required
    /// The auth servier prefers user verification if possible, but will not fail without it
    case preferred
    /// The auth server does not want user verification
    case discouraged
}

Now for implementation of initiateLogin:

private func initiateLogin(challenge: Data) {
    // 1. Create an assertion request
    let publicKeyCredentialProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(
            relyingPartyIdentifier: AuthService.relyingParty)
    let assertionRequest = publicKeyCredentialProvider.createCredentialAssertionRequest(challenge: challenge)

    let authController = ASAuthorizationController(authorizationRequests: [assertionRequest])
    authController.delegate = self
    authController.presentationContextProvider = self

    // 2. Determine the flow to use with ASAuthorizationController
    if preferImmediatelyAvailableCredentials {
        authController.performRequests(options: ASAuthorizationController.RequestOptions.preferImmediatelyAvailableCredentials)
    } else {
        authController.performRequests()
    }
}

A little more detail on what's happening above:

1. We're setting up a public key provider for our relying party, and attaching the challenge from our server to that. Since we're logging in instead of creating a new credential, we create an assertion request and will handle that with ASAuthorizationController, using the delegate we set up earlier during the registration implmentation.

2. For now, we're just going to prefer immediately available credentials. This means that iOS will put up a modal with our saved Passkeys and use biometrics to authenticate the user. If that goes well, we'll get a good callback in the delegate and can continue the process. In the alternative flow, iOS will present a modal sheet with a QR code to use a Passkey from some other device. We are not going to cover that in this article.

Here's what that modal looks like:

Back to our ASAuthorizationControllerDelegate implementation:

extension AuthService: ASAuthorizationControllerDelegate {
    ...

    func authorizationController(controller: ASAuthorizationController,
                                 didCompleteWithAuthorization authorization: ASAuthorization) {
        switch authorization.credential {
            ...

            case let credentialAssertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
             print("\(#function) got a credential assertion (passkey used to sign in): \(credentialAssertion)")

            if !username.isEmpty {
                Task {
                    do {
                        try await authenticate(username: username,
                                               assertion: credentialAssertion)
                    } catch {
                        authErrorTitle = "Error Logging In"
                        authErrorMessage = "Unable to log in. Reason: \(error)"
                        isShowingAuthError = true
                    }
                }
            } else {
                authErrorTitle = "Missing Data"
                authErrorMessage = "Username is required."
                isShowingAuthError = true
            }

            ...
        }
    }
}

Now we're handling the case where the authorization credential is a ASAuthorizationPlatformPublicKeyCredentialAssertion. If that's what we got back from ASAuthorizationController, we're going to pass that to our authenticate function, which will verify the credential on our server:

private func authenticate(username: String,
                          assertion: ASAuthorizationPlatformPublicKeyCredentialAssertion) async throws {        
    do {
        let payload = credentialPayload(credentialAssertion: assertion)
        try await URLSession.shared.post(endpoint: "/authenticate",
                                         queryParams: ["username": username],
                                         postBody: JSONSerialization.data(withJSONObject: payload),
                                         decodingType: EmptyResponse.self)

        authStatus = .loginSuccess
    } catch {
        authErrorTitle = "Login Error"
        authErrorMessage = "\(error)"
        isShowingAuthError = true
    }
}

This calls our /authenticate endpoint, and returns a 200 success response if authentication of the Passkey succeeds. In a production application, you'd want to return some kind of token here that the app will save for subsequent API requests. Here's how we build the credentialPayload above:

private func credentialPayload(credentialAssertion: ASAuthorizationPlatformPublicKeyCredentialAssertion) -> [String: Any] {
    let clientDataJSON = credentialAssertion.rawClientDataJSON
    let credentialId = credentialAssertion.credentialID

    return [
        "rawId": credentialId.base64EncodedString(),
        "id": credentialId.base64URLEncode(),
        "authenticatorAttachment": "platform", // Optional
        "clientExtensionResults": [String: Any](), // Optional
        "type": "public-key",
        "response": [
            "clientDataJSON": clientDataJSON.base64EncodedString(),
            "authenticatorData": credentialAssertion.rawAuthenticatorData.base64EncodedString(),
            "signature": credentialAssertion.signature.base64EncodedString(),
            "userHandle": credentialAssertion.userID.base64URLEncode()
        ]
    ]
}

This kind of payload should be looking pretty familiar by now. We're doing lots of base64 encoding and base 64 url encoding. When I was getting all of this working myself for the first time, I spent the most time getting all of the fields encoded with the right formats. Hopefully having an example laid out like this will save you a lot of time in building your own implementation!

Conclusion

If you've made it this far, congrats! You're ready to fire up ngrok in a terminal, use the generated url as your relying party on your vapor server and iOS application, and test it out!

If you got here first, here are the other 2 articles in this series:

• Build a WebAuthn Passkey server in Swift with Vapor

• Build an Android client application that uses Passkeys

Here's the complete AuthService file for reference:

import SwiftUI
import AuthenticationServices
import CoreAPI

enum AuthStatus: Equatable, Hashable {
    case signUpInProgress
    case signUpSuccess
    case loginInProgress
    case loginSuccess
    case loggedOut

    var displayMessage: String {
        switch self {
        case .signUpInProgress:     "Sign up in progress..."
        case .signUpSuccess:        "Signed up successfully"
        case .loginInProgress:      "Logging in..."
        case .loginSuccess:         "Logged in!"
        case .loggedOut:            "Logged out"
        }
    }
}

@MainActor
class AuthService: NSObject, ObservableObject {

    enum PasskeyError: Error {
        case signup
        case login
    }

    static let relyingParty = "7c42-2600-1700-3e41-88b0-b052-7126-dc42-525f.ngrok-free.app"

    @Published var authErrorTitle = ""
    @Published var authErrorMessage = ""
    @Published var isShowingAuthError = false
    @Published var authStatus = AuthStatus.loggedOut

    private var username = ""
    private var userId = ""
    private var preferImmediatelyAvailableCredentials = true


    // MARK: - Sign Up / Registration

    func signUp(username: String) async {
        authStatus = .signUpInProgress

        do {
            let challengeResponse = try await URLSession.shared.get(endpoint: "/signup",
                                                                    queryParams: ["username": username],
                                                                    decodingType: ChallengeResponse.self)
            userId = challengeResponse.userId
            try startSignUpAuthorization(with: challengeResponse)
        } catch {
            authErrorTitle = "Sign Up Error"
            authErrorMessage = "\(error)"
            isShowingAuthError = true
        }
    }

    /// Sends a POST to /makeCredential
    private func makeCredential(userId: String,
                                registration: ASAuthorizationPlatformPublicKeyCredentialRegistration) async throws {
        self.userId = userId

        guard let attestationObject = registration.rawAttestationObject else {
            authErrorTitle = "Login Error"
            authErrorMessage = "Unable to find attestation object"
            isShowingAuthError = true
            return
        }

        let payload = attestationPayload(userId: userId,
                                         registration: registration,
                                         attestation: attestationObject)
        try await URLSession.shared.post(endpoint: "/makeCredential",
                                         queryParams: ["userId": userId],
                                         postBody: JSONSerialization.data(withJSONObject: payload),
                                         decodingType: EmptyResponse.self)

        authStatus = .signUpSuccess
    }

    private func attestationPayload(userId: String,
                                    registration: ASAuthorizationPlatformPublicKeyCredentialRegistration,
                                    attestation: Data) -> [String: Any] {

        let clientDataJSON = registration.rawClientDataJSON
        let credentialID = registration.credentialID

        return [
            "rawId": credentialID.base64EncodedString(),
            "id": registration.credentialID.base64URLEncode(),
            "authenticatorAttachment": "platform", // Optional
            "clientExtensionResults": [String: Any](), // Optional
            "type": "public-key",
            "response": [
                "attestationObject": attestation.base64EncodedString(),
                "clientDataJSON": clientDataJSON.base64EncodedString()
            ],
            userId: userId
        ]
    }

    /// Uses the `ChallengeResponse` obtained from the /signup endpoint to start the PassKey flow on iOS
    private func startSignUpAuthorization(with challenge: ChallengeResponse) throws {
        guard let challengeData = challenge.challenge.challenge.data(using: .utf8),
              let userIdData = challenge.challenge.user.id.data(using: .utf8) else {

            throw PasskeyError.signup
        }

        let platformProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(
            relyingPartyIdentifier: AuthService.relyingParty)
        let assertionKeyRequest = platformProvider.createCredentialRegistrationRequest(challenge: challengeData,
                                                                                       name: challenge.challenge.user.name,
                                                                                       userID: userIdData)
        let authController = ASAuthorizationController(authorizationRequests: [assertionKeyRequest])
        authController.delegate = self
        authController.presentationContextProvider = self
        authController.performRequests()
    }



    // MARK: - Log in

    func login(username: String) async {
        authStatus = .loginInProgress
        self.username = username

        do {
            let options = try await URLSession.shared.get(endpoint: "/authenticate",
                                                          queryParams: ["username": username],
                                                          decodingType: PublicKeyCredentialRequestOptions.self)

            if let challengeData = options.challenge.data(using: .utf8) {
                initiateLogin(challenge: challengeData)
            } else {
                authErrorTitle = "Error Logging In"
                authErrorMessage = "Things are not working."
                isShowingAuthError = true
            }
        } catch {
            authErrorTitle = "Login Error"
            authErrorMessage = "\(error)"
            isShowingAuthError = true
        }
    }

    private func initiateLogin(challenge: Data) {
        let publicKeyCredentialProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(
            relyingPartyIdentifier: AuthService.relyingParty)
        let assertionRequest = publicKeyCredentialProvider.createCredentialAssertionRequest(challenge: challenge)

        // Pass in any mix of supported sign-in request types.
        let authController = ASAuthorizationController(authorizationRequests: [assertionRequest])
        authController.delegate = self
        authController.presentationContextProvider = self

        if preferImmediatelyAvailableCredentials {
            authController.performRequests(options: ASAuthorizationController.RequestOptions.preferImmediatelyAvailableCredentials)
        } else {
            authController.performRequests()
        }
    }

    private func authenticate(username: String,
                              assertion: ASAuthorizationPlatformPublicKeyCredentialAssertion) async throws {

        do {
            let payload = credentialPayload(credentialAssertion: assertion)
            try await URLSession.shared.post(endpoint: "/authenticate",
                                             queryParams: ["username": username],
                                             postBody: JSONSerialization.data(withJSONObject: payload),
                                             decodingType: EmptyResponse.self)

            authStatus = .loginSuccess
        } catch {
            authErrorTitle = "Login Error"
            authErrorMessage = "\(error)"
            isShowingAuthError = true
        }
    }

    private func credentialPayload(credentialAssertion: ASAuthorizationPlatformPublicKeyCredentialAssertion) -> [String: Any] {
        let clientDataJSON = credentialAssertion.rawClientDataJSON
        let credentialId = credentialAssertion.credentialID

        return [
            "rawId": credentialId.base64EncodedString(),
            "id": credentialId.base64URLEncode(),
            "authenticatorAttachment": "platform", // Optional
            "clientExtensionResults": [String: Any](), // Optional
            "type": "public-key",
            "response": [
                "clientDataJSON": clientDataJSON.base64EncodedString(),
                "authenticatorData": credentialAssertion.rawAuthenticatorData.base64EncodedString(),
                "signature": credentialAssertion.signature.base64EncodedString(),
                "userHandle": credentialAssertion.userID.base64URLEncode()
            ]
        ]
    }
}

extension AuthService: ASAuthorizationControllerDelegate {
    func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) {
        print("\(#function) error: \(error)")
    }

    func authorizationController(controller: ASAuthorizationController,
                                 didCompleteWithAuthorization authorization: ASAuthorization) {
        switch authorization.credential {
        case let credentialRegistration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
            print("\(#function) got a credential registration: \(credentialRegistration)")

            Task {
                do {
                    try await makeCredential(userId: userId,
                                             registration: credentialRegistration)
                } catch {
                    authErrorTitle = "Error Registering Credentials"
                    authErrorMessage = "Unable to register at this time. Reason: \(error)"
                    isShowingAuthError = true
                }
            }

        case let credentialAssertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
             print("\(#function) got a credential assertion (passkey used to sign in): \(credentialAssertion)")

            if !username.isEmpty {
                Task {
                    do {
                        try await authenticate(username: username,
                                               assertion: credentialAssertion)
                        print("success!")
                    } catch {
                        authErrorTitle = "Error Logging In"
                        authErrorMessage = "Unable to log in. Reason: \(error)"
                        isShowingAuthError = true
                    }
                }
            } else {
                authErrorTitle = "Missing Data"
                authErrorMessage = "Username is required."
                isShowingAuthError = true
            }

        case let credential as ASPasswordCredential:
             // Handle other authentication cases, such as Sign in with Apple.
             print("\(#function) got a password credential: \(credential)")

        default:
            print("something went very wrong -- fatal error")
        }
    }
}

extension AuthService: ASAuthorizationControllerPresentationContextProviding {
    func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {
        ASPresentationAnchor()
    }
}

In this series, you’ll learn how to implement passkey support across iOS, Android, and your server backend using Swift, Kotlin, and Vapor. More details about the Swift Webauthn library can be found here.

Whether you're building a new app or modernizing an existing one, this guide will help you bring passwordless login to life with a clean approach on both mobile platforms.

Overview

This project will create a restful server to handle Passkey authentication for iOS and Android apps. MySQL is used for the database layer, although any database supported by Vapor can be used (Postgres, MongoDB, etc... see a full list here). I’m also interacting with MySQL from the Vapor application with raw SQL instead of using Vapor’s Fluent ORM. More information on Fluent can be found here: Vapor Fluent.

Setting up a Vapor Project

Creating a new Vapor project is easy. You should be able to follow this guide to create a project and open it in Xcode. Once you have your project open, here’s the Package.swift file I’m currently using:

// swift-tools-version:5.9
import PackageDescription

let package = Package(
    name: “passkey-server”,
    platforms: [
       .macOS(.v13)
    ],
    dependencies: [
        // 💧 A server-side Swift web framework.
        .package(url: “https://github.com/vapor/vapor.git”, from: “4.83.1”),
        .package(url: “https://github.com/swift-server/webauthn-swift.git”, from: “0.0.3”),
        .package(url: “https://github.com/vapor/mysql-kit.git”, from: “4.7.0”),
        .package(url: “https://github.com/vapor/fluent.git”, from: “4.8.0”),
        .package(url: “https://github.com/vapor/fluent-mysql-driver.git”, from: “4.4.0”),
    ],
    targets: [
        .executableTarget(
            name: “App”,
            dependencies: [
                .product(name: “Vapor”, package: “vapor”),
                .product(name: “WebAuthn”, package: “webauthn-swift”),
                .product(name: “MySQLKit”, package: “mysql-kit”),
                .product(name: “Fluent”, package: “fluent”),
                .product(name: “FluentMySQLDriver”, package: “fluent-mysql-driver”),
            ]
        ),
        .testTarget(name: “AppTests”, dependencies: [
            .target(name: “App”),
            .product(name: “XCTVapor”, package: “vapor”),

            // Workaround for https://github.com/apple/swift-package-manager/issues/6940
            .product(name: “Vapor”, package: “vapor”),
        ])
    ]
)

Setting up the Database

Here are the create table queries to build the MySQL schema for this project:

CREATE TABLE user (
  id varchar(36) NOT NULL,
  username varchar(100) DEFAULT NULL,
  creation_date datetime DEFAULT NULL,
  PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE userauthchallenge (
  user_id varchar(36) NOT NULL,
  challenge text NOT NULL,
  FOREIGN KEY (user_id) 
    REFERENCES user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE userchallenge (
  user_id varchar(36) NOT NULL,
  challenge text,
  FOREIGN KEY (user_id) 
    REFERENCES user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE usercredential (
  user_id varchar(36) NOT NULL,
  credential_id varchar(100),
  public_key text NOT NULL,
  FOREIGN KEY (user_id) 
    REFERENCES user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Once these tables are created, you’ll need to set up the databse connection in your Vapor project. In configure.swift, add this line to your configure(_ app: Application) function:

public func configure(_ app: Application) async throws {
    …
    try setupDatabaseConnection(app)
    …
}

private func setupDatabaseConnection(_ app: Application) throws {
    var tls = TLSConfiguration.makeClientConfiguration()
    tls.trustRoots = .default
    tls.minimumTLSVersion = .tlsv11
    tls.certificateVerification = .none

//    let fileUrl = URL(fileURLWithPath: app.directory.workingDirectory)
//        .appendingPathComponent(“Resources/“ + Environment.dbCertPath, isDirectory: false)
//
//    tls.trustRoots = NIOSSLTrustRoots.certificates(
//        try NIOSSLCertificate.fromPEMFile(fileUrl.path)
//    )

    let config = MySQLConfiguration(hostname: Environment.dbHostName,
                                    username: Environment.dbUsername,
                                    password: Environment.dbPassword,
                                    database: Environment.defaultDB,
                                    tlsConfiguration: tls)
    app.databases.use(.mysql(configuration: config), as: .mysql)
}

For the purposes of this demo I’m setting up a local MySQL database and ignoring TLS settings. I left the actual settings commented out, so hopefully that can serve as a helpful way to get this up and going if needed. I can't remember where exactly I found this information, but it may have come from the vapor discord, it is very active and helpful.

I’m also using environment variables, which require a .env file in the root directory of your project. An example env entry looks pretty standard, like this: DATABASE_URL=localhost.

There’s one more bit of setup I use when I’m working on a vapor project using a database. Even though I’m not using the Fluent ORM, Fluent does help with the management of database connections and exposes a db property on the Request object. I add a little helper extension for even easier access. This will be used later in the part of the app that handles routes:

import Vapor
import SQLKit
import Fluent

extension Request {
    var mySQL: SQLDatabase {
        return db as! SQLDatabase
    }
}

Public Files for Domain Verification

iOS and Android each require a file to be hosted so that your domain can be verified and associated with your app. The files need to be available publicly, in a .well-known directory. In order to expose these files publicly, you’ll need to include this in your configure.swift file, in the configure(app: Application) function:

app.middleware.use(FileMiddleware(publicDirectory: app.directory.publicDirectory))

Apple’s apple-app-site-association File

The apple-app-site-association file, or AASA, is a JSON file that include’s your app’s identifier, including team ID. Include this code in your routes.swift:

func routes(_ app: Application) throws {
    app.get(“.well-known”, “apple-app-site-association”) { req -> Response in
        let appIdentifier = “teamId.appIdentifier”
        let responseString =
            “””
            {
                “applinks”: {
                    “details”: [
                        {
                            “appIDs”: [
                                “\(appIdentifier)”
                            ],
                            “components”: [
                            ]
                        }
                    ]
                },
                “webcredentials”: {
                    “apps”: [
                        “\(appIdentifier)”
                    ]
                }
            }
            “””

        let response = try await responseString.encodeResponse(for: req)
        response.headers.contentType = HTTPMediaType(type: “application”, subType: “json”)
        return response
    }
}

Your Xcode project must also have a corresponding setup. You’ll need to configure Associated Domains in the project settings. Here’s a link to the official documentation. We'll cover that more in the iOS tutorial.

Android’s assetlinks.json File

Android requires a similar file to be hosted, the assetlinks.json file. This file requires your android app’s identifier, as well as a SHA256 certificate fingerprint for the app. Once you’ve created a keystore for your android app, navigate to your project’s directory in terminal and run this command to generate the fingerprint:

keytool -list -v -keystore PasskeysAndroidKeystore.jks

This is what you’ll need to include in your routes.swift file. packageName is your android app identifier:

func routes(_ app: Application) throws {
app.get(“.well-known”, “assetlinks.json”) { req -> Response in
        let packageName = “com.example.passkeys_android”
        let responseString =
        “””
        [
            {
                “relation” : [
                    “delegate_permission/common.handle_all_urls”,
                    “delegate_permission/common.get_login_creds”
                ],
                “target” : {
                    “namespace” : “android_app”,
                    “package_name” : “\(packageName)”,
                    “sha256_cert_fingerprints” : [
                        “YOUR:SHA:FINGERPRINT:GOES:HERE”
                    ]
                }
            }
        ]
        “””

        let response = try await responseString.encodeResponse(for: req)
        response.headers.contentType = HTTPMediaType(type: “application”, subType: “json”)
        return response
    }
}

More information about the assetlinks.json file can be found here.

Setting up WebAuthnManager

This project depends on the great work done on the swift-webauthn library. As of this writing, the official 1.0 release is not out yet, but should be coming soon. WebAuthn is the official name for the standard behind Passkeys, and the swift library is an implementation of WebAuthn that is similar to what has been done for other platforms in different languages. I recommend reading up a WebAuthn a bit if you haven’t already.

One challenge I encountered during this project is that iOS and Android handle Passkeys differently. Android uses a different paradigm for the Relying Party than Apple/iOS and the rest of the web use. For this reason, we’ll need to set up 2 instances of WebAuthnManagerin our project. One to handle the relying party for our iOS app, and another for the Android app.

First, you’re going to need this extension to set up those managers. I created an Application+WebAuthn.swift file:

import Vapor
import WebAuthn

extension Application {
    struct WebAuthnKey: StorageKey {
        typealias Value = WebAuthnManager
    }

    struct AndroidWebAuthnKey: StorageKey {
        typealias Value = WebAuthnManager
    }

    var webAuthn: WebAuthnManager {
        get {
            guard let webAuthn = storage[WebAuthnKey.self] else {
                fatalError(“WebAuthn is not configured. Use app.webAuthn”)
            }
            return webAuthn
        }
        set {
            storage[WebAuthnKey.self] = newValue
        }
    }

    var webAuthnAndroid: WebAuthnManager {
        get {
            guard let webAuthn = storage[AndroidWebAuthnKey.self] else {
                fatalError(“WebAuthn for android is not configured. Use app.webAuthnAndroid”)
            }
            return webAuthn
        }
        set {
            storage[AndroidWebAuthnKey.self] = newValue
        }
    }
}

extension Request {    
    var webAuthn: WebAuthnManager {
        let userAgent = headers[“user-agent”]
        if userAgent.first?.localizedCaseInsensitiveContains(“okhttp”) ?? false {
            return application.webAuthnAndroid
        }
        return application.webAuthn
    }
}

Let’s talk a bit more about what’s going on in this extension. Passkeys for the web and iOS use a URL, referred to as the Relying Party in Passkey terminology. Your iOS or web app might have a relying party of example.com or login.example.com, and when the Passkey authentication dance happens, your server will verify the origin of the passkey, which will be https://www.example.com.

However, Android apps using the CredentialManager API use a different relying party origin format:

android:apk-key-hash:<sha256-hash-for-your-app's-apk-signing-cert>

Since these formats are completely different, a one-size-fits-all approach doesn't exist for iOS and Android. We have to use 2 different instances of WebAuthnManager, and look at the request's user agent header to determine if the request came from Android so we can handle Android's unique format. As you can see above, I've built this into an extension on Vapor's Request so we can easily get the appropriate manager when handling routes.

Side Note -- ngrok

When you're ready to test this out with an iOS or Android app, you're going to need a way to call this server's endpoints with https. If you're just hosting it locally, that's not going to work. Enter ngrok. This tool creates an http or https endpoint and routes the traffic to your local machine, which means you can run this server on your local machine and reach its endpoints both using https and from physical mobile devices (Android will require a physical device, but the iOS simulator will work).

To get started, you'll need to create a free ngrok account and set it up. Then you can follow the instructions here to configure ngrok on your machine. Here's the command I use to run it after it's set up:

./ngrok-2 http 8080

This will create a url that forwards to your localhost on port 8080. This is the default port for running vapor locally in Xcode.

Adding the ngrok url to your environment properties

If everything is set up correctly, ngrok will create a url that looks something like this:

https://5e55-2000-1300-3244-89c0-q049-7106-da49-535g.ngrok-free.app

The full url will be your relying party origin, and the domain without https is your relying party id:

RP_ID=e55-2000-1300-3244-89c0-q049-7106-da49-535g.ngrok-free.app
RP_ORIGIN=https://e55-2000-1300-3244-89c0-q049-7106-da49-535g.ngrok-free.app

You'll need to restart the server after setting environment variables for them to take effect.

Passkey Creation / Sign Up

Current best practice is to require a user to have an account and be authenticated before you allow them to create a Passkey. If you have an existing application, you can offer Passkey creation after a user has signed in. If you're creating something new, some non-Passkey form of account creation and authentication will also need to be created. To keep this project tightly scoped to Passkeys, and provide a working example without getting even deeper into the details, I am not implementing a full login sequence.

Also note that this would also require some of the steps below to be slightly different. A user setting up a passkey would already have a user name and user ID, and you'd know what they are at the time of Passkey creation. You'll want to verify their login credentials before creating a Passkey. You wouldn't want to just let anyone create a Passkey without being authenticated first.

Handling the first sign up step, the user challenge

Users of your client applications will need to create a Passkey the first before they can start authenticating with one. To get the process started, clients will make a GET request to your /signup endpoint:

app.get("signup", use: { req -> ChallengeResponse in
    // 1. the endpoint requires username as a query param
    guard let username: String = req.query["username"] else {
        throw Abort(.badRequest, reason: "Username must be supplied.")
    }

    // 2. check to make sure we don't already have that username in the DB
    let foundUser = try await req.mySQL
        .raw(SQLQueryString("SELECT username FROM user WHERE username = \(bind: username) LIMIT 1"))
        .first(decoding: UserResult.self)

    guard foundUser == nil else {
        throw Abort(.conflict, reason: "Username already taken.")
    }

    // 3. create a new user credential for the requesting user
    return try await makeUserCredential(for: username, req: req)
})

Here's what's going on above:

1. We grab the username query param required by the /signup endpoint

2. We check to make sure that username doesn't already exist. If it does, this user can't sign up again. If this is a new unique user, we move to step 3

3. We'll return a ChallengeResponse. This is the result of calling makeUserCredential, which we'll build next:

func makeUserCredential(for username: String, req: Request) async throws -> ChallengeResponse {

    // 1. Create details for the new user and insert into the DB
    let newUserId = UUID().uuidString
    let timestamp = Date()
    try await req.mySQL
        .raw(SQLQueryString("INSERT INTO user(id, username, creation_date) VALUES(\(bind: newUserId), \(bind: username), \(bind: timestamp))"))
        .run()

    // 2. Create a new user and generate a challenge
    let user = User(id: newUserId,
                    username: username,
                    creationDate: timestamp)

    let options = req.webAuthn.beginRegistration(user: user.webAuthnUser)
    let challenge = Data(options.challenge).base64EncodedString()

    // 3. Save the challenge to the DB and return it back to the client app
    try await req.mySQL
        .raw(SQLQueryString("INSERT INTO userchallenge(user_id, challenge) VALUES(\(bind: newUserId), \(bind: challenge))"))
        .run()

    let response = ChallengeResponse(challenge: options,
                                     userId: newUserId)
    return response
}

Here's a rundown on what's going on in /makeUserCredential:

1. First we create an internal user ID for our new user, and we'll also save their account creation date. You'd already have this for an existing account, but maybe you'd want to track the date of when they created a Passkey. Anyway, we insert the new record into our user table.

2. Create a new User object and use that to generate a PublicKeyCredentialUserEntity that we feed into the WebAuthn registration function to create a PublicKeyCredentialCreationOptions. The challenge is the key piece of information here. We have to convert the byte array to a base 64 string.

3. Finally, we save the challenge data to the database with the user's ID, and send this back in the response to the client app.

At this point, the client app will receive this challenge data and use it to generate a Passkey. In the next step, we'll receive the Passkey from the client in a /makeCredential endpoint and finish the Passkey registration process.

Handling the second sign up step, creating a credential

The next endpoint we need to implement is the /makeCredential endpoint (not to be confused with makeUserCredential above in the previous step. Notice that this is a POST endpoint. The post body is a RegistrationCredential, which is part of the Swift WebAuthn library in our project. This object gets created by the client app when it creates the user's Passkey.

app.post("makeCredential") { req -> HTTPStatus in

    // 1. Find the user we're registering a credential for
    guard let userId: String = req.query["userId"] else {
        throw Abort(.badRequest, reason: "The user id must be supplied.")
    }

    guard let user = try await req.mySQL
        .raw(SQLQueryString("SELECT * from user WHERE id = \(bind: userId)"))
        .first(decoding: User.self) else {
            throw Abort(.badRequest, reason: "UserId must be supplied.")
    }

    // 2. Obtain the challenge we stored on the server for this session
    guard let challenge = try await req.mySQL
        .raw(SQLQueryString("SELECT * from userchallenge WHERE user_id = \(bind: userId)"))
        .first(decoding: ChallengeResult.self),
          let challengeData = Data(base64Encoded: challenge.challenge.urlEncoded.base64String()) else {
            throw Abort(.badRequest, reason: "Missing registration session id.")
    }

    // 3. Delete the challenge from the server to prevent an attacker from reusing it
    try await req.mySQL.raw(SQLQueryString("DELETE FROM userchallenge WHERE user_id = \(bind: userId)")).run()

    // 4. Verify the credential the client sent us
    let credential = try await req.webAuthn.finishRegistration(
        challenge: [UInt8](challengeData),
        credentialCreationData: req.content.decode(RegistrationCredential.self, as: .json),
        confirmCredentialIDNotRegisteredYet: { credentialId in
            let existingCredential = try await req.mySQL
                .raw(SQLQueryString("SELECT * FROM usercredential WHERE credential_id = \(bind: credentialId)"))
                .first(decoding: CredentialResult.self)
            return existingCredential == nil
        }
    )

    // 5. If the credential was verified, save it to the database
    let authnCredential = WebAuthnCredential(from: credential, userId: user.id)
    try await req.mySQL
        .raw(SQLQueryString("INSERT INTO usercredential(user_id, credential_id, public_key) VALUES(\(bind: user.id), \(bind: authnCredential.id), \(bind: authnCredential.publicKey))"))
        .run()

    return .ok
}

There's a going on here, but it's not too hard to understand. Let's break it down:

1. The client app sends us the user id we created in the previous step so we can identify the user and make sure we already know about them.

2. Now we use that user id to grab the user's challenge data that we stored during the first stage of Passkey registration in the previous endpoint's implementation. We're going to take that challenge string, url encode it, base 64 encode it, and convert it to Data.

   1. Note: Get used to base 64 and url encoded strings. This is going to be a really common theme throughout a Passkey implementation.

3. Now that we have our challengeData stored in memory, we're going to delete that challenge from the database. This ensures that the challenge can't be used again by an attacker.

4. There's a lot packed into this step. The first param of the WebAuthn finishRegistration function is our challengeData converted to a byte array. We're also decoding the post body of the request into a RegistrationCredential and making sure that credential's id doesn't already exist in our DB with the confirmCredentialIDNotRegisteredYet closure. If everything succeeds, the credential is verified and we'll get a Credential object.

5. Now we create a homemade object, WebAuthnCredential, and we'll use that to help save our userId, credentialId, and publicKey to the database. If everything succeeds, we'll just return a 200 ok response to the client app.

Phew! Registration is now complete.

Passkey Authentication

Generating an Auth Challenge

You'll need to create a GET endpoint named /authentication. It takes a username field as a query param, which will most likely be the user's email address.

app.get("authenticate") { req -> PublicKeyCredentialRequestOptions in
    guard let username: String = req.query["username"] else {
        throw Abort(.badRequest, reason: "Username must be supplied.")
    }

    // 1. generate a challenge for the user attempting to log in
    let options = try req.webAuthn.beginAuthentication()
    let optionDataString = Data(options.challenge).base64EncodedString()

    guard let existingUser = try await req.mySQL
        .raw(SQLQueryString("SELECT * FROM user WHERE username = \(bind: username)"))
        .first(decoding: User.self) else {
        throw Abort(.badRequest, reason: "User not found.")
    }

    // 2. save that challenge to the database as a base64 encoded string
    try await req.mySQL
        .raw(SQLQueryString("INSERT INTO userauthchallenge(user_id, challenge) VALUES(\(bind: existingUser.id), \(bind: optionDataString))"))
        .run()

    // 3. return the generated credential request options back to the caller
    return options
}

This is all pretty straightforward:

1. After making sure we received a username as a query param, we use our Request extension created earlier to get the right WebAuthnManager instance and call beginAuthentication(). This generates a challenge for this authentication attempt. We also convert it to a base64 encoded string so we can save it to the database.

2. Save that challenge to the database, along with the user's ID

3. Return the PublicKeyCredentialRequestOptions back to the caller so they can perform the next authentication step.

Finishing Authentication

Next we'll create a POST endpoint called /authenticate. We're also taking the username as a query parameter again, and also require an AuthenticationCredential as a post body. Here's the implementation:

app.post("authenticate") { req -> HTTPStatus in
    // 1. Get the user from the query param and make sure we know who it is
    guard let username: String = req.query["username"] else {
        throw Abort(.badRequest, reason: "Username must be supplied.")
    }

    guard let existingUser = try await req.mySQL
        .raw(SQLQueryString("SELECT * FROM user WHERE username = \(bind: username)"))
        .first(decoding: User.self) else {

        throw Abort(.badRequest, reason: "User not found.")
    }

    // 2. Make sure we have a challenge saved for this user
    guard let challenge = try await req.mySQL
        .raw(SQLQueryString("SELECT * from userauthchallenge WHERE user_id = \(bind: existingUser.id)"))
        .first(decoding: ChallengeResult.self),
          let challengeData = Data(base64Encoded: challenge.challenge.urlEncoded.base64String()) else {

        try await removeAuthChallenge(for: existingUser.id, req: req)
        throw Abort(.badRequest, reason: "Missing auth session id.")
    }

    // 3. Delete the challenge from the server to prevent an attacker from reusing it
    try await removeAuthChallenge(for: existingUser.id, req: req)

    // 4. Decode the credential the client sent us
    var authenticationCredential = try req.content.decode(AuthenticationCredential.self)
    let authenticatorData = authenticationCredential.response.authenticatorData
    let authString = String(bytes: authenticatorData, encoding: .utf8)

    // 5. Make sure we have an auth credential saved in our database for this user
    guard let foundCredential = try await req.mySQL
        .raw(SQLQueryString("SELECT * FROM usercredential WHERE credential_id = \(bind: authenticationCredential.id.urlDecoded)"))
        .first(decoding: UserAuthCredential.self) else {
            try? await removeAuthChallenge(for: existingUser.id, req: req)
            throw Abort(.badRequest)
    }

    let credentialPublicKey = URLEncodedBase64(foundCredential.publicKey).urlDecoded
    guard let decodedPublicKey = credentialPublicKey.decoded else {
        try? await removeAuthChallenge(for: existingUser.id, req: req)
        throw Abort(.badRequest)
    }

    // 6. If we found a credential, use the stored public key to verify the challenge
    // sign count will always be 0, we don't need to do anything else with it
    _ = try req.webAuthn.finishAuthentication(
        credential: authenticationCredential,
        expectedChallenge: [UInt8](challengeData),
        credentialPublicKey: [UInt8](decodedPublicKey),
        credentialCurrentSignCount: 0)

    return .ok
}

func removeAuthChallenge(for userId: String, req: Request) async throws {
    try await req.mySQL.raw(SQLQueryString("DELETE FROM userauthchallenge WHERE user_id = \(bind: userId)")).run()
}

Ok, this is a bit of a longer function, but hopefully things are coming together in a way that makes sense:

1. First we're just making sure the client sent a username and that we know enough about that username to do something with it

2. We also need to make sure we've previously saved a challenge for this user. We need to decode that back to Data from it's base64 url encoded format we saved to the database.

3. Similar to some previous spots, we're going to remove this challenge from our database now. If an attacker attempted a replay attack, we won't fall for it because we've already had a request come through for this user and we've cleaned up.

4. It's time to decode the AuthenticationCredential that was sent in the payload of this request. In particular, we're looking for the authenticatorData piece, and we convert that to a String.

5. Now we check if we've previously saved a UserAuthCredential to the database for this user. This contains the public key we'll use to validate the user's credential. Again, if we don't find anything we stored previously in the database, we're deleting the challenge for this user. If anything smells off, we err on the side of caution. Worst case, a legit user will get a failure and can just try again.

6. The WebAuthn library validates the credential. If everything lines up, success!

At this point, instead of sending an empty 200 response, you'd most likely want to send a token in the response that your user will pass with every subsequent request, granting them access to your server's endpoints until the token expires. If you're adding Passkeys to an existing application, you probably already have this in place. If you're starting from scratch, REST API token management would be a great next rabbit hole to go down.

Conclusion

Thanks for reading this far...we've covered a lot! Hopefully I've given you enough information to dive deeper on any areas that aren't as clear or you are interested in learning more about.

This is the first in a series of articles on implementing a Passkey authentication server that can serve iOS and Android mobile apps. The other 2 articles can be found here:

• iOS: https://whiterockstudios.hashnode.dev/creating-a-passkey-client-for-ios

• Android: https://whiterockstudios.hashnode.dev/creating-a-passkey-client-for-android

Sources

The following articles were helpful or served as inspiration:

• Broken Hands VaporPasskeys-Demo

• W3C WebAuthn