Passwordless authentication guide

What is passwordless

Passwordless authentication allows a user to prove their identity without a password.

With FusionAuth, passwordless authentication is by default implemented with a one use, timebound code, delivered by email. However, that is not the only option. If you need more customization, you can use the passwordless API to generate a code. Then you may deliver it by another method, such as an SMS or push notification.

This guide will cover the FusionAuth passwordless authentication implementation including standard configuration, APIs you may use to build a custom experience, and system settings.

Here’s a video showing the default passwordless process in FusionAuth:

When does it make sense

Passwordless authentication eases a user’s sign-in experience. Rather than having to remember which password they used, a user gives their email address and is sent a link. When they click through, they are authenticated.

In addition to being easier for users, a passwordless login experience prevents them from reusing the same password across different sites or applications. No longer will you worry about another website’s data breach causing illicit access to your system. In addition, password brute forcing is no longer a threat since the codes are one-time use.

Setting up for passwordless

If you are planning to use passwordless, you have two options. The first option you can use is the FusionAuth OAuth interface. FusionAuth’s OAuth interface is customizable via themes to make each of the web pages look like your application. The other option is using the passwordless API. Let’s look at each in turn.

In either case, you should:

• Configure your SMTP server settings under Tenants → Email. If you are testing this flow out locally, you may want to use mailcatcher

• Create an application

• Turn on "Passwordless Login" under the "Security" tab of the application configuration:

  

• Add a user and register them with your application. Make sure you register a valid email address

Since, by default, passwordless authentication requires email delivery, ensure FusionAuth is correctly configured to send email. One way to test email delivery is by creating a user and sending them a password setup email.

Using the FusionAuth OAuth interface

Choose the FusionAuth OAuth interface approach if you want to use the Authorization Code grant. Enabling passwordless adds an option for a user to receive a one-time code. Because this is the Authorization Code grant, any library or framework that supports this OAuth grant will work.

To use this option:

• Go to your application configuration page in the administration UI

• Configure the OAuth redirect URL as you would with any application where users authenticate password (more on OAuth config here). Make sure the Authorization Code grant is an enabled grant

Now you’re done with configuration.

To test out how your users would experience this:

As soon as the link is clicked, the user has begun an Authorization Code grant. You can consume the authorization code using a library or your own code. Whatever you would normally do if someone signed in with a password, you can now do here. This means that you’ll be provided with the same refresh tokens, user data, or JWTs that would be delivered if the user had signed in with a password.

To customize the look of the login pages, use themes. While editing the theme, you could remove the username/password form. This would force everyone to use passwordless authentication.

Since changing a theme modifies it across all applications in a tenant, this might also affect the FusionAuth admin application (if the new application is in the default tenant) and other applications in the same tenant. If you want to hide the username/password form on an application by application basis, you can use separate tenants or add logic to your theme to hide parts of the HTML based on the client_id.

Using the API directly

While using the FusionAuth OAuth interface works for many, you may need more control. You can use the passwordless API to authenticate a user with a one-time code. The passwordless API reference docs cover each of the API calls, but this guide will walk you through an implementation.

There are a couple of reasons you might choose this method of integration.

• You can customize every part of the user login experience

• You can send the code using a different method such as a text message or Slack direct message

When using this option, you must set up an API key with the appropriate permissions. The minimum level of privilege required is the POST permission to the /api/passwordless/start endpoint.

API_KEY=...
REQUEST_PAYLOAD='{...}'
curl  -H "Content-type: application/json" -H "Authorization: $API_KEY" https://local.fusionauth.io/api/passwordless/start -d $REQUEST_PAYLOAD

{
  "applicationId": "10000000-0000-0002-0000-000000000001",
  "loginId": "jared@piedpiper.com",
  "state": {
    "client_id": "10000000-0000-0002-0000-000000000001",
    "redirect_uri": "https://piedpiper.com/callback",
    "response_type": "code",
    "scope": "openid",
    "state": "CSRF123"
  }
}

