Developer Tutorial: WebAuthn for Web & FIDO2 for Android

Developer Tutorial:
WebAuthn for Web &
FIDO2 for Android
Christiaan Brand, Product Manager: Identity &
Security, Google
1
All Rights Reserved • FIDO Alliance • Copyright 2019

All Rights Reserved • FIDO Alliance • Copyright 2019 2
codelabs.developers.google.com/codelabs/webauthn-reauth/
Codelab 1: Your First WebAuthn

1. Introduction
3
What is WebAuthn? What is FIDO2?
The FIDO2 / WebAuthn allows you to create and use strong, attested public key based credentials for the purpose of authenticating users.
The API supports the use of BLE, NFC, and USB roaming authenticators (security keys) as well as a platform authenticator, which allows the
user to authenticate using their fingerprint or screenlock.
What you'll build...
In this codelab, you are going to build a website with a simple re-authentication functionality using fingerprint sensor. Re-authentication is a
concept where a user signs into a website once, then authenticate again as they try to enter important sections of the website, or come back
after a certain interval, etc in order to protect the account.
What you'll learn...
You will learn how to call the WebAuthn API and options you can provide in order to cater various occasions. You will also learn re-auth
specific best practices and tricks.
Note: In this codelab, you won't learn how to build a FIDO server.
What you'll need...
• Hardware (one of following)
• Android device with a fingerprint sensor (even without a fingerprint sensor, screenlock can provide equivalent user verification
functionality)
• Touch ID enabled MacBook Pro / Air
• Windows 10 (Build 1903 or later) with Windows Hello
• Browser
• Google Chrome (Or any other browsers supporting WebAuthn)

2. Getting Set Up
4
To work on this codelab, we'll be using a service called glitch. This is where you can edit both client and server side code
using JavaScript and deploy them instantly. Head to the following URL: https://glitch.com/edit/#!/webauthn-codelab-start
See how it works at the beginning
Let's see the initial state of the website first. Click "Show" at the top and press "Next to The Code" to see the live website
side by side.
1. Enter a username and submit (no registration is required, any username will create a new account)
2. Enter a password and submit (password will be ignored and user will be authenticated nevertheless)
3. User lands at home page. Clicking "Sign out" will sign you out. Clicking "Try reauth" sends you back to 2.
What are we going to implement?
1. Let users register a "user verifying platform authenticator" (the Android phone with fingerprint sensor itself can act as
one).
2. Let users re-authenticate themselves to the app using their fingerprint.
You can preview what you are going to build from here.
Remix the code
In https://glitch.com/edit/#!/webauthn-codelab-start find "Remix to Edit" button at the top right corner. By pressing the
button, you can "fork" the glitch and continue with your own version of the project with a new URL.

3. Register a credential using a fingerprint
5
You first need to register a credential generated by a user verifying platform authenticator - an authenticator
that is embedded onto the platform and verifies the user identity using biometrics or screenlock.
We are adding this feature to the
/home page.

Create registerCredential()function
Let's create a function called registerCredential() which registers a credential using a fingerprint.

Feature detection
Now, let's add WebAuthn code. First thing you should do is to detect whether WebAuthn is available. We can achieve this
by examining if window.PublicKeyCredential exists. We'll throw an exception if the feature is not available.
Is User Verifying Platform Authenticator available?
Re-auth is most useful when the authenticator is a user verifying platform authenticator and that is what we will use.
There's a handy function that can detect if there is a user verifying platform authenticator available called
PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(). If it's not available, throw an exception.

Obtain the challenge and other option from server endpoint:
/auth/registerRequest
Before asking the user to provide a credential using fingerprint, ask the server to send back a challenge
and other parameters. Call _fetch()with opts as an argument to send a POST request to the server.

Here's an example options you will be receiving
(aligns with PublicKeyCredentialCreationOptions).
To learn about these options, see the official specification of the WebAuthn. Some
important ones are explained at "Register a credential" section in the next page.

