Choosing the Best CIAM Solution

Introduction

This guide explains the alternatives to traditional username and password authentication, how and when to use them, and how difficult they are for both users and programmers. By the end of this article, you should be able to answer questions like:

• How exactly are passkeys different from passwords, and what benefits do they offer?
• How do users log in with the same passkey on different devices, and is this portability safe?
• What are these marketing buzzwords, like “magic” links, “frictionless” login, and “biometrics”?
• Should my website use multiple authentication methods or just one, and how do I decide?
• How can I code passwordless authentication, or which tool should I use to implement it for me?

‍
What Is Wrong With Passwords?

If you’re conscientious, you might create long, random, unique passwords for every website, keep them in a password manager, and never share them. The average user doesn’t do this. Below are all the difficulties and dangers of passwords as they are commonly used.

• Inconvenience: Websites have onerous, differing requirements for creating passwords and might ask users to change their passwords frequently.
• Forgetfulness: Users forget their passwords, especially with multiple accounts.
• Reuse: Users reuse the same password for many sites. If one site is hacked, all other accounts are in danger.
• Lockout: A user can lose access to their recovery email address, losing their account forever if they forget their password for a website.
• Guessable: Weak passwords are easy for hackers to guess or brute-force.
• Theft: Even with a strong password, a user can be tricked into revealing a password using a fake website (phishing), social engineering, physical theft, shoulder-surfing, or key-logging.
• Breaches: If hackers gain access to a website database, all customers’ passwords are in danger, especially if the website didn’t hash the passwords or hashed them with weak algorithms.
• Sharing: Employees in workplaces share passwords, causing security risks (including sabotage) and making auditing and accountability impossible. For paid services like Netflix, sharing passwords also makes fraud between friends easy.

In summary, passwords fail at convenience and security for non-technical users and for companies.
‍

What Is Passwordless Authentication?

To overcome the problems above, security experts developed the following alternatives: passkeys, magic links, and multi-factor authentication (MFA).

This section discusses how these protocols work in theory. Later, you’ll see what the alternatives look like to users and learn how to implement them for your website.
‍

Passkeys (FIDO2/WebAuthn)

In 2013, the biggest USA software companies formed the FIDO (Fast IDentity Online) Alliance to “help reduce the world’s over-reliance on passwords.” The FIDO Alliance’s standard, FIDO2, was submitted to the World Wide Web Consortium (W3C) and became the WebAuthn standard in 2016. WebAuthn is a protocol that describes how clients and servers can be authenticated using asymmetric cryptography (commonly called passkeys) instead of passwords.

To summarize: - FIDO is both a group of companies and the name of one of the group’s standards. - WebAuthn is the official web standard corresponding to FIDO2. - Passkeys is the common name for the private and public keys used for authentication with WebAuthn.

If you need to revise public-key cryptography, see the Wikipedia page. All you need to remember is that there are two keys, and anything encrypted with one key can only be decrypted with the other key.
‍

How Does Passkey Authentication Work?

Here’s how a passkey is registered on a website: - A browser visits a website, and the website asks it to register with a passkey. - The browser creates a new private-public key pair specific to that website and sends the public key to the website, keeping the private key secret. - The website sends the browser a random string (called a challenge). - The browser encrypts the string with the private key and sends it back to the website. - The website verifies the string can be decrypted with the browser’s public key.

Later, passkey sign-in works the same way as passkey registration: The website sends the browser a random string and checks whether the response shows the browser has the private key.

Note the word “browser”, not “user”. The user does almost nothing in this process except consent to registration or authentication (this ease is why WebAuthn is said to be “frictionless”). The user doesn’t make a password — the browser makes a passkey. So, the authentication process ultimately occurs between a server and a device, not a server and a user.

The user will see something like the screenshot below.

Test passkeys yourself at https://webauthn.io.
‍

How Are Passkeys Managed On And Between Devices?

You probably have the following questions: - What exactly is a “device”? A browser? A computer? - Where are the passkeys kept, and are they secure? - How does a user log in to the same website from a different device or browser? Or if they lose access to their device? - How does a user access or change their passkeys?

The last question is the easiest to answer — they don’t. Using WebAuthn means a user never directly has access to their own passkeys. Instead, they use a master password to authenticate accounts with their device, and the device generates, encrypts, stores, and synchronizes their passkeys across all the user’s devices.

All the questions above can be answered by explaining how key management works on the client device. However, the WebAuthn protocol isn’t concerned with this process and focuses only on the authentication process; key management is up to the client.

The browser itself is not the device, but needs access to a device that can generate passkeys and authenticate user accounts with public-key cryptography. The device may be built into the hardware and operating system, such as on Android and iOS phones; it may be an external USB cryptography device (often called a dongle), such as a Yubikey; or it may be a browser extension, such as Bitwarden. Note that this implies a user is able to choose between different devices when authenticating on a site, which can lead to confusion and an inability to log in if they use many different devices.

For ideal security, the private keys would never leave the hardware device. The browser would pass the challenge to the device, which would return the encrypted version and never expose the key. This system existed long before WebAuthn and is called a hardware security module (HSM). The most famous examples of HSMs are trusted platform modules (TPMs), such as the TPM required for upgrading to Windows 11, and cryptocurrency wallets, which prevent users from accidentally exposing their Bitcoin keys.

For users or banks who want this high level of security, buying a dongle is the answer. However, most users don’t want that expense and prefer the convenience of being able to use the same passkeys on their desktop computers, laptops, tablets, and phones. This means the private keys have to be removed from the secure storage, transferred to an online server, and downloaded to other devices. Microsoft, Apple, and Google provide this functionality in their operating systems. Linux does not. Browser extensions like Bitwarden also provide this feature and have open-source clients.

