|
| 1 | +--- |
| 2 | +title: "Add Login to Your Hono Application" |
| 3 | +mode: wide |
| 4 | +sidebarTitle: Hono |
| 5 | +description: "This Quickstart demonstrates how to secure your Hono applications using Auth0 authentication. Follow the steps to add login, logout, and protected routes to a Hono app." |
| 6 | +--- |
| 7 | + |
| 8 | +import {AuthCodeGroup} from "/snippets/AuthCodeGroup.jsx"; |
| 9 | + |
| 10 | +<Callout icon="pencil" color="#FFC107" iconType="solid"> |
| 11 | + This Quickstart is currently in **Beta**. We'd love to hear your feedback! |
| 12 | +</Callout> |
| 13 | + |
| 14 | +<Note> |
| 15 | + **Prerequisites:** |
| 16 | + |
| 17 | + - **Node.js** 20 LTS or newer |
| 18 | + - **npm** 10+ or **yarn** 1.22+ or **pnpm** 8+ |
| 19 | + - Optional: **[jq](https://jqlang.org/)** - for Auth0 CLI setup and **openssl** to generate secure secrets |
| 20 | + - Hono projects should use Hono >= 3.x (peer dependency) |
| 21 | +</Note> |
| 22 | + |
| 23 | +## Get Started |
| 24 | + |
| 25 | +This quickstart shows the minimal, recommended way to secure a Hono application using `@auth0/auth0-hono`. It follows the repository's recommended patterns: environment-driven configuration, `app.use(auth(...))` middleware, and `requiresAuth()` for selective protection. |
| 26 | + |
| 27 | +<Steps> |
| 28 | + <Step title="Create a new Hono application" stepNumber={1}> |
| 29 | + Create a new Hono application using create-hono utility. |
| 30 | + |
| 31 | + ```shellscript |
| 32 | + npm create hono@latest auth0-hono-app && cd auth0-hono-app |
| 33 | + ``` |
| 34 | + |
| 35 | + Select `nodejs` template |
| 36 | + </Step> |
| 37 | + |
| 38 | + <Step title="Install dependencies" stepNumber={2}> |
| 39 | + Install the Auth0 middleware. |
| 40 | + |
| 41 | + ```shellscript |
| 42 | + npm install @auth0/auth0-hono |
| 43 | + ``` |
| 44 | + |
| 45 | + This quickstart uses `dotenv` package to load environment variables from a `.env` file. |
| 46 | + |
| 47 | + To install `dotenv` locally: |
| 48 | + ```shellscript |
| 49 | + npm install -D dotenv |
| 50 | + ``` |
| 51 | + |
| 52 | + Alterantively, if you prefer not to add a dependency, you can load an env file at process start using node's `--env-file` flag, which lets you omit installing and importing `dotenv`. |
| 53 | + |
| 54 | + Modify the `start` script in `package.json` to: |
| 55 | + |
| 56 | + ```json |
| 57 | + "scripts": { |
| 58 | + "start": "node --env-file=.env dist/index.js" |
| 59 | + } |
| 60 | + ``` |
| 61 | + </Step> |
| 62 | + |
| 63 | + <Step title="Create an Auth0 application" stepNumber={3}> |
| 64 | + Create an Auth0 Application in your Auth0 tenant (Regular Web Application) and record the **Domain**, **Client ID**, and **Client Secret** in environment variables to your project. |
| 65 | + You can choose to do this automatically by running a CLI command or do it manually via the Dashboard: |
| 66 | + |
| 67 | + <Tabs> |
| 68 | + <Tab title="CLI"> |
| 69 | + Run the following shell command on your project’s root directory to create an Auth0 app and generate a `.env` file: |
| 70 | + |
| 71 | + <AuthCodeGroup> |
| 72 | + ```shellscript Mac |
| 73 | + AUTH0_APP_NAME="Hono Quickstart" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && SECRET=$(openssl rand -hex 32) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "BASE_URL=http://localhost:3000" >> .env && echo "AUTH0_SESSION_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env && rm auth0-app-details.json && cat .env |
| 74 | + ``` |
| 75 | + |
| 76 | + ```shellscript Windows |
| 77 | + $AppName = "Hono Quickstart"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:3000/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Secret = [System.Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLower(); Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_CLIENT_SECRET=$ClientSecret"; Add-Content -Path .env -Value "AUTH0_SECRET=$Secret"; Add-Content -Path .env -Value "BASE_URL=http://localhost:3000"; Remove-Item auth0-app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env |
| 78 | + ``` |
| 79 | + </AuthCodeGroup> |
| 80 | + |
| 81 | + Use the generated `.env` or update values manually as needed. |
| 82 | + </Tab> |
| 83 | + |
| 84 | + <Tab title="Dashboard"> |
| 85 | + Manual steps: |
| 86 | + |
| 87 | + 1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/) |
| 88 | + 2. Applications → Create Application → **Regular Web Application** |
| 89 | + 3. In the app settings set: |
| 90 | + |
| 91 | + **Allowed Callback URLs** |
| 92 | + ``` |
| 93 | + http://localhost:3000/auth/callback |
| 94 | + ``` |
| 95 | + |
| 96 | + **Allowed Logout URLs** |
| 97 | + ``` |
| 98 | + http://localhost:3000 |
| 99 | + ``` |
| 100 | + |
| 101 | + 4. Create a `.env` file at your project root and populate these values: |
| 102 | + |
| 103 | + ```env |
| 104 | + AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN |
| 105 | + AUTH0_CLIENT_ID=YOUR_AUTH0_CLIENT_ID |
| 106 | + AUTH0_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET |
| 107 | + BASE_URL=http://localhost:3000 |
| 108 | + AUTH0_SESSION_ENCRYPTION_KEY=your_32_char_min_secret |
| 109 | + # Optional for APIs |
| 110 | + AUTH0_AUDIENCE=YOUR_API_IDENTIFIER |
| 111 | + ``` |
| 112 | + |
| 113 | + Note: `AUTH0_SESSION_ENCRYPTION_KEY` must be at least 32 characters. Use `openssl rand -hex 32` to generate one. |
| 114 | + </Tab> |
| 115 | + </Tabs> |
| 116 | + </Step> |
| 117 | + |
| 118 | + <Step title="Setup Hono web server with Auth0 middleware" stepNumber={4}> |
| 119 | + Replace the initial template in `index.ts` file with the following example. |
| 120 | + |
| 121 | + ```typescript |
| 122 | + // index.ts |
| 123 | + import 'dotenv/config'; // Not required if using --env-file flag |
| 124 | + import { serve } from '@hono/node-server'; |
| 125 | + import { Hono } from 'hono'; |
| 126 | + import { auth, requiresAuth, Auth0Exception, type OIDCEnv } from '@auth0/auth0-hono'; |
| 127 | + |
| 128 | + const app = new Hono<OIDCEnv>(); |
| 129 | + |
| 130 | + // Configure auth middleware using environment variables. |
| 131 | + app.use( |
| 132 | + auth({ |
| 133 | + domain: process.env.AUTH0_DOMAIN, |
| 134 | + clientID: process.env.AUTH0_CLIENT_ID, |
| 135 | + clientSecret: process.env.AUTH0_CLIENT_SECRET, |
| 136 | + baseURL: process.env.BASE_URL, |
| 137 | + authRequired: false, // Make routes public by default, protect specific routes below |
| 138 | + session: { |
| 139 | + secret: process.env.AUTH0_SESSION_ENCRYPTION_KEY, |
| 140 | + }, |
| 141 | + }) |
| 142 | + ); |
| 143 | + |
| 144 | + // Public route |
| 145 | + app.get('/', (c) => c.text('Public — no login required')); |
| 146 | + |
| 147 | + // Make most routes public, but protect /profile/* |
| 148 | + app.use('/profile/*', requiresAuth()); |
| 149 | + |
| 150 | + app.get('/profile', async (c) => { |
| 151 | + const session = await c.var.auth0Client?.getSession(c); |
| 152 | + const user = session?.user; |
| 153 | + return c.json({ message: 'Protected profile', user }); |
| 154 | + }); |
| 155 | + |
| 156 | + const port = Number(process.env.PORT) || 3000; |
| 157 | + serve({ fetch: app.fetch, port }, (info) => { |
| 158 | + console.log(`Server is running on http://localhost:${info.port}`); |
| 159 | + } |
| 160 | + ); |
| 161 | + ``` |
| 162 | + </Step> |
| 163 | + |
| 164 | + <Step title="Run your app" stepNumber={5}> |
| 165 | + Start the server and open `http://localhost:3000`. |
| 166 | + |
| 167 | + ```shellscript |
| 168 | + npm run dev |
| 169 | + ``` |
| 170 | + </Step> |
| 171 | +</Steps> |
| 172 | + |
| 173 | +<Check> |
| 174 | + **Checkpoint** |
| 175 | + |
| 176 | + Your Hono app should be running on [http://localhost:3000](http://localhost:3000). The `/` route is public. Visiting `/profile` should redirect you to login (if not authenticated) and then return profile data after successful authentication. |
| 177 | +</Check> |
| 178 | + |
| 179 | +## Troubleshooting |
| 180 | + |
| 181 | +<Accordion title="Common issues" > |
| 182 | + |
| 183 | + <Accordion title="Callback or Redirect Mismatch" > |
| 184 | + Cause: The callback URL configured in the Auth0 Dashboard does not exactly match `BASE_URL` + the callback route (e.g., `http://localhost:3000/auth/callback`). |
| 185 | + |
| 186 | + Fix: |
| 187 | + 1. Verify `.env` `BASE_URL` value. |
| 188 | + 2. Ensure Allowed Callback URLs in Auth0 Dashboard contain `http://localhost:3000/auth/callback`. |
| 189 | + 3. Restart dev server after changes. |
| 190 | + </Accordion> |
| 191 | + |
| 192 | + <Accordion title="Session decryption / JWEDecryptionFailed" > |
| 193 | + Cause: `AUTH0_SESSION_ENCRYPTION_KEY` is missing or too short, or you changed it while cookies from an old secret remain. |
| 194 | + |
| 195 | + Fix: |
| 196 | + - Ensure `AUTH0_SESSION_ENCRYPTION_KEY` is at least 32 characters. |
| 197 | + - Clear browser cookies for localhost after changing the key. |
| 198 | + - Restart dev server. |
| 199 | + </Accordion> |
| 200 | + |
| 201 | + <Accordion title="Routes 404 (e.g., /auth/login returns 404)" > |
| 202 | + Cause: Middleware not installed or placed after route registration. |
| 203 | + |
| 204 | + Fix: |
| 205 | + - Ensure `app.use(auth(...))` runs before routes that depend on authentication. |
| 206 | + - Confirm package installed: `npm ls @auth0/auth0-hono`. |
| 207 | + </Accordion> |
| 208 | + |
| 209 | + <Accordion title="Missing environment variables in production" > |
| 210 | + Cause: Deployment platform not providing environment variables or using different names. |
| 211 | + |
| 212 | + Fix: |
| 213 | + - Map environment variables in your hosting provider dashboard to the names used in this quickstart. |
| 214 | + - For Cloudflare Workers, verify session/cookie handling is compatible with the platform. |
| 215 | + </Accordion> |
| 216 | + |
| 217 | +</Accordion> |
| 218 | + |
| 219 | +## Advanced Usage |
| 220 | + |
| 221 | +- Selective protection: use `app.use(auth({ authRequired: false }))` to make routes public by default and `app.use('/private/*', requiresAuth())` to protect specific paths. |
| 222 | +- Silent login: use `attemptSilentLogin()` middleware to try silent authentication for better UX. |
| 223 | +- Custom login flow: call `login({...})` to customize forwarded query params, `redirectAfterLogin`, or silent login options. |
| 224 | +- Token management: the middleware exposes access and ID tokens via the session; follow least-privilege for scopes and rotate refresh tokens safely. |
| 225 | + |
| 226 | +## Best Practices & Security |
| 227 | + |
| 228 | +- Keep secrets out of source control — use environment variables. |
| 229 | +- Use a 32+ character `AUTH0_SESSION_ENCRYPTION_KEY`. |
| 230 | +- Set cookie `secure` to `true` in production and set appropriate `sameSite` policy. |
| 231 | +- Limit token scopes; use audience only when requesting access tokens for APIs. |
| 232 | +- Catch `Auth0Exception` in `app.onError` to handle auth-specific errors cleanly. |
| 233 | + |
| 234 | +--- |
0 commit comments