If you’re looking for a user-friendly and secure web authentication method, passkeys are the way to go. Learn how to implement two passkey flows using the Web Authentication API and explore the best practices for the process.

When it comes to authentication on the web, passwords are far from the best option, both in terms of security and user experience. Thankfully, there are also a number of passwordless options, like magic links and one-time passwords, and the one that is the focus of this article – passkeys.

In a previous article, we’ve provided a theoretical overview of passwordless authentication methods. This time, we will dive deeper into the code and explain how to implement two passkey authentication flows—the user registration flow and the login flow—by using the Web Authentication API specification.

Before we get into the Web Authentication API, it’s important to explain how passkeys work. A passkey is a credential, a public-private key pair generated by an authenticator, used to access the application. The private key is stored securely on the user’s device, while the public key is sent to the server. 

Most people already own and use the technology required for the passkey authentication process. For example, we could use a fingerprint reader or a facial recognition system like Apple’s Face ID or Android facial recognition. However, biometric authentication isn’t the only option for using passkeys. There are also software-based solutions like a browser profile, such as a Google Chrome browser profile.

This means that the fingerprint used for verification never leaves the platform, and it is not shared anywhere.

With passkeys, the server does not need to know who the user is specifically, just that they are the same person who created the account, which is verified on the platform itself. This means that the fingerprint used for verification never leaves the platform, and it is not shared anywhere.

A convenient feature is that passkeys can be synced across devices if you are using a large ecosystem like Apple’s (iCloud Keychain) or Google’s (Google Password Manager).

WebAuthn (short for Web Authentication API) is an extension of the Credential Management API. It is an API specification that enables applications to use strong and secure authentication methods and secure multi-factor authentication (MFA) without the need for verification via a text message. 

The WebAuthn API allows the end users to authenticate their identity using hardware or software-based authenticators, such as USB security keys or platform authenticators like fingerprint readers, instead of relying solely on passwords. 

To provide secure registration and authentication of accounts, these authenticators rely on public-key cryptography. The user has to associate an authenticator with their account, which generates a public-private key pair. 

This authentication method has a number of benefits, including:

The Web Authentication API is only available in secure contexts, meaning that the web application must use HTTPS. Using HTTPS means that the connection between the browser and the server is encrypted and secured using digital certificates. This is an industry standard and common practice nowadays.

The WebAuthn API uses two methods. To register new user credentials, we use the create method, while the get method is used to retrieve the credentials we created.

In line with this, the registration flow creates the user account with the credentials provided, and the login flow validates them.

To create a set of user credentials, we call the create method on the navigator.credentials object. The method requires a set of options, and one of them is the publicKey. Note that the credentials objects could also be created with the password option. This is usually used to implement automatic login into a web application.

Passwords are inherently flawed, both in terms of security and user experience. We present a range of passwordless authentication methods you can use to make your app secure and user-friendly. 

In today’s digital-first world, passwords are keys for unlocking the information you desire. A password is a single key shared between the user and the service. It is often the only thing hackers need to access user bank accounts, social media information, and other sensitive data. 

As the number of online services grows, remembering multiple complex passwords has become increasingly challenging, especially if you don’t use password managers.

Studies in recent years have shown that people are using passwords incorrectly. For example, IBM’s global survey found that 82% of respondents reused passwords at least once. Even worse, 21% reuse the same username and password for every new account. This poses a serious security risk. According to the Verizon Data Breach Investigations Report for 2024, stolen credentials account for a whopping 77% of basic web application attacks. 

Fortunately, passwords are not the only authentication solution out there. There is a range of passwordless authentication methods at our disposal, and the technology supporting them has been available for some time now.

In this article, we will discuss passwordless authentication solutions for the web, how to use them, their benefits and pitfalls, and how they improve security and user experience.

Authentication is the process of verifying that the user is who they claim to be. There are three common authentication factors:

When users register for a service, they usually need to provide a username or email address and a password. Identification occurs upon login, when a user enters a username/email address, and authentication occurs when users prove their identity with authentication factors. For example, users are authenticated when they provide their username and correct password. Permissions of the service are then granted based on their proven identity.

Two-factor authentication (2FA) or multi-factor authentication (MFA) is a process where the service checks for two or more authentication factors during the user authentication process. For example, along with the password, the user has to click on a link in an email or enter a one-time passcode received via a text message. Multi-factor authentication ensures that even if one factor is compromised, unauthorized access is still unlikely.

