@pwabuilder/pwaauth

v0.9.7

Published

2 years ago

Web component that lets your users sign-in/sign-up using their Microsoft, Google, Facebook, or Apple account. Your app receives their email address, name, and profile picture.

Downloads

143

0High
0Medium
0Low

zteutsch

metulev

mani-builder

pwa-auth

Web component that lets your users sign-in/sign-up using their Microsoft, Google, Facebook, or Apple account. Your app receives their email address, name, and profile picture. Built with ❤ by the PWABuilder team.

😎 Bonus: It's super lightweight, pulling in the authentication libraries only when the user tries to sign-in with one.

😎😎 Double bonus: It uses the new Credential Management APIs to speed through sign-ins without bulky pop-ups or redirects.

Supported Browsers

Edge
Chrome
Firefox
Safari

Using this component

Install

Add this script tag to your <head>

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@pwabuilder/pwaauth@latest/dist/pwa-auth.min.js"
></script>

Place a <pwa-auth> Sign In button in your html:

<pwa-auth 
    microsoftkey="..."
    googlekey="..."
    facebookkey="..."
    applekey="...">
</pwa-auth>

Create one or more keys to let your users sign-in with Microsoft, Google, Facebook, or Apple. You'll need to provide at least one key. See creating keys to get started.

NPM

You can also use this component via NPM:

npm install @pwabuilder/pwaauth
import @pwabuilder/pwaauth

Then you can use the <pwa-auth> element anywhere in your template, JSX, HTML, etc.

What does it look like?

pwa-auth can be displayed in different ways:

Sign In button (default)

pwa-auth can appear as a single dropdown button:

<pwa-auth appearance="button"></pwa-auth>

Try it: live | code

List of sign-in provider buttons

Or it can be displayed as a list of provider buttons:

<pwa-auth appearance="list"></pwa-auth>

Try it: live | code

Headless

Finally, pwa-auth can be totally headless -- no UI -- letting you create your own sign-in buttons and drive the functionality using the signIn(...) method.

<!-- No UI at all -->
<pwa-auth appearance="none"></pwa-auth>

// Use your own UI buttons to invoke pwa-auth sign-in
const pwaAuth = document.querySelector("pwa-auth");
myOwnSignInBtn.addEventHandler("click", () => pwaAuth.signIn("Microsoft"));

Try it: live | code

All UI in pwa-auth is stylable using CSS. See styling for details. Additionally, all text in pwa-auth is customizable, see pwa-auth properties.

What happens when a user signs in?

You'll get a signin-completed event containing the user's email, name, imageUrl, accessToken and accessTokenExpiration, as well as additional raw data from the provider (e.g. authentication token):

const pwaAuth = document.querySelector("pwa-auth");
pwaAuth.addEventListener("signin-completed", ev => {
    const signIn = ev.detail;
    if (signIn.error) {
        console.error("Sign in failed", signIn.error);
    } else {
        console.log("Email: ", signIn.email);
        console.log("Name: ", signIn.name);
        console.log("Picture: ", signIn.imageUrl);
        console.log("Access token", signIn.accessToken);
        console.log("Access token expiration date", signIn.accessTokenExpiration);
        console.log("Provider (MS, Google, FB): ", signIn.provider);
        console.log("Raw data from provider: ", signIn.providerData);
    }
});

Try it: live | code

Once the signin-completed event fires, you can do whatever you normally do when your users sign in: set an authentication cookie, create a JWT token, etc. You may wish to verify the sign-in in your back-end code: see backend auth for details.

If there's an error, or the user backs out of the authentication process, signin-completed will contain an error:

pwaAuth.addEventListener("signin-completed", ev => {
    const signIn = ev.detail;
    if (signIn.error) {
        console.error("There was an error during sign-in", signIn.error);
    }
});

What does the user see?

The first time a user signs in, he'll see the familiar OAuth flow asking the user to sign-in. For example, signing in with Google looks like this:

Once your user signs-in or cancels, signin-completed event will fire.

When the user signs in successfully the first time, the browser asks to save your credentials:

If the user saves his credentials, it will be stored using the new Credential Management API, enabling fast successive sign-ins.

Successive sign-ins

(Or, Credential Management FTW)

If a user has signed-in previously, future sign-ins will be instantaneous. 😎 The next time the user taps Sign In, he'll have a streamlined experience without needing any OAuth prompts or pop-ups:

<!-- When tapping sign-in, use the saved credential to sign in silently -->
<pwa-auth credentialmode="silent"></pwa-auth>

Try it: live | code

In the above screenshot, the user tapped Sign In, and was automatically signed-in using the first saved credential; no OAuth dialogs, pop-ups, or redirects needed! 😎 The browser typically displays a "Signing in as..." info bar during this process.

As an alternative, you can have the browser prompt the user to confirm his sign-in:

<!-- When tapping sign in, prompt the user to confirm -->
<pwa-auth credentialmode="prompt"></pwa-auth>

Try it: live | code

In the above image, the user tapped the gray Sign In button, and then was prompted by the browser to sign in using his stored credential.

If the user had previously signed-in with multiple accounts (e.g. once with Google, once with Microsoft), he'll be given a choice of which provider to sign-in with:

Finally, you can disable credential management when clicking the Sign In button:

<!-- When tapping sign in, always show the provider dropdown menu -->
<pwa-auth credentialmode="none"></pwa-auth>

When credentialmode="none" and the user taps Sign In, pwa-auth will show the dropdown set of providers. Clicking any of those providers will still attempt to load a stored credential first, falling back to the OAuth flow as necessary. View sample using credentialmode="none".

With regards to browser support, pwa-auth credential management is a progressive enhancement: on browsers that don't support Credential Management, pwa-auth will fallback to credentialmode="none" behavior and always use the OAuth flow.

Creating keys

When you add a <pwa-auth> component to your page, you'll need to specify one or more keys:

<pwa-auth 
    microsoftkey="..."
    googlekey="..."
    facebookkey="..."
    applekey="...">
</pwa-auth>

Each key lets your users sign-in with the corresponding service (e.g. a Microsoft key lets your users sign-in with their Microsoft account).

To create a key, see:

API

You can customize the appearance and behavior of pwa-auth component.

Properties

Events

| Name | Type | Event Data | Description | | - | - | - | - | | signin-completed | CustomEvent | e.detail will contain the details of the sign-in event.e.detail.email: The email address of the signed-in user.e.detail.name: The name of the signed-in user.e.detail.imageUrl: URL of the user's profile picture. May be null in some scenarios.e.detail.provider: The name of the provider the user signed-in with.e.detail.error: The error that occurred during sign-in. Will be null if sign-in was successful.e.detail.providerData: The raw sign-in data received from an OAuth flow sign-in. Maybe be null during successive sign-ins. | Fired when a sign-in completes successfully or unsuccessfully. If the sign-in failed, e.detail.error will be non-null. View code sample.

Methods

Styling

Shadow parts

You can style the different parts of pwa-auth using CSS ::part selectors. Below are the list of parts available for styling:

Styling samples

Jazz up the Sign In button:

pwa-auth::part(signInButton) {
    background-color: green;
    color: white;
    transform: rotate3d(0, 0, 1, 25deg);
}

Try it: live | code

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

pwa-auth

Supported Browsers

Using this component

Install

NPM

What does it look like?

Sign In button (default)

List of sign-in provider buttons

Headless

What happens when a user signs in?

What does the user see?

Successive sign-ins

(Or, Credential Management FTW)

Creating keys

API

Properties

Events

Methods

Styling

Shadow parts

Styling samples