Eiji Kitamura on web.dev

Sign in with a passkey through form autofill

2022-10-12T00:00:00Z

Passkeys replace passwords and make user accounts on the web safer, simpler, easier to use. However, the transition from password-based to passkey-based authentication can complicate the user experience. Using form autofill to suggest passkeys can help create a unified experience.

With a passkey, a user can sign in to a website just by using fingerprint, face, or device PIN.

Ideally, there would be no password users and the authentication flow could be as simple as a single sign-in button. When the user taps the button, an account selector dialog pops up, the user can pick an account, unlock the screen to verify and sign in.

However, the transition from password to passkey-based authentication can be challenging. As users switch to passkeys, there will still be those who use passwords and websites will need to accommodate both types of users. Users themselves should not be expected to remember on which sites they've switched to passkeys, so asking users to select which method to use up front would be poor UX.

Passkeys are also a new technology. Explaining them and making sure users are comfortable using them can be a challenge for websites. We can rely on familiar user experiences for autofilling passwords to solve both problems.

Conditional UI #

To build an efficient user experience for both passkey and password users, you can include passkeys in autofill suggestions. This is called conditional UI and it's a part of the WebAuthn standard.

As soon as the user taps on the username input field, an autofill suggestion dialog pops up which highlights the stored passkeys along with password autofill suggestions. The user can then choose an account and use the device screen lock to sign in.

This way, users can sign in to your website with the existing form as if nothing has changed, but with the added security benefit of passkeys if they have one.

How it works #

To authenticate with a passkey, you use the WebAuthn API.

The four components in a passkey authentication flow are: the user:

Backend: Your backend server that holds the accounts database storing the public key and other metadata about the passkey.
Frontend: Your frontend which communicates with the browser and sends fetch requests to the backend.
Browser: The user's browser which is running your Javascript.
Authenticator: The user's authenticator which creates and stores the passkey. This may be on the same device as the browser (e.g. when using Windows Hello) or on another device, like a phone.

As soon as a user lands on the frontend, it requests a challenge from the backend to authenticate with a passkey and calls navigator.credentials.get() to initiate authenticating with a passkey. This returns a Promise.
When the user puts the cursor in the sign-in field, the browser displays a password autofill dialog including passkeys. An authentication dialog appears if the user selects a passkey.
After the user verifies their identity using the device's screen lock, the promise is resolved and a public key credential is returned to the frontend.
The frontend sends the public key credential to the backend. The backend verifies the signature against the matched account's public key in the database. If it succeeds, the user is signed in.

Prerequisites #

Conditional WebAuthn UI is publicly supported in Safari on iOS 16, iPadOS 16 and macOS Ventura. It's also available on Chrome on Android, macOS and Windows 11 22H2.

Authenticate with a passkey through form autofill #

When a user wants to sign in, you can make a conditional WebAuthn get call to indicate that passkeys may be included in autofill suggestions. A conditional call to WebAuthn's navigator.credentials.get() API does not show UI and remains pending until the user picks an account to sign-in with from the autofill suggestions. If the user picks a passkey the browser will resolve the promise with a credential rather than filling in the sign-in form. It's then the page's responsibility to sign the user in.

Annotate form input field #

Add an autocomplete attribute to the username input field, if needed. Append username and webauthn as its tokens to let it suggest passkeys.

<input type="text" name="username" autocomplete="username webauthn" ...>

Feature detection #

Before invoking a conditional WebAuthn API call, check if:

The browser supports WebAuthn.
The browser supports WebAuthn conditional UI.

// Availability of `window.PublicKeyCredential` means WebAuthn is usable.  
if (window.PublicKeyCredential &&  
    PublicKeyCredential.isConditionalMediationAvailable) {  
  // Check if conditional mediation is available.  
  const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();  
  if (isCMA) {  
    // Call WebAuthn authentication  
  }  
}

Fetch a challenge from the RP server #

Fetch a challenge from the RP server that is required to call navigator.credentials.get():

challenge: A server-generated challenge in an ArrayBuffer. This is required to prevent replay attacks. Make sure to generate a new challenge on every sign-in attempt and disregard it after a certain duration or after a sign-in attempt fails to validate. Consider it like a CSRF token.
allowCredentials: An array of acceptable credentials for this authentication. Pass an empty array to let the user select an available passkey from a list shown by the browser.
userVerification: Indicates whether user verification using the device screen lock is "required", "preferred" or "discouraged". The default is "preferred", which means the authenticator may skip user verification. Set this to "preferred" or omit the property.

Call WebAuthn API with the `conditional` flag to authenticate the user #

Call navigator.credentials.get() to start waiting for the user authentication.

// To abort a WebAuthn call, instantiate an `AbortController`.  
const abortController = new AbortController();

const publicKeyCredentialRequestOptions = {  
  // Server generated challenge  
  challenge: ****,  
  // The same RP ID as used during registration  
  rpId: 'example.com',  
};

const credential = await navigator.credentials.get({  
  publicKey: publicKeyCredentialRequestOptions,  
  signal: abortController.signal,  
  // Specify 'conditional' to activate conditional UI  
  mediation: 'conditional'  
});

rpId: An RP ID is a domain and a website can specify either its domain or a registrable suffix. This value must match the rp.id used when the passkey was created.

Remember to specify mediation: 'conditional' to make the request conditional.

Send the returned public key credential to the RP server #

After the user selects an account and consents using the device's screen lock, the promise is resolved returning a PublicKeyCredential object to the RP frontend.

A promise can be rejected due to several different reasons. You need to handle the errors accordingly, depending on the Error object's name property:

NotAllowedError: The user has canceled the operation.
Other exceptions: Something unexpected happened. The browser shows an error dialog to the user.

The public key credential object contains the following properties:

id: The base64url encoded ID of the authenticated passkey credential.
rawId: An ArrayBuffer version of the credential ID.
response.clientDataJSON: An ArrayBuffer of client data. This field contains information such as the challenge and the origin that the RP server will need to verify.
response.authenticatorData: An ArrayBuffer of authenticator data. This field contains information such as the RP ID.
response.signature: An ArrayBuffer of the signature. This value is the core of the credential and needs to be verified on the server.
response.userHandle: An ArrayBuffer that contained the user ID that was set at creation time. This value can be used, instead of the credential ID, if the server needs to pick the ID values that it uses, or if the backend wishes to avoid creating an index on credential IDs.
authenticatorAttachment: Returns platform when this credential came from the local device. Otherwise cross-platform, notably when the user used a phone to sign in. If the user needed to use a phone to sign-in, consider prompting them to create a passkey on the local device.
type: This field is always set to "public-key".

If you use a library to handle the public-key credential object on the RP server, we recommend that you send the entire object to the server after encoding it partially with base64url.

Verify the signature #

When you receive the public key credential on the server, pass it to the FIDO library to process the object.

Look up the matching credential ID with the id property (If you need to determine the user account, use the userHandle property which is the user.id you specified when creating the credential). See if the credential's signature can be verified with the stored public key. To do so, we recommend using a server side library or a solution instead of writing your own code. You can find open source libraries in the awesome-webauth GitHub repo.

Once the credential is verified with a matching public key, sign the user in.

Resources #

Create a passkey for passwordless logins

2022-10-12T00:00:00Z

Using passkeys instead of passwords is a great way for websites to make their user accounts safer, simpler, easier to use and passwordless. With a passkey, a user can sign in to a website or an app just by using their fingerprint, face or device PIN.

A passkey has to be created, associated with a user account and have its public key be stored on your server before a user can sign in with it.

How it works #

A user can be asked to create a passkey in one of the following situations:

When a user signs in using a password, or a passkey from another device (that is, the authenticatorAttachment is cross-platform).
On a dedicated page where users can manage their passkeys.

To create a passkey, you use the WebAuthn API.

The four components of the passkey registration flow are:

Backend: Your backend server that holds the accounts database storing the public key and other metadata about the passkey.
Frontend: Your frontend which communicates with the browser and sends fetch requests to the backend.
Browser: The user's browser which is running your Javascript.
Authenticator: The user's authenticator which creates and stores the passkey. This may be on the same device as the browser (for example, when using Windows Hello) or on another device, like a phone.

The journey to add a new passkey to an existing user account is as follows:

A user signs in to the website.
Once the user is signed in, they request to create a passkey on the frontend, for example, by pressing a "Create a passkey" button.
The frontend requests information from the backend to create a passkey, such as user information, a challenge, and the credential IDs to exclude.
The frontend calls navigator.credentials.create() to create a passkey. This call returns a promise.
A passkey is created after the user consents using the device's screen lock. The promise is resolved and a public key credential is returned to the frontend.
The frontend sends the public key credential to the backend and stores the credential ID and the public key associated with the user account for future authentications.

Compatibilities #

WebAuthn is supported by most browsers, but there are small gaps. Refer to Device Support - passkeys.dev to learn what combination of browsers and an operating systems support creating a passkey.

Create a new passkey #

Here's how a frontend should operate upon a request to create a new passkey.

Feature detection #

Before displaying a "Create a new passkey" button, check if:

The browser supports WebAuthn.
The device supports a platform authenticator (can create a passkey and authenticate with the passkey).
The browser supports WebAuthn conditional UI.

// Availability of `window.PublicKeyCredential` means WebAuthn is usable.  
// `isUserVerifyingPlatformAuthenticatorAvailable` means the feature detection is usable.  
// `isConditionalMediationAvailable` means the feature detection is usable.  
if (window.PublicKeyCredential &&  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable &&  
    PublicKeyCredential.isConditionalMediationAvailable) {  
  // Check if user verifying platform authenticator is available.  
  Promise.all([  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(),  
    PublicKeyCredential.isConditionalMediationAvailable(),  
  ]).then(results => {  
    if (results.every(r => r === true)) {  
      // Display "Create a new passkey" button  
    }  
  });  
}

Until all the conditions have been met, passkeys will not be supported on this browser. The "Create a new passkey" button shouldn't be displayed until then.

Fetch important information from the backend #

When the user clicks the button, fetch important information to call navigator.credentials.create() from the backend:

challenge: A server-generated challenge in ArrayBuffer for this registration. This is required but unused during registration unless doing attestation—an advanced topic not covered here.
user.id: A user's unique ID. This value must be an ArrayBuffer which does not include personally identifying information, for example, e-mail addresses or usernames. A random, 16-byte value generated per account will work well.
user.name: This field should hold a unique identifier for the account that the user will recognise, like their email address or username. This will be displayed in the account selector. (If using a username, use the same value as in password authentication.)
user.displayName: This field is an optional, more user-friendly name for the account. It need not be unique and could be the user's chosen name. If your site does not have a suitable value to include here, pass an empty string. This may be displayed on the account selector depending on the browser.
excludeCredentials: Prevents registering the same device by providing a list of already registered credential IDs. The transports member, if provided, should contain the result of calling getTransports() during the registration of each credential.

Call WebAuthn API to create a passkey #

Call navigator.credentials.create() to create a new passkey. The API returns a promise, waiting for the user's interaction displaying a modal dialog.

const publicKeyCredentialCreationOptions = {  
  challenge: *****,  
  rp: {  
    name: "Example",  
    id: "example.com",  
  },  
  user: {  
    id: *****,  
    name: "john78",  
    displayName: "John",  
  },  
  pubKeyCredParams: [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}],  
  excludeCredentials: [{  
    id: *****,  
    type: 'public-key',  
    transports: ['internal'],  
  }],  
  authenticatorSelection: {  
    authenticatorAttachment: "platform",  
    requireResidentKey: true,  
  }  
};

const credential = await navigator.credentials.create({  
  publicKey: publicKeyCredentialCreationOptions  
});

// Encode and send the credential to the server for verification.

The parameters not explained above are:

rp.id: An RP ID is a domain and a website can specify either its domain or a registrable suffix. For example, if an RP's origin is https://login.example.com:1337, the RP ID can be either login.example.com or example.com. If the RP ID is specified as example.com, the user can authenticate on login.example.com or on any subdomains on example.com.
rp.name: The RP's name.
pubKeyCredParams: This field specifies the RP's supported public-key algorithms. We recommend setting it to [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}]. This specifies support for ECDSA with P-256 and RSA PKCS#1 and supporting these gives complete coverage.
authenticatorSelection.authenticatorAttachment: Set it to "platform". This indicates that we want an authenticator that is embedded into the platform device, and the user will not be prompted to insert e.g. a USB security key.
authenticatorSelection.requireResidentKey: Set it to a boolean "true". A discoverable credential (resident key) stores user information to the passkey and lets users select the account upon authentication.
authenticatorSelection.userVerification: Indicates whether a user verification using the device screen lock is "required", "preferred" or "discouraged". The default is "preferred", which means the authenticator may skip user verification. Set this to "preferred" or omit the property.

Send the returned public key credential to the backend #

After the user consents using the device's screen lock, a passkey is created and the promise is resolved returning a PublicKeyCredential object to the frontend.

The promise can be rejected for different reasons. You can handle these errors by checking the Error object's name property:

InvalidStateError: A passkey already exists on the device. No error dialog will be shown to the user and the site should not treat this as an error—the user wanted the local device registered and it is.
NotAllowedError: The user has canceled the operation.
Other exceptions: Something unexpected happened. The browser shows an error dialog to the user.

The public key credential object contains the following properties:

id: A Base64URL encoded ID of the created passkey. This ID helps the browser to determine whether a matching passkey is in the device upon authentication. This value needs to be stored in the database on the backend.
rawId: An ArrayBuffer version of the credential ID.
response.clientDataJSON: An ArrayBuffer encoded client data.
response.attestationObject: An ArrayBuffer encoded attestation object. This contains important information such as an RP ID, flags and a public key.
authenticatorAttachment: Returns "platform" when this credential is created on a passkey capable device.
type: This field is always set to "public-key".

If you use a library to handle the public key credential object on the backend, we recommend sending the entire object to the backend after encoding it partially with base64url.

Save the credential #

Upon receiving the public key credential on the backend, pass it to the FIDO library to process the object.

You can then store the information retrieved from the credential to the database for future use. The following list includes some typical properties to save:

Credential ID (Primary key)
User ID
Public key

The public-key credential also includes the following information that you may want to save in the database:

Backup Eligibility flag: true if the device is eligible for passkey synchronization.
Backup State flag: true if the created passkey is actually set to be synchronized.
Transports: A list of transports the device supports: "internal" means the device supports a passkey, "hybrid" means it also supports authentication on another device.

To authenticate the user, read Sign in with a passkey through form autofill.

Resources #

Yahoo! JAPAN's password-free authentication reduced inquiries by 25%, sped up sign-in time by 2.6x

2022-05-10T00:00:00Z

Yahoo! JAPAN is one of the largest media companies in Japan, providing services such as search, news, e-commerce, and e-mail. Over 50 million users log in to Yahoo! JAPAN services every month.

Over the years, there were many attacks on user accounts and issues that led to lost account access. Most of these issues were related to password usage for authentication.

With recent advances in authentication technology, Yahoo! JAPAN has decided to move from password-based to passwordless authentication.

Why passwordless? #

As Yahoo! JAPAN offers e-commerce and other money-related services, there's a risk of significant damage to users in the event of unauthorized access or account loss.

The most common attacks related to passwords were password list attacks and phishing scams. One of the reasons why password list attacks are common and effective is many people's habit of using the same password for multiple applications and websites.

The following figures are the results of a survey conducted by Yahoo! JAPAN.

50 _%

use the same ID and password on six or more sites

60 _%

Use the same password across multiple sites

70 _%

use a password as the primary way to login

Users often forget their passwords, which accounted for the majority of password-related inquiries. There were also inquiries from users who had forgotten their login IDs in addition to their passwords. At their peak, these inquiries accounted for more than a third of all account-related inquiries.

By going passwordless, Yahoo! JAPAN aimed to improve not only security, but also usability, without placing any extra burden on users.

From a security perspective, eliminating passwords from the user authentication process reduces the damage from list-based attacks, and from a usability perspective, providing an authentication method that does not rely on remembering passwords prevents situations where a user is unable to login because they forgot their password.

Yahoo! JAPAN's passwordless initiatives #

Yahoo! JAPAN is taking a number of steps to promote passwordless authentication, which can be broadly divided into three categories:

Provide an alternative means of authentication to passwords.
Password deactivation.
Passwordless account registration.

The first two initiatives aimed at existing users, while passwordless registration is aimed at new users.

1. Providing an alternative means of authentication to passwords #

Yahoo! JAPAN offers the following alternatives to passwords.

In addition, we also offer authentication methods such as e-mail authentication, password combined with SMS OTP (one time password), and password combined with email OTP.

SMS authentication #

SMS authentication is a system which allows a registered user to receive a six-digit authentication code through SMS. Once the user receives the SMS, they can enter the authentication code in the app or website.

Apple has long allowed iOS to read SMS messages and suggest authentication codes from the text body. Recently, it's become possible to use suggestions by specifying "one-time-code" in the autocomplete attribute of the input element. Chrome on Android, Windows, and Mac can provide the same experience using the WebOTP API.

For example:

<form>
  <input type="text" id="code" autocomplete="one-time-code"/>
  <button type="submit">sign in</button>
</form>

if ('OTPCredential' in window) {
  const input = document.getElementById('code');
  if (!input) return;
  const ac = new AbortController();
  const form = input.closest('form');
  if (form) {
    form.addEventListener('submit', e => {
      ac.abort();
    });
  }
  navigator.credentials.get({
    otp: { transport:['sms'] },
    signal: ac.signal
  }).then(otp => {
    input.value = otp.code;
  }).catch(err => {
    console.log(err);
  });
}

Both approaches are designed to prevent phishing by including the domain in the SMS body and providing suggestions only for the specified domain.

For more information about the WebOTP API and autocomplete="one-time-code", check out SMS OTP form best practices.

FIDO with WebAuthn #

FIDO with WebAuthn uses a hardware authenticator to generate a public key cipher pair and prove possession. When a smartphone is used as the authenticator, it can be combined with biometric authentication (such as fingerprint sensors or facial recognition) to perform one-step two-factor authentication. In this case, only the signature and the success indication from the biometric authentication are sent to the server, so there is no risk of biometric data theft.

The following diagram shows the server-client configuration for FIDO. The client authenticator authenticates the user with biometrics and signs the result using public key cryptography. The private key used to create the signature is securely stored in a TEE (Trusted Execution Environment) or similar location. A service provider that uses FIDO is called an RP (relying party).

Once the user performs the authentication (commonly with a biometric scan or PIN), the authenticator uses a private key to send a signed verification signal to the browser. The browser then shares that signal with the RP's website.

The RP website then sends the signed verification signal to the RP's server, which verifies the signature against the public key to complete the authentication.

For more information, read authentication guidelines from the FIDO Alliance.

Yahoo! JAPAN supports FIDO on Android (mobile app and web), iOS (mobile app and web), Windows (Edge, Chrome, Firefox), and macOS (Safari, Chrome). As a consumer service, FIDO can be used on almost any device, which makes it a good option for promoting passwordless authentication.

Operating System	Support for FIDO
Android	Apps, Browser (Chrome)
iOS	Apps (iOS14 or later), Browser (Safari 14 or later)
Windows	Browser (Edge, Chrome, Firefox)
Mac (Big Sur or later)	Browser (Safari, Chrome)

Sample Yahoo! JAPAN prompt to authenticate with FIDO.

Yahoo! JAPAN recommends that users register for FIDO with WebAuthn, if they've not already authenticated through other means. When a user needs to log in with the same device, they can quickly authenticate using a biometric sensor.

Users must set up FIDO authentication with all devices they use to log in to Yahoo! JAPAN.

To promote passwordless authentication and be considerate of users who are transitioning away from passwords, we provide multiple means of authentication. This means that different users can have different authentication method settings, and the authentication methods they can use may differ from browser to browser. We believe it's a better experience if users log in using the same authentication method each time.

To meet these requirements, it's necessary to track previous authentication methods and link this information to the client by storing it in the form of cookies, etc. We can then analyze how different browsers and applications are used for authentication. The user is asked to provide appropriate authentication based on the user's settings, the previous authentication methods used, and the minimum level of authentication required.

2. Password deactivation #

Yahoo! JAPAN asks users to set up an alternative authentication method and then disable their password so that it cannot be used. In addition to setting up alternative authentication, disabling password authentication (therefore making it impossible to sign in with only a password) helps protect users from list-based attacks.

We've taken the following steps to encourage users to disable their passwords.

Promoting alternative authentication methods when users reset their passwords.
Encouraging users to set up easy-to-use authentication methods (such as FIDO) and disable passwords for situations that require frequent authentication.
Urging users to disable their passwords before using high-risk services, such as e-commerce payments.

If a user forgets their password, they can run an account recovery. Previously this involved a password reset. Now, users can choose to set up a different authentication method, and we encourage them to do so.

3. Passwordless account registration #

New users can create password-free Yahoo! JAPAN accounts. Users are first required to register with an SMS authentication. Once they've logged in, we encourage the user to set up FIDO authentication.

Since FIDO is a per-device setting, it can be difficult to recover an account, should the device become inoperable. Therefore, we require users to keep their phone number registered, even after they've set up additional authentication.

Key challenges for passwordless authentication #

Passwords rely on human memory and are device-independent. On the other hand, the authentication methods introduced thus far in our passwordless initiative are device-dependent. This poses several challenges.

When multiple devices are used, there are some issues related to usability:

When using SMS authentication to log in from a PC, users must check their mobile phone for incoming SMS messages. This may be inconvenient, as it requires the user's phone to be available and easy to access at any time.
With FIDO, especially with platform authenticators, a user with multiple devices will be unable to authenticate on unregistered devices. Registration must be completed for each device they intend to use.

FIDO authentication is tied to specific devices, which requires they remain in the user's possession and active.

If the service contract is canceled, it will no longer be possible to send SMS messages to the registered phone number.
FIDO stores private keys on a specific device. If the device is lost, those keys are unusable.

Yahoo! JAPAN is taking various steps to address these problems.

The most important solution is to encourage users to set up multiple authentication methods. This provides alternative account access when devices are lost. Since FIDO keys are device-dependent, it is also good practice to register FIDO private keys on multiple devices.

Alternatively, users can use the WebOTP API to pass SMS verification codes from an Android phone to Chrome on a PC.

We believe that addressing these issues will become even more important as passwordless authentication spreads.

Promoting passwordless authentication #

Yahoo! JAPAN has been working on these passwordless initiatives since 2015. This began with the acquisition of FIDO server certification in May 2015, followed by the introduction of SMS authentication, a password deactivation feature, and FIDO support for each device.

Today, more than 30 million monthly active users have already disabled their passwords and are using non-password authentication methods. Yahoo! JAPAN's support for FIDO started with Chrome on Android, and now more than 10 million users have set up FIDO authentication.

As a result of Yahoo! JAPAN's initiatives, the percentage of inquiries involving forgotten login IDs or passwords has decreased by 25% compared to the period when the number of such inquiries was at its highest, and we have also been able to confirm that unauthorized access has declined as a result of the increase in the number of passwordless accounts.

Since FIDO is so easy to set up, it has a particularly high conversion rate. In fact, Yahoo! JAPAN has found that FIDO has a higher CVR than SMS authentication.

25 _%

Decrease in requests for forgotten credentials

74 _%

Users succeed with FIDO authentication

65 _%

Succeed with SMS verification

FIDO has a higher success rate than SMS authentication, and faster average and median authentication times. As for passwords, some groups have short authentication times, and we suspect that this is due to the browser's autocomplete="current-password".

On average, FIDO takes 8 seconds to authenticate, while passwords take 21 seconds, and SMS verification takes 27.

The greatest difficulty for offering passwordless accounts is not the addition of authentication methods, but popularizing the use of authenticators. If the experience of using a passwordless service is not user-friendly, the transition will not be easy.

We believe that to achieve improved security we must first improve usability, which will require unique innovations for each service.

Conclusion #

Password authentication is risky in terms of security, and it also poses challenges in terms of usability. Now that technologies supporting non-password authentication, such as WebOTP API and FIDO, are more widely available, it's time to start working toward passwordless authentication.

At Yahoo! JAPAN, taking this approach has had a definite effect on both usability and security. However, many users are still using passwords, so we will continue to encourage more users to switch to passwordless authentication methods. We will also continue improving our products to optimize the user experience for passwordless authentication methods.

Photo by olieman.eth on Unsplash

Save Credentials from Forms

2022-02-24T00:00:00Z

Save Credentials from sign-in forms

Keep your registration and sign-in forms as simple as possible.

Save credentials from sign-in forms so users won't have to sign in again when they return.

To store user credentials from forms:

Include autocomplete in the form.
Prevent the form from submitting.
Authenticate by sending a request.
Store the credential.
Update the UI or proceed to the personalized page.

Include `autocomplete` in the form #

Before moving forward, check if your form includes autocomplete attributes. This helps the Credential Management API find the id and password from the form and construct a credential object.

This also helps browsers not supporting the Credential Management API to understand its semantics. Learn more about autofill in this article by Jason Grigsby.

<form id="signup" method="post">
  <input name="email" type="text" autocomplete="username email" />
  <input name="display-name" type="text" autocomplete="name" />
  <input name="password" type="password" autocomplete="new-password" />
  <input type="submit" value="Sign Up!" />
</form>

Prevent the form from submitting #

When the user presses the submit button, prevent the form from submitting, which would otherwise result in a page transition:

    var f = document.querySelector('#signup');
    f.addEventListener('submit', e => {
      e.preventDefault();

By preventing a page transition, you can retain the credential information while verifying its authenticity.

Authenticate by sending a request #

To authenticate the user, deliver credential information to your server using AJAX.

On the server side, create an endpoint (or simply alter an existing endpoint) that responds with HTTP code 200 or 401, so that it’s clear to the browser whether the sign-up/sign-in/change password is successful or not.

For example:

// Try sign-in with AJAX
fetch('/signin', {
  method: 'POST',
  body: new FormData(e.target),
  credentials: 'include',
});

Store the credential #

To store a credential, first check if the API is available, then instantiate a PasswordCredential with the form element as an argument either synchronously or asynchronously. Call navigator.credentials.store(). If the API is not available, you can simply forward the profile information to the next step.

Synchronous example:

if (window.PasswordCredential) {
  var c = new PasswordCredential(e.target);
  return navigator.credentials.store(c);
} else {
  return Promise.resolve(profile);
}

Asynchronous example:

if (window.PasswordCredential) {
  var c = await navigator.credentials.create({password: e.target});
  return navigator.credentials.store(c);
} else {
  return Promise.resolve(profile);
}

Once the request succeeds, store the credential information. (Don't store the credentials information if the request failed as doing so confuses returning users.)

When the Chrome browser obtains credential information, a notification pops up asking to store a credential (or federation provider).

Notification for an auto signed-in user

Update the UI #

If everything went well, update the UI using the profile information, or proceed to the personalized page.

     }).then(profile => {
       if (profile) {
         updateUI(profile);
       }
     }).catch(error => {
       showError('Sign-in Failed');
     });
    });

Full code example #

// Get form's DOM object
var f = document.querySelector('#signup');
f.addEventListener('submit', (e) => {
  // Stop submitting form by itself
  e.preventDefault();

  // Try sign-in with AJAX
  fetch('/signin', {
    method: 'POST',
    body: new FormData(e.target),
    credentials: 'include',
  })
    .then((res) => {
      if (res.status == 200) {
        return Promise.resolve();
      } else {
        return Promise.reject('Sign-in failed');
      }
    })
    .then((profile) => {
      // Instantiate PasswordCredential with the form
      if (window.PasswordCredential) {
        var c = new PasswordCredential(e.target);
        return navigator.credentials.store(c);
      } else {
        return Promise.resolve(profile);
      }
    })
    .then((profile) => {
      // Successful sign-in
      if (profile) {
        updateUI(profile);
      }
    })
    .catch((error) => {
      // Sign-in failed
      showError('Sign-in Failed');
    });
});

Browser compatibility #

`PasswordCredential` #

Browser support

Chrome 51, Supported 51
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

`navigator.credentials.store()` #

Browser support

Chrome 51, Supported 51
Firefox 60, Supported 60
Edge 79, Supported 79
Safari 13, Supported 13

Source

Feedback #

Security headers quick reference

2021-05-18T00:00:00Z

This article lists the most important security headers you can use to protect your website. Use it to understand web-based security features, learn how to implement them on your website, and as a reference for when you need a reminder.

Security headers recommended for websites that handle sensitive user data:: Content Security Policy (CSP); Trusted Types
Security headers recommended for all websites:: X-Content-Type-Options; X-Frame-Options; Cross-Origin Resource Policy (CORP); Cross-Origin Opener Policy (COOP); HTTP Strict Transport Security (HSTS)
Security headers for websites with advanced capabilities:: Cross-Origin Resource Sharing (CORS); Cross-Origin Embedder Policy (COEP)

Known threats on the web

Before diving into security headers, learn about known threats on the web and why you'd want to use these security headers.

Protect your site from injection vulnerabilities #

Injection vulnerabilities arise when untrusted data processed by your application can affect its behavior and, commonly, lead to the execution of attacker-controlled scripts. The most common vulnerability caused by injection bugs is cross-site scripting (XSS) in its various forms, including reflected XSS, stored XSS, DOM-based XSS, and other variants.

An XSS vulnerability can typically give an attacker complete access to user data processed by the application and any other information hosted in the same web origin.

Traditional defenses against injections include consistent use of autoescaping HTML template systems, avoiding the use of dangerous JavaScript APIs, and properly processing user data by hosting file uploads in a separate domain and sanitizing user-controlled HTML.

Use Content Security Policy (CSP) to control which scripts can be executed by your application to mitigate the risk of injections.
Use Trusted Types to enforce sanitization of data passed into dangerous JavaScript APIs.
Use X-Content-Type-Options to prevent the browser from misinterpreting the MIME types of your website's resources, which can lead to script execution.

Isolate your site from other websites #

The openness of the web allows websites to interact with each other in ways that can violate an application's security expectations. This includes unexpectedly making authenticated requests or embedding data from another application in the attacker's document, allowing the attacker to modify or read application data.

Common vulnerabilities that undermine web isolation include clickjacking, cross-site request forgery (CSRF), cross-site script inclusion (XSSI), and various cross-site leaks.

Use X-Frame-Options to prevent your documents from being embedded by a malicious website.
Use Cross-Origin Resource Policy (CORP) to prevent your website's resources from being included by a cross-origin website.
Use Cross-Origin Opener Policy (COOP) to protect your website's windows from interactions by malicious websites.
Use Cross-Origin Resource Sharing (CORS) to control access to your website's resources from cross-origin documents.

Post-Spectre Web Development is a great read if you are interested in these headers.

Build a powerful website securely #

Spectre puts any data loaded into the same browsing context group potentially readable despite same-origin policy. Browsers restrict features that may possibly exploit the vulnerability behind a special environment called "cross-origin isolation". With cross-origin isolation, you can use powerful features such as SharedArrayBuffer.

Use Cross-Origin Embedder Policy (COEP) along with COOP to enable cross-origin isolation.

Encrypt traffic to your site #

Encryption issues appear when an application does not fully encrypt data in transit, allowing eavesdropping attackers to learn about the user's interactions with the application.

Insufficient encryption can arise in the following cases: not using HTTPS, mixed content, setting cookies without the Secure attribute (or __Secure prefix), or lax CORS validation logic.

Use HTTP Strict Transport Security (HSTS) to consisitently serve your contents through HTTPS.

Content Security Policy (CSP) #

Cross-Site Scripting (XSS) is an attack where a vulnerability on a website allows a malicious script to be injected and executed.

Content-Security-Policy provides an added layer to mitigate XSS attacks by restricting which scripts can be executed by the page.

It's recommended that you enable strict CSP using one of the following approaches:

If you render your HTML pages on the server, use a nonce-based strict CSP.
If your HTML has to be served statically or cached, for example if it's a single-page application, use a hash-based strict CSP.

Example usage: A nonce-based CSP

Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

How to use CSP

Recommended usages #

1. Use a nonce-based strict CSP #

If you render your HTML pages on the server, use a nonce-based strict CSP.

Generate a new script nonce value for every request on the server side and set the following header:

server configuration file

Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

In HTML, in order to load the scripts, set the nonce attribute of all <script> tags to the same {RANDOM1} string.

index.html

<script nonce="{RANDOM1}" src="https://example.com/script1.js"></script>
<script nonce="{RANDOM1}">
  // Inline scripts can be used with the `nonce` attribute.
</script>

Google Photos is a good nonce-based strict CSP example. Use DevTools to see how it's used.

2. Use a hash-based strict CSP #

If your HTML has to be served statically or cached, for example if you're building a single-page application, use a hash-based strict CSP.

server configuration file

Content-Security-Policy:
  script-src 'sha256-{HASH1}' 'sha256-{HASH2}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

In HTML, you'll need to inline your scripts in order to apply a hash-based policy, because most browsers don't support hashing external scripts.

index.html

<script>
...// your script1, inlined
</script>
<script>
...// your script2, inlined
</script>

To load external scripts, read "Load sourced scripts dynamically" under Option B: Hash-based CSP Response Header section.

CSP Evaluator is a good tool to evaluate your CSP, but at the same time a good nonce-based strict CSP example. Use DevTools to see how it's used.

Supported browsers #

Browser support

Chrome, Not supported
Firefox, Not supported
Edge, Not supported
Safari, Not supported

Other things to note about CSP #

frame-ancestors directive protects your site from clickjacking—a risk that arises if you allow untrusted sites to embed yours. If you prefer simpler solution, you can use X-Frame-Options to block being loaded, but frame-ancestors gives you an advanced configuration to only allow specific origins as embedders.
You may have used a CSP to ensure that all of your site's resources are loaded over HTTPS. This has become less relevant: nowadays, most browsers block mixed-content.
You can also set a CSP in report-only mode.
If you can't set a CSP as a header server-side, you can also set it as a meta tag. Note that you can't use report-only mode for meta tags (though this may change).

Learn more #

Trusted Types #

DOM-based XSS is an attack where a malicious data is passed into a sink that supports dynamic code execution such as eval() or .innerHTML.

Trusted Types provide the tools to write, security review, and maintain applications free of DOM XSS. They can be enabled via CSP and make JavaScript code secure by default by limiting dangerous web APIs to only accept a special object—a Trusted Type.

To create these objects you can define security policies in which you can ensure that security rules (such as escaping or sanitization) are consistently applied before the data is written to the DOM. These policies are then the only places in code that could potentially introduce DOM XSS.

Example usages

Content-Security-Policy: require-trusted-types-for 'script'

// Feature detection
if (window.trustedTypes && trustedTypes.createPolicy) {
  // Name and create a policy
  const policy = trustedTypes.createPolicy('escapePolicy', {
    createHTML: str => {
      return str.replace(/\</g, '&lt;').replace(/>/g, '&gt;');
    }
  });
}

// Assignment of raw strings is blocked by Trusted Types.
el.innerHTML = 'some string'; // This throws an exception.

// Assignment of Trusted Types is accepted safely.
const escaped = policy.createHTML('<img src=x onerror=alert(1)>');
el.innerHTML = escaped;  // '&lt;img src=x onerror=alert(1)&gt;'

How to use Trusted Types

Recommended usages #

Enforce Trusted Types for dangerous DOM sinks

CSP and Trusted Types header:
```
Content-Security-Policy: require-trusted-types-for 'script'
```
Currently 'script' is the only acceptable value for require-trusted-types-for directive.

Of course, you can combine Trusted Types with other CSP directives:

Merging a nonce-based CSP from above with Trusted Types:
```
Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';
  require-trusted-types-for 'script';
```
You may limit allowed Trusted Types policy names by setting an additional trusted-types directive (for example, trusted-types myPolicy). However, this is not a requirement.

Define a policy

Policy:

// Feature detection
if (window.trustedTypes && trustedTypes.createPolicy) {
  // Name and create a policy
  const policy = trustedTypes.createPolicy('escapePolicy', {
    createHTML: str => {
      return str.replace(/\</g, '&lt;').replace(/>/g, '&gt;');
    }
  });
}

Apply the policy

Use the policy when writing data to the DOM:

// Assignment of raw strings are blocked by Trusted Types.
el.innerHTML = 'some string'; // This throws an exception.

// Assignment of Trusted Types is accepted safely.
const escaped = policy.createHTML('<img src=x onerror=alert(1)>');
el.innerHTML = escaped;  // '&lt;img src=x onerror=alert(1)&gt;'

With require-trusted-types-for 'script', using a trusted type is a requirement. Using any dangerous DOM API with a string will result in an error.

Supported browsers #

Browser support

Chrome, Not supported
Firefox, Not supported
Edge, Not supported
Safari, Not supported

Learn more #

Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types
CSP: require-trusted-types-for - HTTP | MDN
CSP: trusted-types - HTTP | MDN
Trusted Types demo—open DevTools Inspector and see what is happening

X-Content-Type-Options #

When a malicious HTML document is served from your domain (for example, if an image uploaded to a photo service contains valid HTML markup), some browsers will treat it as an active document and allow it to execute scripts in the context of the application, leading to a cross-site scripting bug.

X-Content-Type-Options: nosniff prevents it by instructing the browser that the MIME type set in the Content-Type header for a given response is correct. This header is recommended for all of your resources.

Example usage

X-Content-Type-Options: nosniff

How to use X-Content-Type-Options

Recommended usages #

X-Content-Type-Options: nosniff is recommended for all resources served from your server along with the correct Content-Type header.

Example headers sent with a document HTML

X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8

Supported browsers #

Browser support

Chrome 64, Supported 64
Firefox 50, Supported 50
Edge 12, Supported 12
Safari 11, Supported 11

Source

Learn more #

X-Content-Type-Options - HTTP MDN

X-Frame-Options #

If a malicious website can embed your site as an iframe, this may allow attackers to invoke unintended actions by the user with clickjacking. Also, in some cases Spectre-type attacks give malicious websites a chance to learn about the contents of an embedded document.

X-Frame-Options indicates whether or not a browser should be allowed to render a page in a <frame>, <iframe>, <embed>, or <object>. All documents are recommended to send this header to indicate whether they allow being embedded by other documents.

Example usage

X-Frame-Options: DENY

How to use X-Frame-Options

Recommended usages #

All documents that are not designed to be embedded should use X-Frame-Options header.

You can try how the following configurations affect loading an iframe on this demo. Change the X-Frame-Options dropdown menu and click the Reload the iframe button.

Protects your website from being embedded by any other websites #

Deny being embedded by any other documents.

X-Frame-Options: DENY

Protects your website from being embedded by any cross-origin websites #

Allow being embedded only by same-origin documents.

X-Frame-Options: SAMEORIGIN

Supported browsers #

Browser support

Chrome 4, Supported 4
Firefox 4, Supported 4
Edge 12, Supported 12
Safari 4, Supported 4

Source

Learn more #

X-Frame-Options - HTTP

Cross-Origin Resource Policy (CORP) #

An attacker can embed resources from another origin, for example from your site, to learn information about them by exploiting web-based cross-site leaks.

Cross-Origin-Resource-Policy mitigates this risk by indicating the set of websites it can be loaded by. The header takes one of three values: same-origin, same-site, and cross-origin. All resources are recommended to send this header to indicate whether they allow being loaded by other websites.

Example usage

Cross-Origin-Resource-Policy: same-origin

How to use CORP

Recommended usages #

It is recommended that all resources are served with one of the following three headers.

You can try how the following configurations affect loading resources under a Cross-Origin-Embedder-Policy: require-corp environment on this demo. Change the Cross-Origin-Resource-Policy dropdown menu and click the Reload the iframe or Reload the image button to see the effect.

Allow resources to be loaded `cross-origin` #

It's recommended that CDN-like services apply cross-origin to resources (since they are usually loaded by cross-origin pages), unless they are already served through CORS which has a similar effect.

Cross-Origin-Resource-Policy: cross-origin

Limit resources to be loaded from the `same-origin` #

same-origin should be applied to resources that are intended to be loaded only by same-origin pages. You should apply this to resources that include sensitive information about the user, or responses of an API that is intended to be called only from the same origin.

Keep in mind that resources with this header can still be loaded directly, for example by navigating to the URL in a new browser window. Cross-Origin Resource Policy only protects the resource from being embedded by other websites.

Cross-Origin-Resource-Policy: same-origin

Limit resources to be loaded from the `same-site` #

same-site is recommended to be applied to resources that are similar to above but are intended to be loaded by other subdomains of your site.

Cross-Origin-Resource-Policy: same-site

Supported browsers #

Browser support

Chrome 73, Supported 73
Firefox 74, Supported 74
Edge 79, Supported 79
Safari 12, Supported 12

Source

Learn more #

Cross-Origin Opener Policy (COOP) #

An attacker's website can open another site in a popup window to learn information about it by exploiting web-based cross-site leaks. In some cases, this may also allow the exploitation of side-channel attacks based on Spectre.

The Cross-Origin-Opener-Policy header provides a way for a document to isolate itself from cross-origin windows opened through window.open() or a link with target="_blank" without rel="noopener". As a result, any cross-origin opener of the document will have no reference to it and will not be able to interact with it.

Example usage

Cross-Origin-Opener-Policy: same-origin-allow-popups

How to use COOP

Recommended usages #

You can try how the following configurations affect communication with a cross-origin popup window on this demo. Change the Cross-Origin-Opener-Policy dropdown menu for both the document and the popup window, click the Open a popup button then click Send a postMessage to see if the message is actually delivered.

Isolate a document from cross-origin windows #

Setting same-origin puts the document to be isolated from cross-origin document windows.

Cross-Origin-Opener-Policy: same-origin

Isolate a document from cross-origin windows but allow popups #

Setting same-origin-allow-popups allows a document to retain a reference to its popup windows unless they set COOP with same-origin or same-origin-allow-popups. This means same-origin-allow-popups can still protect the document from being referenced when opened as a popup window, but allow it to communicate with its own popups.

Cross-Origin-Opener-Policy: same-origin-allow-popups

Allow a document to be referenced by cross-origin windows #

unsafe-none is the default value but you can explicitly indicate that this document can be opened by a cross-origin window and retain mutual access.

Cross-Origin-Opener-Policy: unsafe-none

Report patterns incompatible with COOP #

You can receive reports when COOP prevents cross-window interactions with the Reporting API.

Cross-Origin-Opener-Policy: same-origin; report-to="coop"

COOP also supports a report-only mode so you can receive reports without actually blocking communication between cross-origin documents.

Cross-Origin-Opener-Policy-Report-Only: same-origin; report-to="coop"

Supported browsers #

Browser support

Chrome 83, Supported 83
Firefox 79, Supported 79
Edge 83, Supported 83
Safari 15.2, Supported 15.2

Source

Learn more #

Why you need "cross-origin isolated" for powerful features

Cross-Origin Resource Sharing (CORS) #

Unlike other items in this article, Cross-Origin Resource Sharing (CORS) is not a header, but a browser mechanism that requests and permits access to cross-origin resources.

By default, browsers enforce the same-origin policy to prevent a web page from accessing cross-origin resources. For example, when a cross-origin image is loaded, even though it's displayed on the web page visually, the JavaScript on the page doesn't have access to the image's data. The resource provider can relax restrictions and allow other websites to read the resource by opting-in with CORS.

Example usage

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true

How to use CORS

Before looking into how to configure CORS, it's helpful to understand the distinction between request types. Depending on request details, a request will be classified as a simple request or a preflighted request.

Criteria for a simple request:

The method is GET, HEAD, or POST.
The custom headers only include Accept, Accept-Language, Content-Language, and Content-Type.
The Content-Type is application/x-www-form-urlencoded, multipart/form-data, or text/plain.

Everything else is classified as a preflighted request. For more details, check out Cross-Origin Resource Sharing (CORS) - HTTP | MDN.

Recommended usages #

Simple request #

When a request meets the simple request criteria, the browser sends a cross-origin request with an Origin header that indicates the requesting origin.

Example request header

Get / HTTP/1.1
Origin: https://example.com

Example response header

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: https://example.com indicates that the https://example.com can access the contents of the response. Resources meant to be readable by any site can set this header to *, in which case the browser will only require the request to be made without credentials.
Access-Control-Allow-Credentials: true indicates that requests which carry credentials (cookies) are allowed to load the resource. Otherwise, authenticated requests will be rejected even if the requesting origin is present in the Access-Control-Allow-Origin header.

You can try how the simple request affect loading resources under a Cross-Origin-Embedder-Policy: require-corp environment on this demo. Click the Cross-Origin Resource Sharing checkbox and click the Reload the image button to see the effect.

Preflighted requests #

A preflighted request is preceded with an OPTIONS request to check if the subsequent request is allowed to be sent.

Example request header

OPTIONS / HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER, Content-Type

Access-Control-Request-Method: POST allows the following request to be made with the POST method.
Access-Control-Request-Headers: X-PINGOTHER, Content-Type allows the requester to set the X-PINGOTHER and Content-Type HTTP headers in the subsequent request.

Example response headers

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400

Access-Control-Allow-Methods: POST, GET, OPTIONS indicates that subsequent requests can be made with the POST, GET and OPTIONS methods.
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type indicates subsequent requests can include the X-PINGOTHER and Content-Type headers.
Access-Control-Max-Age: 86400 indicates that the result of the preflighted request can be cached for 86400 seconds.

Supported browsers #

Browser support

Chrome 4, Supported 4
Firefox 3.5, Supported 3.5
Edge 12, Supported 12
Safari 4, Supported 4

Source

Learn more #

Cross-Origin Embedder Policy (COEP) #

To reduce the ability of Spectre-based attacks to steal cross-origin resources, features such as SharedArrayBuffer or performance.measureUserAgentSpecificMemory() are disabled by default.

Cross-Origin-Embedder-Policy: require-corp prevents documents and workers from loading cross-origin resources such as images, scripts, stylesheets, iframes and others unless these resources explicitly opt into being loaded via CORS or CORP headers. COEP can be combined withCross-Origin-Opener-Policy to opt a document into cross-origin isolation.

Use Cross-Origin-Embedder-Policy: require-corp when you want to enable cross-origin isolation for your document.

Example usage

Cross-Origin-Embedder-Policy: require-corp

How to use COEP

Example usages #

COEP takes a single value of require-corp. By sending this header, you can instruct the browser to block loading resources that do not opt-in via CORS or CORP.

You can try how the following configurations affect loading resources on this demo. Change the Cross-Origin-Embedder-Policy dropdown menu, the Cross-Origin-Resource-Policy dropdown menu, the Report Only checkbox etc to see how they affect loading resources. Also, open the reporting endpoint demo to see if the blocked resources are reported.

Enable cross-origin isolation #

Enable cross-origin isolation by sending Cross-Origin-Embedder-Policy: require-corp along with Cross-Origin-Opener-Policy: same-origin.

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

Report resources incompatible withn COEP #

You can receive reports of blocked resources caused by COEP with the Reporting API.

Cross-Origin-Embedder-Policy: require-corp; report-to="coep"

COEP also supports report-only mode so you can receive reports without actually blocking loading resources.

Cross-Origin-Embedder-Policy-Report-Only: require-corp; report-to="coep"

Supported browsers #

Browser support

Chrome 83, Supported 83
Firefox 79, Supported 79
Edge 83, Supported 83
Safari 15.2, Supported 15.2

Source

Learn more #

HTTP Strict Transport Security (HSTS) #

Communication over a plain HTTP connection is not encrypted, making the transferred data accessible to network-level eavesdroppers.

Strict-Transport-Security header informs the browser that it should never load the site using HTTP and use HTTPS instead. Once it's set, the browser will use HTTPS instead of HTTP to access the domain without a redirect for a duration defined in the header.

Example usage

Strict-Transport-Security: max-age=31536000

How to use HSTS

Recommended usages #

All websites that transition from HTTP to HTTPS should respond with a Strict-Transport-Security header when a request with HTTP is received.

Strict-Transport-Security: max-age=31536000

Supported browsers #

Browser support

Chrome 4, Supported 4
Firefox 4, Supported 4
Edge 12, Supported 12
Safari 7, Supported 7

Source

Learn more #

Strict-Transport-Security - HTTP

Fill OTP forms within cross-origin iframes with WebOTP API

2021-04-21T00:00:00Z

SMS OTPs (one-time passwords) are commonly used to verify phone numbers, for example as a second step in authentication, or to verify payments on the web. However, switching between the browser and the SMS app, to copy-paste or manually enter the OTP makes it easy to make mistakes and adds friction to the user experience.

The WebOTP API gives websites the ability to programmatically obtain the one-time password from a SMS message and enter it automatically in the form for the users with just one tap without switching the app. The SMS is specially-formatted and bound to the origin, so it mitigates chances for phishing websites to steal the OTP as well.

One use case that has yet to be supported in WebOTP was targeting an origin inside an iframe. This is typically used for payment confirmation, especially with 3D Secure. Having the common format to support cross-origin iframes, WebOTP API now delivers OTPs bound to nested origins starting in Chrome 91.

