{"id":13727302,"url":"https://github.com/pwa-builder/pwa-auth","last_synced_at":"2025-05-07T22:31:05.869Z","repository":{"id":43374180,"uuid":"249483922","full_name":"pwa-builder/pwa-auth","owner":"pwa-builder","description":"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.","archived":true,"fork":false,"pushed_at":"2022-06-07T20:00:52.000Z","size":1812,"stargazers_count":207,"open_issues_count":1,"forks_count":29,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-14T17:48:09.581Z","etag":null,"topics":["apple-login","authentication","facebook-login","google-login","microsoft-login","sign-ins","web-components"],"latest_commit_sha":null,"homepage":"https://pwa-auth-basic.glitch.me","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pwa-builder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-23T16:26:52.000Z","updated_at":"2024-11-03T11:56:31.000Z","dependencies_parsed_at":"2022-08-19T14:52:13.610Z","dependency_job_id":null,"html_url":"https://github.com/pwa-builder/pwa-auth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwa-builder%2Fpwa-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwa-builder%2Fpwa-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwa-builder%2Fpwa-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwa-builder%2Fpwa-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pwa-builder","download_url":"https://codeload.github.com/pwa-builder/pwa-auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252965356,"owners_count":21832877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-login","authentication","facebook-login","google-login","microsoft-login","sign-ins","web-components"],"created_at":"2024-08-03T01:03:48.855Z","updated_at":"2025-05-07T22:31:05.199Z","avatar_url":"https://github.com/pwa-builder.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\n# 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](https://github.com/pwa-builder/pwabuilder).\n\nPlease use our [main repository for any issues/bugs/features suggestion](https://github.com/pwa-builder/PWABuilder/issues/new/choose).\n\n# pwa-auth\nWeb 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 \u003ca href=\"https://pwabuilder.com\"\u003ePWABuilder\u003c/a\u003e team.\n\n😎 Bonus:  It's super lightweight, pulling in the authentication libraries \u003cem\u003eonly\u003c/em\u003e when the user tries to sign-in with one.\n\n😎😎 Double bonus: It uses the new [Credential Management APIs](https://developers.google.com/web/fundamentals/security/credential-management/retrieve-credentials) to speed through sign-ins without bulky pop-ups or redirects.\n\n### Supported Browsers\n- Edge\n- Chrome\n- Firefox\n- Safari\n\n## Using this component\n\n### Install\n1. Add this script tag to your `\u003chead\u003e`\n\n```html\n\u003cscript\n  type=\"module\"\n  src=\"https://cdn.jsdelivr.net/npm/@pwabuilder/pwaauth@latest/dist/pwa-auth.min.js\"\n\u003e\u003c/script\u003e\n```\n\n2. Place a `\u003cpwa-auth\u003e` Sign In button in your html:\n\n```html\n\u003cpwa-auth \n    microsoftkey=\"...\"\n    googlekey=\"...\"\n    facebookkey=\"...\"\n    applekey=\"...\"\u003e\n\u003c/pwa-auth\u003e\n```\n\n3. 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](#creating-keys) to get started.\n\n### NPM\n\nYou can also use this component via NPM:\n1. `npm install @pwabuilder/pwaauth`\n2. `import @pwabuilder/pwaauth`\n\nThen you can use the `\u003cpwa-auth\u003e` element anywhere in your template, JSX, HTML, etc.\n\n## What does it look like?\n\npwa-auth can be displayed in different ways:\n\n### Sign In button (default)\npwa-auth can appear as a single dropdown button:\n```html\n\u003cpwa-auth appearance=\"button\"\u003e\u003c/pwa-auth\u003e\n```\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/install-btn-dropdown.png\"\u003e\n\nTry it: [live](https://pwa-auth-basic.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-basic)\n\n### List of sign-in provider buttons\nOr it can be displayed as a list of provider buttons:\n```html\n\u003cpwa-auth appearance=\"list\"\u003e\u003c/pwa-auth\u003e\n```\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/list.png\"\u003e\n\nTry it: [live](https://pwa-auth-list.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-list)\n\n### Headless\nFinally, pwa-auth can be totally headless -- no UI -- letting you create your own sign-in buttons and drive the functionality using the [signIn(...) method](/#methods).\n```html\n\u003c!-- No UI at all --\u003e\n\u003cpwa-auth appearance=\"none\"\u003e\u003c/pwa-auth\u003e\n```\n```javascript\n// Use your own UI buttons to invoke pwa-auth sign-in\nconst pwaAuth = document.querySelector(\"pwa-auth\");\nmyOwnSignInBtn.addEventHandler(\"click\", () =\u003e pwaAuth.signIn(\"Microsoft\"));\n```\nTry it: [live](https://pwa-auth-headless.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-headless)\n\nAll UI in pwa-auth is stylable using CSS. See [styling](#styling) for details. Additionally, all text in pwa-auth is customizable, see [pwa-auth properties](#properties).\n\n## What happens when a user signs in?\n\nYou'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):\n\n```javascript\nconst pwaAuth = document.querySelector(\"pwa-auth\");\npwaAuth.addEventListener(\"signin-completed\", ev =\u003e {\n    const signIn = ev.detail;\n    if (signIn.error) {\n        console.error(\"Sign in failed\", signIn.error);\n    } else {\n        console.log(\"Email: \", signIn.email);\n        console.log(\"Name: \", signIn.name);\n        console.log(\"Picture: \", signIn.imageUrl);\n        console.log(\"Access token\", signIn.accessToken);\n        console.log(\"Access token expiration date\", signIn.accessTokenExpiration);\n        console.log(\"Provider (MS, Google, FB): \", signIn.provider);\n        console.log(\"Raw data from provider: \", signIn.providerData);\n    }\n});\n```\n\nTry it: [live](https://pwa-auth-basic.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-basic?path=script.js:3:1)\n\nOnce 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](/backend-auth.md) for details.\n\nIf there's an error, or the user backs out of the authentication process, `signin-completed` will contain an `error`:\n\n```javascript\npwaAuth.addEventListener(\"signin-completed\", ev =\u003e {\n    const signIn = ev.detail;\n    if (signIn.error) {\n        console.error(\"There was an error during sign-in\", signIn.error);\n    }\n});\n```\n\n## What does the user see?\n\nThe \u003cem\u003efirst time\u003c/em\u003e 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:\n\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/oauth.png?v=1\"\u003e\n\nOnce your user signs-in or cancels, `signin-completed` event will fire.\n\nWhen the user signs in successfully the first time, the browser asks to save your credentials:\n\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/save-cred.png\"/\u003e\n\nIf the user saves his credentials, it will be stored using the new [Credential Management API](https://developers.google.com/web/fundamentals/security/credential-management/retrieve-credentials), enabling fast successive sign-ins.\n\n## Successive sign-ins\n#### (Or, [Credential Management](https://developers.google.com/web/fundamentals/security/credential-management/retrieve-credentials) FTW)\n\nIf 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:\n\n```html\n\u003c!-- When tapping sign-in, use the saved credential to sign in silently --\u003e\n\u003cpwa-auth credentialmode=\"silent\"\u003e\u003c/pwa-auth\u003e\n```\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/first-cred.png\" /\u003e\n\nTry it: [live](https://pwa-auth-silent.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-silent?path=index.html:33:1)\n\nIn 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.\n\nAs an alternative, you can have the browser \u003cem\u003eprompt\u003c/em\u003e the user to confirm his sign-in:\n\n```html\n\u003c!-- When tapping sign in, prompt the user to confirm --\u003e\n\u003cpwa-auth credentialmode=\"prompt\"\u003e\u003c/pwa-auth\u003e\n```\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/signin-prompt.png\" /\u003e\n\nTry it: [live](https://pwa-auth-prompt.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-prompt?path=index.html:33:1)\n\nIn 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.\n\nIf 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:\n\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/multiple-accounts.png\" /\u003e\n\nFinally, you can disable credential management when clicking the Sign In button:\n```html\n\u003c!-- When tapping sign in, always show the provider dropdown menu --\u003e\n\u003cpwa-auth credentialmode=\"none\"\u003e\u003c/pwa-auth\u003e\n```\n\nWhen `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\"](https://pwa-auth-basic.glitch.me/).\n\nWith regards to browser support, pwa-auth credential management is a \u003cem\u003eprogressive\u003c/em\u003e enhancement: on browsers that don't support Credential Management, pwa-auth will fallback to `credentialmode=\"none\"` behavior and always use the OAuth flow.\n\n### Creating keys\n\nWhen you add a `\u003cpwa-auth\u003e` component to your page, you'll need to specify one or more keys:\n\n```html\n\u003cpwa-auth \n    microsoftkey=\"...\"\n    googlekey=\"...\"\n    facebookkey=\"...\"\n    applekey=\"...\"\u003e\n\u003c/pwa-auth\u003e\n```\n\nEach key lets your users sign-in with the corresponding service (e.g. a Microsoft key lets your users sign-in with their Microsoft account).\n\nTo create a key, see:\n- [Creating a Microsoft key](https://aka.ms/pwaauthmskey)\n- [Creating a Google key](https://aka.ms/pwaauthgooglekey)\n- [Creating a Facebook key](https://aka.ms/pwaauthfbkey)\n- [Creating an Apple key](https://aka.ms/pwaauthapplekey)\n\n## API\n\nYou can customize the appearance and behavior of pwa-auth component.\n\n### Properties\n| Property             | Attribute            | Description                                                                     | Type      | Default |\n| - | - | - | - | - |\n| `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?](#what-does-it-look-like) for details. | `'button'\\|'list'\\|'none'` | `'button'` |\n| `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: \u003cul\u003e\u003cli\u003e`silent`: When clicking `Sign In`, silently sign-in using his saved credential if available.\u003c/li\u003e\u003cli\u003e`prompt`: When clicking `Sign In`, prompt the user to sign-in with his saved crendential if available.\u003c/li\u003e\u003cli\u003e`none`: When clicking `Sign In`, show the dropdown menu with list of sign-in providers\u003c/li\u003e\u003c/ul\u003e See [successive sign-ins](#successive-sign-ins) for details. | `'silent'\\|'prompt'\\|'none'` | `'silent'` |\n| `microsoftKey` | `microsoftkey`  | The `Application (client) ID` of the Microsoft App you created. See [creating a Microsoft key](https://aka.ms/pwaauthmskey). header | `string \\| null` | `null` |\n| `googleKey` | `googlekey`  | The `Client ID` of the Google credential you created. See [creating a Google key](https://aka.ms/pwaauthgooglekey) | `string \\| null` | `null` |\n| `facebookKey` | `facebookkey`  | The `App ID` of the Facebook App you created. See [creating a Facebook key](https://aka.ms/pwaauthfbkey) | `string \\| null`  | `null` |\n| `appleKey` | `applekey`  | The `ID` of the Apple Services ID you created. See [creating an Apple key](https://aka.ms/pwaauthapplekey) | `string \\| null`  | `null` |\n| `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](https://aka.ms/pwaauthapplekey) for more details. | `string \\| null`  | `null` |\n| `signInButtonText` | `signinbuttontext` | The text of the `Sign In` button, displayed when `appearance=\"button\"` | `string` | 'Sign in' |\n| `microsoftButtonText` | `microsoftbuttontext` | The label for the `Sign in with Microsoft` button | `string`  | 'Sign in with Microsoft' |\n| `googleButtonText` | `googlebuttontext` | The label for the `Sign in with Google` button | `string`  | 'Sign in with Google' |\n| `facebookButtonText` | `facebookbuttontext` | The label for the `Sign in with Facebook` button | `string`  | 'Sign in with Facebook' |\n| `menuOpened` | `menuopened`   | Whether the dropdown menu of the `Sign In` button is opened | `boolean`  | `false` |\n| `menuPlacement` | `menuplacement` | The placement of the dropdown menu of the `Sign In` button. \u003cbr\u003e\u003cbr\u003e`start`: \u003cimg loading=\"lazy\" style=\"vertical-align: top\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/menu-start.png\"\u003e \u003cbr\u003e\u003cbr\u003e`end`: \u003cimg loading=\"lazy\" style=\"vertical-align: top\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/menu-end.png\"\u003e | `'start' \\| 'end'`  | `'start'` |\n| `disabled` | `disabled` | Whether the Sign In button(s) are disabled. They will be disabled while a sign-in is in-progress. | `boolean`  | `false` |\n\n### Events\n| Name | Type | Event Data | Description | \n| - | - | - | - | \n| `signin-completed` | `CustomEvent` | `e.detail` will contain the details of the sign-in event.\u003cbr\u003e\u003cul\u003e\u003cli\u003e`e.detail.email`: The email address of the signed-in user.\u003c/li\u003e\u003cli\u003e`e.detail.name`: The name of the signed-in user.\u003c/li\u003e\u003cli\u003e`e.detail.imageUrl`: URL of the user's profile picture. May be null in some scenarios.\u003c/li\u003e\u003cli\u003e`e.detail.provider`: The name of the provider the user signed-in with.\u003c/li\u003e\u003cli\u003e`e.detail.error`: The error that occurred during sign-in. Will be null if sign-in was successful.\u003c/li\u003e\u003cli\u003e`e.detail.providerData`: The raw sign-in data received from an OAuth flow sign-in. Maybe be null during successive sign-ins.\u003c/li\u003e\u003c/ul\u003e | Fired when a sign-in completes successfully or unsuccessfully. If the sign-in failed, `e.detail.error` will be non-null. \u003cbr\u003e\u003cbr\u003e[View code sample](#what-happens-when-a-user-signs-in).\n\n### Methods\n| Name | Arguments | Description |\n| - | - | - |\n| `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. |\n\n## Styling\n\n### Shadow parts\n\nYou can style the different parts of pwa-auth using [CSS ::part selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). Below are the list of parts available for styling:\n\n| Part Name | Description |\n| - | - |\n| `signInButton` | The sign-in button displayed when `appearance=\"button\"`. |\n| `microsoftButton` | The `Sign in with Microsoft` button. |\n| `microsoftIcon` | The icon for the `Sign in with Microsoft` button. |\n| `googleButton` | The `Sign in with Google` button. |\n| `googleIcon` | The icon for the `Sign in with Google` button. |\n| `facebookButton` | The `Sign in with Facebook` button. |\n| `facebookIcon` | The icon for the `Sign in with Facebook` button. |\n| `dropdownMenu` | The dropdown menu of the `Sign In` button displayed when `appearance=\"button\"` |\n\n### Styling samples\n\nJazz up the Sign In button:\n```css\npwa-auth::part(signInButton) {\n    background-color: green;\n    color: white;\n    transform: rotate3d(0, 0, 1, 25deg);\n}\n```\n\u003cimg loading=\"lazy\" src=\"https://github.com/pwa-builder/pwa-auth/raw/master/assets/signin-part.png\"\u003e\n\nTry it: [live](https://pwa-auth-customize.glitch.me/) | [code](https://glitch.com/edit/#!/pwa-auth-customize?path=style.css:18:1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwa-builder%2Fpwa-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpwa-builder%2Fpwa-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwa-builder%2Fpwa-auth/lists"}