WebAuthn is the standard for modern online authentication, combining high security with a simple and easy user experience. Replacing the password with WebAuthn has been a goal frequently stated, but difficult to realize for large deployments. The Yubico WebAuthn Starter Kit was created to provide an Adaptive Multi-Factor Authentication roadmap, simplifying the transition of users to a passwordless WebAuthn experience.
Prior to this project, a developer integrating WebAuthn into their identity provider ran into difficulties finding code examples and documentation that explain:
Step-by-step how to adopt WebAuthn and migrate users away from passwords.
WebAuthn credential management and lifecycle best practices.
We wanted to make this easier by describing an Adaptive Multi-Factor Authentication flow and providing a reference architecture you can try out and share with others.
The starter kit adds WebAuthn to the AWS Cognito identity provider by integrating Yubico’s java webauthn server library into Cognito’s user pool custom authentication flow. It hosts an example web app on AWS Amplify Console so that you can try out the Adaptive Multi-Factor Authentication flow.
The Yubico WebAuthn Starter kit is a project anyone can deploy on their own AWS account, providing a powerful tool for anyone looking to test a proof of concept for their organization, empowering them to deliver the vision and promise of WebAuthn with an end-to-end example of how to implement WebAuthn in their own services.
The Yubico WebAuthn Starter Kit is open source, with the source code freely available to be reviewed or referenced. The kit also includes install scripts for MacOS, Linux and Windows to make it simple to configure and deploy the reference architecture to your AWS account.
Requirements:
AWS account: A free tier account can be used, but the account holder will be charged a small amount for using a t2 small DB.
AWS CLI v2, configured to your AWS account
Once an instance of the Yubico WebAuthn Starter kit is deployed, it opens your default browser to the example web app so you can try out the Adaptive Multi-Factor Authentication flow on any modern browser supporting WebAuthn.
The Yubico WebAuthn Starter Kit features:
A reference architecture demonstrating an Adaptive Multi-Factor Authentication flow for migrating to WebAuthn from existing authentication methods
An AWS Lambda implementation of the Yubico Java WebAuthn Server libraries
Automated setup and deployment to AWS
Implementation of standard Authorization protocols for easy integration to existing services
Support for WebAuthn authentication using biometrics on both platform and roaming authenticators
Additionally, supporting documentation spanning from the high level architecture and concepts to the low level code details are provided to assist in providing context and deeper understanding.
Design and Concepts:
User Interface:
System Design:
Manual Installation and Troubleshooting:
I’m new to WebAuthn, where can I learn more?
Yubico has a wealth of resources for people looking to learn more about WebAuthn. People looking for a high level introduction can visit our What is WebAuthn? page, while developers looking for a deeper dive into WebAuthn can review our WebAuthn Overview.
Who is the WebAuthn Starter Kit designed for?
The WebAuthn Starter Kit was designed with architects and developers in mind, particularly those looking to run their own identity provider service and want their users to adopt WebAuthn. As a developer reference architecture, it is not for users looking for a turn key authentication solution similar to Azure AD, Okta, Ping, Duo and others.
Can I deploy my own instance of the WebAuthn Starter Kit?
Yes - see the Deploy Now section for the necessary prerequisites and to download the source code. Deployment to an AWS account is automated via a script and configuration file.
Will the WebAuthn Starter Kit work with WebAuthn Platform Authenticators or Biometric Authenticators?
The WebAuthn Starter Kit will work with any WebAuthn compliant authenticator, including YubiKeys, Platform Authenticators and Biometric Authenticators.
Is it possible to share my deployment of the WebAuthn Starter Kit with others?
Once deployed, your WebAuthn Starter Kit instance can be accessed by anyone using a WebAuthn supporting browser - no other prerequisites are necessary.
Can I deploy the WebAuthn Starter Kit in production?
The WebAuthn Starter Kit was designed to be a reference for integrating WebAuthn into new or existing sites and services, but was not intended to be used as is in a production environment. Contact Yubico if you are interested in Professional Services to help with your WebAuthn integration.
Is the WebAuthn Starter Kit free to deploy?
The AWS RDS database engine used by the WebAuthn Starter Kit only supports a minimum of db.t2.small, which is not part of the AWS Free Tier. Hence, the WebAuthn Starter Kit does incur a small charge for using Amazon RDS DB. To reduce the charges, the scaling capacity is reduced to one (1) and the AWS RDS database is set to pause after two (2) hours of inactivity. After the AWS RDS database has been paused after two hours of inactivity, there could be a cold start that may result in a failed WebAuthn registration and possibly also failed WebAuthn authentication. A simple retry will resolve the issue.