How WebOTP API works #

WebOTP API itself is simple enough:

…
  const otp = await navigator.credentials.get({
    otp: { transport:['sms'] }
  });
…

The SMS message must be formatted with the origin-bound one-time codes.

Your OTP is: 123456.

@web-otp.glitch.me #12345

Notice that at the last line it contains the origin to be bound to preceded with a @ followed by the OTP preceded with a #.

When the text message arrives, an info bar pops up and prompts the user to verify their phone number. After the user clicks the Verify button, the browser automatically forwards the OTP to the site and resolves the navigator.credentials.get(). The website can then extract the OTP and complete the verification process.

Learn the basics of using WebOTP at Verify phone numbers on the web with the WebOTP API.

Cross-origin iframes use cases #

Entering an OTP in a form within a cross-origin iframe is common in payment scenarios. Some credit card issuers require an additional verification step to check the payer's authenticity. This is called 3D Secure and the form is typically exposed within an iframe on the same page as if it's a part of the payment flow.

For example:

A user visits shop.example to purchase a pair of shoes with a credit card.
After entering the credit card number, the integrated payment provider shows a form from bank.example within an iframe asking the user to verify their phone number for fast checkout.
bank.example sends an SMS that contains an OTP to the user so that they can enter it to verify their identity.

How to use WebOTP API from a cross-origin iframe #

To use WebOTP API from within a cross-origin iframe, you need to do two things:

Annotate both the top-frame origin and the iframe origin in the SMS text message.
Configure permissions policy to allow the cross-origin iframe to receive OTP from the user directly.

WebOTP API within an iframe in action.

You can try the demo yourself at https://web-otp-iframe-demo.stackblitz.io.

Annotate bound-origins to the SMS text message #

When WebOTP API is called from within an iframe, the SMS text message must include the top-frame origin preceded by @ followed by the OTP preceded by # followed by the iframe origin preceded by @.

@shop.example #123456 @bank.exmple

Configure Permissions Policy #

To use WebOTP in a cross-origin iframe, the embedder must grant access to this API via otp-credentials permissions policy to avoid unintended behavior. In general there are two ways to achieve this goal:

via HTTP Header:

Permissions-Policy: otp-credentials=(self "https://bank.example")

via iframe allow attribute:

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

See more examples on how to specify a permission policy .

Caveats #

Nesting levels #

At the moment Chrome only supports WebOTP API calls from cross-origin iframes that have no more than one unique origin in its ancestor chain. In the following scenarios:

a.com -> b.com
a.com -> b.com -> b.com
a.com -> a.com -> b.com
a.com -> b.com -> c.com

using WebOTP in b.com is supported but using it in c.com is not.

Note that the following scenario is also not supported because of lack of demand and UX complexities.

a.com -> b.com -> a.com (calls WebOTP API)

Interoperability #

While browser engines other than Chromium do not implement the WebOTP API, Safari shares the same SMS format with its input[autocomplete="one-time-code"] support. In Safari, as soon as an SMS that contains an origin-bound one-time code format arrives with the matched origin, the keyboard suggests to enter the OTP to the input field.

As of April 2021, Safari supports iframe with a unique SMS format using %. However, as the spec discussion concluded to go with @ instead, we hope the implementation of supported SMS format will converge.

Feedback #

Your feedback is invaluable in making WebOTP API better, so go on and try it out and let us know what you think.

Resources #

Photo by rupixen.com on Unsplash

A guide to enable cross-origin isolation

2021-02-09T00:00:00Z

This guide shows you how to enable cross-origin isolation. Cross-origin isolation is required if you want to use SharedArrayBuffer, performance.measureUserAgentSpecificMemory() or high resolution timer with better precision.

If you intend to enable cross-origin isolation, evaluate the impact this will have on other cross-origin resources on your website, such as ad placements.

Determine where in your website SharedArrayBuffer is used

Starting in Chrome 92, functionalities that use SharedArrayBuffer will no longer work without cross-origin isolation. If you landed on this page due to a SharedArrayBuffer deprecation message, it's likely either your website or one of the resources embedded on it is using SharedArrayBuffer. To ensure nothing breaks on your website due to deprecation, start by identifying where it's used.

If you are not sure where in your site a SharedArrayBuffer is used, there are two ways find out:

Using Chrome DevTools
(Advanced) Using Deprecation Reporting

If you already know where you are using SharedArrayBuffer, skip to Analyze the impact of cross-origin isolation.

Using Chrome DevTools #

Chrome DevTools allows developers to inspect websites.

Open the Chrome DevTools on the page you suspect might be using SharedArrayBuffer.
Select the Console panel.

If the page is using SharedArrayBuffer, the following message will show up:

[Deprecation] SharedArrayBuffer will require cross-origin isolation as of M92, around May 2021. See https://developer.chrome.com/blog/enabling-shared-array-buffer/ for more details. common-bundle.js:535

The filename and the line number at the end of the message (for example, common-bundle.js:535) indicate where the SharedArrayBuffer is coming from. If it's a third-party library, contact the developer to fix the issue. If it's implemented as part of your website, follow the guide below to enable cross-origin isolation.

DevToools Console warning when SharedArrayBuffer is used without cross-origin isolation.

(Advanced) Using Deprecation Reporting #

Some browsers have a reporting functionality of deprecating APIs to a specified endpoint.

Set up a deprecation report server and get the reporting URL. You can achieve this by either using a public service or building one yourself.

Using the URL, set the following HTTP header to pages that are potentially serving SharedArrayBuffer.

Report-To: {"group":"default","max_age":86400,"endpoints":[{"url":"THE_DEPRECATION_ENDPOINT_URL"}]}

Once the header starts to propagate, the endpoint you registered to should start collecting deprecation reports.

See an example implementation here: https://cross-origin-isolation.glitch.me.

Analyze the impact of cross-origin isolation #

Wouldn't it be great if you could assess the impact that enabling cross-origin isolation would have on your site without actually breaking anything? The Cross-Origin-Opener-Policy-Report-Only and Cross-Origin-Embedder-Policy-Report-Only HTTP headers allow you to do just that.

Set Cross-Origin-Opener-Policy-Report-Only: same-origin on your top-level document. As the name indicates, this header only sends reports about the impact that COOP: same-origin would have on your site—it won't actually disable communication with popup windows.
Set up reporting and configure a web server to receive and save the reports.
Set Cross-Origin-Embedder-Policy-Report-Only: require-corp on your top-level document. Again, this header lets you see the impact of enabling COEP: require-corp without actually affecting your site's functioning yet. You can configure this header to send reports to the same reporting server that you set up in the previous step.

Caution

Enabling cross-origin isolation will block the loading of cross-origin resources that you don't explicitly opt-in, and it will prevent your top-level document from being able to communicate with popup windows. We've been exploring ways to deploy Cross-Origin-Resource-Policy at scale, as cross-origin isolation requires all subresources to explicitly opt-in. And we have come up with the idea of going in the opposite direction: a new COEP "credentialless" mode that allows loading resources without the CORP header by stripping all their credentials. We hope this will lighten your burden of making sure the subresources are sending the Cross-Origin-Resource-Policy header. Though credentialless mode is available on Chrome from version 96, it's not supported by any other browsers yet, this may cause some developers find it challenging to deploy COOP or COEP at this stage. Also, it's known that the Cross-Origin-Opener-Policy: same-origin header will break integrations that require cross-origin window interactions such as OAuth and payments. To mitigate this problem, we are exploring relaxing the condition to enable cross-origin isolation to Cross-Origin-Opener-Policy: same-origin-allow-popups. This way the communication with the window opened by itself will be possible. If you want to enable cross-origin isolation but are blocked by these challenges, we recommend registering for an origin trial and waiting until the new modes are available. We are not planning to terminate the origin trial until these new modes are available.

Mitigate the impact of cross-origin isolation #

After you have determined which resources will be affected by cross-origin isolation, here are general guidelines for how you actually opt-in those cross-origin resources:

On cross-origin resources such as images, scripts, stylesheets, iframes, and others, set the Cross-Origin-Resource-Policy: cross-origin header. On same-site resources, set Cross-Origin-Resource-Policy: same-site header.
For resources loadable using CORS, make sure it is enabled, by setting the crossorigin attribute in its HTML tag (for example, <img src="example.jpg" crossorigin>). For JavaScript fetch request, make sure request.mode is set to cors.
If you want to use powerful features such as SharedArrayBuffer inside a loaded iframe, append allow="cross-origin-isolated" to the <iframe>.
If cross-origin resources loaded into iframes or worker scripts involve another layer of iframes or worker scripts, recursively apply steps described in this section before moving forward.
Once you confirm that all cross-origin resources are opted-in, set the Cross-Origin-Embedder-Policy: require-corp header on iframes and worker scripts (This is required regardless of same-origin or cross-origin).
Make sure there are no cross-origin popup windows that require communication through postMessage(). There's no way to keep them working when cross-origin isolation is enabled. You can move the communication to another document that isn't cross-origin isolated, or use a different communication method (for example, HTTP requests).

Enable cross-origin isolation #

After you have mitigated the impact by cross-origin isolation, here are general guidelines to enable cross-origin isolation:

Set the Cross-Origin-Opener-Policy: same-origin header on your top-level document. If you had set Cross-Origin-Opener-Policy-Report-Only: same-origin, replace it. This blocks communication between your top-level document and its popup windows.
Set the Cross-Origin-Embedder-Policy: require-corp header on your top-level document. If you had set Cross-Origin-Embedder-Policy-Report-Only: require-corp, replace it. This will block the loading of cross-origin resources that are not opted-in.
Check that self.crossOriginIsolated returns true in console to verify that your page is cross-origin isolated.

Resources #

SMS OTP form best practices

2020-12-09T00:00:00Z

Asking a user to provide the OTP (one time password) delivered via SMS is a common way to confirm a user's phone number. There are a few use cases for SMS OTP:

Two-factor authentication. In addition to username and password, SMS OTP can be used as a strong signal that the account is owned by the person who received the SMS OTP.
Phone number verification. Some services use a phone number as the user's primary identifier. In such services, users can enter their phone number and the OTP received via SMS to prove their identity. Sometimes it's combined with a PIN to constitute a two-factor authentication.
Account recovery. When a user loses access to their account, there needs to be a way to recover it. Sending an email to their registered email address or an SMS OTP to their phone number are common account recovery methods.
Payment confirmation In payment systems, some banks or credit card issuers request additional authentication from the payer for security reasons. SMS OTP is commonly used for that purpose.

This post explains best practices to build an SMS OTP form for the above use cases.

Checklist #

To provide the best user experience with the SMS OTP, follow these steps:

Use the <input> element with:
- type="text"
- inputmode="numeric"
- autocomplete="one-time-code"
Use @BOUND_DOMAIN #OTP_CODE as the last line of the OTP SMS message.
Use the WebOTP API.

Use the `<input>` element #

Using a form with an <input> element is the most important best practice you can follow because it works in all browsers. Even if other suggestions from this post don't work in some browser, the user will still be able to enter and submit the OTP manually.

<form action="/verify-otp" method="POST">
  <input type="text"
         inputmode="numeric"
         autocomplete="one-time-code"
         pattern="\d{6}"
         required>
</form>

The following are a few ideas to ensure an input field gets the best out of browser functionality.

`type="text"` #

Since OTPs are usually five or six digit numbers, using type="number" for an input field might seem intuitive because it changes the mobile keyboard to numbers only. This is not recommended because the browser expects an input field to be a countable number rather than a sequence of multiple numbers, which can cause unexpected behavior. Using type="number" causes up and down buttons to be displayed beside the input field; pressing these buttons increments or decrements the number and may remove preceding zeros.

Use type="text" instead. This won't turn the mobile keyboard into numbers only, but that is fine because the next tip for using inputmode="numeric" does that job.

`inputmode="numeric"` #

Use inputmode="numeric" to change the mobile keyboard to numbers only.

Some websites use type="tel" for OTP input fields since it also turns the mobile keyboard to numbers only (including * and #) when focused. This hack was used in the past when inputmode="numeric" wasn't widely supported. Since Firefox started supporting inputmode="numeric", there's no need to use the semantically incorrect type="tel" hack.

`autocomplete="one-time-code"` #

autocomplete attribute lets developers specify what permission the browser has to provide autocomplete assistance and informs the browser about the type of information expected in the field.

With autocomplete="one-time-code" whenever a user receives an SMS message while a form is open, the operating system will parse the OTP in the SMS heuristically and the keyboard will suggest the OTP for the user to enter. It works only on Safari 12 and later on iOS, iPadOS, and macOS, but we strongly recommend using it, because it is an easy way to improve the SMS OTP experience on those platforms.

`autocomplete="one-time-code"` in action.

autocomplete="one-time-code" improves the user experience, but there's more you can do by ensuring that the SMS message complies with the origin-bound message format.

Format the SMS text #

Enhance the user experience of entering an OTP by aligning with the origin-bound one-time codes delivered via SMS specification.

The format rule is simple: Finish the SMS message with the receiver domain preceded with @ and the OTP preceded with #.

For example:

Your OTP is 123456

@web-otp.glitch.me #123456

Using a standard format for OTP messages makes extraction of codes from them easier and more reliable. Associating OTP codes with websites makes it harder to trick users into providing a code to malicious sites.

Using this format provides a couple of benefits:

The OTP will be bound to the domain. If the user is on domains other than the one specified in the SMS message, the OTP suggestion won't appear. This also mitigates the risk of phishing attacks and potential account hijacks.
Browser will now be able to reliably extract the OTP without depending on mysterious and flaky heuristics.

When a website uses autocomplete="one-time-code", Safari with iOS 14 or later will suggest the OTP following the above rules.

This SMS message format also benefits browsers other than Safari. Chrome, Opera, and Vivaldi on Android also support the origin-bound one-time codes rule with the WebOTP API, though not through autocomplete="one-time-code".

Use the WebOTP API #

The WebOTP API provides access to the OTP received in an SMS message. By calling navigator.credentials.get() with otp type (OTPCredential) where transport includes sms, the website will wait for an SMS that complies with the origin-bound one-time codes to be delivered and granted access by the user. Once the OTP is passed to JavaScript, the website can use it in a form or POST it directly to the server.

navigator.credentials.get({
  otp: {transport:['sms']}
})
.then(otp => input.value = otp.code);

WebOTP API in action.

Learn how to use the WebOTP API in detail in Verify phone numbers on the web with the WebOTP API or copy and paste the following snippet. (Make sure the <form> element has an action and method attribute properly set.)

// Feature detection
if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    // Cancel the WebOTP API if the form is submitted manually.
    const ac = new AbortController();
    const form = input.closest('form');
    if (form) {
      form.addEventListener('submit', e => {
        // Cancel the WebOTP API.
        ac.abort();
      });
    }
    // Invoke the WebOTP API
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
      input.value = otp.code;
      // Automatically submit the form when an OTP is obtained.
      if (form) form.submit();
    }).catch(err => {
      console.log(err);
    });
  });
}

Photo by Jason Leung on Unsplash.

Help users change passwords easily by adding a well-known URL for changing passwords

2020-09-01T00:00:00Z

Set a redirect from /.well-known/change-password to the change password page of your website. This will enable password managers to navigate your users directly to that page.

Introduction #

As you may know, passwords are not the best way to manage accounts. Luckily, there are emerging technologies such as WebAuthn and techniques such as one-time passwords that are helping us get closer to a world without passwords. However, these technologies are still being developed and things won't change rapidly. Many developers will still need to deal with passwords for at least the next few years. While we wait for the emerging technologies and techniques to become commonplace, we can at least make passwords easier to use.

A good way to do this is to provide better support for password managers.

How password managers help #

Password managers can be built into browsers or provided as third-party apps. They can help users in various ways:

Autofill the password for the correct input field: Some browsers can find the correct input heuristically even if the website is not optimized for this purpose. Web developers can help password managers by correctly annotating HTML input tags.

Prevent phishing: Because password managers remember where the password was recorded, the password can be autofilled only at appropriate URLs, and not at phishing websites.

Generate strong and unique passwords: Because strong and unique passwords are directly generated and stored by the password manager, users don't have to remember a single character of the password.

Generating and autofilling passwords using a password manager have already served the web well, but considering their lifecycle, updating the passwords whenever it's required is as important as generating and autofilling. To properly leverage that, password managers are adding a new feature:

Detect vulnerable passwords and suggest updating them: Password managers can detect passwords that are reused, analyze the entropy and weakness of them, and even detect potentially leaked passwords or ones that are known to be unsafe from sources such as Have I Been Pwned.

A password manager can warn users about problematic passwords, but there's a lot of friction in asking users to navigate from the homepage to a change password page, on top of going through the actual process of changing the password (which varies from site to site). It would be much easier if password managers could navigate the user directly to the change-password URL. This is where a well-known URL for changing passwords becomes useful.

By reserving a well-known URL path that redirects the user to the change password page, the website can easily redirect users to the right place to change their passwords.

Set up "a well-known URL for changing passwords" #

.well-known/change-password is proposed as a well-known URL for changing passwords. All you have to do is to configure your server to redirect requests for .well-known/change-password to the change password URL of your website.

For example, let's say your website is https://example.com and the change password URL is https://example.com/settings/password. You'll just need to set your server to redirect a request for https://example.com/.well-known/change-password to https://example.com/settings/password. That's it. For the redirection, use the HTTP status code 302 Found, 303 See Other or 307 Temporary Redirect.

Alternatively you can serve HTML at your .well-known/change-password URL with a <meta> tag using an http-equiv="refresh".

<meta http-equiv="refresh" content="0;url=https://example.com/settings/password">

Revisit your change password page HTML #

The goal of this feature is to help the user's password lifecycle be more fluid. You can do two things to empower the user to update their password without friction:

If your change-password form needs the current password, add autocomplete="current-password" to the <input> tag to help the password manager autofill it.
For the new password field (in many cases it's two fields to ensure that the user has entered the new password correctly), add autocomplete="new-password" to the <input> tag to help the password manager suggest a generated password.

Learn more at Sign-in form best practices.

How it is used in real world #

Examples #

Thanks to Apple Safari's implementation, /.well-known/change-password, has already been available on some major websites for a while:

Try them yourself and do the same for yours!

Browser compatibility #

A well-known URL for changing passwords has been supported in Safari since 2019. Chrome's password manager is starting to support it from version 86 onwards (which is scheduled for Stable release in late October 2020) and other Chromium-based browsers may follow. Firefox considers it worth implementing, but has not signalled that it plans to do so as of August 2020.

Chrome's password manager behavior #

Let's have a look at how Chrome's password manager treats vulnerable passwords.

Chrome's password manager is able to check for leaked passwords. By navigating to about://settings/passwords users can run Check passwords against stored passwords, and see a list of passwords that are recommended for update.

Chrome's Check passwords functionality

By clicking the Change password button next to a password that is recommended to be updated, the browser will:

Open the website's change password page if /.well-known/change-password is set up correctly.
Open the website's homepage if /.well-known/change-password is not set up and Google doesn't know the fallback.

What if the server returns 200 OK even /.well-known/change-password doesn't exist?

Password managers try to determine if a website supports a well-known URL for changing passwords by sending a request to /.well-known/change-password before actually forwarding a user to this URL. If the request returns 404 Not Found it is obvious that the URL is not available, but a 200 OK response doesn't necessarily mean that the URL is available, because there are a few edge cases:

A server-side-rendering website displays "Not found" when there is no content but with 200 OK.
A server-side-rendering website responds with 200 OK when there is no content after redirecting to the "Not found" page.
A single page app responds with the shell with 200 OK and renders the "Not found" page on the client side when there is no content.

For these edge cases users will be forwarded to a "Not Found" page and that will be a source of confusion.

That's why there's a proposed standard mechanism to determine whether the server is configured to respond with 404 Not Found when there is genuinely no content, by requesting a random page. Actually, the URL is also reserved: /.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200. Chrome for example uses this URL path to determine whether it can expect a proper change password URL from /.well-known/change-password in advance.

When you are deploying /.well-known/change-password, make sure that your server returns 404 Not Found for any non-existing contents.

Feedback #

If you have any feedback on the specification, please file an issue to the spec repository.

Resources #

Photo by Matthew Brodeur on Unsplash

Handling optional payment information with a service worker

2020-08-31T00:00:00Z

Once a web-based payment app receives a payment request and initiates a payment transaction, the service worker will act as the hub for communication between the merchant and the payment app. This post explains how a payment app can pass information about the payment method, shipping address, or contact information to the merchant using a service worker.

Handling optional payment information with a service worker

Inform the merchant of a payment method change #

Payment apps can support multiple payment instruments with different payment methods.

Customer	Payment Method	Payment Instrument
A	Credit Card Issuer 1	`****1234`
	Credit Card Issuer 1	`****4242`
	Bank X	`******123`
B	Credit Card Issuer 2	`****5678`
B	Bank X	`******456`

For example, in the above table, Customer A's web-based wallet has two credit cards and one bank account registered. In this case, the app is handling three payment instruments (****1234, ****4242, ******123) and two payment methods (Credit Card Issuer 1 and Bank X). On a payment transaction, the payment app can let the customer pick one of the payment instruments and use it to pay for the merchant.

Payment method picker UI

The payment app can let the merchant know which payment method the customer picked before sending the full payment response. This is useful when the merchant wants to run a discount campaign for a specific payment method brand, for example.

With the Payment Handler API, the payment app can send a "payment method change" event to the merchant via a service worker to notify the new payment method identifier. The service worker should invoke PaymentRequestEvent.changePaymentMethod() with the new payment method information.

Inform the merchant of a payment method change

Payment apps can pass a methodDetails object as the optional second argument for PaymentRequestEvent.changePaymentMethod(). This object can contain arbitrary payment method details required for the merchant to process the change event.

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_METHOD_CHANGED':
        const newMethod = e.data.paymentMethod;
        const newDetails = e.data.methodDetails;
        // Redact or check that no sensitive information is passed in
        // `newDetails`.
        // Notify the merchant of the payment method change
        details =
          await payment_request_event.changePaymentMethod(newMethod, newDetails);
      …

When the merchant receives a paymentmethodchange event from the Payment Request API, they can update the payment details and respond with a PaymentDetailsUpdate object.

[merchant]

request.addEventListener('paymentmethodchange', e => {
  if (e.methodName === 'another-pay') {
    // Apply $10 discount for example.
    const discount = {
      label: 'special discount',
      amount: {
        currency: 'USD',
        // The value being string complies the spec
        value: '-10.00'
      }
    };
    let total = 0;
    details.displayItems.push(discount);
    for (let item of details.displayItems) {
     total += parseFloat(item.amount.value);
    }
    // Convert the number back to string
    details.total.amount.value = total.toString();
  }
  // Pass a promise to `updateWith()` and send updated payment details
  e.updateWith(details);
});

When the merchant responds, the promise that PaymentRequestEvent.changePaymentMethod() returned will resolve with a PaymentRequestDetailsUpdate object.

[payment handler] service-worker.js

…
        // Notify the merchant of the payment method change
        details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Use the object to update the UI on the frontend. See Reflect the updated payment details.

Inform the merchant of a shipping address change #

Payment apps can provide a customer's shipping address to the merchant as part of a payment transaction.

This is useful for merchants because they can delegate the address collection to payment apps. And, because the address data will be provided in the standard data format, the merchant can expect to receive shipping addresses in consistent structure.

Additionally, customers can register their address information with their preferred payment app and reuse it for different merchants.

Shipping address picker UI

Payment apps can provide a UI to edit a shipping address or to select pre-registered address information for the customer on a payment transaction. When a shipping address is determined temporarily, the payment app can let the merchant know of the redacted address information. This provides merchants with multiple benefits:

A merchant can determine whether the customer meets the regional restriction to ship the item (for example, domestic only).
A merchant can change the list of shipping options based on the region of the shipping address (For example, international regular or express).
A merchant can apply the new shipping cost based on the address and update the total price.

With the Payment Handler API, the payment app can send a "shipping address change" event to the merchant from the service worker to notify the new shipping address. The service worker should invoke PaymentRequestEvent.changeShippingAddress() with the new address object.

Inform the merchant of a shipping address change

[payment handler] service-worker.js

...
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      …

The merchant will receive a shippingaddresschange event from the Payment Request API so they can respond with the updated PaymentDetailsUpdate.

[merchant]

request.addEventListener('shippingaddresschange', e => {
  // Read the updated shipping address and update the request.
  const addr = request.shippingAddress;
  const details = getPaymentDetailsFromShippingAddress(addr);
  // `updateWith()` sends back updated payment details
  e.updateWith(details);
});

When the merchant responds, the promise PaymentRequestEvent.changeShippingAddress() returned will resolve with a PaymentRequestDetailsUpdate object.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping address change
        details = await payment_request_event.changeShippingAddress(newAddress);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Use the object to update the UI on the frontend. See Reflect the updated payment details.

Inform the merchant of a shipping option change #

Shipping options are delivery methods merchants use to ship purchased items to a customer. Typical shipping options include:

Free shipping
Express shipping
International shipping
Premium international shipping

Each comes with its own cost. Usually faster methods/options are more expensive.

Merchants using the Payment Request API can delegate this selection to a payment app. The payment app can use the information to construct a UI and let the customer pick a shipping option.

Shipping option picker UI

The list of shipping options specified in the merchant's Payment Request API is propagated to the payment app's service worker as a property of PaymentRequestEvent.

[merchant]

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: { transactionId: '****' }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  shippingOptions: [{
    id: 'standard',
    label: 'Standard',
    amount: { value: '0.00', currency: 'USD' },
    selected: true
  }, {
    id: 'express',
    label: 'Express',
    amount: { value: '5.00', currency: 'USD' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {  requestShipping: true });

The payment app can let the merchant know which shipping option the customer picked. This is important for both the merchant and the customer because changing the shipping option changes the total price as well. The merchant needs to be informed of the latest price for the payment verification later and the customer also needs to be aware of the change.

With the Payment Handler API, the payment app can send a "shipping option change" event to the merchant from the service worker. The service worker should invoke PaymentRequestEvent.changeShippingOption() with the new shipping option ID.

Inform the merchant of a shipping option change

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      …

The merchant will receive a shippingoptionchange event from the Payment Request API. The merchant should use the information to update the total price and then respond with the updated PaymentDetailsUpdate.

[merchant]

request.addEventListener('shippingoptionchange', e => {
  // selected shipping option
  const shippingOption = request.shippingOption;
  const newTotal = {
    currency: 'USD',
    label: 'Total due',
    value: calculateNewTotal(shippingOption),
  };
  // `updateWith()` sends back updated payment details
  e.updateWith({ total: newTotal });
});

When the merchant responds, the promise that PaymentRequestEvent.changeShippingOption() returned will resolve with a PaymentRequestDetailsUpdate object.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping option change
        details = await payment_request_event.changeShippingOption(newOption);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Use the object to update the UI on the frontend. See Reflect the updated payment details.

Reflect the updated payment details #

Once the merchant finishes updating the payment details, the promises returned from .changePaymentMethod(), .changeShippingAddress() and .changeShippingOption() will resolve with a common PaymentRequestDetailsUpdate object. The payment handler can use the result to reflect updated total price and shipping options to the UI.

Merchants may return errors for a few reasons:

The payment method is not acceptable.
The shipping address is outside of their supported regions.
The shipping address contains invalid information.
The shipping option is not selectable for the provided shipping address or some other reason.

Use the following properties to reflect the error status:

error: Human readable error string. This is the best string to display to customers.
shippingAddressErrors: AddressErrors object that contains in-detail error string per address property. This is useful if you want to open a form that lets the customer edit their address and you need to point them directly to the invalid fields.
paymentMethodErrors: Payment-method-specific error object. You can ask merchants to provide a structured error, but the Web Payments spec authors recommend keeping it a simple string.

Sample code #

Most of sample codes you saw in this document were excerpts from the following working sample app:

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

To try it out:

Go to https://paymentrequest-demo.glitch.me/.
Go to the bottom of the page.
Press Add a payment button.
Enter https://paymenthandler-demo.glitch.me to the Payment Method Identifier field.
Press Pay button next to the field.

Orchestrating payment transactions with a service worker

2020-08-31T00:00:00Z

Once the payment app is registered, you are ready to accept payment requests from merchants. This post explains how to orchestrate a payment transaction from a service worker during runtime (i.e. when a window is displayed and the user is interacting with it).

Orchestrating payment transactions with a service worker

"Runtime payment parameter changes" refer to a set of events that allows the merchant and payment handler to exchange messages while the user is interacting with the payment handler. Learn more in Handling optional payment information with a service worker.

Receive a payment request event from the merchant #

When a customer chooses to pay with your web-based payment app and the merchant invokes PaymentRequest.show(), your service worker will receive a paymentrequest event. Add an event listener to the service worker to capture the event and prepare for the next action.

[payment handler] service-worker.js:

…
let payment_request_event;
let resolver;
let client;

// `self` is the global object in service worker
self.addEventListener('paymentrequest', async e => {
  if (payment_request_event) {
    // If there's an ongoing payment transaction, reject it.
    resolver.reject();
  }
  // Preserve the event for future use
  payment_request_event = e;
…

The preserved PaymentRequestEvent contains important information about this transaction:

Property name	Description
`topOrigin`	A string that indicates the origin of the top-level web page (usually the payee merchant). Use this to identify the merchant origin.
`paymentRequestOrigin`	A string that indicates the origin of the invoker. This can be the same as `topOrigin` when the merchant invokes the Payment Request API directly, but may be different if the API is invoked from within an iframe by a third party such as a payment gateway.
`paymentRequestId`	The `id` property of the `PaymentDetailsInit` provided to the Payment Request API. If the merchant omits, the browser will provide an auto-generated ID.
`methodData`	The payment-method-specific data provided by the merchant as part of `PaymentMethodData`. Use this to determine the payment transaction details.
`total`	The total amount provided by the merchant as part of `PaymentDetailsInit`. Use this to construct a UI to let the customer know the total amount to pay.
`instrumentKey`	The instrument key selected by the user. This reflects the `instrumentKey` you provided in advance. An empty string indicates that the user did not specify any instruments.

Open the payment handler window to display the web-based payment app frontend #

When a paymentrequest event is received, the payment app can open a payment handler window by calling PaymentRequestEvent.openWindow(). The payment handler window will present the customers your payment app's interface where they can authenticate, choose shipping address and options, and authorize the payment. We'll cover how to write the frontend code in Handling payments on the payment frontend (coming soon).

Checkout flow with a web-based payment app.

Pass a preserved promise to PaymentRequestEvent.respondWith() so that you can resolve it with a payment result in the future.

[payment handler] service-worker.js:

…
self.addEventListener('paymentrequest', async e => {
…
  // Retain a promise for future resolution
  // Polyfill for PromiseResolver is provided below.
  resolver = new PromiseResolver();

  // Pass a promise that resolves when payment is done.
  e.respondWith(resolver.promise);
  // Open the checkout page.
  try {
    // Open the window and preserve the client
    client = await e.openWindow(checkoutURL);
    if (!client) {
      // Reject if the window fails to open
      throw 'Failed to open window';
    }
  } catch (err) {
    // Reject the promise on failure
    resolver.reject(err);
  };
});
…

You can use a convenient PromiseResolver polyfill to resolve a promise at arbitrary timing.

class PromiseResolver {
  constructor() {
    this.promise_ = new Promise((resolve, reject) => {
      this.resolve_ = resolve;
      this.reject_ = reject;
    })
  }
  get promise() { return this.promise_ }
  get resolve() { return this.resolve_ }
  get reject() { return this.reject_ }
}

Exchange information with the frontend #

The payment app's service worker can exchange messages with the payment app's frontend through ServiceWorkerController.postMessage(). To receive messages from the frontend, listen to message events.

[payment handler] service-worker.js:

// Define a convenient `postMessage()` method
const postMessage = (type, contents = {}) => {
  if (client) client.postMessage({ type, ...contents });
}

Receive the ready signal from the frontend #

Once the payment handler window is opened, the service worker should wait for a ready-state signal from the payment app frontend. The service worker can pass important information to the frontend when it is ready.

[payment handler] frontend:

navigator.serviceWorker.controller.postMessage({
  type: 'WINDOW_IS_READY'
});

[payment handler] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      // `WINDOW_IS_READY` is a frontend's ready state signal
      case 'WINDOW_IS_READY':
        const { total } = payment_request_event;
…

Pass the transaction details to the frontend #

Now send the payment details back. In this case you're only sending the total of the payment request, but you can pass more details if you like.

[payment handler] service-worker.js:

…
        // Pass the payment details to the frontend
        postMessage('PAYMENT_IS_READY', { total });
        break;
…

[payment handler] frontend:

let total;

navigator.serviceWorker.addEventListener('message', async e => {
  switch (e.data.type) {
      case 'PAYMENT_IS_READY':
        ({ total } = e.data);
        // Update the UI
        renderHTML(total);
        break;
…

Return the customer's payment credentials #

When the customer authorizes the payment, the frontend can send a post message to the service worker to proceed. You can resolve the promise passed to PaymentRequestEvent.respondWith() to send the result back to the merchant. Pass a PaymentHandlerResponse object.

Property name	Description
`methodName`	The payment method identifier used to make payment.
`details`	The payment method specific data that provides necessary information for the merchant to process payment.

[payment handler] frontend:

  const paymentMethod = …

  postMessage('PAYMENT_AUTHORIZED', {
    paymentMethod,              // Payment method identifier
  });

[payment handler] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_AUTHORIZED':
        // Resolve the payment request event promise
        // with a payment response object
        const response = {
          methodName: e.data.paymentMethod,
          details: { id: 'put payment credential here' },
        }
        resolver.resolve(response);
        // Don't forget to initialize.
        payment_request_event = null;
        break;
      …

Cancel the payment transaction #

To allow the customer to cancel the transaction, the frontend can send a post message to the service worker to do so. The service worker can then resolve the promise passed to PaymentRequestEvent.respondWith() with null to indicate to the merchant that the transaction has been cancelled.

[payment handler] frontend:

  postMessage('CANCEL_PAYMENT');

[payment handler] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'CANCEL_PAYMENT':
        // Resolve the payment request event promise
        // with null
        resolver.resolve(null);
        // Don't forget to initialize.
        payment_request_event = null;
        break;
      …

Sample code #

All sample codes you saw in this document were excerpts from the following working sample app:

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

To try it out:

Go to https://paymentrequest-demo.glitch.me/.
Go to the bottom of the page.
Press Add a payment button.
Enter https://paymenthandler-demo.glitch.me to the Payment Method Identifier field.
Press Pay button next to the field.

Next steps #

In this article, we learned how to orchestrate a payment transaction from a service worker. The next step is to learn how to add some more advanced features to the service worker.

Handling optional payment information with a service worker

Registering a web-based payment app

2020-07-17T00:00:00Z

Web-based payment apps are Progressive Web Apps (PWA) and run on top of service workers. The service worker in a payment app plays an important role as it captures payment requests from a merchant, launches the payment app, and mediates the communication with the merchant.

To configure a web-based payment app, you need to register available payment methods, and a service worker. You can configure your web-based payment app declaratively with a web app manifest.

Browser support #

Web Payments consists of a few different pieces of technologies and the support status depends on the browser.

	Chromium		Safari		Firefox
	Desktop	Android	Desktop	Mobile	Desktop/Mobile
Payment Request API	✔	✔	✔	✔
Payment Handler API	✔	✔
iOS/Android payment app	✔	✔	✔*	✔*

Configuring a payment app with a web app manifest #

To configure your web-based payment app declaratively, serve a web app manifest.

The following properties in the web app manifest are relevant for web-based payment apps:

name
icons
serviceworker
- src
- scope
- use_cache

Check out Setting up a payment method to make sure your payment method manifest points to your web app manifest properly.

Registering a service worker just-in-time (JIT) #

The JIT registration requires only serving the web app manifest and no additional coding. If you've already configured your web app manifest and are serving it properly, you should be all set. The browser will handle the rest.

Debugging a web-based payment app #

When developing a web-based payment app frontend, you'll probably jump between merchant context and payment app context. The following debugging tips will help your developing experience on Chrome.

Developing on a local server #

Which server do you use for development? Many developers tend to use localhost or a company-internal server environment which can be challenging because powerful features in the browser tend to require a secure environment (HTTPS) and a valid certificate. The Payment Request API and the Payment Handler API are no exception and localhosts or company-internal servers usually don't come with a valid certificate.

The good news is some browsers, including Chrome, exempt certificates for http://localhost by default. Also in Chrome, you can exempt the certificate requirement by launching a Chrome instance. For example, to exempt the requirement from http://*.corp.company.com, use the following flags:

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --ignore-certificate-errors --unsafely-treat-insecure-origin-as-secure=http://*.corp.company.com

Windows

chrome.exe --ignore-certificate-errors --unsafely-treat-insecure-origin-as-secure=http://*.corp.company.com

Learn more about running Chrome with a runtime flag at Run Chromium with flags.

Port forwarding a local server #

You can port forward the local web server to an Android device using Chrome's DevTools and test how it works from a mobile browser. To learn how to do it, check out Access Local Servers.

Remote debugging a website on Android Chrome from desktop DevTools #

You can also debug Android Chrome on desktop DevTools. To learn how to do it, check out Get Started with Remote Debugging Android Devices.

Payment Handler event logging #

DevTools can display Payment Handler API events for easier local development. Open DevTools on the merchant context and go to the "Payment Handler" section under the Application pane. Check "Show events from other domains" and click the "Record" button to start capturing events sent to the service worker that handles payments.

Payment Handler event logging.

Next steps #

The next step is to learn how the service worker can orchestrate a payment transaction at runtime.

Orchestrating payment transactions with a service worker

Web-based payment apps overview

2020-07-17T00:00:00Z

Web Payments brings to the web a browser's built-in interface that allows users to enter required payment information easier than ever before. The APIs can invoke web-based payment apps, as well as Android payment apps.

Browser support #

Web Payments consists of a few different pieces of technologies and the support status depends on the browser.

	Chromium		Safari		Firefox
	Desktop	Android	Desktop	Mobile	Desktop/Mobile
Payment Request API	✔	✔	✔	✔
Payment Handler API	✔	✔
iOS/Android payment app	✔	✔	✔*	✔*

Benefits of web-based payment apps #

Checkout flow with a web-based payment app.

Payments are made in modals, in the context of the merchant website, which provides better user experience than typical payment app techniques that use redirects or pop-ups.
Web Payments APIs can be integrated into established websites allowing you to leverage the existing user base.
Unlike platform-specific apps, web-based payment apps don't need to be installed in advance.

How does a web-based payment app work? #

Web-based payment apps are built using the standard web technologies. Every web-based payment app must include a service worker.

In a web-based payment app, a service worker can act as a mediator for payment requests by:

Opening a modal window and displaying the payment app's interface.
Bridging the communication between the payment app and the merchant.
Getting an authorization from the customer and passing the payment credential to the merchant.

Learn how a payment app works on a merchant in Life of a payment transaction.

How merchants discover your payment app #

In order for a merchant to use your payment app, they need to use the Payment Request API and specify the payment method you support using the payment method identifier.

If you have a payment method identifier that is unique to your payment app, you can set up your own payment method manifest and let browsers discover your app.

Learn how it works and how you can set up a new payment method in Setting up a payment method.

APIs you can use inside the payment handler window #

A "payment handler window" is a window in which payment apps are launched. In Chrome, since it's a regular Chrome browser window, most web APIs should work as if used in a top-level document, with only a few exceptions:

Resizing the viewport is disabled.
window.open() is disabled.

WebAuthn support #

WebAuthn is an authentication mechanism based on the public key cryptography. You can let users sign-in through a biometric verification. WebAuthn is already supported in the payment handler window on Chrome, and the standard body is looking into creating an even-tighter connection between Web Payments and WebAuthn.

Credential Management API support #

The Credential Management API provides a programmatic interface between the site and the browser for seamless sign-in across devices. You can let users sign-in to your website automatically based on the information stored to the browser's password manager. It's planned to be enabled in Chrome, but still under development.

WebOTP support #

The WebOTP API helps you programmatically obtain an OTP from an SMS message and verify a phone number for the user more easily. It's planned to be enabled in Chrome, but still under development.

You can check out the list of known issues and features planned to be added to the payment handler window in the Chromium bug tracker.

Next steps #

To start building a web-based payment app, you have three distinct parts to implement:

Setting up a payment method

2020-05-25T00:00:00Z

To be used with the Payment Request API, a payment app must be associated with a payment method identifier. Merchants that want to integrate with a payment app will use the payment method identifier to indicate that to the browser. This article discusses how payment app discovery works, and how to configure your payment app to be properly discovered and invoked by a browser.

If you are new to the concept of Web Payments or how a payment transaction works through payment apps, read the following articles first:

Browser support #

Web Payments consists of a few different pieces of technologies and the support status depends on the browser.

	Chromium		Safari		Firefox
	Desktop	Android	Desktop	Mobile	Desktop/Mobile
Payment Request API	✔	✔	✔	✔
Payment Handler API	✔	✔
iOS/Android payment app	✔	✔	✔*	✔*

How a browser discovers a payment app #

Every payment app needs to provide the following:

URL-based payment method identifier
Payment method manifest (except when the payment method identifier is provided by a third party)
Web app manifest

The discovery process starts when a merchant initiates a transaction:

The browser sends a request to the payment method identifier URL and fetches the payment method manifest.
The browser determines the web app manifest URL from the payment method manifest and fetches the web app manifest.
The browser determines whether to launch the OS payment app or the web-based payment app from the web app manifest.

The next sections explain in detail how to set up your own payment method so that browsers can discover it.

Step 1: Provide the payment method identifier #

A payment method identifier is a URL-based string. For example, Google Pay's identifier is https://google.com/pay. Payment app developers can pick any URL as a payment method identifier as long as they have control over it and can serve arbitrary content. In this article, we'll use https://bobbucks.dev/pay as the payment method identifier.

How merchants use the payment method identifier #

A PaymentRequest object is constructed with a list of payment method identifiers that identifies payment apps a merchant decides to accept. Payment method identifiers are set as a value for the supportedMethods property. For example:

[merchant] requests payment:

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay'
}], {
  total: {
    label: 'total',
    amount: { value: '10', currency: 'USD' }
  }
});

Step 2: Serve the payment method manifest #

A payment method manifest is a JSON file that defines which payment app can use this payment method.

Provide the payment method manifest #

When a merchant initiates a payment transaction, the browser sends an HTTP GET request to the payment method identifier URL. The server responds with the payment method manifest body.

A payment method manifest has two fields, default_applications and supported_origins.

Payment method manifest fields
Property name	Description
`default_applications` (required)	An array of URLs that points to web app manifests where the payment apps are hosted. (The URL can be a relative). This array is expected to reference the development manifest, production manifest, etc.
`supported_origins`	An array of URLs that points to origins that may host third-party payment apps implementing the same payment method. Note that a payment method can be implemented by multiple payment apps.

A payment method manifest file should look like this:

[payment handler] /payment-manifest.json:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": [
    "https://alicepay.friendsofalice.example"
  ]
}

When the browser reads the default_applications field, it finds a list of links to web app manifests of supported payment apps.

Optionally route the browser to find the payment method manifest in another location #

The payment method identifier URL can optionally respond with a Link header that points to another URL where the browser can fetch the payment method manifest. This is useful when a payment method manifest is hosted at a different server or when the payment app is served by a third party.

Configure the payment method server to respond with a HTTP Link header with the rel="payment-method-manifest" attribute and the payment method manifest URL.

For example, if the manifest is at https://bobbucks.dev/payment-manifest.json, the response header would include:

Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"

The URL can be a fully-qualified domain name or a relative path. Inspect https://bobbucks.dev/pay/ for network traffic to see an example. You may use a curl command as well:

curl --include https://bobbucks.dev/pay

Step 3: Serve a web app manifest #

A web app manifest is used to define a web app as the name suggests. It's a widely used manifest file to define a Progressive Web App (PWA).

Typical web app manifest would look like this:

[payment handler] /manifest.json:

{
  "name": "Pay with Bobpay",
  "short_name": "Bobpay",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

The information described in a web app manifest is also used to define how a payment app appears in the Payment Request UI.

Important web app manifest fields
Property name	Description
`name` (required)	Used as the payment app name.
`icons` (required)	Used as the payment app icon. Only Chrome uses these icons; other browsers may use them as fallback icons if you don't specify them as part of the payment instrument.
`serviceworker`	Used to detect the service worker that runs as the web-based payment app.
`serviceworker.src`	The URL to download the service worker script from.
`serviceworker.scope`	A string representing a URL that defines a service worker's registration scope.
`serviceworker.use_cache`	The URL to download the service worker script from.
`related_applications`	Used to detect the app that acts as the OS-provided payment app. Find more details at Android payment apps developer guide.
`prefer_related_applications`	Used to determine which payment app to launch when both an OS-provided payment app and a web-based payment app are available.

Payment app label and icon.

The web app manifest's name property is used as the payment app name, icons property is used as the payment app icon.

How Chrome determines which payment app to launch #

Launching the platform-specific payment app #

To launch the platform-specific payment app, the following conditions must be met:

The related_applications field is specified in the web app manifest and:
- The installed app's package ID and signature match, while the minimum version (min_version) in the web app manifest is less than or equal to the version of the installed application.
The prefer_related_applications field is true.
The platform-specific payment app is installed and has:
- An intent filter of org.chromium.action.PAY.
- A payment method identifier specified as the value for the org.chromium.default_payment_method_name property.

Check out the Android payment apps: developer's guide for more details about how to set these up.

[payment handler] /manifest.json

"prefer_related_applications": true,
"related_applications": [{
  "platform": "play",
  "id": "xyz.bobpay.app",
  "min_version": "1",
  "fingerprints": [{
    "type": "sha256_cert",
    "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2:05:0A:1E:57:5F:23:40:E9:E3:87:14:EC:6D:A2:04:21:E0:FD:3B:D1"
  }]
}]

If the browser has determined that the platform-specific payment app is available, the discovery flow is terminated here. Otherwise it continues to the next step -- launching the web-based payment app.

Launching the web-based payment app #

The web-based payment app should be specified in the web app manifest's serviceworker field.

[payment handler] /manifest.json:

"serviceworker": {
  "src": "payment-handler.js"
}

The browser launches the web-based payment app by sending a paymentrequest event to the service worker. The service worker doesn't have to be registered in advance. It can be registered just-in-time.

Understanding the special optimizations #

How browsers can skip the Payment Request UI and launch a payment app directly #

In Chrome, when show() method of PaymentRequest is called, the Payment Request API displays a browser-provided UI called the "Payment Request UI". This UI allows users to choose a payment app. After pressing the Continue button in the Payment Request UI, the selected payment app is launched.

Payment Request UI intervenes before launching the payment app.

Showing the Payment Request UI before launching a payment app increases the number of steps needed for a user to fulfill a payment. To optimize the process, the browser can delegate fulfillment of that information to payment apps and launch a payment app directly without showing the Payment Request UI when show() is called.

Skip the Payment Request UI and launch the payment app directly.

To launch a payment app directly, the following conditions must be met:

show() is triggered with a user gesture (for example, a mouse click).
There is only a single payment app that:
- Supports the requested payment method identifier.

When is a web-based payment app registered just-in-time (JIT)? #

Web-based payment apps can be launched without the user's explicit prior visit to the payment app website and registering the service worker. The service worker can be registered just-in-time when the user chooses to pay with the web-based payment app. There are two variations for the registration timing:

If the Payment Request UI is shown to the user, the app is registered just-in-time and launched when the user clicks Continue.
If the Payment Request UI is skipped, the payment app is registered just-in-time and launched directly. Skipping the Payment Request UI to launch a just-in-time registered app requires a user gesture, which prevents unexpected registration of cross-origin service workers.

Next Steps #

Now that you have your payment app discoverable, learn how to develop a platform-specific payment app and a web-based payment app.

Life of a payment transaction

2020-05-25T00:00:00Z

Web Payments APIs are dedicated payment features built into the browser for the first time. With Web Payments, merchant integration with payment apps becomes simpler while the customer experience gets streamlined and more secure.

To learn more about the benefits of using Web Payments check out Empowering payment apps with Web Payments.

This article walks you through a payment transaction on a merchant website and helps you understand how payment app integration works.

The process involves 6 steps:

The merchant initiates a payment transaction.
The merchant shows a payment button.
The customer presses the payment button.
The browser launches the payment app.
If the customer changes any details (such as shipping options or their address), the merchant updates the transaction details reflecting the change.
After the customer confirms the purchase, the merchant validates the payment and completes the transaction.

Step 1: The merchant initiates a payment transaction #

When a customer decides to make a purchase, the merchant initiates the payment transaction by constructing a PaymentRequest object. This object includes important information about the transaction:

Acceptable payment methods and their data to process the transaction.
Details, such as the total price (required) and information about the items.
Options in which merchants can request shipping information such as a shipping address and a shipping option.
Merchants can also request the billing address, the payer's name, email, and phone number.
Merchants can also include optional shipping type (shipping, delivery, or pickup) in the PaymentRequest. The payment app can use that as a hint to display the correct labels in its UI.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Including a transaction ID

Some payment handlers may require the merchant to provide the transaction ID which they have issued in advance as part of the transaction information. A typical integration includes communication between the merchant's and the payment handler's server to reserve the total price. This prevents malicious customers from manipulating the price and cheating the merchant with a validation at the end of the transaction.

The merchant can pass a transaction ID as part of the PaymentMethodData object's data property.

Provided the transaction information, the browser goes through a discovery process of payment apps specified in the PaymentRequest based on the payment method identifiers. This way, the browser can determine the payment app to launch as soon as the merchant is ready to proceed with the transaction.

To learn how the discovery process works in detail check out Setting up a payment method.

Step 2: The merchant shows a payment button #

Merchants can support many payment methods, but should only present the payment buttons for those that a customer can actually use. Showing a payment button that is unusable is poor user experience. If a merchant can predict that a payment method specified in the PaymentRequest object won't work for the customer, they can provide a fallback solution or not show that button at all.

Using a PaymentRequest instance, a merchant can query whether a customer has the payment app available.

Does the customer have the payment app available? #

The canMakePayment() method of PaymentRequest returns true if a payment app is available on the customer's device. "Available" means that a payment app that supports the payment method is discovered, and that the platform-specific payment app is installed, or the web-based payment app is ready to be registered.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Step 3: The customer presses the payment button #

When the customer presses the payment button, the merchant calls the show() method of the PaymentRequest instance which immediately triggers the launch of the payment UI.

In case the final total price is set dynamically (for example, retrieved from a server), the merchant can defer the launch of the payment UI until the total is known.

Deferring the launch of the payment UI #

Check out a demo of deferring the payment UI until the final total price is determined.

To defer the payment UI, the merchant passes a promise to the show() method. The browser will show a loading indicator until the promise resolves and the transaction is ready to begin.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

If there is no promise specified as an argument for show(), the browser will launch the payment UI immediately.

Step 4: The browser launches the payment app #

The browser can launch a platform-specific or a web-based payment app. (You can learn more about how Chrome determines which payment app to launch.)

How the payment app is built is up to the developer for the most part, but the events emitted from and to the merchant, as well as the structure of the data passed along with those events, are standardized.

When the payment app is launched, it receives the transaction information passed to the PaymentRequest object in Step 1, which includes the following:

Payment method data
Total price
Payment options

The payment app uses the transaction information to label its UI.

Step 5: How a merchant can update the transaction details depending on customer's actions #

Customers have an option to change the transaction details such as payment method and shipping option in the payment app. While the customer makes changes, the merchant receives the change events and updates the transaction details.

There are four types of events a merchant can receive:

Payment method change event
Shipping address change event
Shipping option change event
Merchant validation event

Payment method change event #

A payment app can support multiple payment methods and a merchant may offer a special discount depending on the customer's selection. To cover this use case, the payment method change event can inform the merchant of the new payment method so that they can update the total price with the discount and return it back to the payment app.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Shipping address change event #

A payment app can optionally provide the customer's shipping address. This is convenient for customers because they don't have to manually enter any details into a form and they can store their shipping address in their preferred payment apps, rather than on multiple different merchant websites.

If a customer updates their shipping address in a payment app after the transaction has been initiated, a 'shippingaddresschange' event will be sent to the merchant. This event helps the merchant determine the shipping cost based on the new address, update the total price, and return it to the payment app.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

If the merchant can't ship to the updated address, they can provide an error message by adding an error parameter to the transaction details returned to the payment app.

Shipping option change event #

A merchant can offer multiple shipping options to the customer and can delegate that choice to the payment app. The shipping options are displayed as a list of prices and service names the customer can select from. For example:

Standard shipping - Free
Express shipping - 5 USD

When a customer updates the shipping option in a payment app, a 'shippingoptionchange' event will be sent to the merchant. The merchant can then determine the shipping cost, update the total price, and return it to the payment app.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

The merchant can dynamically modify the shipping options based on the customer's shipping address as well. This is useful when a merchant wants to offer different sets of shipping options for domestic and international customers.

Merchant validation event #

For additional security, a payment app can perform a merchant validation before proceeding to the payment flow. The design of the validation mechanism is up to the payment app, but the merchant validation event serves to inform the merchant of the URL they can use to validate themselves.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Step 6: The merchant validates the payment and completes the transaction #

When the customer successfully authorizes the payment, the show() method returns a promise that resolves to a PaymentResponse. The PaymentResponse object includes the following information:

Payment result details
Shipping address
Shipping option
Contact information

At this point, the browser UI may still show a loading indicator meaning that the transaction is not completed yet.

If the payment app is terminated because of a payment failure or error, the promise returned from show() rejects, and the browser terminates the payment transaction.

Processing and validating the payment #

The details in PaymentResponse is the payment credential object returned from the payment app. The merchant can use the credential to process or validate the payment. How this critical process works is up to the payment handler.

Completing or retrying the transaction #

After the merchant determines whether the transaction has succeded or failed, they can either:

Call the .complete() method to complete the transaction and dismiss the loading indicator.
Let the customer retry by calling the retry() method.

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Next Steps #

Learn how to declare a payment method identifier in detail in Setting up a payment method.
Learn how to build a platform-specific payment app in Android payment apps developer's guide.
Learn how to build a web-based payment app in Web-based payment apps developer's guide.

Empowering payment apps with Web Payments

2020-05-25T00:00:00Z

One of the key ecosystem drivers for the web are payments. With secure, seamless, and flexible payment systems, the web can become a sustainable and profitable platform. The Web Payments standards have the potential to be a key building block that will enable seamless integration of payment solutions into merchant checkout flows.

What is Web Payments? #

Web Payments is a series of new standardized payment APIs available in modern browsers, including Payment Request API, Payment Handler API and a few others. These new browser primitives simplify online payments and enable payment apps to integrate with browsers easier than ever.

The standards are flexible; they work with various types of payment systems and are intended to work on any browser on any device, payment method, or payment service provider. This flexibility enables development simplicity, deployment consistency, and future compatibility with emerging payment technologies.

Research shows that long checkout flows lead to cart abandonment. With Web Payments, checkout flow is simplified to a few taps instead of manual entry of billing data for every purchase. See a demo below of how Google Pay leverages Web Payments to build a seamless flow. The same can be achieved by any other payment app:

Checkout flow with Google Pay and Web Payments.

The customer goes to checkout and presses the GPay button.
The Google Pay app launches in front of the merchant website.
The customer confirms payment in the Google Pay app after examining the details.
The merchant verifies the payment and the purchase is approved.

Browser support #

Web Payments consists of a few different pieces of technologies and the support status depends on the browser.

	Chromium		Safari		Firefox
	Desktop	Android	Desktop	Mobile	Desktop/Mobile
Payment Request API	✔	✔	✔	✔
Payment Handler API	✔	✔
iOS/Android payment app	✔	✔	✔*	✔*

The benefits of integrating Web Payments in a payment app #

By integrating with Web Payments, payment apps can provide better user experience to customers, have better developer experience, and stricter security.

Better user experience #

In-context payments: Payments are made in modals, in context of the merchant website, without redirects or pop-up windows.
Faster checkout: Customers can save their payment details securely in their browser or a payment app, ready to be used on any supporting merchant site.
Streamlined purchase experience: After completing (or aborting) the payment, the customer is on the merchant website exactly where they left off.

Better developer experience #

Easy integration: Web Payments can be extended from an existing platform-specific payment app or a web-based payment app.
Low integration cost: Merchants can integrate Web Payments with JavaScript and basic level server-side integration.
Standards: The protocol and data format for exchanging information with merchants is standardized and doesn't require deep integration.

Stricter security #

Sideloading prevention when invoking platform-specific payment apps.
Designed with upcoming security and privacy paradigms in mind.

Using Web Payments also enables payment apps to bring any kind of payment method to the web such as e-money, cryptocurrency, bank transfers, and more. Web Payments is designed with sustainability in mind and doesn't put any restrictions on payment processing and payment methods.

Comparing Web Payments to other approaches #

Consider the existing approaches to integrating payments on the web:

iframes: Using JavaScript to inject the payment handler's website in an iframe and collect the customer's payment credential through a form.
Pop-ups: Using JavaScript to open a pop-up window and collect the customer's payment credentials, either through a form or by having the customer authenticate and select a payment credential.
Redirects: Merchant redirects the customer to a payment handler's website and lets the customer authenticate and select payment credentials. The redirect URL is communicated via a server.
OAuth: Merchant lets the customer authenticate and authorize with a payment handler's identity via OAuth, select a payment method, shipping address etc through in-context iframe UI.

Here's how they compare to Web Payments:

	Web Payments	iframe	Popup	Redirect	OAuth
In-context payments	✔	✔		✔*	✔
Dynamic price updates	✔				✔
Streamlined purchase experience	✔	✔			✔
Platform-specific app integration	✔			✔
Low integration cost	✔	✔	✔	✔
Standards	✔

Integrating Web Payments in existing apps #

You can integrate Web Payments in both platform-specific and web-based payment apps: if the platform-specific payment app is not installed, the web-based payment app can be used as a fallback. Customers and merchants can seamlessly send and receive payments through a payment method of their choice, depending on the environment.

Platform-specific payment apps #

Ideal for payment apps that already have a large install base and want to give existing users a consistent experience on the web.
Unlike Android's "Intent" feature, Web Payments performs signature verification before running the payment app which makes malicious payment apps impossible to be sideloaded.

In the video above, Google Pay is a platform-specific payment app.

Web based payment apps #

More future proof: typical payment app techniques like redirects or pop-ups are based on third party cookies that may become obsolete. While it's still hard to foresee the consequences, Web Payments look to the web with better privacy and a world without third party cookies.
The web-based route is ideal for web services that have a large number of customers with their card on file.

Checkout flow with a web-based payment app.

How does merchant adoption work? #

For a payment app to be available on a merchant, the merchant needs to explicitly adopt it. Technically speaking, the merchant has to specify the payment app's identifier (payment method identifier) and use the Payment Request API with it.

We suggest that you provide good documentation in integration guides and SDKs or libraries to facilitate integration. For example, Google Pay provides a developer's guide.

Working with payment gateways is also a good option as they can help scale your outreach as well.

How much does it cost? #

Web Payments is all about standard technology in the browser. Payment apps adopting it nor activating it on the browser won't charge them any fees by itself.

Android payment app developers guide

2020-05-25T00:00:00Z

The Payment Request API brings to the web a built-in browser-based interface that allows users to enter required payment information easier than ever before. The API can also invoke platform-specific payment apps.

Browser support

Chrome 60, Supported 60
Firefox 55, Behind a flag
Edge 15, Supported 15
Safari 11.1, Supported 11.1

Source

Checkout flow with platform-specific Google Pay app that uses Web Payments.

Compared to using just Android Intents, Web Payments allow better integration with the browser, security, and user experience:

The payment app is launched as a modal, in context of the merchant website.
Implementation is supplemental to your existing payment app, enabling you to take advantage of your user base.
The payment app's signature is checked to prevent sideloading.
Payment apps can support multiple payment methods.
Any payment method, such as cryptocurrency, bank transfers, and more, can be integrated. Payment apps on Android devices can even integrate methods that require access to the hardware chip on the device.

It takes four steps to implement Web Payments in an Android payment app:

Let merchants discover your payment app.
Let a merchant know if a customer has an enrolled instrument (such as credit card) that is ready to pay.
Let a customer make payment.
Verify the caller's signing certificate.

To see Web Payments in action, check out the android-web-payment demo.

Step 1: Let merchants discover your payment app #

In order for a merchant to use your payment app, they need to use the Payment Request API and specify the payment method you support using the payment method identifier.

If you have a payment method identifier that is unique to your payment app, you can set up your own payment method manifest so browsers can discover your app.

Step 2: Let a merchant know if a customer has an enrolled instrument that is ready to pay #

The merchant can call hasEnrolledInstrument() to query whether the customer is able to make a payment. You can implement IS_READY_TO_PAY as an Android service to answer this query.

`AndroidManifest.xml` #

Declare your service with an intent filter with the action org.chromium.intent.action.IS_READY_TO_PAY.

<service
  android:name=".SampleIsReadyToPayService"
  android:exported="true">
  <intent-filter>
    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY" />
  </intent-filter>
</service>

The IS_READY_TO_PAY service is optional. If there's no such intent handler in the payment app, then the web browser assumes that the app can always make payments.

AIDL #

The API for the IS_READY_TO_PAY service is defined in AIDL. Create two AIDL files with the following content:

app/src/main/aidl/org/chromium/IsReadyToPayServiceCallback.aidl

package org.chromium;
interface IsReadyToPayServiceCallback {
    oneway void handleIsReadyToPay(boolean isReadyToPay);
}

app/src/main/aidl/org/chromium/IsReadyToPayService.aidl

package org.chromium;
import org.chromium.IsReadyToPayServiceCallback;

interface IsReadyToPayService {
    oneway void isReadyToPay(IsReadyToPayServiceCallback callback);
}

Implementing `IsReadyToPayService` #

The simplest implementation of IsReadyToPayService is shown in the following example:

class SampleIsReadyToPayService : Service() {
  private val binder = object : IsReadyToPayService.Stub() {
    override fun isReadyToPay(callback: IsReadyToPayServiceCallback?) {
      callback?.handleIsReadyToPay(true)
    }
  }

  override fun onBind(intent: Intent?): IBinder? {
    return binder
  }
}

Response #

The service can send its response via handleIsReadyToPay(Boolean) method.

callback?.handleIsReadyToPay(true)

Permission #

You can use Binder.getCallingUid() to check who the caller is. Note that you have to do this in the isReadyToPay method, not in the onBind method.

override fun isReadyToPay(callback: IsReadyToPayServiceCallback?) {
  try {
    val callingPackage = packageManager.getNameForUid(Binder.getCallingUid())
    // …

See Verify the caller's signing certificate about how to verify that the calling package has the right signature.

Step 3: Let a customer make payment #

The merchant calls show() to launch the payment app so the customer can make a payment. The payment app is invoked via an Android intent PAY with transaction information in the intent parameters.

The payment app responds with methodName and details, which are payment app specific and are opaque to the browser. The browser converts the details string into a JavaScript object for the merchant via JSON deserialization, but does not enforce any validity beyond that. The browser does not modify the details; that parameter's value is passed directly to the merchant.

`AndroidManifest.xml` #

The activity with the PAY intent filter should have a <meta-data> tag that identifies the default payment method identifier for the app.

To support multiple payment methods, add a <meta-data> tag with a <string-array> resource.

<activity
  android:name=".PaymentActivity"
  android:theme="@style/Theme.SamplePay.Dialog">
  <intent-filter>
    <action android:name="org.chromium.intent.action.PAY" />
  </intent-filter>

  <meta-data
    android:name="org.chromium.default_payment_method_name"
    android:value="https://bobbucks.dev/pay" />
  <meta-data
    android:name="org.chromium.payment_method_names"
    android:resource="@array/method_names" />
</activity>

The resource must be a list of strings, each of which must be a valid, absolute URL with an HTTPS scheme as shown here.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="method_names">
        <item>https://alicepay.com/put/optional/path/here</item>
        <item>https://charliepay.com/put/optional/path/here</item>
    </string-array>
</resources>

Parameters #

The following parameters are passed to the activity as Intent extras:

methodNames
methodData
topLevelOrigin
topLevelCertificateChain
paymentRequestOrigin
total
modifiers
paymentRequestId

val extras: Bundle? = intent?.extras

methodNames #

The names of the methods being used. The elements are the keys in the methodData dictionary. These are the methods that the payment app supports.

val methodNames: List<String>? = extras.getStringArrayList("methodNames")

`methodData` #

A mapping from each of the methodNames to the methodData.

val methodData: Bundle? = extras.getBundle("methodData")

merchantName #

The contents of the <title> HTML tag of the merchant's checkout page (the browser's top-level browsing context).

val merchantName: String? = extras.getString("merchantName")

`topLevelOrigin` #

The merchant's origin without the scheme (The scheme-less origin of the top-level browsing context). For example, https://mystore.com/checkout is passed as mystore.com.

val topLevelOrigin: String? = extras.getString("topLevelOrigin")

`topLevelCertificateChain` #

The merchant's certificate chain (The certificate chain of the top-level browsing context). Null for localhost and file on disk, which are both secure contexts without SSL certificates. Each Parcelable is a Bundle with a certificate key and a byte array value.

val topLevelCertificateChain: Array<Parcelable>? =
    extras.getParcelableArray("topLevelCertificateChain")
val list: List<ByteArray>? = topLevelCertificateChain?.mapNotNull { p ->
  (p as Bundle).getByteArray("certificate")
}

`paymentRequestOrigin` #

The scheme-less origin of the iframe browsing context that invoked the new PaymentRequest(methodData, details, options) constructor in JavaScript. If the constructor was invoked from the top-level context, then the value of this parameter equals the value of topLevelOrigin parameter.

val paymentRequestOrigin: String? = extras.getString("paymentRequestOrigin")

`total` #

The JSON string representing the total amount of the transaction.

val total: String? = extras.getString("total")

Here's an example content of the string:

{"currency":"USD","value":"25.00"}

`modifiers` #

The output of JSON.stringify(details.modifiers), where details.modifiers contain only supportedMethods and total.

`paymentRequestId` #

The PaymentRequest.id field that "push-payment" apps should associate with the transaction state. Merchant websites will use this field to query the "push-payment" apps for the state of transaction out of band.

val paymentRequestId: String? = extras.getString("paymentRequestId")

Response #

The activity can send its response back through setResult with RESULT_OK.

setResult(Activity.RESULT_OK, Intent().apply {
  putExtra("methodName", "https://bobbucks.dev/pay")
  putExtra("details", "{\"token\": \"put-some-data-here\"}")
})
finish()

You must specify two parameters as Intent extras:

methodName: The name of the method being used.
details: JSON string containing information necessary for the merchant to complete the transaction. If success is true, then details must be constructed in such a way that JSON.parse(details) will succeed.

You can pass RESULT_CANCELED if the transaction was not completed in the payment app, for example, if the user failed to type in the correct PIN code for their account in the payment app. The browser may let the user choose a different payment app.

setResult(RESULT_CANCELED)
finish()

If the activity result of a payment response received from the invoked payment app is set to RESULT_OK, then Chrome will check for non-empty methodName and details in its extras. If the validation fails Chrome will return a rejected promise from request.show() with one of the following developer facing error messages:

'Payment app returned invalid response. Missing field "details".'
'Payment app returned invalid response. Missing field "methodName".'

Permission #

The activity can check the caller with its getCallingPackage() method.

val caller: String? = callingPackage

The final step is to verify the caller's signing certificate to confirm that the calling package has the right signature.

Step 4: Verify the caller's signing certificate #

You can check the caller's package name with Binder.getCallingUid() in IS_READY_TO_PAY, and with Activity.getCallingPackage() in PAY. In order to actually verify that the caller is the browser you have in mind, you should check its signing certificate and make sure that it matches with the correct value.

If you're targeting API level 28 and above and are integrating with a browser that has a single signing certificate, you can use PackageManager.hasSigningCertificate().

val packageName: String = … // The caller's package name
val certificate: ByteArray = … // The correct signing certificate.
val verified = packageManager.hasSigningCertificate(
  callingPackage,
  certificate,
  PackageManager.CERT_INPUT_SHA256
)

PackageManager.hasSigningCertificate() is preferred for single certificate browsers, because it correctly handles certificate rotation. (Chrome has a single signing certificate.) Apps that have multiple signing certificates cannot rotate them.

If you need to support older API levels 27 and below, or if you need to handle browsers with multiple signing certificates, you can use PackageManager.GET_SIGNATURES.

val packageName: String = … // The caller's package name
val certificates: Set<ByteArray> = … // The correct set of signing certificates

val packageInfo = getPackageInfo(packageName, PackageManager.GET_SIGNATURES)
val sha256 = MessageDigest.getInstance("SHA-256")
val signatures = packageInfo.signatures.map { sha256.digest(it.toByteArray()) }
val verified = signatures.size == certificates.size &&
    signatures.all { s -> certificates.any { it.contentEquals(s) } }

Why you need "cross-origin isolated" for powerful features

2020-05-04T00:00:00Z

Introduction #

In Making your website "cross-origin isolated" using COOP and COEP we explained how to adopt to "cross-origin isolated" state using COOP and COEP. This is a companion article that explains why cross-origin isolation is required to enable powerful features on the browser.

Background #

The web is built on the same-origin policy: a security feature that restricts how documents and scripts can interact with resources from another origin. This principle restricts the ways websites can access cross-origin resources. For example, a document from https://a.example is prevented from accessing data hosted at https://b.example.

However, the same-origin policy has had some historical exceptions. Any website can:

Embed cross-origin iframes
Include cross-origin resources such as images or scripts
Open cross-origin popup windows with a DOM reference

If the web could be designed from scratch, these exceptions wouldn't exist. Unfortunately, by the time the web community realized the key benefits of a strict same-origin policy, the web was already relying on these exceptions.

The security side-effects of such a lax same-origin policy were patched in two ways. One way was through the introduction of a new protocol called Cross Origin Resource Sharing (CORS) whose purpose is to make sure that the server allows sharing a resource with a given origin. The other way is by implicitly removing direct script access to cross-origin resources while preserving backward compatibility. Such cross-origin resources are called "opaque" resources. For example, this is why manipulating the pixels of a cross-origin image via CanvasRenderingContext2D fails unless CORS is applied to the image.

All these policy decisions are happening within a browsing context group.

For a long time, the combination of CORS and opaque resources was enough to make browsers safe. Sometimes edge cases (such as JSON vulnerabilities) were discovered, and needed to be patched, but overall the principle of not allowing direct read access to the raw bytes of cross-origin resources was successful.

This all changed with Spectre, which makes any data that is loaded to the same browsing context group as your code potentially readable. By measuring the time certain operations take, attackers can guess the contents of the CPU caches, and through that, the contents of the process' memory. Such timing attacks are possible with low-granularity timers that exist in the platform, but can be sped up with high-granularity timers, both explicit (like performance.now()) and implicit (like SharedArrayBuffers). If evil.com embeds a cross-origin image, they can use a Spectre attack to read its pixel data, which makes protections relying on "opaqueness" ineffective.

Ideally, all cross-origin requests should be explicitly vetted by the server that owns the resource. If vetting is not provided by the resource-owning server, then the data will never make it into the browsing context group of an evil actor, and therefore will stay out of reach of any Spectre attacks a web page could carry out. We call it a cross-origin isolated state. This is exactly what COOP+COEP is about.

Under a cross-origin isolated state, the requesting site is considered less dangerous and this unlocks powerful features such as SharedArrayBuffer, performance.measureUserAgentSpecificMemory() and high resolution timers with better precision which could otherwise be used for Spectre-like attacks. It also prevents modifying document.domain.

Cross Origin Embedder Policy #

Cross Origin Embedder Policy (COEP) prevents a document from loading any cross-origin resources that don't explicitly grant the document permission (using CORP or CORS). With this feature, you can declare that a document cannot load such resources.

To activate this policy, append the following HTTP header to the document:

Cross-Origin-Embedder-Policy: require-corp

The require-corp keyword is the only accepted value for COEP. This enforces the policy that the document can only load resources from the same origin, or resources explicitly marked as loadable from another origin.

For resources to be loadable from another origin, they need to support either Cross Origin Resource Sharing (CORS) or Cross Origin Resource Policy (CORP).

Cross Origin Resource Sharing #

If a cross origin resource supports Cross Origin Resource Sharing (CORS), you may use the crossorigin attribute to load it to your web page without being blocked by COEP.

<img src="https://third-party.example.com/image.jpg" crossorigin>

For example, if this image resource is served with CORS headers, use the crossorigin attribute so that the request to fetch the resource will use CORS mode. This also prevents the image from being loaded unless it sets CORS headers.

Similarly, you may fetch cross origin data through the fetch() method, which doesn't require special handling as long as the server responds with the right HTTP headers.

Cross Origin Resource Policy #

Cross Origin Resource Policy (CORP) was originally introduced as an opt-in to protect your resources from being loaded by another origin. In the context of COEP, CORP can specify the resource owner's policy for who can load a resource.

The Cross-Origin-Resource-Policy header takes three possible values:

Cross-Origin-Resource-Policy: same-site

Resources that are marked same-site can only be loaded from the same site.

Cross-Origin-Resource-Policy: same-origin

Resources that are marked same-origin can only be loaded from the same origin.

Cross-Origin-Resource-Policy: cross-origin

Resources that are marked cross-origin can be loaded by any website. (This value was added to the CORP spec along with COEP.)

Cross Origin Opener Policy #

Cross Origin Opener Policy (COOP) allows you to ensure that a top-level window is isolated from other documents by putting them in a different browsing context group, so that they cannot directly interact with the top-level window. For example, if a document with COOP opens a pop-up, its window.opener property will be null. Also, the .closed property of the opener's reference to it will return true.

The Cross-Origin-Opener-Policy header takes three possible values:

Cross-Origin-Opener-Policy: same-origin

Documents that are marked same-origin can share the same browsing context group with same-origin documents that are also explicitly marked same-origin.

Cross-Origin-Opener-Policy: same-origin-allow-popups

A top-level document with same-origin-allow-popups retains references to any of its popups which either don't set COOP or which opt out of isolation by setting a COOP of unsafe-none.

Cross-Origin-Opener-Policy: unsafe-none

unsafe-none is the default and allows the document to be added to its opener's browsing context group unless the opener itself has a COOP of same-origin.

Summary #

If you want guaranteed access to powerful features like SharedArrayBuffer, performance.measureUserAgentSpecificMemory() or high resolution timers with better precision, just remember that your document needs to use both COEP with the value of require-corp and COOP with the value of same-origin. In the absence of either, the browser will not guarantee sufficient isolation to safely enable those powerful features. You can determine your page's situation by checking if self.crossOriginIsolated returns true.

Learn the steps to implement this at Making your website "cross-origin isolated" using COOP and COEP.

Resources #

Understanding "same-site" and "same-origin"

2020-04-15T00:00:00Z

"same-site" and "same-origin" are frequently cited but often misunderstood terms. For example, they are mentioned in the context of page transitions, fetch() requests, cookies, opening popups, embedded resources, and iframes.

Origin #

"Origin" is a combination of a scheme (also known as the protocol, for example HTTP or HTTPS), hostname, and port (if specified). For example, given a URL of https://www.example.com:443/foo , the "origin" is https://www.example.com:443.

"same-origin" and "cross-origin" #

Websites that have the combination of the same scheme, hostname, and port are considered "same-origin". Everything else is considered "cross-origin".

Origin A	Origin B	Explanation of whether Origin A and B are "same-origin" or "cross-origin"
https://www.example.com:443	https://www.evil.com:443	cross-origin: different domains
	https://example.com:443	cross-origin: different subdomains
	https://login.example.com:443	cross-origin: different subdomains
	http://www.example.com:443	cross-origin: different schemes
	https://www.example.com:80	cross-origin: different ports
	https://www.example.com:443	same-origin: exact match
	https://www.example.com	same-origin: implicit port number (443) matches

Site #

Top-level domains (TLDs) such as .com and .org are listed in the Root Zone Database. In the example above, "site" is the combination of the scheme, the TLD and the part of the domain just before it (We call it TLD+1). For example, given a URL of https://www.example.com:443/foo , the "site" is https://example.com.

Public Suffix List and eTLD #

For domains that include things such as .co.jp or .github.io, just using .jp or .io is not granular enough to identify the "site". There is no way to algorithmically determine the level of registrable domains for a particular TLD. That's why a list of public suffixes defined in the Public Suffix List was created. These public suffixes are also called effective TLDs (eTLDs). The list of eTLDs is maintained at publicsuffix.org/list.

To identify the "site" part of a domain that includes an eTLD, apply the same practice as the example with .com. Taking https://www.project.github.io:443/foo as an example, the scheme is https, the eTLD is .github.io and the eTLD+1 is project.github.io, so https://project.github.io is considered the "site" for this URL.

"same-site" and "cross-site" #

Websites that have the same scheme and the same eTLD+1 are considered "same-site". Websites that have a different scheme or a different eTLD+1 are "cross-site".

Origin A	Origin B	Explanation of whether Origin A and B are "same-site" or "cross-site"
https://www.example.com:443	https://www.evil.com:443	cross-site: different domains
	https://login.example.com:443	same-site: different subdomains don't matter
	http://www.example.com:443	cross-site: different schemes
	https://www.example.com:80	same-site: different ports don't matter
	https://www.example.com:443	same-site: exact match
	https://www.example.com	same-site: ports don't matter

"schemeless same-site" #

The definition of "same-site" evolved to consider the URL scheme as part of the site in order to prevent HTTP being used as a weak channel. The older concept of "same-site" without scheme comparison is now called "schemeless same-site". For example, http://www.example.com and https://www.example.com are considered schemeless same-site but not same-site, because only the eTLD+1 part matters and the scheme is not taken into account.

Origin A	Origin B	Explanation of whether Origin A and B are "schemeless same-site"
https://www.example.com:443	https://www.evil.com:443	cross-site: different domains
	https://login.example.com:443	schemeless same-site: different subdomains don't matter
	http://www.example.com:443	schemeless same-site: different schemes don't matter
	https://www.example.com:80	schemeless same-site: different ports don't matter
	https://www.example.com:443	schemeless same-site: exact match
	https://www.example.com	schemeless same-site: ports don't matter

How to check if a request is "same-site", "same-origin", or "cross-site" #

All modern browsers (Safari support landing soon) send requests along with a Sec-Fetch-Site HTTP header. The header has one of the following values:

cross-site
same-site
same-origin
none

By examining the value of Sec-Fetch-Site, you can determine if the request is "same-site", "same-origin", or "cross-site".

Making your website "cross-origin isolated" using COOP and COEP

2020-04-13T00:00:00Z

Updates

June 21, 2022: Worker scripts also need care when cross-origin isolation is enabled. Added some explanations.
Aug 5, 2021: JS Self-Profiling API has been mentioned as one of APIs that require cross-origin isolation, but reflecting recent change of the direction, it's removed.
May 6, 2021: Based on feedback and issues reported we've decided to adjust the timeline for SharedArrayBuffer usage in none cross-origin isolated sites to be restricted in Chrome M92.
April 16, 2021: Added notes about a new COEP credentialless mode and COOP same-origin-allow-popups to be a relaxed condition for cross-origin isolation.
March 5, 2021: Removed limitations for SharedArrayBuffer, performance.measureUserAgentSpecificMemory(), and debugging functionalities, which are now fully enabled in Chrome 89. Added upcoming capabilities, performance.now() and performance.timeOrigin, that will have higher precision.
February 19, 2021: Added a note about feature policy allow="cross-origin-isolated" and debugging functionality on DevTools.
October 15, 2020: self.crossOriginIsolated is available from Chrome 87. Reflecting that, document.domain is immutable when self.crossOriginIsolated returns true. performance.measureUserAgentSpecificMemory() is ending its origin trial and is enabled by default in Chrome 89. Shared Array Buffer on Android Chrome will be available from Chrome 88.

Some web APIs increase the risk of side-channel attacks like Spectre. To mitigate that risk, browsers offer an opt-in-based isolated environment called cross-origin isolated. With a cross-origin isolated state, the webpage will be able to use privileged features including:

Features that will be available behind cross-origin isolated state.
API	Description
`SharedArrayBuffer`	Required for WebAssembly threads. This is available from Android Chrome 88. Desktop version is currently enabled by default with the help of Site Isolation, but will require the cross-origin isolated state and will be disabled by default in Chrome 92.
`performance.measureUserAgentSpecificMemory()`	Available from Chrome 89.
`performance.now()`, `performance.timeOrigin`	Currently available in many browsers with the resolution limited to 100 microseconds or higher. With cross-origin isolation, the resolution can be 5 microseconds or higher.

The cross-origin isolated state also prevents modifications of document.domain. (Being able to alter document.domain allows communication between same-site documents and has been considered a loophole in the same-origin policy.)

To opt in to a cross-origin isolated state, you need to send the following HTTP headers on the main document:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

These headers instruct the browser to block loading of resources or iframes which haven't opted into being loaded by cross-origin documents, and prevent cross-origin windows from directly interacting with your document. This also means those resources being loaded cross-origin require opt-ins.

You can determine whether a web page is in a cross-origin isolated state by examining self.crossOriginIsolated.

This article shows how to use these new headers. In a follow-up article I will provide more background and context.

Deploy COOP and COEP to make your website cross-origin isolated #

Integrate COOP and COEP #

1. Set the `Cross-Origin-Opener-Policy: same-origin` header on the top-level document #

By enabling COOP: same-origin on a top-level document, windows with the same origin, and windows opened from the document, will have a separate browsing context group unless they are in the same origin with the same COOP setting. Thus, isolation is enforced for opened windows and mutual communication between both windows is disabled.

A browsing context group is a set of windows that can reference each other. For example, a top-level document and its child documents embedded via <iframe>. If a website (https://a.example) opens a popup window (https://b.example), the opener window and the popup window share the same browsing context, therefore they have access to each other via DOM APIs such as window.opener.

You can check if the window opener and its openee are in separate browsing context groups from DevTools.

2. Ensure resources have CORP or CORS enabled #

Make sure that all resources in the page are loaded with CORP or CORS HTTP headers. This step is required for step four, enabling COEP.

Here is what you need to do depending on the nature of the resource:

If the resource is expected to be loaded only from the same origin, set the Cross-Origin-Resource-Policy: same-origin header.
If the resource is expected to be loaded only from the same site but cross origin, set the Cross-Origin-Resource-Policy: same-site header.
If the resource is loaded from cross origin(s) under your control, set the Cross-Origin-Resource-Policy: cross-origin header if possible.
For cross origin resources that you have no control over:
- Use the crossorigin attribute in the loading HTML tag if the resource is served with CORS. (For example, <img src="***" crossorigin>.)
- Ask the owner of the resource to support either CORS or CORP.
For iframes, follow the same principles above and set the Cross-Origin-Resource-Policy: cross-origin (or same-site, same-origin depending on the context).
Scripts loaded with a WebWorker must be served from same-origin, so you don't need a CORP or CORS headers.
For a document or a worker served with COEP: require-corp, cross-origin subresources loaded without CORS must set the Cross-Origin-Resource-Policy: cross-origin header to opt into being embedded. For example, this applies to <script>, importScripts, <link>, <video>, <iframe>, etc.

3. Use the COEP Report-Only HTTP header to assess embedded resources #

Before fully enabling COEP, you can do a dry run by using the Cross-Origin-Embedder-Policy-Report-Only header to examine whether the policy actually works. You will receive reports without blocking embedded content.

Recursively apply this to all documents including the top-level document, iframes and worker scripts. For information on the Report-Only HTTP header, see Observe issues using the Reporting API.

4. Enable COEP #

Once you've confirmed that everything works, and that all resources can be successfully loaded, switch the Cross-Origin-Embedder-Policy-Report-Only header to the Cross-Origin-Embedder-Policy header with the same value to all documents including those that are embedded via iframes and worker scripts.

Caution

We've been exploring ways to deploy Cross-Origin-Resource-Policy at scale, as cross-origin isolation requires all subresources to explicitly opt-in. And we have come up with the idea of going in the opposite direction: a new COEP "credentialless" mode that allows loading resources without the CORP header by stripping all their credentials. We hope this will lighten your burden of making sure the subresources are sending the Cross-Origin-Resource-Policy header. However, since credentialless mode is available on Chrome from version 96 but not supported by any other browsers yet, some developers might find it challenging to deploy COOP or COEP. If you prefer not to enable cross-origin isolation yet, we recommend registering for an origin trial and waiting until credentialless is available in more browsers.

Determine whether isolation succeeded with `self.crossOriginIsolated` #

The self.crossOriginIsolated property returns true when the web page is in a cross-origin isolated state and all resources and windows are isolated within the same browsing context group. You can use this API to determine whether you have successfully isolated the browsing context group and gained access to powerful features like performance.measureUserAgentSpecificMemory().

Debug issues using Chrome DevTools #

For resources that are rendered on the screen such as images, it's fairly easy to detect COEP issues because the request will be blocked and the page will indicate a missing image. However, for resources that don't necessarily have a visual impact, such as scripts or styles, COEP issues might go unnoticed. For those, use the DevTools Network panel. If there's an issue with COEP, you should see (blocked:NotSameOriginAfterDefaultedToSameOriginByCoep) in the Status column.

You can then click the entry to see more details.

You can also determine the status of iframes and popup windows through the Application panel. Go to the "Frames" section on the left hand side and expand "top" to see the breakdown of the resource structure.

You can check the iframe's status such as availability of `SharedArrayBuffer`, etc.

You can also check the popup windows's status such as whether it's cross-origin isolated.

Observe issues using the Reporting API #

The Reporting API is another mechanism through which you can detect various issues. You can configure the Reporting API to instruct your users' browser to send a report whenever COEP blocks the loading of a resource or COOP isolates a pop-up window. Chrome has supported the Reporting API since version 69 for a variety of uses including COEP and COOP.

To learn how to configure the Reporting API and set up a server to receive reports, head over to Using the Reporting API.

Example COEP report #

An example COEP report payload when cross-origin resource is blocked looks like this:

[{
  "age": 25101,
  "body": {
    "blocked-url": "https://third-party-test.glitch.me/check.svg?",
    "blockedURL": "https://third-party-test.glitch.me/check.svg?",
    "destination": "image",
    "disposition": "enforce",
    "type": "corp"
  },
  "type": "coep",
  "url": "https://cross-origin-isolation.glitch.me/?coep=require-corp&coop=same-origin&",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4249.0 Safari/537.36"
}]

Example COOP report #

An example COOP report payload when a pop-up window is opened isolated looks like this:

[{
  "age": 7,
  "body": {
    "disposition": "enforce",
    "effectivePolicy": "same-origin",
    "nextResponseURL": "https://third-party-test.glitch.me/popup?report-only&coop=same-origin&",
    "type": "navigation-from-response"
  },
  "type": "coop",
  "url": "https://cross-origin-isolation.glitch.me/coop?coop=same-origin&",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4246.0 Safari/537.36"
}]

When different browsing context groups try to access each other (only on "report-only" mode), COOP also sends a report. For example, a report when postMessage() is attempted would look like this:

[{
  "age": 51785,
  "body": {
    "columnNumber": 18,
    "disposition": "reporting",
    "effectivePolicy": "same-origin",
    "lineNumber": 83,
    "property": "postMessage",
    "sourceFile": "https://cross-origin-isolation.glitch.me/popup.js",
    "type": "access-from-coop-page-to-openee"
  },
  "type": "coop",
  "url": "https://cross-origin-isolation.glitch.me/coop?report-only&coop=same-origin&",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4246.0 Safari/537.36"
},
{
  "age": 51785,
  "body": {
    "disposition": "reporting",
    "effectivePolicy": "same-origin",
    "property": "postMessage",
    "type": "access-to-coop-page-from-openee"
  },
  "type": "coop",
  "url": "https://cross-origin-isolation.glitch.me/coop?report-only&coop=same-origin&",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4246.0 Safari/537.36"
}]

Conclusion #

Use a combination of COOP and COEP HTTP headers to opt a web page into a special cross-origin isolated state. You will be able to examine self.crossOriginIsolated to determine whether a web page is in a cross-origin isolated state.

We'll keep this post updated as new features are made available to this cross-origin isolated state, and further improvements are made to DevTools around COOP and COEP.

Resources #

Updates to the Web Payments APIs

2019-06-13T00:00:00Z

Web Payments have been publicly available in browsers since 2016. The core feature—the Payment Request API—is now available across multiple browsers: Chrome, Safari, Edge and soon Firefox. If you're new to Web Payments take a look at the "Web Payments Overview" to get started.

Since the launch of the Payment Request API and the Payment Handler API, there have been quite a few changes made to their respective specifications. These changes won't break your working code, but we recommend that you look out for them. This post summarizes those updates and will continue accumulating those API changes.

New method: `hasEnrolledInstrument()` #

In the previous version of the Payment Request API, canMakePayment() was used to check for the user's presence of the user's payment instrument. In a recent update to the spec, canMakePayment() has been replaced with hasEnrolledInstrument() without changing its functionality.

The hasEnrolledInstrument() method has consensus from all major browsers. Chrome has implemented it in version 74 and both Webkit and Gecko have tracking bugs but have not yet implemented the method as of June 2019.

To use the new hasEnrolledInstrument() method, replace code that looks like this:

// Checking for instrument presence.
request.canMakePayment().then(handleInstrumentPresence).catch(handleError);

With code that looks like this:

// Checking for instrument presence.
if (request.hasEnrolledInstrument) {
  // hasEnrolledInstrument() is available.
  request.hasEnrolledInstrument().then(handleInstrumentPresence).catch(handleError);
} else {
  request.canMakePayment().then(handleInstrumentPresence).catch(handleError);
}

`canMakePayment()` no longer checks for instrument presence #

Because hasEnrolledInstrument() now handles checking for the user's payment instrument, canMakePayment() has been updated to only check for payment app availability.

This change to canMakePayment() is bound to the implementation of hasEnrolledInstrument(). As of June 2019, it is implemented in Chrome 74 but not in any other browsers. Be sure to check if the hasEnrolledInstrument() method is available in the user's browser before attempting to use it.

// Checking for payment app availability without checking for instrument presence.
if (request.hasEnrolledInstrument) {
  // `canMakePayment()` behavior change corresponds to
  // `hasEnrolledInstrument()` availability.
  request.canMakePayment().then(handlePaymentAppAvailable).catch(handleError);
} else {
  console.log("Cannot check for payment app availability without checking for instrument presence.");
}

`languageCode` removed from `basic-card` payment method #

PaymentAddress.languageCode has been removed from the shipping addresses and billing addresses for basic-card. The billing addresses of other payment methods (such as Google Pay) are not affected.

This change has been implemented in Chrome 74, Firefox, and Safari.

`PaymentRequest.show()` now takes an optional `detailsPromise` #

PaymentRequest.show() allows a merchant to present a payment request UI before the final total is known. The merchant has ten seconds to resolve the detailsPromise before a timeout. This feature is intended for a quick server-side roundtrip.

This feature has shipped in Chrome 75 and Safari.

// Not implemented in Chrome 74 and older.
// There's no way to feature-detect this, so check a few
// older versions of Chrome that you're seeing hit your servers.
if (/Chrome\/((6[0-9])|(7[0-4]))/g.exec(navigator.userAgent) !== null) {
  return;
}

// Supported in Chrome 75+.
request.show(new Promise(function(resolveDetailsPromise, rejectDetailsPromise) {
  // Find out the exact total amount and call
  // `resolveDetailsPromise(details)`.
  // Use a 3 second timeout as an example.
  window.setTimeout(function() {
    resolveDetailsPromise(details);
  }, 3000); // 3 seconds.
}))
.then(handleResponse)
.catch(handleError);

`PaymentRequestEvent.changePaymentMethod()` #

The Payment Handler API feature PaymentRequestEvent.changePaymentMethod() allows payment handlers (e.g., Google Pay) to trigger the onpaymentmethodchange event handler. changePaymentMethod() returns a promise that resolves to a merchant response with updated price information (e.g., tax recalculation).

Both PaymentRequestEvent.changePaymentMethod() and the paymentmethodchange event are available in Chrome 76 and Webkit has implemented the paymentmethodchange event in its Technology Preview.

// In service worker context, `self` is the global object.
self.addEventListener('paymentrequest', (evt) => {
  evt.respondWith(new Promise((confirmPaymentFunction, rejectPaymentFunction) => {
    if (evt.changePaymentMethod === undefined) {
      // Not implemented in this version of Chrome.
      return;
    }
    // Notify merchant that the user selected a different payment method.
    evt.changePaymentMethod('https://paymentapp.com', {country: 'US'})
    .then((responseFromMerchant) => {
      if (responseFromMerchant === null) {
        // Merchant ignored the 'paymentmethodchange' event.
        return;
      }
      handleResponseFromMerchant(responseFromMerchant);
    })
    .catch((error) => {
      handleError(error);
    });
  }));
});

Merchant example:

if (request.onpaymentmethodchange === undefined) {
  // Feature not available in this browser.
  return;
}

request.addEventListener('paymentmethodchange', (evt) => {
  evt.updateWith(updateDetailsBasedOnPaymentMethod(evt, paymentDetails));
});

Improved local development #

Chrome 76 adds two small improvements for developer productivity. If your local development environment uses a self-signed certificate, you can now use the --ignore-certificate-errors command line flag to make Chrome allow Web Payments APIs in your development environment. If you develop using a local web server that does not support HTTPS, you can also use the --unsafely-treat-insecure-origin-as-secure=<origin> flag to make Chrome treat the HTTP origin as HTTPS.

How Payment Request API works

2018-09-10T00:00:00Z

Payment Request API #

When a customer tries to purchase something from your website, the site must ask the customer to provide payment information and, optionally, other information such as shipping preference. You can achieve this easily and quickly using the Payment Request API (PR API).

Basic structure #

Constructing a PaymentRequest object requires two parameters: payment methods and payment details. In addition, a third payment options parameter is optional. A basic request could be created like this:

const request = new PaymentRequest(paymentMethods, paymentDetails);

Let's look at how each parameter is built and used.

Payment methods #

The first parameter, paymentMethods, is a list of supported payment methods in an array variable. Each element in the array comprises two components, supportedMethods and, optionally, data.

For supportedMethods, the merchant needs to specify a Payment Method Identifier such as https://bobbucks.dev/pay. The existence and content of data depends on the content of supportedMethods and payment app provider's design.

Both pieces of information should be provided by the payment app provider.

// Supported payment methods
const paymentMethods = [{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: {
    ... // Optional parameters defined by the payment app provider.
  }
}];

Payment details #

The second parameter, paymentDetails, is passed as an object and specifies payment details for the transaction. It contains the required value total, which specifies the total amount due from the customer. This parameter can also optionally list the purchased items.

In the example below, the optional purchased items list (just one item, in this case) is shown, as is the required total amount due. In both cases the currency unit is specified with each individual amount.

const paymentDetails = {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
};

Check whether the payment method is available #

Before invoking the payment procedure, the merchant can check whether the user and the environment are ready for making a payment.

Calling canMakePayment() checks if the browser supports at least one payment method specified in the object.

request.canMakePayment().then(result => {
  if (result) {
    // This browser supports the specified payment method.
  } else {
    // This browser does NOT support the specified payment method.
  }
}).catch(e => {
  // An exception
});

Learn more about PaymentRequest.canMakePayment() on MDN

The `show()` method #

After setting the two parameters and creating the request object as shown above, you can call the show() method, which displays the payment app user interface.

request.show().then(response => {
  // [process payment]
  // send to a PSP etc.
  response.complete('success');
});

How payment app user interface will look is completely up to the payment app provider. After the customer agrees to make a payment, a JSON object is passed to the merchant which contains all the required information to transfer money. The merchant can then send it to the PSP to process the payment.

Finally, you may close the Payment Request UI by completing the process with response.complete('success') or response.complete('fail') depending on the result that the PSP returns.

Next up #

Learn more about Web Payments.

How the payment ecosystem works

2018-09-10T00:00:00Z

Let's see how the payment ecosystem works with Web Payments.

The anatomy of Web Payments #

Web Payments comprises multiple web standards:

Payment Request API: The Payment Request API enables fast and easy checkouts through a native browser UI. It provides a consistent checkout flow while reducing the need for users to enter their shipping and payment information on every checkout.
Payment Handler API: The Payment Handler API opens up the ecosystem to payment providers by allowing their web-based payment applications to act as payment methods on merchant websites through the standard Payment Request API.
Payment Method Identifiers: The Payment Method Identifiers defines how strings (https://google.com/pay, https://apple.com/apple-pay, and so on) can be used to identify a payment method. Along with standardized payment method identifiers, it allows anyone to define their own payment method with URL-based payment method identifiers.
Payment Method Manifest: The Payment Method Manifest defines the machine-readable manifest file, known as a payment method manifest, describing how a payment method participates in the payment ecosystem, and how such files are to be used.

How the payment request process works #

There are typically four participants in an online transaction.

Players	Description	API usage
Customers	Users who go through a checkout flow to purchase item(s) online.	N/A
Merchants	Businesses selling products on their website.	Payment Request API
Payment Service Providers (PSPs)	Third-party companies that actually process payments, which involves charging customers and crediting merchants. Alternatively called payment gateways or payment processors.	Payment Request API
Payment Handlers	Third-party companies which provide applications that typically store customers' payment credentials and on their authorization provide them to merchants to process a transaction.	Payment Handler API

The typical sequence of events in processing a credit card payment on the web

The Customer visits a merchant's website, adds items to a shopping cart, and starts the checkout flow.
The Merchant needs the customer's payment credentials to process the transaction. They present a payment request UI to the customer using the Payment Request API. The UI lists various methods of payment specified by the Payment Method Identifiers. The payment methods can include credit card numbers saved to the browser, or payment handlers such as Google Pay, Samsung Pay, and similar. The Merchant can optionally request the customer's shipping address and contact information.
If the customer chooses a payment method like Google Pay, Chrome launches either a platform-native payment app or a web-based payment app. This step is completely up to the payment handler's implementation, based on the Payment Method Manifest. After the customer authorizes the payment, the payment handler returns a response to the Payment Request API, which relays it to the merchant site. (If the payment is push type such as bank transfers, cryptocurrencies, the payment is already processed when the merchant receives the response.)
The merchant site sends a payment credential to a PSP to process the payment and initiate funds transfer. Usually, verifying the payment on the server side is also required.
The PSP processes the payment, securely requesting a funds transfer from the customer's bank or credit card issuer to the merchant, and then returns a success or failure result to the merchant website.
The merchant website notifies the customer of the success or failure of the transaction and displays the next step, for example, shipping the purchased item.

Caveat: PSP Reliance #

If you are a merchant and want to accept credit card payments, PSPs are an important link in the payment processing chain. Implementing the Payment Request API does not remove the need for a PSP.

Merchants usually rely on a third-party PSP to perform payment processing for convenience and expense reasons. This is primarily because most PSPs maintain compliance with PCI DSS, an information security standard that regulates the safety of cardholder data.

Because achieving and maintaining strict PCI DSS compliance can be expensive and difficult, most merchants find that relying on a compliant PSP avoids going through the certification process themselves. Some large and financially robust companies, however, obtain their own PCI DSS certification specifically to avoid such third-party reliance.

It's especially important when you are handling a primary account number (PAN) as a payment credential, that is the number embossed on the card. Handling one with JavaScript requires PCI SAQ A-EP compliance.

Thus, delegating payment processing to a PCI DSS-compliant PSP both simplifies the merchant site's requirements and ensures payment information integrity for the customer.

Next up #

Learn about the Payment Request API's fields and methods in How the Payment Request API Works.

Web Payments overview

2018-09-10T00:00:00Z

Web Payments is an emerging web standard being developed by the W3C to simplify online payments and enable a broader set of players to participate easily in the payments ecosystem on the web. The standards are flexible; they work with various types of payment systems and are intended to work on any browser on any device, payment method, or payment service provider. This flexibility enables development simplicity, deployment consistency, and future compatibility with emerging payment technologies.

Benefits of Web Payments #

For consumers, they simplify checkout flow, by making it a few taps instead of typing small characters many times on a virtual keyboard.

For merchants, they make it easier to implement with a variety of payment options already filtered for the customer.

For payment handlers, they allow bringing any type of payment methods to the web with relatively easy integration.

For payment service providers, they bring new payment methods and enhance the ability of businesses to serve more customers with a better developer experience and more secure solutions.

Three principles of Web Payments #

Standard and open

Web Payments are an open payment standard for the web platform for the first time in history. They are available for anyone to implement.

Easy and consistent

Web Payments make checkout easy for the user, by reusing stored payments and address information and removing the need for the user to fill in checkout forms. Since the UI is implemented by the browser natively, users see a familiar and consistent checkout experience on any website that uses the standard.

Secure and flexible

Web Payments provide industry-leading payment technology to the web, and can easily integrate a secure payment solution.

Next up #

Learn How payment ecosystem works with Web Payments.

Credential Management API Feature Detection Check-up

2018-03-14T00:00:00Z

Summary #

WebAuthn helps increase security by bringing public-key credential based authentication to the Web, and is soon to be supported in Chrome, Firefox and Edge (with the updated spec). It adds a new kind of Credential object, which, however, may break websites that use the Credential Management API without feature-detecting the specific credential types they're using.

If you are currently doing this for feature detection #

if (navigator.credentials && navigator.credentials.preventSilentAccess) {
    // use CM API
}

Do these instead #

if (window.PasswordCredential || window.FederatedCredential) {
    // Call navigator.credentials.get() to retrieve stored
    // PasswordCredentials or FederatedCredentials.
}

if (window.PasswordCredential) {
    // Get/Store PasswordCredential
}

if (window.FederatedCredential) {
    // Get/Store FederatedCredential
}

if (navigator.credentials && navigator.credentials.preventSilentAccess) {
    // Call navigator.credentials.preventSilentAccess()
}

See changes made to the sample code as an example.

Read on to learn more.

What is the Credential Management API #

The Credential Management API (CM API) gives websites programmatic access to the user agent’s credential store for storing/retrieving user credentials for the calling origin.

Basic APIs are:

navigator.credentials.get()
navigator.credentials.store()
navigator.credentials.create()
navigator.credentials.preventSilentAccess()

The original CM API specification defines 2 credential types:

PasswordCredential
FederatedCredential

The PasswordCredential is a credential that contains user's id and password. The FederatedCredential is a credential that contains user's id and a string that represents an identity provider.

With these 2 credentials, websites can:

Let the user sign-in with a previously saved password-based or federated credential as soon as they land (auto sign-in),
Store the password-based or federated credential the user has signed in with,
Keep the user's sign-in credentials up-to-date (e.g. after a password change)

What is WebAuthn #

WebAuthn (Web Authentication) adds public-key credentials to the CM API. For example, it gives websites a standardized way to implement second-factor authentication using FIDO 2.0 compliant authenticator devices.

On a technical level, WebAuthn extends the CM API with the PublicKeyCredential interface.

What is the problem? #

Previously we have been guiding developers to feature detect the CM API with following code:

if (navigator.credentials && navigator.credentials.preventSilentAccess) {
  // Use CM API
}

But as you can see from the descriptions above, the `navigator.credentials` is
now expanded to support public-key credentials in addition to password
credentials and federated credentials.

The problem is that user agents don't necessarily support all kinds of
credentials. If you continue feature detect using `navigator.credentials`, your
website may break when you are using a certain credential type not supported by
the browser.

**Supported credential types by browsers**
<table class="properties with-heading-tint"><tbody><tr>
<th></th>
<th>PasswordCredential / FederatedCredential</th>
<th>PublicKeyCredential</th>
</tr><tr><th>Chrome
</th><td>Available
</td><td>In development
</td></tr><tr><th>Firefox
</th><td>N/A
</td><td>Aiming to ship on 60
</td></tr><tr><th>Edge
</th><td>N/A
</td><td>Implemented with <a href="https://blogs.windows.com/msedgedev/2016/04/12/a-world-without-passwords-windows-hello-in-microsoft-edge/">older API</a>. New API (navigator.credentials) coming soon.
</td></tr></tbody></table>


## The solution
You can avoid this by modifying feature detection code as follows to explicitly
test for the credential type that you intend to use.

```js
if (window.PasswordCredential || window.FederatedCredential) {
    // Call navigator.credentials.get() to retrieve stored
    // PasswordCredentials or FederatedCredentials.
}

if (window.PasswordCredential) {
    // Get/Store PasswordCredential
}

if (window.FederatedCredential) {
    // Get/Store FederatedCredential
}

if (navigator.credentials && navigator.credentials.preventSilentAccess) {
    // Call navigator.credentials.preventSilentAccess()
}

See actual changes made to the sample code as an example.

For a reference, here's how to detect PublicKeyCredential added in WebAuthn:

if (window.PublicKeyCredential) {
    // use CM API with PublicKeyCredential added in the WebAuthn spec
}

Timeline #

Earliest available implementation of WebAuthn is Firefox and is planned to be stable around early May 2018.

Finally #

If you have any questions, send them over to @agektmr or agektmr@chromium.org.

Sign in Users

2016-11-08T00:00:00Z

To sign in users, retrieve the credentials from the browser's password manager and use those to automatically log in users. For users with multiple accounts, let them select the account with just one tap using the account chooser.

Auto sign-in can happen anywhere on your website; not only the top page but other leaf pages too. This is useful when users reach various pages in your website, via a search engine.

To enable auto sign-in:

Get credential information.
Authenticate the user.
Update the UI or proceed to the personalized page.

Get credential information #

Browser support

Chrome 51, Supported 51
Firefox 60, Supported 60
Edge 18, Supported 18
Safari 13, Supported 13

Source

To get credential information, invoke navigator.credentials.get(). Specify the type of credentials to request by giving it a password or federated.

Always use mediation: 'silent' for auto sign-ins, so you can easily dismiss the process if the user:

Has no credentials stored.
Has multiple credentials stored.
Is signed out.

Before getting a credential, don’t forget to check if the user is already signed in:

if (window.PasswordCredential || window.FederatedCredential) {
  if (!user.isSignedIn()) {
    navigator.credentials.get({
      password: true,
      federated: {
        providers: ['https://accounts.google.com'],
      },
      mediation: 'silent',
    });
    // ...
  }
}

The promise returned by navigator.credentials.get() resolves with either a credential object or null. To determine whether it is a PasswordCredential or a FederatedCredential, simply look at the .type property of the object, which will be either password or federated.

If the .type is federated, the .provider property is a string that represents the identity provider.

Authenticate user #

Once you have the credential, run an authentication flow depending on the type of credential, password or federated:

    }).then(c => {
     if (c) {
       switch (c.type) {
         case 'password':
           return sendRequest(c);
           break;
         case 'federated':
           return gSignIn(c);
           break;
       }
     } else {
       return Promise.resolve();
     }

When the promise resolves, check if you've received a credential object. If not, it means auto sign-in couldn’t happen. Silently dismiss the auto sign-in process.

Update UI #

If the authentication is successful, update the UI or forward the user to the personalized page:

    }).then(profile => {
     if (profile) {
       updateUI(profile);
     }

Don’t forget to show authentication error message #

To avoid user confusion, users should see a blue toast saying “Signing in” at the time of getting the credential object:

One important tip: if you succeed in obtaining a credential object but fail to authenticate the user, you should show an error message:

        }).catch(error => {
          showError('Sign-in Failed');
        });
      }
    }

Full code example #

if (window.PasswordCredential || window.FederatedCredential) {
  if (!user.isSignedIn()) {
    navigator.credentials
      .get({
        password: true,
        federated: {
          providers: ['https://accounts.google.com'],
        },
        mediation: 'silent',
      })
      .then((c) => {
        if (c) {
          switch (c.type) {
            case 'password':
              return sendRequest(c);
              break;
            case 'federated':
              return gSignIn(c);
              break;
          }
        } else {
          return Promise.resolve();
        }
      })
      .then((profile) => {
        if (profile) {
          updateUI(profile);
        }
      })
      .catch((error) => {
        showError('Sign-in Failed');
      });
  }
}

If a user requires mediation, or has multiple accounts, use the account chooser to let the user sign-in, skipping the ordinary sign-in form, for example:

The steps to sign in via the account chooser are the same as in auto sign-in, with an additional call to show the account chooser as part of getting credential information:

Get the credential information and show the account chooser.
Authenticate the user.
Update the UI or proceed to a personalized page.

Get credential information and show account chooser #

Show an account chooser in response to a defined user action, for example, when the user taps the "Sign-In" button. Call navigator.credentials.get(), and add mediation: 'optional' or mediation: 'required' to show the account chooser.

When mediation is required, the user is always shown an account chooser to sign in. This option allows users with multiple accounts to easily switch between them. When mediation is optional, the user is explicitly shown an account chooser to sign in after a navigator.credentials.preventSilentAccess() call. This is normally to ensure automatic sign-in doesn't happen after the user chooses to sign-out or unregister.

Example showing mediation: 'optional':

    var signin = document.querySelector('#signin');
    signin.addEventListener('click', e => {
     if (window.PasswordCredential || window.FederatedCredential) {
       navigator.credentials.get({
         password: true,
         federated: {
           providers: [
             'https://accounts.google.com'
           ]
         },
         mediation: 'optional'
       }).then(c => {

Once the user selects an account, the promise resolves with the credential. If the users cancels the account chooser, or there are no credentials stored, the promise resolves with null. In that case, fall back to the sign in form experience.

You should fall back to a sign-in form for any of these reasons:

No credentials are stored.
The user dismissed the account chooser without selecting an account.
The API is not available.

    }).then(profile => {
        if (profile) {
          updateUI(profile);
        } else {
          location.href = '/signin';
        }
    }).catch(error => {
        location.href = '/signin';
    });

Full code example #

var signin = document.querySelector('#signin');
signin.addEventListener('click', (e) => {
  if (window.PasswordCredential || window.FederatedCredential) {
    navigator.credentials
      .get({
        password: true,
        federated: {
          providers: ['https://accounts.google.com'],
        },
        mediation: 'optional',
      })
      .then((c) => {
        if (c) {
          switch (c.type) {
            case 'password':
              return sendRequest(c);
              break;
            case 'federated':
              return gSignIn(c);
              break;
          }
        } else {
          return Promise.resolve();
        }
      })
      .then((profile) => {
        if (profile) {
          updateUI(profile);
        } else {
          location.href = '/signin';
        }
      })
      .catch((error) => {
        location.href = '/signin';
      });
  }
});

Federated login lets users sign in with one tap and without having to remember additional login details for your website.

To implement federated login:

Authenticate the user with a third-party identity.
Store the identity information.
Update the UI or proceed to a personalized page (same as in auto sign-in).

Authenticate user with third-party identity #

When a user taps on a federated login button, run the specific identity provider authentication flow with the FederatedCredential.

Browser support

Chrome 51, Supported 51
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

For example, if the provider is Google, use the Google Sign-In JavaScript library:

navigator.credentials
  .get({
    password: true,
    mediation: 'optional',
    federated: {
      providers: ['https://account.google.com'],
    },
  })
  .then(function (cred) {
    if (cred) {
      // Instantiate an auth object
      var auth2 = gapi.auth2.getAuthInstance();

      // Is this user already signed in?
      if (auth2.isSignedIn.get()) {
        var googleUser = auth2.currentUser.get();

        // Same user as in the credential object?
        if (googleUser.getBasicProfile().getEmail() === cred.id) {
          // Continue with the signed-in user.
          return Promise.resolve(googleUser);
        }
      }

      // Otherwise, run a new authentication flow.
      return auth2.signIn({
        login_hint: id || '',
      });
    }
  });

Google Sign-In results in an ID token as a proof of authentication.

In general, federated logins are built on top of standard protocols such as OpenID Connect or OAuth. To learn how to authenticate with federated accounts, refer to respective federated identity providers' docs. Popular examples include:

Store identity information #

Once authentication is done, you can store the identity information. The information you’ll store here is the id from the identity provider and a provider string that represents the identity provider (name and iconURL are optional). Learn more about this information in the Credential Management specification.

To store federated account details, instantiate a new FederatedCredential object with the user's identifier and the provider's identifier. Then invoke navigator.credentials.store() to store the identity information.

After successful federation, instantiate a FederatedCredential synchronously, or asynchronously:

Example of synchronous approach:

// Create credential object synchronously.
var cred = new FederatedCredential({
  id: id, // id in IdP
  provider: 'https://account.google.com', // A string representing IdP
  name: name, // name in IdP
  iconURL: iconUrl, // Profile image url
});

Example of asynchronous approach:

// Create credential object asynchronously.
var cred = await navigator.credentials.create({
  federated: {
    id: id,
    provider: 'https://accounts.google.com',
    name: name,
    iconURL: iconUrl,
  },
});

Then store the credential object:

// Store it
navigator.credentials.store(cred).then(function () {
  // continuation
});

Sign out #

Sign out your users when the sign-out button is tapped. First terminate the session, then turn off auto sign-in for future visits. (How you terminate your sessions is totally up to you.)

Call navigator.credentials.preventSilentAccess():

signoutUser();
if (navigator.credentials && navigator.credentials.preventSilentAccess) {
  navigator.credentials.preventSilentAccess();
}

This will ensure the auto sign-in won’t happen until next time the user enables auto sign-in. To resume auto sign-in, a user can choose to intentionally sign in by choosing the account they wish to sign in with from the account chooser. Then the user is always signed back in until they explicitly sign out.

Feedback #

The Credential Management API

2016-11-08T00:00:00Z

The Credential Management API is a standards-based browser API that provides a programmatic interface between the site and the browser for seamless sign-in across devices.

The Credential Management API:

Removes friction from sign-in flows - Users can be automatically signed back into a site even if their session has expired or they saved credentials on another device.
Allows one tap sign in with account chooser - Users can choose an account in a native account chooser.
Stores credentials - Your application can store either a username and password combination or even federated account details. These credentials can be synced across devices by the browser.

Want to see it in action? Try the Credential Management API Demo and take a look at the code.

Check Credential Management API browser support #

Browser support

Chrome 51, Supported 51
Firefox 60, Supported 60
Edge 18, Supported 18
Safari 13, Supported 13

Source

Before using the Credential Management API, first check if PasswordCredential or FederatedCredential is supported.

if (window.PasswordCredential || window.FederatedCredential) {
  // Call navigator.credentials.get() to retrieve stored
  // PasswordCredentials or FederatedCredentials.
}

To sign in the user, retrieve the credentials from the browser's password manager and use them to log in the user.

For example:

When a user lands on your site and they are not signed in, call navigator.credentials.get().
Use the retrieved credentials to sign in the user.
Update the UI to indicate the user has been signed in.

Learn more in Sign In Users.

Save or update user credentials #

If the user signed in with a federated identity provider such as Google Sign-In, Facebook, GitHub:

After the user successfully signs in or creates an account, create the FederatedCredential with the user's email address as the ID and specify the identity provider with FederatedCredentials.provider.
Save the credential object using navigator.credentials.store().

Learn more in Sign In Users.

If the user signed in with a username and password:

After the user successfully signs in or creates an account, create the PasswordCredential with the user ID and the password.
Save the credential object using navigator.credentials.store().

Learn more in Save Credentials from Forms.

Sign out #

When the user signs out, call navigator.credentials.preventSilentAccess() to prevent the user from being automatically signed back in.

Disabling auto-sign-in also enables users to switch between accounts easily, for example, between work and personal accounts, or between accounts on shared devices, without having to re-enter their sign-in information.

Learn more in Sign out.

Feedback #

Social discovery

2014-10-07T00:00:00Z

You can influence the way your site appears when shared via social media by adding a few lines of code to each page. This can help bring more people to your site by providing previews with richer information than would otherwise be available.

Summary #

Use schema.org microdata to provide page title, description, and an image for Google+.
Use Open Graph Protocol (OGP) to provide page title, description, and an image for Facebook.
Use Twitter Cards to provide page title, description, an image, and a Twitter id for Twitter.

You can influence the way your site appears when shared via social media by adding a few lines of code to each page. This can help increase engagement by providing previews with richer information than would otherwise be available. Without it, social sites will provide only basic information, without images or other helpful information.

Which one do you think is more likely to be clicked? People are drawn to images and feel more confident they'll like what they find when they have an early preview.

With the appropriate markup: the correct title, a short description, and an image are included. Adding these items can help increase engagement.

Without the proper mark up, only the page title is included.

When someone on a social network wants to share your website with their friends, they would probably add some notes explaining how awesome it is, and share it. But describing a website tends be cumbersome and can miss the point from the page owner's point of view. Some services restrict the number of characters users can put in the note.

By adding the appropriate metadata to your pages, you can simplify the sharing process for users by providing the title, a description, and an attractive image. This means they don't have to spend valuable time (or characters) describing the link.

Use schema.org + microdata to provide rich snippets on Google+ #

Crawlers use many methods to parse a page and understand its content. By using microdata, and schema.org vocabulary, you help social sites and search engines better understand the contents of the page.

Here's an example:

<div itemscope itemtype="http://schema.org/Article">
  <h1 itemprop="name">Enjoy fireworks</h1>
  <p itemprop="description">Fireworks are beautiful.
   This article explains how beautiful fireworks are.</p>
  <img itemprop="image" src="//developers.google.com/web/imgs/fireworks.jpg" />
</div>

While most metadata are embedded in the head section of a web page, microdata lives where the context exists.

Add `itemscope` to define microdata scope #

By adding itemscope, you can specify the tag as a block of contents about a particular item.

Add `itemtype` to define type of your website #

You can specify the type of item by using the itemtype attribute along with the itemscope. The value of an itemtype can be determined according to the type of content on your web page. You should be able to find one that is relevant in this page.

Add `itemprop` to describe each item using schema.org vocabulary #

itemprop defines properties for itemtype in the scope. For providing metadata to social sites, typical itemprop values are name, description, and image.

Validate rich snippets #

To validate rich snippets on Google+, you can use tools such as:

Structured Data Testing Tool - Webmaster Tools

Use Open Graph Protocol (OGP) to provide rich snippets on Facebook #

The Open Graph Protocol (OGP) provides Facebook with the metadata necessary to allow web pages to have the same functionality as other Facebook objects.

<html prefix="og: http://ogp.me/ns#">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
    <link rel="stylesheet" href="https://code.getmdl.io/1.2.1/material.indigo-pink.min.css">
    <script defer src="https://code.getmdl.io/1.2.1/material.min.js"></script>
    <style>
      body {
        margin: 2em;
      }
    </style>
    <meta property="og:title" content="Enjoy Fireworks">
    <meta property="og:description"
          content="Fireworks are beautiful. This article explains how beautiful fireworks are.">
    <meta property="og:image"
          content="https://developers.google.com/web/imgs/fireworks.jpg">
    <meta property="og:url"
          content="https://example.com/discovery-and-distribution/optimizations-for-crawlers/social-sites.html">
    <meta property="og:type" content="website">

When included in the head section of your page, this metadata provides rich snippet information when the page is shared.

Use `og:` namespaced `meta` tags to describe metadata #

A meta tag consists of a property attribute and a content attribute. Properties and contents may take the following values:

Property	Content
`og:title`	The title of the web page.
`og:description`	The description of the web page.
`og:url`	The canonical url of the web page.
`og:image`	URL to an image attached to the shared post.
`og:type`	A string that indicates the type of the web page. You can find one that is suitable for your web page here.

These meta tags provide semantic information to crawlers from social sites, like Facebook.

Learn more #

To learn more about things you can attach to the post on Facebook, visit the official Open Graph Protocol site.

ogp.me

Validate rich snippets #

To validate your markup on Facebook, you can use tools such as:

Debugger

Use Twitter Cards to provide rich snippets on Twitter #

Twitter Cards are an extension to the Open Graph Protocol applicable for Twitter. They allow you to add media attachments like images and video to Tweets with a link to your web page. By adding the appropriate metadata, Tweets with links to your page will have a card added that includes the rich detail you've added.

Use `twitter:` namespaced meta tags to describe metadata #

To get a Twitter Card working, your domain must be approved and must contain a meta tag that has twitter:card as the name attribute instead of property attribute.

Here's a quick example:

<html prefix="og: http://ogp.me/ns#">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
    <link rel="stylesheet" href="https://code.getmdl.io/1.2.1/material.indigo-pink.min.css">
    <script defer src="https://code.getmdl.io/1.2.1/material.min.js"></script>
    <style>
      body {
        margin: 2em;
      }
    </style>
    <meta property="og:title" content="Enjoy Fireworks">
    <meta property="og:description"
          content="Fireworks are beautiful. This article explains how beautiful fireworks are.">
    <meta property="og:image"
          content="https://developers.google.com/web/imgs/fireworks.jpg">
    <meta property="og:url"
          content="https://example.com/discovery-and-distribution/optimizations-for-crawlers/social-sites.html">
    <meta property="og:type" content="website">
    <meta name="twitter:card" content="summary_large_image">
    <meta name="twitter:site" content="agektmr">

By assigning the Twitter id to the value of twitter:site, Twitter embeds this information in the shared post so that people can easily engage with the page owner.

Learn more #

To learn more about Twitter Cards, visit:

Twitter's developer site

Validate rich snippets #

To validate your markup, Twitter provides:

Card Validator

The Best Practice #

Given all three options, the best thing you can do is to include them all in your web page. Here's an example:

<!-- namespace declaration -->
<html prefix="og: http://ogp.me/ns#">
  <!-- define microdata scope and type -->
  <head itemscope itemtype="http://schema.org/Article">
    <title>Social Site Example</title>
    <!-- define ogp and itemprop of microdata in one line -->
    <meta property="og:title" itemprop="name" content="Enjoy Fireworks">
    <!-- define ogp image -->
    <meta property="og:image"
          content="https://developers.google.com/web/imgs/fireworks.jpg">
    <!-- use link[href] to define image url for microdata -->
    <link itemprop="image" href="//developers.google.com/web/imgs/fireworks.jpg">
    <!-- define ogp and itemprop of microdata in one line -->
    <meta property="og:url"
          content="https://example.com/discovery-and-distribution/optimizations-for-crawlers/social-sites2.html">
    <!-- define ogp type -->
    <meta property="og:type" content="website">
    <!-- define twitter cards type -->
    <meta name="twitter:card" content="summary_large_image">
    <!-- define site's owner twitter id -->
    <meta name="twitter:site" content="agektmr">
    <!-- define description for ogp and itemprop of microdata in one line -->
    <meta property="og:description" itemprop="description"
          content="Fireworks are beautiful. This article explains how beautiful fireworks are.">
    <!-- general description (separate with ogp and microdata) -->
    <meta name="description"
          content="Fireworks are beautiful. This article explains how beautiful fireworks are.">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
    <link rel="stylesheet" href="https://code.getmdl.io/1.2.1/material.indigo-pink.min.css">
    <script defer src="https://code.getmdl.io/1.2.1/material.min.js"></script>
    <style>
      body {
        margin: 2em;
      }
    </style>
  </head>

Notice that microdata and OGP share some markup:

itemscope is located at head tag
title and description are shared between microdata and OGP
itemprop="image" is using link tag with href attribute instead of reusing meta tag with property="og:image"

Lastly, make sure to validate that your web page appears as expected on each social site before publishing.

Introducing WebSockets - Bringing Sockets to the Web

2012-10-20T00:00:00Z

The problem: Low latency client-server and server-client connections #

The web has been largely built around the so-called request/response paradigm of HTTP. A client loads up a web page and then nothing happens until the user clicks onto the next page. Around 2005, AJAX started to make the web feel more dynamic. Still, all HTTP communication was steered by the client, which required user interaction or periodic polling to load new data from the server.

Technologies that enable the server to send data to the client in the very moment when it knows that new data is available have been around for quite some time. They go by names such as 'Push' or 'Comet'. One of the most common hacks to create the illusion of a server initiated connection is called long polling. With long polling, the client opens an HTTP connection to the server which keeps it open until sending response. Whenever the server actually has new data it sends the response (other techniques involve Flash, XHR multipart requests and so called htmlfiles). Long polling and the other techniques work quite well. You use them every day in applications such as GMail chat.

However, all of these work-arounds share one problem: They carry the overhead of HTTP, which doesn't make them well suited for low latency applications. Think multiplayer first person shooter games in the browser or any other online game with a realtime component.

Introducing WebSocket: Bringing sockets to the web #

The WebSocket specification defines an API establishing "socket" connections between a web browser and a server. In plain words: There is an persistent connection between the client and the server and both parties can start sending data at any time.

Getting Started #

You open up a WebSocket connection simply by calling the WebSocket constructor:

var connection = new WebSocket('ws://html5rocks.websocket.org/echo', ['soap', 'xmpp']);

Notice the ws:. This is the new URL schema for WebSocket connections. There is also wss: for secure WebSocket connection the same way https: is used for secure HTTP connections.

Attaching some event handlers immediately to the connection allows you to know when the connection is opened, received incoming messages, or there is an error.

The second argument accepts optional sub-protocols. It can be a string or an array of strings. Each string should represent a sub-protocol name and server accepts only one of passed sub-protocols in the array. Accepted sub-protocol can be determined by accessing protocol property of WebSocket object.

The sub-protocol names must be one of registered sub-protocol names in IANA registry. There is currently only one sub-protocol name (soap) registered as of February 2012.

// When the connection is open, send some data to the server
connection.onopen = function () {
connection.send('Ping'); // Send the message 'Ping' to the server
};

// Log errors
connection.onerror = function (error) {
console.log('WebSocket Error ' + error);
};

// Log messages from the server
connection.onmessage = function (e) {
console.log('Server: ' + e.data);
};

Communicating with the server #

As soon as we have a connection to the server (when the open event is fired) we can start sending data to the server using the send('your message') method on the connection object. It used to support only strings, but in the latest spec it now can send binary messages too. To send binary data, you can use either Blob or ArrayBuffer object.

// Sending String
connection.send('your message');

// Sending canvas ImageData as ArrayBuffer
var img = canvas_context.getImageData(0, 0, 400, 320);
var binary = new Uint8Array(img.data.length);
for (var i = 0; i < img.data.length; i++) {
binary[i] = img.data[i];
}
connection.send(binary.buffer);

// Sending file as Blob
var file = document.querySelector('input[type="file"]').files[0];
connection.send(file);

Equally the server might send us messages at any time. Whenever this happens the onmessage callback fires. The callback receives an event object and the actual message is accessible via the data property.

WebSocket can also receive binary messages in the latest spec. Binary frames can be received in Blob or ArrayBuffer format. To specify the format of the received binary, set the binaryType property of WebSocket object to either 'blob' or 'arraybuffer'. The default format is 'blob'. (You don't have to align binaryType param on sending.)

// Setting binaryType to accept received binary as either 'blob' or 'arraybuffer'
connection.binaryType = 'arraybuffer';
connection.onmessage = function(e) {
console.log(e.data.byteLength); // ArrayBuffer object if binary
};

Another newly added feature of WebSocket is extensions. Using extensions, it will be possible to send frames compressed, multiplexed, etc. You can find server accepted extensions by examining the extensions property of the WebSocket object after the open event. There is no officially published extensions spec just yet as of February 2012.

// Determining accepted extensions
console.log(connection.extensions);

Cross-origin communication #

Being a modern protocol, cross origin communication is baked right into WebSocket. While you should still make sure only to communicate with clients and servers that you trust, WebSocket enables communication between parties on any domain. The server decides whether to make its service available to all clients or only those that reside on a set of well defined domains.

Proxy servers #

Every new technology comes with a new set of problems. In the case of WebSocket it is the compatibility with proxy servers which mediate HTTP connections in most company networks. The WebSocket protocol uses the HTTP upgrade system (which is normally used for HTTP/SSL) to 'upgrade' an HTTP connection to a WebSocket connection. Some proxy servers do not like this and will drop the connection. Thus, even if a given client uses the WebSocket protocol, it may not be possible to establish a connection. This makes the next section even more important :)

Use WebSockets today #

WebSocket is still a young technology and not fully implemented in all browsers. However, you can use WebSocket today with libraries that use one of the fallbacks mentioned above whenever WebSocket is not available. A library that has become very popular in this domain is socket.io which comes with a client and a server implementation of the protocol and includes fallbacks (socket.io doesn't support binary messaging yet as of Februrary 2012). There are also commercial solutions such as PusherApp which can be easily integrated into any web environment by providing a HTTP API to send WebSocket messages to clients. Due to the extra HTTP request there will always be extra overhead compared to pure WebSocket.

The server side #

Using WebSocket creates a whole new usage pattern for server side applications. While traditional server stacks such as LAMP are designed around the HTTP request/response cycle they often do not deal well with a large number of open WebSocket connections. Keeping a large number of connections open at the same time requires an architecture that receives high concurrency at a low performance cost. Such architectures are usually designed around either threading or so called non-blocking IO.

Server side implementations #

Node.js
Java
- Jetty
Ruby
- EventMachine
Python
- pywebsocket
- Tornado
Erlang
- Shirasu
C++
- libwebsockets
.NET
- SuperWebSocket

Protocol versions #

The wire protocol (a handshake and the data transfer between client and server) for WebSocket is now RFC6455. The latest Chrome and Chrome for Android are fully compatible with RFC6455 including binary messaging. Also, Firefox will be compatible on version 11, Internet Explorer on version 10. You can still use older protocol versions but it is not recommended since they are known to be vulnerable. If you have server implementations for older versions of WebSocket protocol, we recommend you to upgrade it to the latest version.

Use cases #

Use WebSocket whenever you need a truly low latency, near realtime connection between the client and the server. Keep in mind that this might involve rethinking how you build your server side applications with a new focus on technologies such as event queues. Some example use cases are:

Multiplayer online games
Chat applications
Live sports ticker
Realtime updating social streams

Demos #

References #

The Basics of Web Workers

2012-10-20T00:00:00Z

The problem: JavaScript concurrency #

There are a number of bottlenecks preventing interesting applications from being ported (say, from server-heavy implementations) to client-side JavaScript. Some of these include browser compatibility, static typing, accessibility, and performance. Fortunately, the latter is quickly becoming a thing of the past as browser vendors rapidly improve the speed of their JavaScript engines.

One thing that's remained a hindrance for JavaScript is actually the language itself. JavaScript is a single-threaded environment, meaning multiple scripts cannot run at the same time. As an example, imagine a site that needs to handle UI events, query and process large amounts of API data, and manipulate the DOM. Pretty common, right? Unfortunately all of that can't be simultaneous due to limitations in browsers' JavaScript runtime. Script execution happens within a single thread.

Developers mimic 'concurrency' by using techniques like setTimeout(), setInterval(), XMLHttpRequest, and event handlers. Yes, all of these features run asynchronously, but non-blocking doesn't necessarily mean concurrency. Asynchronous events are processed after the current executing script has yielded. The good news is that HTML5 gives us something better than these hacks!

Introducing Web Workers: bring threading to JavaScript #

The Web Workers specification defines an API for spawning background scripts in your web application. Web Workers allow you to do things like fire up long-running scripts to handle computationally intensive tasks, but without blocking the UI or other scripts to handle user interactions. They're going to help put and end to that nasty 'unresponsive script' dialog that we've all come to love:

Common unresponsive script dialog.

Workers utilize thread-like message passing to achieve parallelism. They're perfect for keeping your UI refresh, performant, and responsive for users.

Types of Web Workers #

It's worth noting that the specification discusses two kinds of Web Workers, Dedicated Workers and Shared Workers. This article will only cover dedicated workers. I'll refer to them as 'web workers' or 'workers' throughout.

Getting started #

Web Workers run in an isolated thread. As a result, the code that they execute needs to be contained in a separate file. But before we do that, the first thing to do is create a new Worker object in your main page. The constructor takes the name of the worker script:

var worker = new Worker('task.js');

If the specified file exists, the browser will spawn a new worker thread, which is downloaded asynchronously. The worker will not begin until the file has completely downloaded and executed. If the path to your worker returns an 404, the worker will fail silently.

After creating the worker, start it by calling the postMessage() method:

worker.postMessage(); // Start the worker.

Communicating with a worker via message passing #

Communication between a work and its parent page is done using an event model and the postMessage() method. Depending on your browser/version, postMessage() can accept either a string or JSON object as its single argument. The latest versions of the modern browsers support passing a JSON object.

Below is a example of using a string to pass 'Hello World' to a worker in doWork.js. The worker simply returns the message that is passed to it.

Main script:

var worker = new Worker('doWork.js');

worker.addEventListener('message', function(e) {
console.log('Worker said: ', e.data);
}, false);

worker.postMessage('Hello World'); // Send data to our worker.

doWork.js (the worker):

self.addEventListener('message', function(e) {
self.postMessage(e.data);
}, false);

When postMessage() is called from the main page, our worker handles that message by defining an onmessage handler for the message event. The message payload (in this case 'Hello World') is accessible in Event.data. Although this particular example isn't very exciting, it demonstrates that postMessage() is also your means for passing data back to the main thread. Convenient!

Messages passed between the main page and workers are copied, not shared. For example, in the next example the 'msg' property of the JSON message is accessible in both locations. It appears that the object is being passed directly to the worker even though it's running in a separate, dedicated space. In actuality, what is happening is that the object is being serialized as it's handed to the worker, and subsequently, de-serialized on the other end. The page and worker do not share the same instance, so the end result is that a duplicate is created on each pass. Most browsers implement this feature by automatically JSON encoding/decoding the value on either end.

The following is a more complex example that passes messages using JSON objects.

Main script:

<button onclick="sayHI()">Say HI</button>
<button onclick="unknownCmd()">Send unknown command</button>
<button onclick="stop()">Stop worker</button>
<output id="result"></output>

<script>
function sayHI() {
worker.postMessage({'cmd': 'start', 'msg': 'Hi'});
}

function stop() {
// worker.terminate() from this script would also stop the worker.
worker.postMessage({'cmd': 'stop', 'msg': 'Bye'});
}

function unknownCmd() {
worker.postMessage({'cmd': 'foobard', 'msg': '???'});
}

var worker = new Worker('doWork2.js');

worker.addEventListener('message', function(e) {
document.getElementById('result').textContent = e.data;
}, false);
</script>

doWork2.js:

self.addEventListener('message', function(e) {
var data = e.data;
switch (data.cmd) {
case 'start':
    self.postMessage('WORKER STARTED: ' + data.msg);
    break;
case 'stop':
    self.postMessage('WORKER STOPPED: ' + data.msg +
                    '. (buttons will no longer work)');
    self.close(); // Terminates the worker.
    break;
default:
    self.postMessage('Unknown command: ' + data.msg);
};
}, false);

Transferrable objects #

Most browsers implement the structured cloning algorithm, which allows you to pass more complex types in/out of Workers such as File, Blob, ArrayBuffer, and JSON objects. However, when passing these types of data using postMessage(), a copy is still made. Therefore, if you're passing a large 50MB file (for example), there's a noticeable overhead in getting that file between the worker and the main thread.

Structured cloning is great, but a copy can take hundreds of milliseconds. To combat the perf hit, you can use Transferable Objects.

With Transferable Objects, data is transferred from one context to another. It is zero-copy, which vastly improves the performance of sending data to a Worker. Think of it as pass-by-reference if you're from the C/C++ world. However, unlike pass-by-reference, the 'version' from the calling context is no longer available once transferred to the new context. For example, when transferring an ArrayBuffer from your main app to Worker, the original ArrayBuffer is cleared and no longer usable. Its contents are (quiet literally) transferred to the Worker context.

To use transferrable objects, use a slightly different signature of postMessage():

worker.postMessage(arrayBuffer, [arrayBuffer]);
window.postMessage(arrayBuffer, targetOrigin, [arrayBuffer]);

The worker case, the first argument is the data and the second is the list of items that should be transferred. The first argument doesn't have to be an ArrayBuffer by the way. For example, it can be a JSON object:

worker.postMessage({data: int8View, moreData: anotherBuffer},
                [int8View.buffer, anotherBuffer]);

The important point being: the second argument must be an array of ArrayBuffers. This is your list of transferrable items.

For more information on transferrables, see our post at developer.chrome.com.

The worker environment #

Worker scope #

In the context of a worker, both self and this reference the global scope for the worker. Thus, the previous example could also be written as:

addEventListener('message', function(e) {
var data = e.data;
switch (data.cmd) {
case 'start':
    postMessage('WORKER STARTED: ' + data.msg);
    break;
case 'stop':
...
}, false);

Alternatively, you could set the onmessage event handler directly (though addEventListener is always encouraged by JavaScript ninjas).

onmessage = function(e) {
var data = e.data;
...
};

Features available to workers #

Due to their multithreaded behavior, Web Workers only has access to a subset of JavaScript's features:

The navigator object
The location object (read-only)
XMLHttpRequest
setTimeout()/clearTimeout() and setInterval()/clearInterval()
The Application Cache
Importing external scripts using the importScripts() method
Spawning other web workers

Workers do NOT have access to:

The DOM (it's not thread-safe)
The window object
The document object
The parent object

Loading external scripts #

You can load external script files or libraries into a worker with the importScripts() function. The method takes zero or more strings representing the filenames for the resources to import.

This example loads script1.js and script2.js into the worker:

worker.js:

importScripts('script1.js');
importScripts('script2.js');

Which can also be written as a single import statement:

importScripts('script1.js', 'script2.js');

Subworkers #

Workers have the ability to spawn child workers. This is great for further breaking up large tasks at runtime. However, subworkers come with a few caveats:

Subworkers must be hosted within the same origin as the parent page.
URIs within subworkers are resolved relative to their parent worker's location (as opposed to the main page).

Keep in mind most browsers spawn separate processes for each worker. Before you go spawning a worker farm, be cautious about hogging too many of the user's system resources. One reason for this is that messages passed between main pages and workers are copied, not shared. See Communicating with a Worker via Message Passing.

For an sample of how to spawn a subworker, see the example in the specification.

Inline workers #

What if you want to create your worker script on the fly, or create a self-contained page without having to create separate worker files? With Blob(), you can "inline" your worker in the same HTML file as your main logic by creating a URL handle to the worker code as a string:

var blob = new Blob([
"onmessage = function(e) { postMessage('msg from worker'); }"]);

// Obtain a blob URL reference to our worker 'file'.
var blobURL = window.URL.createObjectURL(blob);

var worker = new Worker(blobURL);
worker.onmessage = function(e) {
// e.data == 'msg from worker'
};
worker.postMessage(); // Start the worker.

Blob URLs #

The magic comes with the call to window.URL.createObjectURL(). This method creates a simple URL string which can be used to reference data stored in a DOM File or Blob object. For example:

blob:http://localhost/c745ef73-ece9-46da-8f66-ebes574789b1

Blob URLs are unique and last for the lifetime of your application (e.g. until the document is unloaded). If you're creating many Blob URLs, it's a good idea to release references that are no longer needed. You can explicitly release a Blob URLs by passing it towindow.URL.revokeObjectURL():

window.URL.revokeObjectURL(blobURL);

In Chrome, there's a nice page to view all of the created blob URLs: chrome://blob-internals/.

Full example #

Taking this one step further, we can get clever with how the worker's JS code is inlined in our page. This technique uses a <script> tag to define the worker:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
</head>
<body>

<div id="log"></div>

<script id="worker1" type="javascript/worker">
// This script won't be parsed by JS engines
// because its type is javascript/worker.
self.onmessage = function(e) {
    self.postMessage('msg from worker');
};
// Rest of your worker code goes here.
</script>

<script>
function log(msg) {
    // Use a fragment: browser will only render/reflow once.
    var fragment = document.createDocumentFragment();
    fragment.appendChild(document.createTextNode(msg));
    fragment.appendChild(document.createElement('br'));

    document.querySelector("#log").appendChild(fragment);
}

var blob = new Blob([document.querySelector('#worker1').textContent]);

var worker = new Worker(window.URL.createObjectURL(blob));
worker.onmessage = function(e) {
    log("Received: " + e.data);
}
worker.postMessage(); // Start the worker.
</script>
</body>
</html>

In my opinion, this new approach is a bit cleaner and more legible. It defines a script tag with id="worker1" and type='javascript/worker' (so the browser doesn't parse the JS). That code is extracted as a string using document.querySelector('#worker1').textContent and passed to Blob() to create the file.

Loading external scripts #

When using these techniques to inline your worker code, importScripts() will only work if you supply an absolute URI. If you attempt to pass a relative URI, the browser will complain with a security error. The reason being: the worker (now created from a blob URL) will be resolved with a blob: prefix, while your app will be running from a different (presumably http://) scheme. Hence, the failure will be due to cross origin restrictions.

One way to utilize importScripts() in an inline worker is to "inject" the current url of your main script is running from by passing it to the inline worker and constructing the absolute URL manually. This will insure the external script is imported from the same origin. Assuming your main app is running from http://example.com/index.html:

...
<script id="worker2" type="javascript/worker">
self.onmessage = function(e) {
var data = e.data;

if (data.url) {
var url = data.url.href;
var index = url.indexOf('index.html');
if (index != -1) {
    url = url.substring(0, index);
}
importScripts(url + 'engine.js');
}
...
};
</script>
<script>
var worker = new Worker(window.URL.createObjectURL(bb.getBlob()));
worker.postMessage(<b>{url: document.location}</b>);
</script>

handling errors #

As with any JavaScript logic, you'll want to handle any errors that are thrown in your web workers. If an error occurs while a worker is executing, the an ErrorEvent is fired. The interface contains three useful properties for figuring out what went wrong: filename - the name of the worker script that caused the error, lineno - the line number where the error occurred, and message - a meaningful description of the error. Here is an example of setting up an onerror event handler to print the properties of the error:

<output id="error" style="color: red;"></output>
<output id="result"></output>

<script>
function onError(e) {
document.getElementById('error').textContent = [
    'ERROR: Line ', e.lineno, ' in ', e.filename, ': ', e.message
].join('');
}

function onMsg(e) {
document.getElementById('result').textContent = e.data;
}

var worker = new Worker('workerWithError.js');
worker.addEventListener('message', onMsg, false);
worker.addEventListener('error', onError, false);
worker.postMessage(); // Start worker without a message.
</script>

Example: workerWithError.js tries to perform 1/x, where x is undefined.

workerWithError.js:

self.addEventListener('message', function(e) {
postMessage(1/x); // Intentional error.
};

A word on security #

Restrictions with local access #

Due to Google Chrome's security restrictions, workers will not run locally (e.g. from file://) in the latest versions of the browser. Instead, they fail silently! To run your app from the file:// scheme, run Chrome with the --allow-file-access-from-files flag set.

Other browsers do not impose the same restriction.

Same-origin considerations #

Worker scripts must be external files with the same scheme as their calling page. Thus, you cannot load a script from a data: URL or javascript: URL, and an https: page cannot start worker scripts that begin with http: URLs.

Use cases #

So what kind app would utilize web workers? Here are a few more ideas to get your brain churning:

Prefetching and/or caching data for later use.
Code syntax highlighting or other real-time text formatting.
Spell checker.
Analyzing video or audio data.
Background I/O or polling of webservices.
Processing large arrays or humungous JSON responses.
Image filtering in <canvas>.
Updating many rows of a local web database.

For more information about use cases involving the Web Workers API, visit Workers Overview.

Demos #

HTML5demos sample

References #

Web Workers specification
"Using web workers" from the Mozilla Developer Network Web Docs.
"Web Workers rise up!" from Dev.Opera

Eiji Kitamura on web.dev

Sign in with a passkey through form autofill

Why use form autofill to sign-in with a passkey? #

Conditional UI #

How it works #

Prerequisites #

Authenticate with a passkey through form autofill #

Annotate form input field #

Feature detection #

Fetch a challenge from the RP server #

Call WebAuthn API with the conditional flag to authenticate the user #

Send the returned public key credential to the RP server #

Verify the signature #

Resources #

Create a passkey for passwordless logins

How it works #

Compatibilities #

Create a new passkey #

Feature detection #

Fetch important information from the backend #

Call WebAuthn API to create a passkey #

Send the returned public key credential to the backend #

Save the credential #

Resources #

Yahoo! JAPAN's password-free authentication reduced inquiries by 25%, sped up sign-in time by 2.6x

Why passwordless? #

Yahoo! JAPAN's passwordless initiatives #

1. Providing an alternative means of authentication to passwords #

SMS authentication #

FIDO with WebAuthn #

2. Password deactivation #

3. Passwordless account registration #

Key challenges for passwordless authentication #

Promoting passwordless authentication #

Conclusion #

Save Credentials from Forms

Include autocomplete in the form #

Prevent the form from submitting #

Authenticate by sending a request #

Store the credential #

Update the UI #

Full code example #

Browser compatibility #

PasswordCredential #

navigator.credentials.store() #

Feedback #

Security headers quick reference

Protect your site from injection vulnerabilities #

Isolate your site from other websites #

Build a powerful website securely #

Encrypt traffic to your site #

Content Security Policy (CSP) #

Recommended usages #

1. Use a nonce-based strict CSP #

2. Use a hash-based strict CSP #

Supported browsers #

Other things to note about CSP #

Learn more #

Trusted Types #

Recommended usages #

Supported browsers #

Learn more #

X-Content-Type-Options #

Recommended usages #

Supported browsers #

Learn more #

X-Frame-Options #

Recommended usages #

Protects your website from being embedded by any other websites #

Protects your website from being embedded by any cross-origin websites #

Supported browsers #

Learn more #

Cross-Origin Resource Policy (CORP) #

Recommended usages #

Allow resources to be loaded cross-origin #

Limit resources to be loaded from the same-origin #

Limit resources to be loaded from the same-site #

Supported browsers #

Learn more #

Cross-Origin Opener Policy (COOP) #

Call WebAuthn API with the `conditional` flag to authenticate the user #

Include `autocomplete` in the form #

`PasswordCredential` #

`navigator.credentials.store()` #

Allow resources to be loaded `cross-origin` #

Limit resources to be loaded from the `same-origin` #

Limit resources to be loaded from the `same-site` #

Use the `<input>` element #

`type="text"` #

`inputmode="numeric"` #

`autocomplete="one-time-code"` #