"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "background", "hProperties": { "id": "background" } }, "depth": 2, "value": "Background" }, { "data": { "id": "prerequisites", "hProperties": { "id": "prerequisites" } }, "depth": 2, "value": "Prerequisites" }, { "data": { "id": "create-your-custom-sign-in-ui", "hProperties": { "id": "create-your-custom-sign-in-ui" } }, "depth": 2, "value": "Create your custom sign-in UI" }, { "data": { "id": "setup-logto-tunnel-cli", "hProperties": { "id": "setup-logto-tunnel-cli" } }, "depth": 2, "value": "Setup Logto tunnel CLI" }, { "data": { "id": "trigger-sign-in-from-your-application", "hProperties": { "id": "trigger-sign-in-from-your-application" } }, "depth": 2, "value": "Trigger sign-in from your application" }, { "data": { "id": "interact-with-logto-experience-api", "hProperties": { "id": "interact-with-logto-experience-api" } }, "depth": 2, "value": "Interact with Logto Experience API" }, { "data": { "id": "test-your-custom-sign-in-page", "hProperties": { "id": "test-your-custom-sign-in-page" } }, "depth": 2, "value": "Test your custom sign-in page" }, { "data": { "id": "deploy-your-custom-sign-in-ui-to-logto-cloud", "hProperties": { "id": "deploy-your-custom-sign-in-ui-to-logto-cloud" } }, "depth": 2, "value": "Deploy your custom sign-in UI to Logto Cloud" }, { "data": { "id": "conclusion", "hProperties": { "id": "conclusion" } }, "depth": 2, "value": "Conclusion" }]; const readingTime = { "minutes": 4, "words": 1059, "text": "4 min read" }; const frontmatter = undefined; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", li: "li", ol: "ol", p: "p", pre: "pre", span: "span", ul: "ul", ..._provideComponents(), ...props.components }, {LogtoCloudButton} = _components; if (!LogtoCloudButton) _missingMdxReference("LogtoCloudButton", true); return _jsxs(_Fragment, { children: [_jsxs(_components.h2, { id: "background", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#background", children: _jsx(_components.span, { children: "#" }) }), "Background"] }), "\n", _jsx(_components.p, { children: "Logto provides an out-of-box sign-in experience UI that covers all Logto features, including sign-in, registration, password recovery, single sign-on (SSO), and more.\nUsers can also customize the look and feel of the sign-in experience UI using our \"Custom CSS\" feature." }), "\n", _jsx(_components.p, { children: "However, some users still want to deeply customize their sign-in experience (both UI and auth flows) to match their branding and specific business requirements.\nWe've heard you! And we're excited to announce that the \"Bring your own UI\" feature is now available in Logto Cloud." }), "\n", _jsx(_components.p, { children: "In this tutorial, we'll guide you through the steps to create and deploy your own custom sign-in UI to Logto Cloud." }), "\n", _jsxs(_components.h2, { id: "prerequisites", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#prerequisites", children: _jsx(_components.span, { children: "#" }) }), "Prerequisites"] }), "\n", _jsx(_components.p, { children: "Before you start, ensure you have the following:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["A ", _jsx(_components.a, { href: "http://cloud.logto.io/?sign_up=true", children: "Logto Cloud" }), " account with a subscription plan"] }), "\n", _jsxs(_components.li, { children: ["An application integrated with Logto (", _jsx(_components.a, { href: "https://docs.logto.io/quick-starts", children: "Quick-starts" }), ")"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "https://docs.logto.io/docs/references/tunnel-cli/", children: "Logto tunnel CLI" }), " installed"] }), "\n", _jsx(_components.li, { children: "Basic knowledge of HTML, CSS, and JavaScript" }), "\n"] }), "\n", _jsx(_components.p, { children: "For simplicity, we will use the classic \"username & password\" sign-in method in the following steps. Remember to change your sign-in method in Logto Console." }), "\n", _jsx("center", { children: _jsx("img", { width: "600", src: "https://uploads.strapi.logto.io/1/username_password_sign_in_78a7d8588c.webp", alt: "Username password sign-in" }) }), "\n", _jsxs(_components.h2, { id: "create-your-custom-sign-in-ui", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#create-your-custom-sign-in-ui", children: _jsx(_components.span, { children: "#" }) }), "Create your custom sign-in UI"] }), "\n", _jsxs(_components.p, { children: ["The minimum requirement for a sign-in UI is to have an ", _jsx(_components.code, { children: "index.html" }), " file, with a sign-in form that includes at least a username input, a password input, and a submit button.\nI used ChatGPT to generate a sample HTML, and here I come with this pinky lovely sign-in page."] }), "\n", _jsx("center", { children: _jsx("img", { width: "600", src: "https://uploads.strapi.logto.io/1/pinky_sign_in_page_b11e43251d.webp", alt: "Custom sign-in page" }) }), "\n", _jsx(_components.p, { children: "I have omitted the CSS styles for simplicity, and here is how simple the HTML looks like:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-html", children: "\n\n \n \n \n Fun Sign-in Page\n \n \n

Welcome Back

\n \n

\n \n\n" }) }), "\n", _jsx(_components.p, { children: "You can also start with a boilerplate from your favorite front-end framework, such as Create React App, Next.js, or Vue CLI." }), "\n", _jsxs(_components.p, { children: ["Since Logto is open source, another recommendation is to clone the ", _jsx(_components.a, { href: "https://github.com/logto-io/logto/tree/master/packages/experience", children: "Logto Experience project" }), ", and modify the code to fit your needs. This is the full feature Logto built-in sign-in experience UI, written in React and TypeScript."] }), "\n", _jsxs(_components.h2, { id: "setup-logto-tunnel-cli", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#setup-logto-tunnel-cli", children: _jsx(_components.span, { children: "#" }) }), "Setup Logto tunnel CLI"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.a, { href: "https://docs.logto.io/docs/references/tunnel-cli/", children: "Logto tunnel CLI" }), " is a tool that not only servers your HTML pages, but also allows you to interact with Logto's Experience API from your HTML pages in local dev environment."] }), "\n", _jsxs(_components.p, { children: ["Assuming your ", _jsx(_components.code, { children: "index.html" }), " page is located in ", _jsx(_components.code, { children: "/path/to/your/custom-ui" }), ", and your Logto tenant ID is ", _jsx(_components.code, { children: "foobar" }), ", you can run the command this way:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "npx @logto/tunnel --path /path/to/your/custom-ui --endpoint https://foobar.logto.app/ -p 9000\n" }) }), "\n", _jsxs(_components.p, { children: ["Or, if you are using a UI framework that has a built-in development server, and your page is served at ", _jsx(_components.code, { children: "http://localhost:4000" }), ", you can run the command like this:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "npx @logto/tunnel --uri http://localhost:4000 --endpoint https://foobar.logto.app/ -p 9000\n" }) }), "\n", _jsxs(_components.p, { children: ["After running the command, the tunnel service will be started on your local machine ", _jsx(_components.code, { children: "http://localhost:9000/" }), "."] }), "\n", _jsxs(_components.h2, { id: "trigger-sign-in-from-your-application", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#trigger-sign-in-from-your-application", children: _jsx(_components.span, { children: "#" }) }), "Trigger sign-in from your application"] }), "\n", _jsxs(_components.p, { children: ["Go to the application you created earlier, and change the Logto endpoint from ", _jsx(_components.code, { children: "https://foobar.logto.app/" }), " to ", _jsx(_components.code, { children: "http://localhost:9000/" }), " in your Logto SDK config."] }), "\n", _jsx(_components.p, { children: "Let's take our React sample project as an example:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", title: "src/App.tsx", children: "import { LogtoProvider, LogtoConfig } from '@logto/react';\n\nconst config: LogtoConfig = {\n // endpoint: 'https://foobar.logto.app/', // original Logto Cloud endpoint\n endpoint: 'http://localhost:9000/', // tunnel service address\n appId: '',\n};\n\nconst App = () => (\n \n \n \n);\n" }) }), "\n", _jsx(_components.p, { children: "Click the \"Sign in\" button in your application. Instead of seeing the built-in Logto sign-in UI, you should now be redirected to your custom sign-in page." }), "\n", _jsxs(_components.h2, { id: "interact-with-logto-experience-api", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#interact-with-logto-experience-api", children: _jsx(_components.span, { children: "#" }) }), "Interact with Logto Experience API"] }), "\n", _jsxs(_components.p, { children: ["In this step, we will interact with Logto Experience API in your custom UI. First, let's create a ", _jsx(_components.code, { children: "script.js" }), " file and add the reference in your ", _jsx(_components.code, { children: "index.html" }), "."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-html", title: "index.html", children: "\n \n \n \n \n \n\n" }) }), "\n", _jsxs(_components.p, { children: ["Put the following code in your ", _jsx(_components.code, { children: "script.js" }), " file."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", title: "script.js", children: "window.onload = function () {\n const form = document.getElementById('loginForm');\n form.addEventListener('submit', async function (event) {\n event.preventDefault();\n const formData = new FormData(event.target);\n \n try {\n await fetch('/api/experience', {\n method: 'PUT',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ interactionEvent: 'SignIn' }),\n });\n\n const verificationResponse = await fetch('/api/experience/verification/password', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n identifier: { type: 'username', value: formData.get('username') },\n password: formData.get('password'),\n }),\n });\n\n const { verificationId } = await verificationResponse.json();\n\n await fetch('/api/experience/identification', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ verificationId }),\n });\n\n const submitReponse = await fetch('/api/experience/submit', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n });\n\n const { redirectTo } = await submitReponse.json();\n window.location.replace(redirectTo);\n\n } catch (error) {\n console.error('Oops!', error);\n }\n });\n};\n" }) }), "\n", _jsx(_components.p, { children: "This script will complete the username and password sign-in flow with the help of these APIs:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "PUT /api/experience" }), " - Start the sign-in interaction"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "POST /api/experience/verification/password" }), " - Verify the username and password"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "POST /api/experience/identification" }), " - Identify user for the current interaction"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "POST /api/experience/submit" }), " - Submit the sign-in interaction"] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["Refer to ", _jsx(_components.a, { href: "https://openapi.logto.io/group/endpoint-experience", children: "Logto Experience API docs" }), " for more details."] }), "\n", _jsxs(_components.h2, { id: "test-your-custom-sign-in-page", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#test-your-custom-sign-in-page", children: _jsx(_components.span, { children: "#" }) }), "Test your custom sign-in page"] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "Go to your application and click the \"Sign in\" button." }), "\n", _jsxs(_components.li, { children: ["You should be redirected to your custom sign-in page at ", _jsx(_components.code, { children: "http://localhost:9000/" }), "."] }), "\n", _jsx(_components.li, { children: "Enter username and password, and click the \"Submit\" button." }), "\n", _jsx(_components.li, { children: "If everything is set up correctly, you should be redirected back to your application, with authenticated user information." }), "\n"] }), "\n", _jsxs(_components.h2, { id: "deploy-your-custom-sign-in-ui-to-logto-cloud", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#deploy-your-custom-sign-in-ui-to-logto-cloud", children: _jsx(_components.span, { children: "#" }) }), "Deploy your custom sign-in UI to Logto Cloud"] }), "\n", _jsx(_components.p, { children: "Once you have finished developing and testing your custom sign-in UI locally, you can deploy it to Logto Cloud.\nSimply create a zip file of your custom UI folder and upload it to the \"Custom UI\" section in your Logto Console." }), "\n", _jsx("center", { children: _jsx("img", { src: "https://uploads.strapi.logto.io/1/upload_custom_ui_assets_d5d99b43d9.webp", alt: "Upload custom UI" }) }), "\n", _jsx(_components.p, { children: "After uploading, save the changes, and your custom sign-in UI will go live in your Logto Cloud tenant, replacing the built-in Logto sign-in experience." }), "\n", _jsx("center", { children: _jsx("img", { src: "https://uploads.strapi.logto.io/1/sie_custom_ui_enabled_53f4445188.webp", alt: "Custom UI enabled" }) }), "\n", _jsxs(_components.p, { children: ["Finally, go back to your application and change the endpoint URI back to your Logto cloud endpoint: ", _jsx(_components.code, { children: "https://foobar.logto.app/" }), ".\nThis time, you can stop the Logto tunnel service, and your application should now work directly with the custom UI hosted online."] }), "\n", _jsxs(_components.h2, { id: "conclusion", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#conclusion", children: _jsx(_components.span, { children: "#" }) }), "Conclusion"] }), "\n", _jsx(_components.p, { children: "In this tutorial, we've walked you through the process of implementing and deploying your own custom sign-in UI to Logto Cloud." }), "\n", _jsx(_components.p, { children: "With this feature, you can now deeply customize your sign-in UI and auth flows to match your branding and specific business requirements." }), "\n", _jsx(_components.p, { children: "Happy coding! 🚀" }), "\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."); }