Create a credential
Because these options are delivered encoded in order to go through HTTP protocol, you have to convert some parameters
back to binary - specifically, user.id, challenge and id s included in excludeCredentials array:
And finally call the navigator.credentials.create() method in order to create a new credential. With this call,
the browser will interact with the authenticator and tries to verify the user's identity using a fingerprint sensor or a
screenlock.

Once the user verifies their identity, you should be receiving a credential object you can send to the server and register
the authenticator.

Register the credential to the server endpoint: /auth/registerResponse
Here’s an example credential object you should have received.
Like when you received an option object for registering a credential, you should encode the binary parameters of the credential
so that it can be delivered to the server as a string.

Store the credential id locally so that we can use it for authentication when the user comes back.
Finally, send the object to the server and if it returns HTTP code 200, consider the new credential has
been successfully registered.
Congratulations, you now have the complete registerCredential()function!

4. Build the UI to register, get and remove
credentials
14
It will be nice to have a list of registered credentials along with buttons to remove them.
Build UI placeholder
Let's add UI to list credentials and a button to register a new credential. ul#list will be the placeholder for
adding a list of registered credentials

Get a list of credentials and display: getCredentials()
Let's create getCredentials()function so you can get registered credentials and display them in a list. Luckily, we
already have a handy endpoint on the server /auth/getKeys which you can fetch registered credentials for the signed-
in user.
The returned JSON includes credential information such as id and publicKey. By building HTML you can show them to the
user.

Note: We are using a library called "lit-html" for handy template building. See lit-html project page
to learn more, if you are interested.
Let's display available credentials as soon as user lands on /home by invoking
getCredentials().

Remove the credential: removeCredential()
In the list of credentials, you have added a button to remove each credential. By sending a request
to /auth/removeKey along with credId query parameter, you can remove them.

Register a credential
Finally, call registerCredential()to register a new credential when (+) button is clicked. Don't forget to
renew the credential list by calling getCredentials()after registration.
Import registerCredential from client.js we created earlier:

Following is important options to remember to pass in
registerCredential()(PublicKeyCredentialCreationOptions we referred earlier).

attestation Preference for attestation conveyance (none, indirect or
direct). Choose none unless you need one.
excludeCredentials Array of credential descriptors so that the authenticator can
avoid creating duplicate ones.
authenticatorSelection authenticatorAttachment Filter available authenticators. If you want
an authenticator attached to the device,
use "platform". For roaming
authenticators, use "cross-platform".
requireResidentKey Use true if the created credential should
be available for future "account picker"
UX.
userVerification Determine whether authenticator local
user verification is "required", "preferred"
or "discouraged". If you want fingerprint or
screenlock auth happen, use "required".

5. Authenticate the user with a fingerprint
21
We now have a credential registered and ready to use it as a way to authenticate the user. Let's add re-auth functionality
to the website. Here's the user experience:
As soon as a user lands on /reauth, the website asks for re-auth using a fingerprint. When the user succeeds to
authenticate, forward the user to /home, otherwise fallback to use the existing form to enter and submit a password.

Create authenticate() function:
Let's create a function called authenticate()which verifies user identity using a fingerprint. We'll be adding JavaScript code here.
Feature detection and User Verifying Platform Authenticator check
We can replicate the same behavior we did on registration.

Obtain the challenge and other options from server endpoint: /auth/signinRequest
Before authenticating, let's examine if the user has a stored credential id and set it as a query param if they do. By
providing a credential id along with other options, the server can provide relevant allowCredentials and this will make
user verification reliable.

Before asking the user to authenticate, ask the server to send back a challenge and other parameters. Call _fetch()with opts as an
argument to send a POST request to the server.
Here's an example options you should be receiving (aligns with PublicKeyCredentialRequestOptions).

Note: To learn about these options, see the official specification of the WebAuthn.

Locally verify the user and get a credential
Because these options are delivered encoded in order to go through HTTP protocol, you have to convert some parameters
back to binary - specifically, challenge and ids included in allowCredentials array:

Once the user verifies their identity, you should be
receiving a credential object you can send to the server
and authenticate the user.

Verify the user identity: /auth/signinResponse
Here's an example credential object you should have received.
Again, encode the binary parameters of the credential so that it can be delivered to the server as a string.

Finally, send the object to the server and if it returns HTTP code 200, consider the user has been successfully
signed-in.
Congratulations, you now have the complete authencation()function!
Don't forget to store the credential id locally so that we can use it for authentication when the
user comes back.

6. Enable reauth experience
31
To enable the reauth step, all you need is to run the authentication()as soon as user lands /reauth.
Import authenticate from client.js we created earlier.
Invoke authenticate()immediately.

7. Congratulations!
32
You have successfully finished the codelab - Your first WebAuthn.
What you’ve learned
• How to register a credential using a user verifying platform authenticator.
• How to authenticate a user using a registered authenticator.
• Available options for registering a new authenticator.
• UX best practices for reauth using a biometric sensor.
Next step
• Learn how to build similar experience in Android native app using FIDO2 API.
• Learn how to associate a website and an Android app and share credentials between them using the
Digital Asset Links.
You can learn both by trying out the Your first Android FIDO2 API codelab!

Resources
• WebAuthn specification
• Introduction to WebAuthn API
• FIDO WebAuthn Workshop
• WebAuthn Guide: DUOSEC
Special thanks to Yuriy Ackermann from FIDO Alliance for your help.

Codelab 2: Your First Android FIDO2 API
https://codelabs.developers.google.com/codelabs/fido2-for-android/#0

Introduction
35
What is the FIDO2 API?
The FIDO2 API allows Android applications to create and use strong, attested public key-based credentials for the purpose of
authenticating users. The API provides a WebAuthn Client implementation, which supports the use of BLE, NFC, and USB roaming
authenticators (security keys) as well as a platform authenticator, which allows the user to authenticate using their fingerprint or
screenlock.
What you'll build...
In this codelab, you are going to build an Android app with a simple re-authentication functionality using fingerprint sensor. "Re-
authentication" is a concept where user signs into an app once, then authenticate again when they come back to your app, or
trying to access an important section of your app.
What you'll learn...
You will learn how to call the Android FIDO2 API and options you can provide in order to cater various occasions. You will also
learn re-auth specific best practices.
Note: In this codelab, you won't learn how to build a FIDO server.
What you'll need...
Android device with a fingerprint sensor (even without a fingerprint sensor, screenlock can provide equivalent user verification
functionality)
Android OS 7.0 or later with latest updates. Make sure to register a fingerprint (or screenlock).

2. Getting Setup
36
Clone the Repository
Check out the GitHub repository.
https://github.com/googlecodelabs/fido2-codelab
What are we going to implement?
• Let users register a "user verifying platform authenticator" (the Android phone with fingerprint sensor itself will act as one).
• Let users re-authenticate themselves to the app using their fingerprint.
You can preview what you are going to build from here.
Start your codelab project
The completed app sends requests to a server at https://webauthn-codelab.glitch.me. You may try web version of the same app
there.

You are going to work on your own version of the app.
1. Go to the edit page of the website at https://glitch.com/edit/#!/webauthn-codelab.
2. Find "Remix to Edit" button at the top right corner. By pressing the button, you can "fork" the code and continue with
your own version along with a new project URL.
3. Copy the project name on top left (you may modify it as you want).

4. Paste it to the .env file's HOSTNAME section in glitch.

3. Associate your app and a website with
the Digital Asset Links
39
To use FIDO2 API on an Android app, associate it with a website and share credentials between them. To do so, leverage
the Digital Asset Links. You can declare associations by hosting a Digital Asset Links JSON file on your website, and adding
a link to the Digital Asset Link file to your app's manifest.
Host .well-known/assetlinks.json at your domain
You can define an association between your app and the website by creating a JSON file and put it at .well-
known/assetlinks.json. Luckily, we have a server code that displays assetlinks.json file automatically, just by
adding following environment params to the .env file in glitch:
• ANDROID_PACKAGENAME: Package name of your app (com.example.android.fido2)
• ANDROID_SHA256HASH: SHA256 Hash of your signing certificate
In order to get the SHA256 hash of your developer signing certificate, use the command below. The default password of
the debug keystore is "android".