No matter the provider you use, synchronization works the same way: The passkeys are encrypted with the user’s master password, uploaded, stored, and then downloaded and decrypted with the user’s master password.

‍

So Passkeys Need A Password?

So ultimately, passkeys are dependent on passwords? What about the “biometrics” that people are talking about?

Yes, the user needs to authenticate their account with their device using a password, and the password is needed to encrypt all the passkeys for transit (unless they use a dongle). However, a local copy of the passkeys can be stored on the device and encrypted not with the master password but with something more convenient, like a short PIN (personal identification number), a fingerprint, or a face photograph. If the user loses access to their master password, they lose access to all their passkeys.

So while security companies advertising biometric security may give you visions of websites doing retinal scans like a sci-fi movie, all it really means is that the user can unlock their phone with their face. It’s a bit misleading: WebAuthn doesn’t require biometrics. The WebAuthn specification talks about “authentication gestures” - a gesture could be a fingerprint or even just a PIN. Biometrics can be used if the user wants, and if their device has the feature, but they are more for convenience than for security.
‍

Magic Links

A magic link is a unique URL sent to a user in an email. When the user browses to the URL, it automatically logs the user into the website. The link expires after a short time.

Using a magic link means that a user doesn’t need a password or a passkey; they only need an email address. The disadvantage is that whenever the user’s session expires, they have to request a new link, wait, open their email client, click the link, and delete the email. Magic links are more convenient than passwords for most users, unless they frequently log out of sites or the website sets a very short session duration.
‍

OTPs

An OTP (one-time password or one-time PIN) can be used in two ways: as an alternative to entering a password or in addition to entering a password.

The use of OTPs instead of passwords results in a process that is effectively identical to being emailed a magic link for login, except the message is a PIN, not a URL. However, it’s more effort for the user to type in a code than to click a link, so there’s no reason to use an OTP instead of a magic link.

The use of OTPs in addition to passwords is a process known as multi-factor authentication (MFA) or two-factor authentication (2FA). This isn’t passwordless authentication, as you still have to enter a password, with the extra effort of also entering an OTP. However, requiring an OTP does reduce some of the security flaws of passwords.

MFA is useful because it proves the user has access to more than one piece of information about themself, such as email or phone access, increasing the chances they are not an attacker.
‍

TOTPs

A TOTP (time-based OTP) works similarly to an OTP, except instead of being sent by a server, a TOTP is generated by an app that shares a secret key with a server. Rather than being messaged the PIN by the server, the user gets the PIN from this app on their phone. Every thirty seconds, the app generates a new PIN, which the user types into the server to verify. A phone is usually required because the shared secret is often a QR code that has to be photographed. All apps use the same protocol, so the user can choose their favorite.

Although TOTPs don’t need to be sent from server to user and could be used instead of passwords for login, they generally aren’t, and are rather used only as a second factor of authentication. TOTPs are also notoriously inconvenient when a user changes their phone and forgets to migrate their authenticator app.
‍

What Are The Benefits Of Passwordless Authentication?

Let’s consider how these three methods — passkeys, magic links, and MFA — solve the password problems listed earlier. These flaws can be grouped into three types of problems:

1. Inconvenience
2. Forgetfulness, Reuse, Guessable, Breaches, Sharing
3. Theft, Lockout

‍

Passkey Benefits

Passkeys are highly convenient, requiring almost no effort from the user, and since private keys never leave the device unencrypted, they solve the second group of problems too. However, if a user has Google and Apple devices (a phone and tablet), passkeys will not be shared.

Passkeys are still vulnerable to theft and lockout. Users remain vulnerable to having their master passwords stolen, physical theft of devices, keylogging, and having their faces faked; they can still experience lockout if they lose access to a master password or device.
‍

Magic Link Benefits

Magic links are convenient and solve the second group of problems as long as the user uses a secure email provider and doesn’t share their email account with anyone.

Theft and lockout are difficult to prevent. A user’s email account suffers all the vulnerabilities of a password, and if stolen, allows an attacker to log in to any website that uses magic links. If a user loses access to their email account, they lose access to all magic-link websites.

Passkeys and magic links have almost identical advantages, but passkeys are slightly more convenient. With magic links, users experience delays between requesting a login and receiving the email. There is also a chance that the website’s email provider could go down or the user’s email client could reject the email as spam.
‍

MFA Benefits

MFA is more inconvenient than using only a password, but generally solves all the problems in the second group except forgetfulness. Once again, theft and lockout are not solved by this method.
‍

What Are The Problems With Passkeys?

If passkeys are endorsed by the software giants and solve most of the problems of passwords, why do so few sites use them?
‍

Limited Support

Operating systems may not support passkeys. For instance, most Linux users and users running older versions of Windows (that don’t log in to online accounts) don’t have passkey support. Users on these systems may not know how to, or may not want to, enable passkey support.

Browsers themselves have various passkey peculiarities, quirks, and support issues. Safari is fussy, and Firefox does not support direct attestations (to avoid fingerprinting browsers and to maintain users’ privacy) or the use of TouchID, the Apple device fingerprint scan.
‍

Single Point Of Failure

Magic links and passkeys both create a single point of vulnerability for the user — their email address or phone. If an attacker gains access to a point of vulnerability, they have access to every one of that user’s sites. Phone theft (and kidnapping in high-crime countries) has increased significantly in recent years due to the high reward of gaining access to mobile banking apps and TOTP authenticator apps, which are, ironically, the tools banks have been promoting for increased security.

Similarly, if a user loses access to their master password and recovery codes, they are locked out of every account.

In contrast, if a user uses different passwords for every site, an attacker gaining access to one site gains no access to any other. Forgetting a password for one site doesn’t lock you out of all others.
‍

User Trust And Familiarity

Passwords are instantly intuitive to most people; they’re like a door key. In contrast, passkeys are impossible to explain to a non-technical user, and they’ve only been around for the last few years.

You need to convince your users that they can log in to your site with some new invisible technology, that logging in without entering a password is completely secure, and that they won’t lose access to your site.

Finally, users need to trust Google, Apple, and Microsoft with storing their passkeys for every site they use. These companies may claim that they transmit and store private keys with encryption, but since their code is not open-source, users can never know for sure. Further, if your country is hit with US sanctions and you lose cloud access, you lose access to all your keys. You can prevent the risks of relying on cloud providers by using a dongle or an open-source provider like Bitwarden.
‍

Which Type Of Authentication Should You Use?

Given the advantages and disadvantages of all these authentication methods, which should you use?

Firstly, if you are stuck with using passwords, choose sensible password restrictions with a framework like zxcvbn. Rules stating passwords should “contain a number, uppercase, lowercase, and special characters” are antiquated, annoying, and still not secure. Provide links on your registration page to password managers to educate users on secure practices.

If your site is dangerous (banking or medical), require your users to use MFA. Ensure MFA is as convenient as possible by allowing users to choose from multiple delivery options, such as email, SMS, WhatsApp, and TOTP.

If you have a public website and don’t have to use passwords, you should always use magic links instead. Passwords offer almost no advantages. Choosing between magic links and passkeys is more difficult. If possible, provide both options to users to support those who may not be able or willing to use passkeys. Magic links rely on email, which has more security risks than passkeys (especially when it comes to interception), so for industries needing extreme security, rather choose passkeys.

If you want to use only passkeys, you should provide a brief explanation of passkeys on your registration page and communicate to users which devices they can use and how they can synchronize their passkeys to other computers.

Passkeys are a good choice when you have users using known equipment, such as in a corporation where all employees use Windows 11 with TPM hardware and a Microsoft account.

There are some use cases where specific authentication methods are required. For devices without keyboards (such as TVs, fridges, and cars), passkeys are a good option. Highly regulated industries, such as banking and large corporations, may require passkeys.

For devices used in extreme cases of life and death, like pacemakers or aircraft security devices, you need to balance the extra security of passkeys with the need to grant immediate access during an emergency (which is easier with a password) and the risk of account lockout if keys are lost.

For desktop apps like Steam or Discord, you don’t have to use passwords. All modern operating systems allow a desktop app to open a browser window and return a value to the app, so magic links and passkeys can also be used.
‍

How Do You Implement Passwordless Options?

Now that you know the theory of various authentication methods, let’s see what they look like in practice from the user’s point of view and how difficult they are to implement.

While you can code authentication yourself, it’s much safer and faster to use a dedicated authentication gateway or framework. This section will show you examples of authentication using FusionAuth, but you can use similar configurations with software like Ory, Keycloak, Auth0, and others.

FusionAuth, like most of these tools, provides login screens for users, a separate administrative web portal, and an API so that your website can create custom screens that use the authentication system programmatically.

If you want to test the examples yourself, you need an installation of FusionAuth. The easiest way to run FusionAuth is in a Docker container. Clone the example GitHub repository. Open a terminal in the light subdirectory, and run docker compose up in a terminal to start FusionAuth. Log in at http://localhost:9011 with admin@example.com and password.

Using passkeys requires a free community license. Some advanced features may require a paid license.
‍

Implementing Magic Links

You can configure FusionAuth to allow a user to log in with magic links, either in addition to or as an alternative to username and password authentication.

Log in to FusionAuth, and in the Tenants page, edit the default tenant. In the Email tab, set the Host to mail.smtpbucket.com and the Port to 8025. SMTPBucket is a free online mail-testing service. To configure other email providers for a real service, follow the SMTP guide.

To configure magic links, follow the magic links guide. In brief, you need to ensure that you have an email template configured in your FusionAuth tenant under Email -> Template settings -> Passwordless login for sending users emails (this template was configured for you in the Kickstart file of the repository you downloaded) and that you have Passwordless login enabled in the Security tab of the application settings

Email templates can be customized by navigating to Customizations -> Email Templates, so you can format your magic links and the message that accompanies them as you prefer.

Finally, you need to have a user to test the login. This demonstration application already has a user with the email richard@example.com and the password password.

In reality, your website’s login page would redirect to a FusionAuth login page, but FusionAuth also provides a standalone login page that requires no client website. On the applications page, select View to see more details about an application, including its OAuth IdP login URL.

If you visit the login page, you can see that it has a magic link option.

If you enter the email address of a user registered in the application and click Send, a login URL will be emailed to the registered email address.

Clicking this link will log you in to FusionAuth and redirect you to the URL of the website set in the application, under OAuth -> Authorized redirect URLs.

More information on magic links in FusionAuth is available in the magic links guide.
‍

Implementing OTPs

An OTP can be used in two ways: as an alternative to entering a password or for MFA. However, FusionAuth only supports the use of OTPs for MFA. However, FusionAuth only supports the use of OTPs for MFA. FusionAuth supports the use of OTPs only for MFA, and doesn’t support OTPs as an alternative to passwords.

To configure MFA, follow the guide. In brief, you need to enable email settings, then select the email template in your tenant Multi-Factor tab, and set the multi-factor On login policy to Required for your application.

Now when a user logs in, they will be asked to configure MFA. Log in to your application using the OAuth IdP login URL specified in your FusionAuth application details, as before.

After entering the login details, you will be asked to configure MFA. In this example, you can choose email authentication.