{ "cart_id" : 1234 }

{
  "code" : "CynAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}

{
  "code" : "CynAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "state": {
    "client_id": "10000000-0000-0002-0000-000000000001",
    "redirect_uri": "https://piedpiper.com/callback",
    "response_type": "code",
    "scope": "openid",
    "state": "CSRF123"
  },
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

Two factor authentication

You can use FusionAuth passwordless authentication in combination with two-factor authentication.

When two-factor authentication is enabled for a user, after the one-time code has been provided they are prompted to provide an additional two-factor verification code.

Learn more about setting up two-factor authentication.

{"twoFactorId":"VnNILnXs_EDG-cjwokwITRApmAxCMkojeT3CUqqLhLc"}

Customizing passwordless

You can configure the FusionAuth passwordless implementation to meet your application’s needs in a number of ways.

Templates

If you are using the FusionAuth provided email templates, whether you are using the standard FusionAuth user interface or the /api/passwordless/send call, you will need to customize them. Since the template references "FusionAuth", duplicate the template:

Then modify it with your branding and messaging.

Configure the tenant email template settings to use your passwordless login template.

When customizing, you can use any Apache FreeMarker built-ins within the template. Make sure you modify both the HTML and text templates. Here are the default templates:

The default passwordless HTML template

[#setting url_escaping_charset="UTF-8"]
You have requested to log into FusionAuth using this email address. If you do not recognize this request please ignore this email.
<p>
  [#-- The optional 'state' map provided on the Start Passwordless API call is exposed in the template as 'state' --]
  [#assign url = "http://localhost:9011/oauth2/passwordless/${code}?tenantId=${user.tenantId}" /]
  [#list state!{} as key, value][#if key != "tenantId" && value??][#assign url = url + "&" + key?url + "=" + value?url/][/#if][/#list]
  <a href="${url}">${url}</a>
</p>
- FusionAuth Admin

The default passwordless text template

[#setting url_escaping_charset="UTF-8"]
You have requested to log into FusionAuth using this email address. If you do not recognize this request please ignore this email.

[#-- The optional 'state' map provided on the Start Passwordless API call is exposed in the template as 'state' --]
[#assign url = "http://localhost:9011/oauth2/passwordless/${code}?tenantId=${user.tenantId}" /]
[#list state!{} as key, value][#if key != "tenantId" && value??][#assign url = url + "&" + key?url + "=" + value?url/][/#if][/#list]

${url}

- FusionAuth Admin

You can localize the template as well:

Here is more information about email templates.

One time code customization

You can modify the lifetime of the code delivered to users. By default it is 180 seconds; change this in the tenant settings:

You can also change the type of the code generated. For example, you may want your code to be only alphanumeric characters.

You may change your code length or generation strategy for security or user experience reasons. You may have requirements that specify a certain code length. If you deliver the code by text message, having a user enter a six digit alphanumeric code sent to them by SMS is a lot easier than a 64 byte string.

You have the following options for the code generation strategy:

• alphabetic characters

• alphanumeric characters

• bytes

• digits

Consult the tenant API documentation for the length limits, which vary based on the strategy.

Security

With passwordless authentication, if the user’s email account is hijacked, their account on your system is compromised. However, many organizations have security policies and protections around email accounts. It is often easier to protect and regularly change one email account password than to change all of a user’s passwords. Email accounts are also more likely to have two-factor authentication enabled.

One way to increase the security of your passwordless authentications is to decrease the lifetime of the code. This will help if the email is compromised or accidentally forwarded.

There are no limits on how many passwordless requests can be made for a user, but only the most recent code is valid. Using any of the others, even if they have not yet expired, will display an Invalid login credentials message to the user.

If someone tries to log in with an email that is not present in the FusionAuth user database, they’ll see the same notification as they would if the email existed. No email will be sent.

If you use the passwordless API, follow the principle of least privilege, and limit the calls to which the API key has access. If you are using the API key only for passwordless login, then don’t give this key any other permissions.