A password is secret data, typically a string of characters, usually used to confirm a user’s identity. Using passwords, in general, is not a bad concept. Implementing password-based authentication is fast and simple and gets the job done. 

However, fast and simple as it may be, using passwords as a single point of user authentication can be insecure. There are ways to improve password security, from validating the password’s length and character diversity to requiring special characters, for example. We can also scramble the password, for instance, by salting and peppering it upon saving it in the database. This modifies the password by adding a set of characters and encrypting it with a one-way function to make it unrecognizable and hard to decrypt. 

The second problem with password-based authentication is the people factor.

Even worse, if the leaked password is the same as the user’s email password, the hacker can access all services connected to that email. For example, they could request a password reset on all services connected to the user’s email and set a new password.

One way to prevent this is two-factor authentication, commonly known as 2FA. The first authentication factor is a password, and the second one can be email or text message confirmation, device authentication, or similar methods. This improves security, but the process is more complicated for the user.

We’ve concluded that password-based authentication is not the best option, either from a security or user experience standpoint. Fortunately, there are also passwordless authentication methods. Choosing which one to use will depend on the needs of the application you are building and whether you need to prioritize security or the user experience because one often comes at the expense of the other.

User authentication can be done through a third-party service provider, for example, by implementing the OAuth2 protocol. When a user requests authentication, they are redirected to the third-party service provider. The service provider performs the authentication, creating a session for the user.

This passwordless authentication method is simple to implement and simple to use from the user’s side. Its most common implementation is login via Google or Facebook. Using this approach removes the need to store the passwords on your server, as a third-party service handles that part, but in the end, the service still has to validate the user. 

One drawback of this passwordless method is user privacy concerns, as some users may not be happy with linking their Google or Facebook accounts to your application and sharing their data.

Magic links are a token-based passwordless authentication solution that uses a unique, time-sensitive URL, which provides a token to serve as a credential for user authentication. The magic link is sent to the user’s registered email or phone number. When a user clicks on a magic link, the embedded token is validated against the server to authenticate the user’s identity. This process, by design, eliminates the traditional risks associated with password-based authentication and simplifies the login experience.

Each magic link is a one-time authentication, somewhat similar to a one-time password (OTP). The major difference is that unlike OTP, where the user has to type in the password they received, with a magic link, they don’t need to input any information, as the token will be extracted from the link itself.

The magic link approach offers a solid passwordless experience. But is it safe? Magic links tend to be valid for a short period, meaning the attacker has only a small window of opportunity to intercept one. In essence, magic link authentication is as safe as the service the magic link is sent to, as that service performs the user authentication. If an attacker gets into that service, entering the service that uses magic links is as easy as re-login.

OTP or one-time passwords are mainly used as part of multi-factor authentication, not as a single authentication method. During the login flow, the user receives an email or text with a unique combination of characters called a one-time password. This authenticates the user for a single login session. In addition to email and texts, there is a third option – authenticator apps like Google Authenticator, Microsoft Authenticator, and various others.

This likely won’t present much of an issue for an average user, but can become very challenging for an elderly person or someone with a disability. In any case,  it is always good practice to allow users to paste the copied one-time password into the application.

The security and user experience of this method can be slightly improved by implementing WebOTP API – an extension of Credential Management API. The WebOTP API provides a streamlined user experience for web apps to verify that a phone number belongs to a user when using it as a sign-in factor. The downside is that the support is not available across all major browsers, so some users will not have access to this user experience enhancement.

The flow is straightforward – a user enters a username, email, or phone number used for the service, and then they receive the one-time password via email or text, which serves as an additional authentication factor. With an authenticator app, the user needs to open the app on the linked device and enter the OTP into the login form, which is then sent to the server for verification.

In the case of WebOTP API, if the text message is formatted in a defined way, the browsers that support this can automatically prompt the user to enter the one-time password into the login flow. The security is slightly improved with WebOTP API as the domain part will render phishing attacks impossible since the OTP is tied to the domain.

Passkeys are the beginning of the end of passwords. They are the most secure way of user authentication and provide a seamless experience – a significant step toward a passwordless future. Most people already own and use the technology that can be used for authentication through passkeys. For example, this would be a fingerprint reader or a facial recognition system like Apple’s Face ID or Android facial recognition. Another example is software-based solutions like a browser profile, such as a Google Chrome browser profile.