After clicking the Send a one-time code button, you’ll receive a PIN via email. Use the PIN as the Verification code and click the Enable button.

After logging in, you’ll be able to save recovery codes in case you lose access to your email account.

Now that you’ve configured email authentication, the MFA login will be simpler in the future.

Implementing TOTPs

The TOTP setup process and user authentication flow are almost identical to the OTP processes. The user enters an OTP on the FusionAuth login page from the TOTP app on their phone.

Follow the MFA guide to enable TOTPs. Unlike for OTPs and magic links, you won’t need to use any email templates
‍

Implementing Passkeys (FIDO2/WebAuthn)

Configure passkeys using the passkey guide. In brief, you only need to enable them in the WebAuthn tab of the tenant, ensuring you also enable the bootstrap and reauthentication protocols (for creating and reusing passkeys). Like all the other authentication options you’ve seen so far, you can override tenant settings for different applications.

Now when you browse to the application login page, you’ll see there is an option to log in with a fingerprint or a device (in other words, with a passkey).

However, you’ll see that no passkeys are found on your device. This is because you can’t use passkeys in FusionAuth without setting them up first: either when a user first registers or on the FusionAuth self-service account page.

You need to enable self-service by selecting a User Self-service form to use under the Registration tab of your application and by directing your existing users to the self-service account management page to create their passkeys. The application configuration details can be found by selecting View for a listed application. For this example, the self-service page is http://localhost:9011/account/?client_id=e9fdb985-9173-4e01-9d73-ac2d60d1dc8e.

The user registration URL for the application can be found in the application details. For this example, it will be here. But first, you have to enable self-service registration for any user in the application settings.

Now, as a user, you can browse to the registration URL and register with any email address and password you want. For testing purposes, it’s faster if you (as the administrator) disable email address verification in the application settings.

On the next page of the registration, you can choose to create a passkey.

When you’ve completed these steps, you’ll be able to use your passkey to log in on the application’s OAuth IdP login URL in future.

As you may have noticed, your new user still had to enter a password at registration. This is because FusionAuth doesn’t yet offer a fully passwordless user experience. There is an open GitHub issue for this feature. If avoiding passwords entirely is important to you, please vote and comment on this issue to increase its priority
‍

Using The FusionAuth API

You can use the FusionAuth API to perform the same login tasks programmaticaly that the user performed using the login screens. For example, although you can style the FusionAuth login pages to match your website, you could create a highly customized login page that is built into your existing website if you use the API. Instead of the user entering their credentials on the FusionAuth login page, the user would enter them on your website, which would then forward the credentials to FusionAuth.

APIs are more commonly used for reauthentication than for login. With the FusionAuth API, you can ask the user to securely confirm a decision by reauthenticating themselves. For example, when making a purchase on your site.

This is one case in which a more onerous authentication flow is preferable to a faster one. For example, assume a user’s child is playing on their parent’s computer and is trying to buy something without permission. If the user relies on passkeys, their child can click the passkey in the desktop browser when it pops up. If the user instead uses SMS OTPs or a TOTP on their phone, reauthentication would be much more difficult for the child. Passkeys can be made more secure by the user enabling the browser setting that requires the user to enter a PIN to access the passkey vault. However, this relies on the user to set it up, and is not something your website or FusionAuth can enforce.

Let’s take a quick look at what an API call would look like for an OTP request or passkey authentication request from your website to FusionAuth.
‍

OTP Reauthentication

For MFA with OTPs, FusionAuth calls reauthentication step up auth.

‍

Start the MFA process using the curl command below, specifying for which user and application you want to generate the OTP. (In a real application, you could use any programming language instead of curl.)

curl 'http://localhost:9011/api/two-factor/start' \
-H 'Authorization: 33052c8a-c283-4e96-9d2a-eb1215c69f8f-not-for-prod' \
-H 'Content-Type: application/json' \
-d '{
  "applicationId": "e9fdb985-9173-4e01-9d73-ac2d60d1dc8e",
  "loginId": "richard@example.com",
  "method": "email",
  "state": { "transaction": "pending" }
}'


# RESPONSE:
# {"code":"872887","methods":[],"twoFactorId":"XFb2zBIKB5PoA7ZdZA_A3TjfVPm6fMhD_ypl7axBvyE"}

The response above contains the code (OTP) that the user will be challenged to enter. You need to ask the user to enter this code on your website. The two-factor Id is a field that you use in subsequent FusionAuth calls to remember which MFA transaction you’re busy with.

Next, ask FusionAuth to send the OTP to the user’s email. You specify the two-factor Id in the URL and the identifier methodId of the user’s enabled MFA method, which you can access under the Multi-Factor tab on the user’s details in FusionAuth.

curl 'http://localhost:9011/api/two-factor/send/XFb2zBIKB5PoA7ZdZA_A3TjfVPm6fMhD_ypl7axBvyE' \
-H 'Authorization: 33052c8a-c283-4e96-9d2a-eb1215c69f8f-not-for-prod' \
-H 'Content-Type: application/json' \
-d '{
  "methodId": "LJBD"
}'

The user will receive an email with the OTP.

Once the user enters this code on your website, you can complete the authentication by verifying the code with FusionAuth.

curl 'http://localhost:9011/api/two-factor/login' \
-H 'Authorization: 33052c8a-c283-4e96-9d2a-eb1215c69f8f-not-for-prod' \
-H 'Content-Type: application/json' \
-d '{
  "code": "872887",
  "twoFactorId": "XFb2zBIKB5PoA7ZdZA_A3TjfVPm6fMhD_ypl7axBvyE"
}'

All you need to check in this response is the success code 200. You can ignore the JSON returned.

