The code for this component has moved to the main PWABuilder monorepo and this repository has been archived. Please visit our monorepo for issues, discussions, or controbutions.
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
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/pwaauthimport @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>
List of sign-in provider buttons
Or it can be displayed as a list of provider buttons:
<pwa-auth appearance="list"></pwa-auth>
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"));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);
}
});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. 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>
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!
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>
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'|'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.
|
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);
}