Setting up WebAuthn

There are two steps during a WebAuthn authentication flow, registration and authentication. The first step handles registering a WebAuthn device to a user. The second step handles the authentication attempt.

For both the registration and authentication steps, you’ll make two Stytch requests. The first request returns the necessary components to communicate with the WebAuthn device. The second request is used to pass the response from the WebAuthn call back to Stytch for verification.

We’ll be using the webauthn-json library to assist this integration. This library converts the JSON request into the correct data types by unmarshalling and decoding the body and then outputs marshalled JSON that you can pass back to Stytch.

If you get stuck while working through this guide, feel free to ask questions in our forum, via support@stytch.com, or in our Slack community.

Step 1: Create Stytch User

If the user attempting to register isn't associated with a Stytch user ID, you'll have to add them with Stytch's /v1/users/create endpoint if you haven't already. Pass the user's email address or phone number and store the returned user_id. The user_id will be used to register and authenticate with WebAuthn.

curl --request POST \
  --url https://test.stytch.com/v1/users \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "sandbox@stytch.com"
  }'

Step 2: Start Registration Process

To authenticate with WebAuthn, you first need to register an authenticator. This will have to happen once per registration. Start by generating the request needed for webauthn-json's create call. To do this you'll make a request to /v1/webauthn/register/start. You need two fields for the request, a Stytch user_id and the domain where the webauthn-json's create call will be invoked, i.e. your login page's domain. There are two optional fields, user_agent and authenticator_type. You can pass a user_agent to help identify the WebAuthn registration. This could be helpful for telling registrations apart. You can use authenticator_type to require a certain type of WebAuthn device, either platform (like a fingerprint reader) or cross-platform (like a YubiKey). If you omit the field, we'll assume either type is acceptable.

curl --request POST \
  --url https://test.stytch.com/v1/webauthn/register/start \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
      "domain": "example.com"
  }'

Step 3: Calling webauthn-json's Create Method

Within the browser, using the public_key_credential_creation_options field from the /v1/webauthn/register/start response, call webauthn-json's create method. You'll want to handle any errors that crop up in this step, like if there are no WebAuthn devices available to register. If the WebAuthn call is successful, JSON.stringify the response and get ready for another Stytch call.

// Note this code runs on the browser (frontend)
import * as webauthnJson from '@github/webauthn-json';

// You implemented this in Step 2
const registerStartData = await callWebauthnRegisterStart()
const credential = await webauthnJson.create({
  publicKey: registerStartData.public_key_credential_creation_options
});
// And you'll implement this in Step 4
await callWebauthnRegister({
  public_key_credential: JSON.stringify(credential)
})

Step 4: Register the WebAuthn Registration with Stytch

Next we'll use the JSON string you created in Step 3 as the public_key_credential in our request to /v1/webauthn/register. Stytch will validate the credential and return the webauthn_registration_id if the registration is successful. The user now has a registered WebAuthn registration that can be used for authentication. We recommend saving the webauthn_registration_id and domain. This allows you to check that the user in question has a valid WebAuthn registration on file with Stytch before you call /v1/webauthn/authenticate/start for subsequent logins.

curl --request POST \
  --url https://test.stytch.com/v1/webauthn/register \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
      "public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiaFladExOVDlTSWdacVBuS2ZiblFYM25DSjdOYXZUVF9TNm9DOVhSRVl2MEYiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEYwRAIgLEvyXrb_aMCVOjpYBLpm3cPaaquDN0ouXaL27SF9Lp0CIB2f56tWUDvs6oBl3pMxIIrJqJhZKkK7btJtWVDLsFFbaGF1dGhEYXRhWP5Jlg3liA6MaHQ0Fw9kdmBbj-SuuaKGMseZXPO6gx2XY0VheZqwrc4AAjW8xgpkiwsl8fBVAwB6Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlalAQIDJiABIVggFCI-4HODPxlfeBwfFyzQG_btRm_pB6mb9E1E-rANMwoiWCBCr6C2SQOGElh9N9OMzVBcMnOolAcvz3S0STbnNTHOmg\"},\"clientExtensionResults\":{}}"
  }'

Step 5: Start Authentication Process

Similar to registering, authentication starts by generating the request for the webauthn-json's get method. To do this you'll make a request to /v1/webauthn/authenticate/start. You need two fields for the request, the user_id of the user and the domain the WebAuthn call will be invoked on.

curl --request POST \
  --url https://test.stytch.com/v1/webauthn/authenticate/start \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
      "domain": "example.com"
  }'

Step 6: Calling webauthn-json's Get Method

Within the browser, using the public_key_credential_request_options field from the /v1/webauthn/authenticate/start response, call webauthn-json's get method. Again, you'll want to handle any errors that might arise here. If webauthn-json's get call is successful, JSON.stringify the response and get ready for another Stytch call.

// Note this code runs on the browser (frontend)
import * as webauthnJson from '@github/webauthn-json';

// You implemented this in Step 5
const authenticationStartData = await callWebauthnAuthenticateStart()
const credential = await webauthnJson.get({
  publicKey: authenticationStartData.public_key_credential_request_options
});
// And you'll implement this in Step 7
await callWebauthnAuthenticate({
  public_key_credential: JSON.stringify(credential)
})

Step 7: Authenticate the WebAuthn Registration with Stytch

Using the JSON string you created from webauthn-json's get method as the public_key_credential, make a request to /v1/webauthn/authenticate. Stytch will perform validation on the passed credential and return a 400 if there are any issues. If the authentication is successful, we'll return a 200.

curl --request POST \
  --url https://test.stytch.com/v1/webauthn/authenticate \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"authenticatorData\":\"SZYN5YgOjGh7NBcPZHZgW1_krrmihjLHmVzzuoNcl2MFYZKokg\",\"clientDataJSON\":\"eyJ2eXBlOjopo2ViYBx0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWEtEWDVJa25EWEU3by1KQlRkYTNfS1NiTXdmb3dMWDQxMldlNEFDY04tYWgiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"signature\":\"MEYCIQDU1FGXEBrq3hsQ2ye1pBcYLMu7zmzLVVdcbs6R21hGyAIhAJmpdBo2Hd7P4Ks9VFKBUYbKSIioMdhl2XIIjWHNKD77\",\"userHandle\":\"dXNlus1kZXZlbG9wLBC2M2E1MGI0LWEwMGEtNGU3NC89NTJmLTFlOGRhODE2nDBnMw\"},\"clientExtensionResults\":{}}"
  }'

Step 8: You're Done!

You just finished all the critical components to authenticate your users via WebAuthn! Have any feedback after having integrated WebAuthn? Get in touch with us and tell us what you think in our forum, support@stytch.com, or in our community Slack.