If the code has expired, no JSON will be returned, and the HTML response will be a 404 (not found) error message. Use curl -v to see this extra information. Response 421 indicates the code was invalid.

If you’re trying to test the above commands yourself but can’t complete all the steps before the token expires, you can ignore the middle email step and instead copy the code directly from the first command into the final verification command.

You may be wondering why you need to call FusionAuth to check whether the code the user entered in the final step was correct when you already have the code from the first command’s response, and your website can compare the two codes itself. There are two reasons: 1. FusionAuth automatically handles the rejection of expiring codes, so your website doesn’t need to implement a timer. 2. FusionAuth remembers the code for you (by associating everything with the two-factor Id), so you don’t have to store the code in server session state in order to check it later.
‍

Passkey Reauthentication

This final example demonstrates how to ask a user for confirmation with their passkey instead of an OTP. It uses the SimpleWebauthn TypeScript library.

You need to have a user that is registered to use passkeys, so you can reuse the user you created in the passkey example earlier.

In any directory on your computer, create a page called index.html and insert the code below.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>FusionAuth passkey test</title>
    <script src="https://unpkg.com/@simplewebauthn/browser@13.1.0/dist/bundle/index.umd.min.js"></script>
</head>
<body>
    <textarea id="input"></textarea><br />
    <button onclick="authenticate()">Authenticate</button><br />
    <textarea id="output"></textarea>

    <script>
      async function authenticate() {
        // get passkey from FusionAuth data
        console.clear();
        const input = document.getElementById("input").value;
        let json = JSON.parse(input);
        const bts = SimpleWebAuthnBrowser.base64URLStringToBuffer;
        json.options.challenge              = bts(json.options.challenge);
        json.options.allowCredentials[0].id = bts(json.options.allowCredentials[0].id);
        const { 'options': publicKey, ...rest } = json;
        json = { publicKey, ...rest };
        const passkey = await navigator.credentials.get(json);

        // convert passkey to JSON
        console.log('Passkey:');
        console.dir(passkey);
        const stb = SimpleWebAuthnBrowser.bufferToBase64URLString;
        passkey.response.authenticatorData = stb(passkey.response.authenticatorData);
        passkey.response.clientDataJSON    = stb(passkey.response.clientDataJSON);
        passkey.response.signature         = stb(passkey.response.signature);
        passkey.response.userHandle        = stb(passkey.response.userHandle);
        delete(passkey.getClientExtensionResults);
        delete(passkey.rawId);
        const result = {
          'origin': 'http://localhost:3000',
          'rpId': 'localhost',
          'credential': JSON.parse(JSON.stringify(passkey))
        };
        document.getElementById("output").value = JSON.stringify({ ...result });
      }
    </script>
</body>
</html>

This page has an input textbox, an output textbox, and an authenticate button that runs code to take the input JSON, ask the user to enter the passkey for the JSON, and output the passkey as JSON. To understand how it all works in detail, see the complete FusionAuth guide to passkeys.

Open a terminal in the directory with the HTML file. Then, run the command below to serve the page at http://localhost:3000 using Docker.

docker run --rm --network faNetwork -v .:/app -w /app -p 3000:4507 
denoland/deno:latest run --allow-sys --allow-net --allow-read 
https://deno.land/std/http/file_server.ts /app

Start the passkey reauthentication process using the curl command below. You might need to replace the userId value with the value of the user you created.

echo && curl -w '\n\n' 'http://localhost:9011/api/webauthn/start' \
-H 'Authorization: 33052c8a-c283-4e96-9d2a-eb1215c69f8f-not-for-prod' \
-H 'Content-Type: application/json' \
-d '{
  "applicationId": "e9fdb985-9173-4e01-9d73-ac2d60d1dc8e",
  "userId": "e202246a-0308-4a3f-8700-e809a174656a",
  "workflow": "reauthentication"
}'

# RESPONSE
# {
#   "options": {
#       "allowCredentials": [
#           {
#               "id": "OZZ_t9_hSYifTaQRY7zqHA",
#               "transports": [ "internal" ],
#               "type": "public-key"
#           }
#       ],
#       "challenge": "jbwImkaXKarROwdtFUHpbtYCN3QirwMNnPwih5xWi_Y",
#       "timeout": 180000,
#       "userVerification": "required"
#   }
# }

Paste the curl JSON response in the textbox at the top of the page at http://localhost:3000 and click Authenticate. Authorize the request to access the user’s passkey in the browser popup.

If your browser reports a generic DOM error in the browser console stating that access to passkeys is not allowed, it’s probably not a permissions error. The error is likely due to incorrectly formatted JSON (which you can see using a console.log statement in the JavaScript code). This example was tested on Firefox. If you’re using a different browser, check its documentation to see what it requires in a navigator.credentials.get() request, and check whether the browser has any quirks.

In Firefox, you might need to browse to about:config, search for webauthn, and enable all settings, but the default settings should allow passkeys.

Note also that you don’t need to change the relying party Id, despite using both localhost:9011 and localhost:3000, because cookies separate domains using ports, but Webauthn does not.

Copy the text that appears in the lower textbox, paste it between the ' quotes following -d at the end of the command below (overwriting the example payload), and run the command.