During the registration process, the user associates the public key with the account, and upon login, the public key is verified against the user’s private key on the platform authenticator.

The perspective in this passwordless solution is that the server does not need to know who the user is specifically, just that they are the same one who created the account, and that part is verified on the platform itself. This means that the fingerprint used for verifying the user in the authentication process never leaves the platform, and it is not shared anywhere.

What happens if I lose or replace the device that contains my passkey credential? Since passkeys are tied to a single device, users need to register multiple devices to ensure access to the application if one of them gets terminated. This can pose a user experience problem, as now the user has to own and register multiple devices.

Here is where large platforms and operating systems come into the picture. They use their own secure channels to sync passkeys across multiple user devices in the background, making them available across all of the user’s compatible devices. 

For example, Apple uses its iCloud Keychain, and Google uses Google Password Manager. The downside to this passwordless experience is vendor lock-in because it is complicated to move out of a company’s ecosystem if you decide to make a switch. Moving to another passkey manager would require changing all passkeys on all services.

WebAuthn (short for Web Authentication API) provides a passwordless authentication method using hardware or software-based authenticators like USB security keys or fingerprint readers. An extension of the Credential Management API, it can provide your users with a more secure and user-friendly authentication process. 

The API specification enables applications to use strong and secure authentication methods for user registration and the login process. It enables passwordless authentication and secure multi-factor authentication (MFA) without needing a text or an authenticator application. 

These authenticators rely on public-key cryptography to provide secure registration and authentication of accounts. To achieve this, the user has to complete a sequence of steps to associate an authenticator device with their account, which generates a public-private key pair. Using this way of passwordless authentication, by nature, has some benefits:

The key concept in understanding passkeys is public-key cryptography or asymmetric cryptography. We can explain this simply with a color-mixing analogy. When you mix two colors, you get a new color. However, guessing the exact colors that created the new one is nearly impossible.

Complementary colors are pairs of colors that, when combined or mixed, cancel each other out (lose hue) by producing a grayscale color like white or black. For this example, we will use a color mixer that produces a complementary color of the starting one. In this example, we assume that mixing colors is a one-way function as it is fast to mix colors and output a third color, and it is much slower to undo.

Let’s say two parties, Alice and Bob, want to start an encrypted conversation. Alice starts by selecting a color: red.

Step 1: Alice mixes the private red color with the color mixer to create a complementary color—cyan. She then sends the cyan to Bob.

How do you debug when you can’t seem to catch the bug? During our work, we came across a complex issue involving CORS, cache invalidation, and naming – a rare find in frontend development. We present our path to the solution. 

Debugging software issues can be both challenging and rewarding. However, when not done systematically, it is easy to lose yourself in the maze of errors, symptoms, and possible solutions. 

Sometimes, tracking that one elusive issue can make an engineer feel like they should consider a career switch to forensics. The story we’re about to share is a perfect example of this – a real-world debugging experience that revolved around one frustrating CORS (Cross-Origin Resource Sharing) issue. 

The idea is to demonstrate the thought process and methods used to identify and ultimately resolve the problem. Whether you are new to frontend development or an experienced senior, there’s something to learn from this journey.

To follow this story, it’s important first to understand what CORS is and what’s its purpose.

Cross-Origin Resource Sharing (CORS) is a security feature implemented by web browsers to restrict web pages from making requests to a different domain than the one that served the original web page. It is a set of HTTP headers that allows or denies web browsers to execute cross-origin requests based on the policy defined by the server. 

CORS is crucial for web security and helps prevent potential security vulnerabilities, such as cross-site request forgery (CSRF) and cross-site scripting (XSS).

With the theoretical part covered, we can delve into the issue. 

During our project work, we were developing a content management application for a client. The application also includes an image editor, used for attaching an image to the content. On the image editor page, users are able to select one of the previously uploaded images for additional editing, for example, cropping. The selection is made by fetching the image via the fetch method, and the image is used to populate the canvas element later on.

This was the part of the app that contained a bug.

It all started with a user report stating that the image could not be selected. When something like this happens, the first thing to do is to check the error monitoring system for errors. In our case, the logs were showing a CORS error. 

