The internet would be a much more secure place for its users if passkeys replaced passwords. They are phishing-proof, guess-proof and come with built-in two-factor authentication (2FA). They are also more privacy-preserving than OAuth methods like Sign In With Google, because they don’t attach your account to a centralised identity.

But they aren’t that easy for us developers to implement.

The aim of this article, therefore, is to show you how to implement passkeys in your Android app all the way from back- to front-end.

That back-end part is important, as that’s what I found missing in existing documentation. It’s too easy to build an Android front-end that doesn’t works against any back-end, and likewise a back-end that doesn’t work with Android.

Here are the repos we’ll use in this article:
Android app: https://github.com/tdcolvin/PasskeyAuthDemoAndroid
Back-end server (NodeJS): https://github.com/tdcolvin/PasskeyAuthDemoServer

The full-stack application we’re going to build

This is the application we’re going to build. We’ll use Android’s Jetpack Credential Manager to sign ourselves up — that is, “register” a passkey — and then sign in (“authenticate”) with that passkey. And at each step we’ll see what the server needs to respond with:

But before we can build this, we need a back end to sign up to. I promised a full-stack tutorial, right? So:

An Android-compatible passkey server

You can do this the easy way, or you can give yourself full control:

• Easy: Use my implementation at auth.tomcolvin.co.uk which works for every part of this tutorial (but is deliberately insecure so not for production use!)
• Full control: Or, you can run your own server locally on your computer, which gives you the benefit of being able to tinker with the back end and see it working. To do that, install NodeJS then clone this repo: https://github.com/tdcolvin/PasskeyAuthDemoServer.
  Then run npm i and npm run start. More details are in the readme of that repo.

Either way, you’ll be talking to a NodeJS server which uses SimpleWebAuthn to do the complex cryptographic work. On top of that I’ve added the relevant bits to make it compatible with Android’s needs. We’ll see what those are later.

Now that we’ve got the server working, let’s create an Android app to talk to it.

The Android app using Jetpack Credential Manager

If you’re creating a new project for tinkering, your life will be made easier if you give it the ID com.tdcolvin.passkeyauthdemo, because then you can use the above back ends without alteration. But don’t worry if not!

To add the relevant libraries, add the following lines to your app/build.gradle.kts and gradle/lib.versions.toml files:

The libraries we’re adding are:

• Jetpack Credential Manager, which does all the complex cryptography stuff around passkeys, and manages secure storage of passkeys
• OkHttp, my chosen HTTP library (there are others! For tutorial purposes OkHttp is useful for its simplicity)

Right, now that we’ve got an Android app with the relevant libraries, let’s tell the server about it.

Authorising your app: easy mode

Android will refuse to talk to a passkey auth server which isn’t expecting it. And a passkey auth server will refuse to talk to an app it’s not expecting.

If you just want to make this work with the ready-made back-end I posted above (either auth.tomcolvin.co.uk or the self-host NodeJS back-end), then:

1. Set your app’s ID to com.tdcolvin.passkeyauthdemo
2. Sign it with this key (password aaaaaa).

That gives it a recognised ID and fingerprint. And it means you can skip the next bit. But don’t use this key for production apps! (Obviously. It’s been posted online 😂).

Otherwise, let’s go hardcore.

Authorising your app: hard mode

But, if you’re integrating passkeys into your own app with an existing ID/key, then you’ll need to tell the server about its ID and fingerprint.

To make things difficult, the Android app has to be specified in two different places in two different ways. Which is nuts. The server needs to know about your app:

1. In a publicly available file which the server provides (assetlinks.json)
2. In the server’s configuration (the expected origin).

Note in both places we identify the app using its SHA-256 fingerprint, which is slightly unusual in the Android world (SHA-1 being more common).

The assetlinks.json file

The publicly available file has to be served at /.well-known/assetlinks.json. In the demo project, you can find it in the public directory. Its format is as follows:

Edit package_name and sha256_cert_fingerprints to match your app. Note that the SHA-256 fingerprint has colon-separators. (How to find your app’s SHA-256 fingerprint.)

The expected origin

In the demo project’s /src/simplewebauthn/index.ts file, we have:

What’s that weird format after android:apk-key-hash:!?!

It turns out it’s the raw bytes of the SHA-256 hash, converted to base64url format. You can use this utility to do that, but make sure you select Base64url as the Base64 variant:

Cryptii pipeline for converting raw hex bytes to base64url (credit: author)

Edit that line, then you’re good to go.

OK, now that we’ve got an Android app set up and its ID is authorised, let’s create a new passkey in the front end.

Registering a user

Looking ahead, here’s an overview of how passkeys are created. You will need to keep this process in mind because without it the code is going to look pretty strange.

You create a passkey like this:

Those steps are:

1. The client asks for information necessary to create a passkey for their account
2. The server responds with a small piece of JSON which contains, among other things, the user’s unique ID and some cryptographic details
3. The client creates the passkey for the user and sends it to the server

Signing up a brand new user

Note that the above assumes that the user already exists on the system. That’s really important. If the user is brand new, they need to create an account first. From a UI perspective, you can make it look like it’s all happening in one, but actually you need to create an account first and assign a passkey to it after.

Getting the registration options

The client asks the server for /generate-registration-options, which contains the information it needs to create a passkey.

Note: /generate-registration-options is what I’ve called it in my back-end implementation. But note that there’s no particular naming convention defined, so other back end implementations will probably call it something else. (This fact confused me during research because the back end documentation talked about different URLs than the front end documentation did.)

Here’s the code to get that, using OkHttp:

Those registration options look like this:

// Registration Options retrieved from server
{
  "challenge": "Fsfnx23eI0x07Dbd63QMDiqXH3WelwsVADSowKgninI",
  "rp": {
    "name": "Tom's secret site",
    "id": "auth.tomcolvin.co.uk"
  },
  "user": {
    "id": "9M0ZKXgNSaqpYkNm9vt9ay6RYwfa8Px7WZvvmcCTLC8",
    "name": "tomcolvin",
    "displayName": "tomcolvin"
  },
  "pubKeyCredParams": [
    {
      "alg": -7,
      "type": "public-key"
    },
    {
      "alg": -257,
      "type": "public-key"
    }
  ],
  "timeout": 60000,
  "attestation": "none",
  "excludeCredentials": [],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "preferred",
    "requireResidentKey": true
  },
  "extensions": {
    "credProps": true
  },
  "hints": []
}

This is like an “offer” to allow you, the client, to create a passkey. It tells you which user you can create the passkey for, when you can create it, and some security constraints. Specifically:

• challenge: this is like a one-time passcode to ensure that this request can’t be reused to create another passkey at a later date
• rp: stands for “Relying Party” — identification details for the server
• user: information on the user, according to the server. Importantly this contains the user ID as generated by the server
• timeout: the passkey needs to be created within this time
• attestation: allows the server to request that the device creating the passkey proves it’s of a certain type or has certain features. We set this to “none” because that’s better for privacy (otherwise, it potentially requires users to reveal hardware details and IDs).
• authenticatorSelection: allows the server to specify security properties of the passkey created. Can it be used across devices? Are biometrics required?

Question: can’t the client just generate this registration options JSON itself? The answer is no: for security reasons, only the server should control whether a client is allowed to create a passkey for a given account. This registrations options response is like a “ticket” allowing the client to do so. The “barcode” on the ticket (the bit which gets scanned to allow you in) is the challenge element.

Now that we have the registration options, we have all the info we need to ask the user to create a passkey. Let’s get Jetpack Credential Manager to do that for us…

Generating the passkey

Jetpack Credential Manager takes the registration options, maybe asks the user some questions, takes their biometrics or screenlock, then builds a passkey.

We never get to see the passkey itself! It gets saved to whatever password manager we want, and obviously plays a part in the login phase, but the actual private key can never be seen by human eyes. That’s why passkeys are almost completely phishing-proof.

We start by creating an instance of CredentialManager. Assuming you’re using Compose:

We can then feed that CredentialManager our registration options JSON, and ask it to make a passkey:

And that results in the following popup:

Note that this popup is actually from Google Password Manager, not Jetpack Credential Manager. If you use a different password manager (which you can, because recent Android version support third-party ones) then you’ll see a different UI.

Follow that UI through and a passkey gets created by your password manager. It has a private key which gets encrypted and secured using your biometrics or PIN, and a public key which we have to pass to the server. Let’s do that bit next…

Passing the passkey back to the server

The createCredentialResponse that we get back from credentialManager.createCredential() has a registrationResponseJson field, which we pass as-is to the server. That contains all it needs to know about the passkey we’ve just created.

This process is what the passkey standard calls verifying a credential. My server accepts this JSON via an HTTP POST to /verify-registration. (Again, no formally-defined URLs, so your implementation will differ).

Here’s the function for doing that POST:

And we use it in our sign up flow:

The server creates the user’s account at that point (if necessary — the user might already be logged into an existing account using another authentication method). And it adds the passkey to the account.

Even a server break-in won’t compromise your passkey

By the way, we’ve just seen another bit of passkey cleverness. That is, the data in this response JSON isn’t sufficient for someone else to figure out your passkey and use it for themselves.

Passkeys rely on public key cryptography, where you have a private and public key. The private key is needed for authentication. The public key is there to allow you to prove that you have the private key without revealing it.

Only the public key gets sent to the server. So even if a bad guy broke into the server and stole all those public keys, they still couldn’t authenticate as you. They don’t have the private key, as it never left your device.

Contrast this with passwords where there has to be a shared secret. The reason I can authenticate with my password “abc123” is because the server has stored “abc123” in some form, and compares it to my input.

Public key cryptography is magic. 🪄🎩🐇

OK, now we have an account with a passkey. How do we authenticate next time?

Authenticating with a passkey

The process starts in the same way for authentication as it did for registration:

To start with, we need an “offer” from the server. This contains details of the credentials it’ll accept, and a challenge for us to sign using one of them:

The authentication options JSON looks like this:

{
  "rpId": "auth.tomcolvin.co.uk",
  "challenge": "nL_rWyPqXhvnyo-6_C8V7FaJITnDg6uUa2KWAlrJpEM",
  "allowCredentials": [
    {
      "id": "wsHlHo8rk1RjUpMZV4eLNw",
      "type": "public-key",
      "transports": [
        "hybrid",
        "internal"
      ]
    }
  ],
  "timeout": 60000,
  "userVerification": "preferred"
}

That challenge is all-important. In order to authenticate ourselves, we’ll have to sign it (together with some other bits) with our private key. The passkey server then knows it’s us because it has our public key to verify that signature.

And in order to get the private key, we have to ask the user for their biometrics and decrypt it out of the secure storage.

But we don’t have to worry about the complexity of any of the above! Because Credential Manager does everything we need, in just a single credentialManager.getCredential() call:

That code pops up the following screen:

The credential we get out of the code above has an authenticationResponse field. This is a JSON object containing the proof of our identity, and it’s what needs to go up to the server.

This article was previously published on proandroiddev.com.