echo && curl -w '\n\n' 'http://localhost:9011/api/webauthn/assert' \
-H 'Authorization: 33052c8a-c283-4e96-9d2a-eb1215c69f8f-not-for-prod' \
-H 'Content-Type: application/json' \
-d '{"origin":"http://localhost:3000","rpId":"localhost","credential":{"id":"OZZ_t9_hSYifTaQRY7zqHA","type":"public-key","response":{"authenticatorData":"SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MdAAAAAA","clientDataJSON":"eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiamJ3SW1rYVhLYXJST3dkdEZVSHBidFlDTjNRaXJ3TU5uUHdpaDV4V2lfWSIsIm9yaWdpbiI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMCIsImNyb3NzT3JpZ2luIjpmYWxzZX0","signature":"MEYCIQD2-ZC9kTcI5stHY-eii4yoZbu_r0vG5bEiyPB9OcrQXwIhANblFrkPgKFoaI3ysm9GlU6XxwDIhbmaabuZ3UPIz6Wj","userHandle":"NjcxZDE5YjctNjM2NC00MGNlLWI3YmMtY2MzMjRjZTMzZDM5"},"authenticatorAttachment":"platform"}}'

# RESPONSE

# {
#   "credential": {
#       "algorithm": -7,
#       "attestationType": "none",
#       "authenticatorSupportsUserVerification": true,
#       "credentialId": "OZZ_t9_hSYifTaQRY7zqHA",
#       "data": {},
#       "discoverable": false,
#       "displayName": "passkey",
#       "id": "50398a84-1d25-4bec-b87a-dafaae56702d",
#       "insertInstant": 1739354896368,
#       "lastUseInstant": 1739790906822,
#       "name": "r@example.com",
#       "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELgV+MzwRuHh/h/js5jwO1BCGCDph\n5spWR+JYfY9J6iUEvO2AwOlnq9WtLoocvo7u1pW1wEwD9rs4RO96z+C4Tg==\n-----END PUBLIC KEY-----",
#       "relyingPartyId": "localhost",
#       "signCount": 0,
#       "tenantId": "d7d09513-a3f5-401c-9685-34ab6c552453",
#       "transports": [
#           "internal"
#       ],
#       "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:135.0) Gecko/20100101 Firefox/135.0",
#       "userId": "671d19b7-6364-40ce-b7bc-cc324ce33d39"
#   }
# }

The JSON above confirms that the user’s passkey authentication is correct and that you can let them continue with their transaction. As long as the API response returns code 200 and has no errors, the user has been verified successfully.

If you don’t run all the commands fast enough, your authentication request might time out. If any part of your JSON is incorrect, FusionAuth will give you an error message like: {"fieldErrors":{},"generalErrors":[{"code":"[Exception]","message":"FusionAuth encountered an unexpected error. Please review the troubleshooting guide found in the documentation for assistance and the available support channels."}]}. To find the problem, you will need to compare your JSON (which you are sending to the FusionAuth API specification) to the expected example JSON parameters manually.

How Do You Choose An Authentication Gateway?

In the previous section, you saw that configuring complex technologies like WebAuthn and TOTPs takes only a few button clicks using an authentication gateway. But when there are so many gateways available, how do you choose?

If you are using only the basic features of a gateway, without API integration, don’t worry. Just pick a gateway that looks decent and point your website login toward it. It’s generally easy to migrate your user emails from one gateway to another.

But if you’re using deep integration, you need to consider cost, feature set, ease of use, reliability, support, documentation, customization, and hosting possibilities. FusionAuth offers detailed articles comparing the different gateways.

Here are a few basics to consider: - Deployment model: Is the gateway cloud-only (fully online), self-hosted, or hybrid? Generally, the paid gateways are cloud, whereas open-source gateways and gateways free tiers have self-hosting options. Online managed solutions are quick to set up but might be less customizable and more costly than hybrid or self-hosted tools. - Focus area: Does the gateway focus on developer usability (offering APIs and SDKs for easy integration), enterprise usability (prioritizing scalability, compliance, and integration with corporate tools), or end-user usability (prioritizing elegant user experiences with customizable workflows)? - Features: Does the gateway offer all the passwordless options discussed in this article, and are they easy to configure? - Scalability: Can the gateway handle your number of users, including during usage spikes at peak times? - Compliance: Do you need the gateway to be legally compliant with any rules in your industry or country, like the GDPR or HIPAA?
‍

Further Reading

Below are all the links mentioned in this guide if you’d like to learn more.

• The WebAuthn specification
• The WebAuthn API documentation
• WebAuthn browser compatibility
• WebAuthn browser quirks
• WebAuthn device compatibility
• Public-key cryptography
• The Bitwarden password manager
• The Yubikey passkey dongle
• The SimpleWebAuthn JS library
• The zxcvbn password strength library
• The FusionAuth documentation on passwordless authentication
• The FusionAuth gateway comparisons
• The FusionAuth gateway migration guides

‍

SSO has become essential for modern applications. It lets you offer a secure, seamless login experience to your customers or users, reducing friction and letting them get to your application or applications quickly.
‍
For developers, SSO isn't just about reducing friction—it also lets you outsource management of identity so you don’t have to worry about it.

‍

‍What is SSO?

SSO, or single sign-on, is an authentication method that allows users to access one or more applications with a single set of credentials, eliminating the need for them to remember and enter different passwords or repeatedly offer up other credentials. SSO creates a better user experience while enhancing security through centralized management of user identities and credentials. 

SSO works by establishing a trust relationship between applications and an identity provider, which handles the verification of user credentials. The identity provider then issues tokens or other forms of identity proof  which can be used by the trusting application. 

With centralized authentication, often implemented using a customer identity and access management (CIAM) system, organizations gain improved access insight, control via policies, better management of permissions across applications, and enhanced security through consistent enforcement of authentication standards such as use of multi-factor authentication (MFA). 

For developers implementing customer-facing applications, SSO reduces friction in the user journey, leading to higher conversion rates and improved customer satisfaction.

‍
Benefits of SSO

