"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "introduction", "hProperties": { "id": "introduction" } }, "depth": 2, "value": "Introduction" }, { "data": { "id": "create-a-logto-application", "hProperties": { "id": "create-a-logto-application" } }, "depth": 2, "value": "Create a Logto application" }, { "data": { "id": "set-up-your-chrome-extension", "hProperties": { "id": "set-up-your-chrome-extension" } }, "depth": 2, "value": "Set up your Chrome extension" }, { "data": { "id": "install-logto-sdk", "hProperties": { "id": "install-logto-sdk" } }, "depth": 3, "value": "Install Logto SDK" }, { "data": { "id": "update-the-manifestjson", "hProperties": { "id": "update-the-manifestjson" } }, "depth": 3, "value": "Update the manifest.json" }, { "data": { "id": "set-up-a-background-script-service-worker", "hProperties": { "id": "set-up-a-background-script-service-worker" } }, "depth": 3, "value": "Set up a background script (service worker)" }, { "data": { "id": "update-logto-application-settings", "hProperties": { "id": "update-logto-application-settings" } }, "depth": 2, "value": "Update Logto application settings" }, { "data": { "id": "add-sign-in-and-sign-out-buttons-to-the-popup", "hProperties": { "id": "add-sign-in-and-sign-out-buttons-to-the-popup" } }, "depth": 2, "value": "Add sign-in and sign-out buttons to the popup" }, { "data": { "id": "checkpoint-test-the-authentication-flow", "hProperties": { "id": "checkpoint-test-the-authentication-flow" } }, "depth": 2, "value": "Checkpoint: Test the authentication flow" }, { "data": { "id": "check-authentication-state", "hProperties": { "id": "check-authentication-state" } }, "depth": 2, "value": "Check authentication state" }, { "data": { "id": "other-considerations", "hProperties": { "id": "other-considerations" } }, "depth": 2, "value": "Other considerations" }, { "data": { "id": "conclusion", "hProperties": { "id": "conclusion" } }, "depth": 2, "value": "Conclusion" }]; const readingTime = { "minutes": 5, "words": 1356, "text": "5 min read" }; const frontmatter = undefined; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", h3: "h3", img: "img", li: "li", ol: "ol", p: "p", pre: "pre", span: "span", strong: "strong", ul: "ul", ..._provideComponents(), ...props.components }, {Info, LogtoCloudButton, Note} = _components; if (!Info) _missingMdxReference("Info", true); if (!LogtoCloudButton) _missingMdxReference("LogtoCloudButton", true); if (!Note) _missingMdxReference("Note", true); return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "Chrome extensions are a great way to extend the functionality of the Chrome browser. When you have a popular extension, you might want to monetize it by offering pro features to users who pay for them. User authentication is must for this purpose:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "User identification" }), ": You need to know who the user is to provide personalized features."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Access control" }), ": You need to control who can access the paid features."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Subscription management" }), ": You need to provide a way for users to subscribe and manage their subscriptions."] }), "\n"] }), "\n", _jsx(_components.p, { children: "On the other hand, we don't want to stick on the Google account system, as your users might prefer to use other accounts, or, you may have multiple services that you want to integrate with the same identity system." }), "\n", _jsx(_components.p, { children: "A quick summary of the benefits of using OpenID Connect (OIDC) for authentication:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "No vendor lock-in" }), ": Your users can use various methods to sign in, rather than being forced to Google."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Single Sign-On (SSO)" }), ": Users can sign in once and access multiple services or applications."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Standardized" }), ": OIDC is an open standard that is widely adopted and supported, also it's secure."] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["In this tutorial, we will use ", _jsx(_components.a, { href: "https://logto.io/", children: "Logto" }), " as the OIDC provider, which is an Auth0 alternative for building identity infrastructures."] }), "\n", _jsx(_components.p, { children: "Let's get started!" }), "\n", _jsx(Note, { children: _jsxs(_components.p, { children: ["You can find a sample project for this tutorial on ", _jsx(_components.a, { href: "https://github.com/logto-io/js/tree/HEAD/packages/chrome-extension-sample", children: "our GitHub\nrepository" }), "."] }) }), "\n", _jsxs(_components.h2, { id: "introduction", children: ["Introduction", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#introduction", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Assuming you put a \"Sign in\" button in your Chrome extension's popup, the authentication flow will look like this:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant A as Extension popup\n participant B as Extension service worker\n participant C as Logto sign-in experience\n\n A->>B: Invokes sign-in\n B->>C: Redirects to Logto\n C->>C: User signs in\n C->>B: Redirects back to extension\n B->>A: Notifies the popup\n" }) }), "\n", _jsxs(_components.p, { children: ["For other interactive pages in your extension, you just need to replace the ", _jsx(_components.code, { children: "Extension popup" }), " participant with the page's name. In this tutorial, we will focus on the popup page."] }), "\n", _jsxs(_components.h2, { id: "create-a-logto-application", children: ["Create a Logto application", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#create-a-logto-application", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "To get started, create a Logto application with the \"Single page app\" type. Follow these steps to create a Logto application:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["Sign in to the ", _jsx(_components.a, { href: "https://cloud.logto.io/", children: "Logto Console" }), "."] }), "\n", _jsxs(_components.li, { children: ["Click on ", _jsx(_components.strong, { children: "Create application" }), "."] }), "\n", _jsx(_components.li, { children: "In the opened page, find the \"Create app without framework\" button in the bottom and click on it." }), "\n", _jsx(_components.li, { children: "Choose the \"Single page app\" type, and enter your application name." }), "\n", _jsxs(_components.li, { children: ["Click on ", _jsx(_components.strong, { children: "Create" }), "."] }), "\n"] }), "\n", _jsxs(_components.h2, { id: "set-up-your-chrome-extension", children: ["Set up your Chrome extension", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#set-up-your-chrome-extension", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.h3, { id: "install-logto-sdk", children: ["Install Logto SDK", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#install-logto-sdk", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Install Logto SDK in your Chrome extension project:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "# or pnpm, yarn, etc.\nnpm i @logto/chrome-extension\n" }) }), "\n", _jsxs(_components.h3, { id: "update-the-manifestjson", children: ["Update the ", _jsx(_components.code, { children: "manifest.json" }), _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#update-the-manifestjson", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["Logto SDK requires the following permissions in the ", _jsx(_components.code, { children: "manifest.json" }), ":"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-json", children: "{\n \"permissions\": [\"identity\", \"storage\"],\n \"host_permissions\": [\"https://*.logto.app/*\"]\n}\n" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "permissions.identity" }), ": Required for the Chrome Identity API, which is used to sign in and sign out."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "permissions.storage" }), ": Required for storing the user's session."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "host_permissions" }), ": Required for the Logto SDK to communicate with the Logto APIs."] }), "\n"] }), "\n", _jsx(Note, { children: _jsxs(_components.p, { children: ["If you are using a custom domain on Logto Cloud, you need to update the ", _jsx(_components.code, { children: "host_permissions" }), " to match your domain."] }) }), "\n", _jsxs(_components.h3, { id: "set-up-a-background-script-service-worker", children: ["Set up a background script (service worker)", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#set-up-a-background-script-service-worker", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "In your Chrome extension's background script, initialize the Logto SDK:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "// service-worker.js\nimport LogtoClient from '@logto/chrome-extension';\n\nexport const client = new LogtoClient({\n endpoint: ''\n appId: '',\n});\n" }) }), "\n", _jsxs(_components.p, { children: ["Replace ", _jsx(_components.code, { children: "" }), " and ", _jsx(_components.code, { children: "" }), " with the actual values. You can find these values in the application page you just created in the Logto Console."] }), "\n", _jsxs(_components.p, { children: ["If you don't have a background script, you can follow the ", _jsx(_components.a, { href: "https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/basics", children: "official guide" }), " to create one."] }), "\n", _jsxs(Info, { children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "Why do we need a background script?" }) }), _jsx(_components.p, { children: "Normal extension pages like the popup or options page can't run in the background, and they have the possibility to be closed during the authentication process. A background script ensures the authentication process can be properly handled." })] }), "\n", _jsx(_components.p, { children: "Then, we need to listen to the message from other extension pages and handle the authentication process:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "// service-worker.js\nchrome.runtime.onMessage.addListener((message, sender, sendResponse) => {\n // In the below code, since we return `true` for each action, we need to call `sendResponse`\n // to notify the sender. You can also handle errors here, or use other ways to notify the sender.\n\n if (message.action === 'signIn') {\n const redirectUri = chrome.identity.getRedirectURL('/callback');\n client.signIn(redirectUri).finally(sendResponse);\n return true;\n }\n\n if (message.action === 'signOut') {\n const redirectUri = chrome.identity.getRedirectURL();\n client.signOut(redirectUri).finally(sendResponse);\n return true;\n }\n\n return false;\n});\n" }) }), "\n", _jsxs(_components.p, { children: ["You may notice there are two redirect URIs used in the code above. They are both created by ", _jsx(_components.code, { children: "chrome.identity.getRedirectURL" }), ", which is a ", _jsx(_components.a, { href: "https://developer.chrome.com/docs/extensions/reference/api/identity#method-getRedirectURL", children: "built-in Chrome API" }), " to generate a redirect URL for auth flows. The two URIs will be:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "https://.chromiumapp.org/callback" }), " for sign-in."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "https://.chromiumapp.org/" }), " for sign-out."] }), "\n"] }), "\n", _jsx(_components.p, { children: "Note that these URIs are not accessible, and they are only used for Chrome to trigger specific actions for the authentication process." }), "\n", _jsxs(_components.h2, { id: "update-logto-application-settings", children: ["Update Logto application settings", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#update-logto-application-settings", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Now we need to update the Logto application settings to allow the redirect URIs we just created." }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "Go to the application page in the Logto Console." }), "\n", _jsxs(_components.li, { children: ["In the \"Redirect URIs\" section, add the URI: ", _jsx(_components.code, { children: "https://.chromiumapp.org/callback" }), "."] }), "\n", _jsxs(_components.li, { children: ["In the \"Post sign-out redirect URIs\" section, add the URI: ", _jsx(_components.code, { children: "https://.chromiumapp.org/" }), "."] }), "\n", _jsxs(_components.li, { children: ["In the \"CORS allowed origins\" section, add the URI: ", _jsx(_components.code, { children: "chrome-extension://" }), ". The SDK in Chrome extension will use this origin to communicate with the Logto APIs."] }), "\n", _jsxs(_components.li, { children: ["Click on ", _jsx(_components.strong, { children: "Save changes" }), "."] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["Remember to replace ", _jsx(_components.code, { children: "" }), " with your actual extension ID. You can find the extension ID in the ", _jsx(_components.code, { children: "chrome://extensions" }), " page."] }), "\n", _jsx(_components.p, { children: "After updating the settings, your Logto application settings should look like this:" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "https://uploads.strapi.logto.io/1/app_settings_f30c24be38.webp", alt: "Application settings" }) }), "\n", _jsxs(_components.h2, { id: "add-sign-in-and-sign-out-buttons-to-the-popup", children: ["Add sign-in and sign-out buttons to the popup", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#add-sign-in-and-sign-out-buttons-to-the-popup", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "We're almost there! Let's add the sign-in and sign-out buttons and other necessary logic to the popup page." }), "\n", _jsxs(_components.p, { children: ["In the ", _jsx(_components.code, { children: "popup.html" }), " file:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-html", children: "\n\n\n" }) }), "\n", _jsxs(_components.p, { children: ["In the ", _jsx(_components.code, { children: "popup.js" }), " file (assuming ", _jsx(_components.code, { children: "popup.js" }), " is included in the ", _jsx(_components.code, { children: "popup.html" }), "):"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "// popup.js\ndocument.getElementById('sign-in').addEventListener('click', async () => {\n await chrome.runtime.sendMessage({ action: 'signIn' });\n // Sign-in completed (or failed), you can update the UI here.\n});\n\ndocument.getElementById('sign-out').addEventListener('click', async () => {\n await chrome.runtime.sendMessage({ action: 'signOut' });\n // Sign-out completed (or failed), you can update the UI here.\n});\n" }) }), "\n", _jsxs(_components.h2, { id: "checkpoint-test-the-authentication-flow", children: ["Checkpoint: Test the authentication flow", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#checkpoint-test-the-authentication-flow", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Now you can test the authentication flow in your Chrome extension:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "Open the extension popup." }), "\n", _jsx(_components.li, { children: "Click on the \"Sign in\" button." }), "\n", _jsx(_components.li, { children: "You will be redirected to the Logto sign-in page." }), "\n", _jsx(_components.li, { children: "Sign in with your Logto account." }), "\n", _jsx(_components.li, { children: "You will be redirected back to the Chrome." }), "\n"] }), "\n", _jsxs(_components.h2, { id: "check-authentication-state", children: ["Check authentication state", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#check-authentication-state", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Since Chrome provide unified storage APIs, rather than the sign-in and sign-out flow, all other Logto SDK methods can be used in the popup page directly." }), "\n", _jsxs(_components.p, { children: ["In your ", _jsx(_components.code, { children: "popup.js" }), ", you can reuse the ", _jsx(_components.code, { children: "LogtoClient" }), " instance created in the background script, or create a new one with the same configuration:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "// popup.js\nimport LogtoClient from '@logto/chrome-extension';\n\nconst client = new LogtoClient({\n endpoint: ''\n appId: '',\n});\n\n// Or reuse the client instance created in the background script\nimport { client } from './service-worker.js';\n" }) }), "\n", _jsx(_components.p, { children: "Then you can create a function to load the authentication state and user's profile:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "// popup.js\nconst loadAuthenticationState = async () => {\n const isAuthenticated = await client.isAuthenticated();\n // Update the UI based on the authentication state\n\n if (isAuthenticated) {\n const user = await client.getIdTokenClaims(); // { sub: '...', email: '...', ... }\n // Update the UI with the user's profile\n }\n};\n" }) }), "\n", _jsxs(_components.p, { children: ["You can also combine the ", _jsx(_components.code, { children: "loadAuthenticationState" }), " function with the sign-in and sign-out logic:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "// popup.js\ndocument.getElementById('sign-in').addEventListener('click', async () => {\n await chrome.runtime.sendMessage({ action: 'signIn' });\n await loadAuthenticationState();\n});\n\ndocument.getElementById('sign-out').addEventListener('click', async () => {\n await chrome.runtime.sendMessage({ action: 'signOut' });\n await loadAuthenticationState();\n});\n" }) }), "\n", _jsx(_components.p, { children: "Here's an example of the popup page with the authentication state:" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "https://uploads.strapi.logto.io/1/extension_popup_03b2ad10b2.webp", alt: "Popup page" }) }), "\n", _jsxs(_components.p, { children: ["For more information about the SDK, you can refer to the ", _jsx(_components.a, { href: "https://docs.logto.io/sdk/vanilla-js/", children: "official documentation of browser SDK" }), ". The browser SDK shares the same APIs with the Chrome extension SDK."] }), "\n", _jsxs(_components.h2, { id: "other-considerations", children: ["Other considerations", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#other-considerations", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Service worker bundling" }), ": If you use a bundler like Webpack or Rollup, you need to explicitly set the target to ", _jsx(_components.code, { children: "browser" }), " or similar to avoid unnecessary bundling of Node.js modules."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Module resolution" }), ": Logto Chrome extension SDK is an ESM-only module."] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["See our ", _jsx(_components.a, { href: "https://github.com/logto-io/js/tree/HEAD/packages/chrome-extension-sample", children: "sample project" }), " for a complete example with TypeScript, Rollup, and other configurations."] }), "\n", _jsxs(_components.h2, { id: "conclusion", children: ["Conclusion", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#conclusion", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "With users authenticated, you can now securely offer paid features in your Chrome extension. For instance, you can store the user's subscription status in the user profile, and check it when the user opens the extension." }), "\n", _jsx(_components.p, { children: "Combining the power of Chrome extensions and Logto, you can build a more flexible and customizable extension that both you and your users will love." }), "\n", _jsx(LogtoCloudButton, {})] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { headings, readingTime, frontmatter, default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }