Skip to content
This repository has been archived by the owner on Mar 12, 2024. It is now read-only.

Latest commit

 

History

History
 
 

pwa-auth

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
assets
assets
 
 
docs
docs
 
 
src
src
 
 
www
www
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
rollup.config.js
rollup.config.js
 
 
tsconfig.json
tsconfig.json
 
 

README.md

Please use our main repository for any issues/bugs/features suggestion.

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

  1. 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>
  1. Place a <pwa-auth> Sign In button in your html:
<pwa-auth 
    microsoftkey="..."
    googlekey="..."
    facebookkey="..."
    applekey="...">
</pwa-auth>
  1. 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:

  1. npm install @pwabuilder/pwaauth
  2. 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

Property Attribute Description Type Default
appearance appearance Whether to render a single Sign In dropdown button or a list of sign-in provider buttons. See what does it look like? for details. 'button'|'list'|'none' 'button'
credentialMode credentialmode What happens when you click the Sign In button. If the user has previously signed-in and saved his credential, you can speed the user through sign-in:
  • silent: When clicking Sign In, silently sign-in using his saved credential if available.
  • prompt: When clicking Sign In, prompt the user to sign-in with his saved crendential if available.
  • none: When clicking Sign In, show the dropdown menu with list of sign-in providers
See successive sign-ins for details.		 'silent'|'prompt'|'none' 'silent'
microsoftKey microsoftkey The Application (client) ID of the Microsoft App you created. See creating a Microsoft key. header string | null null
googleKey googlekey The Client ID of the Google credential you created. See creating a Google key string | null null
facebookKey facebookkey The App ID of the Facebook App you created. See creating a Facebook key string | null null
appleKey applekey The ID of the Apple Services ID you created. See creating an Apple key string | null null
appleRedirectUri appleredirecturi The URI that will be POSTed to by Apple during a sign-in. If not specified, this will default to the location.href of your web app. See creating an Apple key for more details. string | null null
signInButtonText signinbuttontext The text of the Sign In button, displayed when appearance="button" string 'Sign in'
microsoftButtonText microsoftbuttontext The label for the Sign in with Microsoft button string 'Sign in with Microsoft'
googleButtonText googlebuttontext The label for the Sign in with Google button string 'Sign in with Google'
facebookButtonText facebookbuttontext The label for the Sign in with Facebook button string 'Sign in with Facebook'
menuOpened menuopened Whether the dropdown menu of the Sign In button is opened boolean false
menuPlacement menuplacement The placement of the dropdown menu of the Sign In button.

start:

end: 		'start' | 'end' 'start'
disabled disabled Whether the Sign In button(s) are disabled. They will be disabled while a sign-in is in-progress. boolean false

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

Name Arguments Description
signIn(provider: string) provider: 'Microsoft' | 'Google' | 'Facebook' Kicks off the sign-in process. If the user hasn't previously authenticated, he'll be prompted to sign-in via OAuth flow. If the user saved a previous credential, it will be used to sign-in quickly without the need for OAuth flow.

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:

Part Name Description
signInButton The sign-in button displayed when appearance="button".
microsoftButton The Sign in with Microsoft button.
microsoftIcon The icon for the Sign in with Microsoft button.
googleButton The Sign in with Google button.
googleIcon The icon for the Sign in with Google button.
facebookButton The Sign in with Facebook button.
facebookIcon The icon for the Sign in with Facebook button.
dropdownMenu The dropdown menu of the Sign In button displayed when appearance="button"

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