This is an example of how to use AuthKit with an HTML frontend.
``` Clicking the "Sign in" and "Sign out" links should invoke actions on our server, which we'll set up next. ### Add a sign-in endpoint We'll need a sign-in endpoint to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. This endpoint should generate an AuthKit authorization URL server side and redirect the user to it. You can use the optional state parameter to encode arbitrary information to help restore application `state` between redirects. For this guide we'll be using the `express` web server for Node. This guide won't cover how to set up an Express app, but you can find more information in the [Express documentation](https://expressjs.com/en/starter/installing.html). #### server.js ```jsx require('dotenv').config(); const path = require('path'); const express = require('express'); const { WorkOS } = require('@workos-inc/node'); const app = express(); const workos = new WorkOS(process.env.WORKOS_API_KEY, { clientId: process.env.WORKOS_CLIENT_ID, }); // This `/login` endpoint should be registered as the login endpoint // on the "Redirects" page of the WorkOS Dashboard. app.get('/login', (req, res) => { const authorizationUrl = workos.userManagement.getAuthorizationUrl({ // Specify that we'd like AuthKit to handle the authentication flow provider: 'authkit', // The callback endpoint that WorkOS will redirect to after a user authenticates redirectUri: 'http://localhost:3000/callback', clientId: process.env.WORKOS_CLIENT_ID, }); // Redirect the user to the AuthKit sign-in page res.redirect(authorizationUrl); }); app.get('/', (req, res) => { res.sendFile(path.join(__dirname, 'index.html')); }); app.listen(3000, () => { console.log('Server running on http://localhost:3000'); }); ``` > WorkOS will redirect to your [Redirect URI](https://workos.com/docs/glossary/redirect-uri) if there is an issue generating an authorization URL. Read our [API Reference](https://workos.com/docs/reference) for more details. ### Add a callback endpoint Next, let's add the callback endpoint (referenced in [Configure a redirect URI](https://workos.com/docs/authkit/1-configure-your-project/configure-a-redirect-uri)) which will exchange the authorization code (valid for 10 minutes) for an authenticated User object. #### server.js ```js const express = require('express'); const { WorkOS } = require('@workos-inc/node'); const app = express(); const workos = new WorkOS(process.env.WORKOS_API_KEY, { clientId: process.env.WORKOS_CLIENT_ID, }); // +diff-start app.get('/callback', async (req, res) => { // The authorization code returned by AuthKit const code = req.query.code; if (!code) { return res.status(400).send('No code provided'); } const { user } = await workos.userManagement.authenticateWithCode({ code, clientId: process.env.WORKOS_CLIENT_ID, }); // Use the information in `user` for further business logic. // Redirect the user to the homepage return res.redirect('/'); }); // +diff-end ``` ## (3) Handle the user session Session management helper methods are included in our SDKs to make integration easy. For security reasons, sessions are automatically "sealed", meaning they are encrypted with a strong password. ### Create a session password The SDK requires you to set a strong password to encrypt cookies. This password must be 32 characters long. You can generate a secure password by using the [1Password generator](https://1password.com/password-generator/) or the `openssl` library via the command line: ```bash title="Generate a strong password" openssl rand -base64 32 ``` Then add it to the environment variables file. ```plain title=".env" WORKOS_API_KEY='sk_example_123456789' WORKOS_CLIENT_ID='client_123456789' # +diff-start WORKOS_COOKIE_PASSWORD='Welcome, ${user.email}!
`); } else { html = html.replace('{{USER_DATA}}', ''); } res.send(html); }); ``` And, we should make sure to update the index page to present this info. #### index.html ```htmlThis is an example of how to use AuthKit with an HTML frontend.
``` ### Protected routes Then, use middleware to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one. #### server.js ```js import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS(process.env.WORKOS_API_KEY, { clientId: process.env.WORKOS_CLIENT_ID, }); // Auth middleware function async function withAuth(req, res, next) { const session = workos.userManagement.loadSealedSession({ sessionData: req.cookies['wos-session'], cookiePassword: process.env.WORKOS_COOKIE_PASSWORD, }); const { authenticated, reason } = await session.authenticate(); if (authenticated) { return next(); } // If the cookie is missing, redirect to login if (!authenticated && reason === 'no_session_cookie_provided') { return res.redirect('/login'); } // If the session is invalid, attempt to refresh try { const { authenticated, sealedSession } = await session.refresh(); if (!authenticated) { return res.redirect('/login'); } // update the cookie res.cookie('wos-session', sealedSession, { path: '/', httpOnly: true, secure: true, sameSite: 'lax', }); // Redirect to the same route to ensure the updated cookie is used return res.redirect(req.originalUrl); } catch (e) { // Failed to refresh access token, redirect user to login page // after deleting the cookie res.clearCookie('wos-session'); res.redirect('/login'); } } ``` Add the middleware to the route that should only be accessible to logged in users. #### server.js ```js // Specify the `withAuth` middleware function we defined earlier to protect this route app.get('/dashboard', withAuth, async (req, res) => { const session = workos.userManagement.loadSealedSession({ sessionData: req.cookies['wos-session'], cookiePassword: process.env.WORKOS_COOKIE_PASSWORD, }); const { user } = await session.authenticate(); console.log(`User ${user.firstName} is logged in`); // ... render dashboard page }); ``` ### Ending the session Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Sign-out redirect](https://workos.com/docs/authkit/sessions/configuring-sessions/sign-out-redirect) location, which is configured in the WorkOS dashboard. #### server.js ```js const { doubleCsrf } = require('csrf-csrf'); const cookieParser = require('cookie-parser'); app.use(cookieParser()); app.use(express.urlencoded({ extended: false })); const { generateCsrfToken, doubleCsrfProtection } = doubleCsrf({ getSecret: () => process.env.CSRF_SECRET, getSessionIdentifier: (req) => req.cookies['wos-session'] ?? '', }); // Endpoint to get CSRF token for forms app.get('/csrf-token', (req, res) => { const csrfToken = generateCsrfToken(req, res); res.json({ csrfToken }); }); app.post('/logout', doubleCsrfProtection, async (req, res) => { const session = workos.userManagement.loadSealedSession({ sessionData: req.cookies['wos-session'], cookiePassword: process.env.WORKOS_COOKIE_PASSWORD, }); const url = await session.getLogoutUrl(); res.clearCookie('wos-session'); res.redirect(url); }); ``` > **Note:** CSRF Protection: The logout endpoint uses POST to prevent > unintended logouts from browser prefetching. CSRF protection with >csrf-csrf prevents cross-site request forgery attacks. The
> frontend fetches a CSRF token from /csrf-token and includes it
> in the logout form submission.
> If you haven't configured a [Sign-out redirect](https://workos.com/docs/authkit/sessions/configuring-sessions/sign-out-redirect) in the WorkOS dashboard, users will see an error when logging out.
## Validate the authentication flow
To test all of this out, start your server with `node server.js`, navigate to `localhost:3000`, and sign up for an account.
You can then sign in with the newly created credentials and see the user listed in the **Users** section of the [WorkOS Dashboard](https://dashboard.workos.com).