By accessing https://<your-project-name>.glitch.me/.well-known/assetlinks.json, you
should see a JSON string like this:

Open the project in Android Studio
Click "Open an existing Android Studio project" on the welcome screen of Android Studio.
Choose the "android" folder inside the repository check out.

Associate the app with your remix
Open gradle.properties file. At the bottom of the file, change the host URL to the Glitch remix you just
created.
At this point, your Digital Asset Links configuration should be all set.

4. See how the app works now
43
Let's start by checking out how the app works now. Make sure to select "app-start" in the run configuration combobox. Click "Run" (the
green triangular next to the combobox) to launch the app on your connected Android device.
When you launch the app you'll see the screen to type your username. This is UsernameFragment. For the purpose of demonstration,
the app and the server accept any username. Just type something and press "Next".

The next screen you see is AuthFragment. This is where the user can sign in with a password. We will later add a feature to sign in with
FIDO2 here. Again, for the purpose of demonstration the app and the server accept any password. Just type something and press "Sign In".

This is the last screen of this app, HomeFragment. For now, you only see an empty list of credentials here. Pressing "Reauth" takes you back
to AuthFragment. Pressing "Sign Out" takes you back to UsernameFragment. The floating action button with "+" sign doesn't do anything
now, but it will initiate registration of a new credential once you have implemented the FIDO2 registration flow.

Before starting to code, here's a useful technique. On Android Studio, press "TODO" at the bottom. It will show a list of all
the TODOs in this codelab. We'll start with the first TODO in the next section.

5. Register a credential using a fingerprint
47
In order to enable authentication using a fingerprint, you'll first need to register a credential generated by a user verifying platform
authenticator - a device-embedded authenticator that verifies the user using biometrics, such as a fingerprint sensor.
As we have seen in the previous section, the floating action
button doesn't do anything now. Let's see how we can register
a new credential.

Call the server API: /auth/registerRequest
Open AuthRepository.kt and find TODO(1).
Here, registerRequest is the method that is called when the FAB is pressed. We'd like to make this
method call the server API /auth/registerRequest. The API returns all the
PublicKeyCredentialCreationOptions that the client needs to generate a new credential. It also
returns a challenge as a string. We need this for a subsequent API call of /auth/registerResponse, so let's
save this in a local property.
We can then call getRegisterIntent with said options. This FIDO2 API returns an Android Intent to open a
fingerprint dialog and generate a new credential.
Now we have the Intent, all we have to do is to pass it back to our UI so it can proceed to show the
fingerprint dialog. The method returns a MutableLiveData. We can simply post the Intent as the
LiveData’s value.

The method will then look like something below.

Open the fingerprint dialog for registration
Open HomeFragment.kt and find TODO(2).
This is where the UI gets the Intent back from our AuthRepository. The returned object has a convenient method
called launchPendingIntent. Calling it will open a dialog for credential generation.

Call the server API: /auth/registerResponse
This registerReponse method is called after the UI successfully generated a new credential. The parameter data has all the information about
this new credential. We want to send it back to the server.
First, we have to extract an AuthenticatorAttestationResponse from the data. The data Intent has an extra field of byte array with the key
Fido.FIDO2_KEY_RESPONSE_EXTRA. You can use a static method in AuthenticatorAttestationResponse called deserializeFromBytes to
turn the byte array into an AuthenticatorAttestationResponse object.
The AuthenticatorAttestationResponse object has information about the newly generated credential inside. We now want to remember the
ID of our local key so we can distinguish it from other keys registered on the server. In the AuthenticatorAttestationResponse object, take
its keyHandle property and save it in a local string variable as using toBase64.
Now we are ready to send the information to the server. Use api.registerReponse to call the server API and send the token, the challenge
string and the response. The returned value is a list of all the credentials registered on the server, including the new one.
Finally, we can save the results in our SharedPreferences. The list of credentials should be saved with the key PREF_CREDENTIALS as a
StringSet. You can use toStringSet to convert the list of credentials into a StringSet.
In addition, we save the credential ID with the key PREF_LOCAL_CREDENTIAL_ID.