SSO delivers significant benefits for both users logging in and organizations, by creating a frictionless authentication experience and enhancing overall security. By allowing users to access multiple applications with a single set of credentials, SSO eliminates password fatigue and reduces login frequency, streamlining the customer journey and improving conversion rates. 

From a security perspective, centralized authentication enables consistent enforcement of password policies or breached password detection, simplified credential management, and faster implementation of security measures like MFA across all trusting applications. This centralization makes it easier to introduce advanced authentication features including:

• adaptive authentication
• risk-based access controls
• passwordless features such as magic links or passkeys

All of this without disrupting the user experience or requiring separate implementations for each application.

Additionally, SSO aids compliance efforts by providing audit trails and access controls that simplify reporting for regulations like GDPR, CCPA, and HIPAA. With all user logins flowing through a single system, organizations gain visibility into user access patterns. They can more easily demonstrate adherence to regulations with centralized logging and monitoring. 

This consolidated approach to identity management reduces the burden on engineering teams, allowing them to focus on core application functionality rather than building and maintaining multiple authentication systems.
‍

Challenges of SSO

It’s not all roses, though.

SSO introduces additional complexity to your application ecosystem, as it creates dependencies between the trusting applications and the identity provider. This interdependence means that changes to authentication flows, token formats, or security policies in the SSO solution can potentially impact multiple downstream applications. Developers must carefully consider how these systems interact and establish robust testing to ensure that updates don't disrupt users ability to log in. Additionally, SSO needs standard authentication protocols across applications; depending on the applications, this can require changes to existing codebases.

A significant concern with centralized authentication is the creation of a single point of failure (SPOF). If your SSO service or provider experiences downtime, customers may be unable to access any applications, affecting critical business operations. To avoid this, invest in high-availability solutions and disaster recovery plans to mitigate outage risks. Evaluate SSO provider's reliability guarantees and consider the business impact of authentication system failures when selecting a solution.

Implementation costs for SSO can be substantial, beyond licensing fees of the CIAM solution. These costs include:

• development time for integration
• staff training on the new systems
• ongoing maintenance after implementation
• planning and engineering time for user profile migration, if applicable

The initial implementation typically requires specialized knowledge of identity protocols like Security Assertion Markup Language (SAML), OAuth, and OpenID Connect (OIDC), which may mean hiring experts.

Compatibility challenges often arise when integrating SSO with legacy applications or third-party systems that weren't designed with modern authentication protocols in mind. Applications may lack support for standards like SAML or OAuth, requiring middleware solutions to enable SSO functionality. 

Migration from existing authentication systems may present additional hurdles. These include:

• maintaining existing user credentials
• managing the transition period when both systems might need to operate in parallel
• ensuring that user profile data and permissions are correctly mapped between systems

Develop a comprehensive migration strategy that addresses any potential data inconsistencies and plan for time to handle integration issues. Migrations almost always take longer than you think.
‍

Single Sign-On And Federation

Federation and SSO are related but distinct identity management concepts. They serve different purposes. While SSO enables users to access multiple applications with one set of credentials, federation extends this capability across organizational boundaries by establishing trust relationships between separately managed identity stores.

The key distinction is that federation involves explicitly trusting external identity stores outside your organization's direct control, allowing users to authenticate using credentials managed by others. These include social media platforms like Google or Facebook or third-party identity providers like a customer’s Entra ID or Okta instance. Cross-organizational authentication enables seamless collaboration without requiring additional user accounts. As a bonus, it delegates control and responsibility for the identity to the external provider. 

In contrast, SSO typically operates within a single organization's ecosystem, leveraging either internal identity sources (like a corporate directory) or external providers that the organization has selected. 

SSO focuses primarily on streamlining the user experience and centralizing authentication management. Federation addresses the broader challenge of sharing identity across organizational boundaries, enabling businesses to safely collaborate with partners, contractors, and customers without managing their identity lifecycle.
‍

SSO Implementation Steps

1. Choose an Authentication Protocol

Select the appropriate protocol based on your technical and ecosystem compatibility requirements:

• OIDC: a modern protocol built on OAuth 2.0, ideal for web and mobile applications; this is the recommended option 
• SAML: an enterprise-focused protocol with robust, sometimes complex, security features, commonly used for B2B or older older applications

Why It Matters: Your protocol choice affects integration complexity, security features, and compatibility with your application stack. You might notice that “build your own” is not on this list; it’s not recommended.

2. Define Participating Parties

Here are the components needed for an SSO implementation:

• OpenID Provider: the system that authenticates users and issues proof of user identity and authentication
• Relying Parties: the applications that will accept the proof of authentication
• Users: the individuals who will log in through the system
• Clients: mobile or web applications used to interact with the other components 

SSO systems definitely use a lot of jargon. Below is a table mapping terms between OIDC (the terminology used above and throughout this article) and SAML, the older, enterprise-y technology.
‍

‍

Why It Matters: Understanding the relationships between your applications, store of identity and users helps planning, establishing trust, and understanding user and data flows.

3. Establish Trust Relationships

Configure trust between your OP, which manages user identity, and RPs, the applications which trust the OP:

• Exchange metadata or configuration information between systems.
• Set up public/private keypairs for secure signing of tokens.
• Share or publish the public portions of the keypairs.
• Configure allowed callback URLs and validation parameters.
• Define token lifetimes and security constraints.

Why It Matters: Establishing trust makes sure only the known and trusted OP can issue identity tokens for the RPs.

4. Implement Mapping

Define how user claims will be used across applications:

• Identify required claims for each RP (the trusting applications).
• Make sure the OP has all the required information, or figure out a way to get it.
• Configure what information is shared with which RPs.
• Set up any needed transformations of claims.
• Address privacy considerations for sensitive data. Do you need to scrub it, encrypt it or can you simply remove it?

Why It Matters: Proper mapping ensures applications receive the user profile data they need while respecting user privacy and regulations.

5. Integrate Applications with SSO

Modify your applications to accept identity assertions from the OP:

• Choose protocol-specific libraries or SDKs; this will differ based on the protocol you picked above.
• Update applications to send users to the OP when they authenticate.
• Configure applications to validate tokens.
• Implement session management, including session termination if needed.

Why It Matters: Application integration is often the most time-consuming part of SSO implementation and requires careful manual and automated testing.

6. Implement Logout Functionality

Design and implement support for logging users out.

• Decide between front-channel (on the client) and back-channel (on the server) logout mechanisms.
• Plan and configure active session termination across applications where needed.
• Implement proper redirects after logout.
• Consider session timeouts and inactivity handling, in particular how session length on the OP differs from session length at each of the RPs.

Why It Matters: Without proper logout, unintended application sessions can remain alive, creating confusion and possibly security vulnerabilities.

7. Develop Testing Strategy

Create a testing plan that validates authentication flows:

• Test successful authentication paths across all applications
• Verify error handling for invalid credentials or tokens
• Test session timeouts and renewal processes
• Validate logout functionality
• Test across different browsers, devices, and network conditions
• Simulate high traffic and failure scenarios

Create automated tests for high-risk, important, or unstable user flows so that you can know if they change or break.

You should also plan to set up different environments for your SSO server (dev, test, prod), the same as you have for your applications that depend on it. This way you can migrate changes or versions based on SDLC best practices.

Why It Matters: Thorough testing prevents issues in production that could block users from accessing applications.

8. Plan for Monitoring and Maintenance

Establish ongoing operational procedures:

• Implement logging and monitoring for authentication events as required by your compliance needs, including sending logs to SIEM tools or other log management solutions.
• Set up alerts for unusual activity or authentication failures, as well as a plan for how to handle them.
• Create a secret or certificate rotation schedule and the automated tooling or configuration do implement it.
• Develop a change management process for updates to the SSO configuration, preferring infrastructure as code to minimize configuration drift.

Why It Matters: SSO systems require ongoing maintenance to remain secure and functional.
‍

Additional SSO Implementation Considerations

Starting A Login

Determine how and where users begin their authentication journey, as this impacts the user experience, security, and technical implementation. In particular, considerations for SSO built using SAML include:

• IdP-Initiated Flows: Users start at the identity provider and select which application to access after authentication.
• SP-Initiated Flows: Users start at the service provider (application), which redirects to the IdP for authentication; this is the recommended option because it is more secure.

OIDC is more straightforward and usually begins with creating a correct authorization URL pointing to the OP.

Why It Matters: The initiation point affects user journeys, security, and bookmarking.

Deep Linking

Often a user will log in after interacting with an application. For example, a user might browse to a page of an ecommerce site and then want to log in to purchase or save the item. 

Make sure you support deep linking, which enables users to access specific application states after authentication, rather than the default landing page.

Why It Matters: Deep linking support minimizes the disruption of the user experience after logging in. 

User Provisioning Strategies

You can’t SSO without a user account. Select appropriate user provisioning methods based on your requirements:

• Self-service Registration: Allow users to create accounts in applications by providing profile information and credentials; if allowed consider some kind of verification.
• Just-in-Time (JIT) Provisioning: Create user accounts in applications automatically during first login; the application trusts the OP.
• SCIM (System for Cross-domain Identity Management): Use this standardized API-based provisioning to provision users from an external identity store.

Why It Matters: Effective provisioning strategies make sure users have appropriate access across applications without human effort.

Account Linking and Identity Federation

Establish a strategy for managing users with multiple identities across different systems.

This is more important if you are using federation rather than pure SSO.

• Account Linking: connect separate user accounts based on verified claims like email or phone number
• Identity Mapping: maintain relationships, including immutable identifiers, between different identity providers for the same user
• Conflict Resolution: define procedures for handling duplicate or conflicting user information; this may be manual 

Why It Matters: Customers, if offered multiple identity stores, may log in using different ones at different times. They may not remember which one they used. Work to provide a consistent experience.

Step-Up Authentication

When something is doing a risky action, simply being authenticated may not be enough. You can implement contextual security measures that adapt to risk levels and resource sensitivity:

• Risk-Based Authentication: adjust login requirements based on user behavior, location, or device
• Progressive Authentication: start with minimal friction and increase security by requiring additional credentials or actions for sensitive operations
• Authentication Level Mapping: define which resources require which levels of authentication assurance

Why It Matters: Step-up authentication balances security and user experience by applying appropriate protection levels. This might be useful when a financial application allows general account access with a password but requires biometric verification before initiating transfers above a certain threshold or to a new recipient.

Account Recovery and Self-Service

Design robust account recovery flows that maintain security while preventing as many instances of user lockout as possible:

• Multi-Channel Verification: use multiple communication channels or authentication methods to verify user identity during recovery
• Recovery Token Lifecycle: minimize timeframes and usage limits for recovery credentials
• Self-Service Options: provide user-friendly tools for password resets and account unlocking while balancing this operation with security
• Delegated Recovery: allow trusted administrators to assist with account recovery; providing a phone number is nice

Why It Matters: Without secure recovery options, users may be permanently locked out of their accounts or vulnerable to account takeover attacks
‍

Ready to take control of SSO, user identity and access management?

Get started with FusionAuth for free today and experience the power of a developer-focused CIAM solution. With a comprehensive API, customizable workflows, and robust security features, FusionAuth gives you the flexibility and control you need to build secure and engaging user experiences.

Get Started