This is where the real mystery began, as our app had been up and running for some time, and the CORS should not have been the problem. At least, that is what we thought.

After not being able to reproduce the issue in an isolated environment, we jumped into the production environment to examine the issue. A perplexing challenge presented itself – the bug was not reproducible. 

Everything appeared to work fine from the developer’s standpoint; the problem couldn’t be reproduced by us or the user anymore. Nevertheless, the issue persisted, and it resurfaced a week later, leaving both the user and us baffled.

A key breakthrough came through the process of asking questions and retrieving user feedback combined with thorough testing. 

Reaching out to users is always a great idea. Only when we attempted to replicate the entire workflow fully did the error finally surface. We discovered that the error occurred only after the user completed a series of specific steps. The end result was the error present in our console:

After defining the right steps to reproduce the bug in an isolated environment, the key thing to learn is the minimal set of steps that lead to the bug. 

When we eliminated all of the unnecessary steps, the bug was revealed. It was reproducible if the user viewed the image somewhere in the app before selecting it in the image editor.

Knowing that the prerequisite for reproducing the bug was viewing the image before selection, the next step was to jump into developer tools, the network tab, and examine the requests leading to the bug. How was it possible that the image that we were displaying suddenly broke CORS?

When we were inspecting the request that failed with the CORS error, one thing stood out – the “Provisional headers are shown” warning message in the developer console. This meant that the browser returned the request from the cache instead of creating a new request.

The question now was – how come the request returned from the cache did not trigger the CORS issue upon the initial request? We tried disabling the cache to see if the issue was still reproducible, and you can probably already guess it – it wasn’t.

The key revelation was that the response headers differed when fetching the image via an image tag:

As compared to using JavaScript via a fetch method:

Notably, the

header was absent in responses when fetched via an image tag.

This disparity in response headers meant that when an image was initially rendered on the UI and subsequently fetched via JavaScript, it became cached with the response header:

This indicated a cache duration of one year. When a JavaScript fetch call attempted to access the cached image, the missing

header triggered the CORS error.

In the world of software development, cache invalidation is usually tricky to handle. There are multiple ways of solving this problem. Let’s go through some of them.

If headers for the fetch method for fetching the image via JavaScript were updated to contain Cache: no store, the problem would be resolved. The same result would be accomplished by adding a timestamp as a query parameter to the request. However, this method comes with a downside – this request would never be cached, meaning that the next time the app fetches an image like this, the request would also be sent to the backend, even if the valid request is already present in the cache.

The more correct approach would be to implement a query parameter that is constantly the same. This brings us to another complex issue in the development world – naming. How to name such a parameter? For example, adding provisional: true to the request from fetch would ignore the cache for the first time but would return the cached request every other time.

The best approach requires some server setup, or to be exact, the ability to add specific response headers. This approach includes adding a header to the response:

This way, the browser knows when to ignore the cached request. The Vary header tells the browser that the requests may vary depending on the value that you set in the header.

For example, the request that originates from an image tag will have the Accept header value set to image/avif, image/webp, image/apng, image/svg+xml…, and if you’re using fetch, you can set the value to image/jpeg. Based on that, the browser will cache the request depending on the URL and the value of the Accept header.

In our example, we went with the addition of a query parameter:

We decided on this approach because we were using an Amazon S3 bucket for serving the images, and Vary is not a user-configurable header. A different file storage service might allow setting the Vary response header. If it does, that would be the preferred solution.

As the first letter in REST (representational state transfer) implies, the requested resource can be represented in many different ways. The same API endpoint can return a different representation of the same resource, depending on the way the resource is requested. 

In our example, the same image was returned as content, but REST allows for much more. For example, the image can be requested with different values in the Accept header, like image/png or image/webp, and the API should then be able to return the image in other formats.

One of the common uses of the Content Negotiation principle is to apply the Accept-language header based on which the resource will be translated. Some browsers will send this header by default, filled with the value from the browser settings. The Vary header also plays a role in this, as we’ve seen in the example provided.

This debugging journey teaches us the importance of thorough investigation, asking the right questions, and understanding the intricacies of the technologies we work with. 

Mysterious issues can be tricky, but with patience and persistence, combined with a systematic debugging approach, they can be overcome. This at least applies to the CORS and cache issues. The naming will always be tricky.

In the fast-paced world of software development, it’s easy to overlook the importance of documentation. Many developers view it as a tedious and time-consuming task, but the truth is, documentation is critical to the success of any project.

If you want to build great digital products, your documentation needs to follow suit. Without proper documentation, projects can quickly spiral out of control, leading to missed deadlines, increased costs, and frustrated stakeholders.

In this article we take you through the most common types of documentation, explain how taking the time to document your work actually saves time and money in the long run, and provide tips for mastering the art of documentation writing. Should you lean on AI assistants for help? We tackle that question too.

Let’s get documenting.

Many developers view documentation as a chore, something that takes away from the more exciting and challenging work of writing code. They may feel that documentation is a distraction from the creative and technical aspects of software development, or that it doesn’t directly contribute to the functionality of the software. However, this mindset is short-sighted and ultimately leads to more problems down the road.

Documentation serves as a roadmap for the development process, providing clear and concise information about how a project is intended to work and how it was implemented. This information is essential for maintaining and updating the software over time, as well as for onboarding new team members. Good documentation helps to ensure that everyone is on the same page, reducing the risk of misunderstandings and errors.

In addition, documentation helps to improve the overall quality of software. By providing clear and detailed information about the design and implementation of software, developers can more easily identify and resolve issues, resulting in a better and more reliable product.

When referring to documentation, most of the time people will think about the most commonly used types – code documentation or API documentation. But in fact, there are multiple types of documentation in the world of software development, and other variants can also be crucial for project scalability and maintainability. 

Let’s look at a few of the most common types of documentation.

Process documentation refers to documentation that outlines the various steps and procedures involved in completing a specific task or process. This can include anything from onboarding new people to the project to creating a marketing campaign. Process documentation helps to ensure consistency and efficiency in completing tasks, and can be used as a reference for training new people.

It’s the type of documentation that provides information about the code itself, including variables, functions, and classes. This type of documentation typically includes comments within the code itself, as well as separate documentation files like API documentation.

Well-written end-to-end, integration, and unit tests can also be considered code documentation, as they are executable and verifiable documentation that can be read as if you were reading system requirements.

The bare minimum for code documentation is a readme file that contains information about how to run the project, and how to contribute to it. Contribution guidelines might include things like information on coding standards and branching/release processes.

This type of documentation is a combination of process and code documentation. Having a general overview of how the whole project works is very important. Architectural changes may occur in the project’s lifecycle, and it is important that they are documented, as the context behind some decisions may also change over time.

User documentation refers to documentation that is intended for end-users of a product or service. This can include user manuals, online help files, or tutorials. User documentation guides users to use the product or service effectively, reducing the risk of errors or confusion and improving overall user satisfaction.

There are multiple real-life scenarios where clear and detailed documentation saves time, and with that money. One of the most common examples is onboarding new developers to the project. With clear and detailed project documentation, new developers need less time for project onboarding, as the documentation includes not only the project setup, but also explains the processes involved. 

For example, documentation for onboarding a new developer will include notes from meetings with project managers, definitions relevant for certain tasks, notes from meetings with other developers to provide technical support for project installation, release process documentation, and so on.

For example, leaving out one step could lead to an unsuccessful release, which can cause delays and missed deadlines on the project. In this event, finding out which step was missed without documentation could be a huge headache.

Further, every project can be affected by changes in personnel, either from the side of the implementation team, or from the sides of the project owner or client. New project owners might not know the full history of the project, and the reasoning behind previous decisions. Proper documentation helps to explain why some decisions were made, and the reasons behind them.

Another example where documentation is crucial is when the developer is implementing a quick-fix or a hack in the code. Sometimes hacks are a necessary evil, solving a burning issue until a better solution is implemented. These situations must be documented so that everyone involved is aware of potential risks when removing the hack.

When writing documentation, you first need to consider your audience. If it’s aimed at other developers, it can be more technical and detailed. However, when you’re writing for a non-technical audience such as stakeholders or end-users, documentation should be written in plain language, avoiding technical jargon. 

Sometimes the audience types will overlap, and you should consider providing different levels of documentation – detailed technical documentation for developers and simpler, user-friendly documentation for other stakeholders.

One of the most common pitfalls when writing documentation is not providing the backstory behind an initiative. You need to explain the problem that needs solving, how it should be solved, and why you need to do it in the first place. By providing answers to these three questions, the audience will easily get onboard with the problem and its solution.