Run the app, and you will be able to click on the FAB and register a new credential.

6. Authenticate the user with a fingerprint
54
We now have a credential registered on the app and the server. We can now use it to let the user sign in. We are adding
fingerprint sign-in feature to AuthFragment. When a user lands on it, it shows a fingerprint dialog. When the
authentication succeeds, the user to redirected to HomeFragment.
Call the server API: /auth/signinRequest
This signinRequest method is called when AuthFragment is opened. Here, we want to request the server and see if we
can let the user sign in with FIDO2.
First, we have to retrieve PublicKeyCredentialRequestOptions from the server. Use api.signInRequest to
call the server API. It returns two values, PublicKeyCredentialRequestOptions and a challenge string. We will use
the challenge string later, so let's save it in a property.
With the PublicKeyCredentialRequestOptions, we can use FIDO2 API getSignIntent to create an Intent to
open the fingerprint dialog.
Finally, we can pass the Intent back to the UI.

Open the fingerprint dialog for assertion
Open AuthFragment.kt and find TODO(5).
This is pretty much the same as what we did for registration. We can launch the fingerprint dialog with the
launchPendingIntent method.

Call the server API: /auth/signinResponse
First, we have to extract an AuthenticatorAssertionResponse from the method parameter data. You can use
AuthenticatorAssertionResponse.deserializeFromBytes to convert the byte array extra stored in data with
the key Fido.FIDO2_KEY_RESPONSE_EXTRA.
The response object has a credential ID in it as keyHandle. Just like we did in the registration flow, let's save this in a
local string variable so we can store it later.
We are now ready to call the server API with api.signinResponse. It will return two values, a list of credentials, and a
sign-in token.
At this point, the sign-in is successful. We have to store all the results in our SharedPreferences. The sign-in token
should be stored as a string with key PREF_TOKEN. The list of credentials should be stored as StringSet with the key
PREF_CREDENTIALS. The local credential ID we saved above should be stored as a string with key
PREF_LOCAL_CREDENTIAL_ID.
Finally, we have to let the UI know that the sign-in has succeeded so that the user is redirected to the home screen. This
can be done by calling invokeSignInStateListeners. Pass SignInState.SignedIn as an argument.

Run the app and click on "Reauth" to open AuthFragment. You should now see a fingerprint dialog prompting you to sign in with
your fingerprint.
Congrats! You have now learned how to use FIDO2 API on Android for registration and sign-in.

7. Congratulations!
60
You have successfully finished the codelab - Your first Android FIDO2 API.
What you've learned
• How to register a credential using a user verifying platform authenticator.
• How to authenticate a user using a registered authenticator.
• Available options for registering a new authenticator.
• UX best practices for reauth using a biometric sensor.
Next step
• Learn how to build similar experience in a website.
You can learn it by trying out the Your first WebAuthn codelab!

Resources
• WebAuthn specification
• Introduction to WebAuthn API
• FIDO WebAuthn Workshop
• WebAuthn Guide: DUOSEC
Special thanks to Yuriy Ackermann from FIDO Alliance for your help.

Developer Tutorial: WebAuthn for Web & FIDO2 for Android

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a Developer Tutorial: WebAuthn for Web & FIDO2 for Android

Semelhante a Developer Tutorial: WebAuthn for Web & FIDO2 for Android (20)

Mais de FIDO Alliance

Mais de FIDO Alliance (20)

Último

Último (20)

Developer Tutorial: WebAuthn for Web & FIDO2 for Android