Good documentation should be easy to understand. Use simple language and clear explanations of concepts and processes. Avoid using acronyms or abbreviations without explaining what they mean. 

Additionally, be concise and stick to the main points, avoiding unnecessary details or tangents that can confuse the reader. Use the DRY principle of software development – Do Not Repeat Yourself. Provide simple and clear examples stripped of unnecessary details.

When it comes to documentation, consistency is key. Use the same format for each section, such as headings, subheadings, bullet points, and numbering. Add a table of contents and linkable sections if possible. This makes it easier for readers to navigate the document and find the information they need quickly. Additionally, consider using templates or standardized formats to ensure consistency across different documents and projects.

Documentation is only useful if it is accurate and up to date. Make sure to regularly review and update your documentation as changes are made to the project or code. This includes keeping track of new features or functionalities, changes to code structure or architecture, and updates to external dependencies or libraries. By keeping your documentation current, you can ensure that it remains a valuable resource for yourself and others involved in the project.

Just like code, documentation should be managed and version-controlled. Using a version control system can help track changes to the documentation over time. Additionally, it can facilitate collaboration among team members, allowing multiple people to work on the documentation simultaneously, merging changes as needed.

Code documentation is an essential component of software development, and AI can help you with it. By providing clear and detailed information about functions, variables, and other components of the code, developers can more easily understand how the software works and make changes as needed. This information is especially important for large and complex codebases, where it can be difficult to keep track of how everything fits together.

Using GitHub Copilot to write documentation can save time and provide great results. Here is an example of documentation written by GitHub Copilot Labs Visual Studio Code extension for the refreshToken function.

The function comment generated by GitHub Copilot Labs extension describes the context of the function and related parameters. The purpose and the application of the function is described in a detailed way, which provides value to the developer.

Despite the fact that the GitHub Copilot only deals with the “why” part, it’s a great stepping stone for kicking off documentation. For example, the provided example could be expanded with additional context on the cases when the token can expire and when this function should be called.

Writing good documentation can sometimes be a hard job, but it’s a lot easier if you know what to avoid. Here are some common anti-patterns you might come across.

This one is obvious: lack of documentation can make it difficult for everyone involved to understand how a system or a process works, which can lead to confusion, errors, and delays. It is important to have at least some level of documentation in place, even if it’s just basic notes or comments in the code.

On the other end of the spectrum, over-documentation can be just as problematic. If there is too much documentation, it can be difficult to navigate and find the information you need, which can be just as confusing and time-consuming as having no documentation at all. It is important to strike a balance between providing too little information and overwhelming the reader.

Poorly organized or poorly structured documentation can be difficult to navigate and understand. It is important to use a consistent format and structure throughout the document, with clear headings, subheadings, and bullet points. Consider using tables of contents, glossaries, or indexes to help readers find the information they need quickly.

Outdated documentation can be misleading or inaccurate, leading to errors and confusion. It is important to keep documentation up to date as changes are made to the system or process.

Documentation that is written for the wrong audience can be confusing or irrelevant. Make sure to consider who the intended audience is when writing documentation, and tailor the language and level of detail accordingly. For example, documentation intended for developers may be more technical and detailed, while documentation intended for end-users may need to be more simple and user-friendly.

It’s kind of like an iOS developer wanting to learn about the DocC documentation environment and reaching this page instead. They would be much better off reading the article Documentation Is the Key to Happy Coding, for example.

In conclusion, documentation is an essential aspect of software development. From feature documentation to process documentation and code documentation, it provides the foundation for clear communication and understanding. Good documentation also reduces the risk of misunderstandings and errors, and improves the quality and maintainability of software. 

With solid documentation in place, clients can save time and money in the long run. When everything is properly documented, onboarding new developers to the project is quicker, it’s easier to manage changes in staff and monitor the release process.

To make your documentation effective, it’s important to consider the different types available, such as process documentation, code documentation and user documentation. Additionally, it is important to avoid common anti-patterns, such as lack of documentation, over-documentation, poor organization, outdated documentation, and writing for the wrong audience.

By prioritizing documentation and following best practices, developers and other stakeholders can ensure that they save time and money, avoid common problems, and create high-quality products for their clients and users.