--- name: auth0-express description: Use when adding authentication to Express.js server-rendered web applications with session management - integrates express-openid-connect for traditional web apps --- # Auth0 Express Integration Add authentication to Express.js web applications using express-openid-connect. --- ## Prerequisites - Express.js application - Auth0 account and application configured - If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first ## When NOT to Use - **Single Page Applications** - Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth - **Next.js applications** - Use `auth0-nextjs` skill which handles both client and server - **Mobile applications** - Use `auth0-react-native` for React Native\/Expo - **Stateless APIs** - Use JWT validation middleware instead of session-based auth - **Microservices** - Use JWT validation for service-to-service auth --- ## Quick Start Workflow ### 1. Install SDK ```bash npm install express-openid-connect dotenv ``` ### 2. Configure Environment **For automated setup with Auth0 CLI**, see [Setup Guide](reference\/setup.md) for complete scripts. **For manual setup:** Create `.env`: ```bash AUTH0_SECRET= AUTH0_BASE_URL=http:\/\/localhost:3000 AUTH0_CLIENT_ID=your-client-id AUTH0_CLIENT_SECRET=your-client-secret AUTH0_ISSUER_BASE_URL=https:\/\/your-tenant.auth0.com ``` Generate secret: `openssl rand -hex 32` ### 3. Configure Auth Middleware Update your Express app (`app.js` or `index.js`): ```javascript require('dotenv').config(); const express = require('express'); const { auth, requiresAuth } = require('express-openid-connect'); const app = express(); \/\/ Configure Auth0 middleware app.use(auth({ authRequired: false, \/\/ Don't require auth for all routes auth0Logout: true, \/\/ Enable logout endpoint secret: process.env.AUTH0_SECRET, baseURL: process.env.AUTH0_BASE_URL, clientID: process.env.AUTH0_CLIENT_ID, issuerBaseURL: process.env.AUTH0_ISSUER_BASE_URL, clientSecret: process.env.AUTH0_CLIENT_SECRET })); app.listen(3000, () => { console.log('Server running on http:\/\/localhost:3000'); }); ``` This automatically creates: - `\/login` - Login endpoint - `\/logout` - Logout endpoint - `\/callback` - OAuth callback ### 4. Add Routes ```javascript \/\/ Public route app.get('\/', (req, res) => { res.send(req.oidc.isAuthenticated() ? 'Logged in' : 'Logged out'); }); \/\/ Protected route app.get('\/profile', requiresAuth(), (req, res) => { res.send(`

Profile<\/h1>

Name: ${req.oidc.user.name}<\/p>

Email: ${req.oidc.user.email}<\/p>

${JSON.stringify(req.oidc.user, null, 2)}<\/pre>
    Logout<\/a>
  `);
});

\/\/ Login\/logout links
app.get('\/', (req, res) => {
  res.send(`
    ${req.oidc.isAuthenticated() ? `
      Welcome, ${req.oidc.user.name}!<\/p>
      Profile<\/a>
      Logout<\/a>
    ` : `
      Login<\/a>
    `}
  `);
});
```

### 5. Test Authentication

Start your server:

```bash
node app.js
```

Visit `http:\/\/localhost:3000` and test the login flow.

---

## Detailed Documentation

- **[Setup Guide](reference\/setup.md)** - Automated setup scripts, environment configuration, Auth0 CLI usage
- **[Integration Guide](reference\/integration.md)** - Protected routes, sessions, API integration, error handling
- **[API Reference](reference\/api.md)** - Complete middleware API, configuration options, request properties

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Forgot to add callback URL in Auth0 Dashboard | Add `\/callback` path to Allowed Callback URLs (e.g., `http:\/\/localhost:3000\/callback`) |
| Missing or weak SECRET | Generate secure secret with `openssl rand -hex 32` and store in .env |
| Setting authRequired: true globally | Set to false and use `requiresAuth()` middleware on specific routes |
| App created as SPA type in Auth0 | Must be Regular Web Application type for server-side auth |
| Session secret exposed in code | Always use environment variables, never hardcode secrets |
| Wrong baseURL for production | Update AUTH0_BASE_URL to match your production domain |
| Not handling logout returnTo | Add your domain to Allowed Logout URLs in Auth0 Dashboard |

---

## Related Skills

- `auth0-quickstart` - Basic Auth0 setup
- `auth0-migration` - Migrate from another auth provider
- `auth0-mfa` - Add Multi-Factor Authentication

---

## Quick Reference

**Middleware Options:**
- `authRequired` - Require auth for all routes (default: false)
- `auth0Logout` - Enable \/logout endpoint (default: false)
- `secret` - Session secret (required)
- `baseURL` - Application URL (required)
- `clientID` - Auth0 client ID (required)
- `issuerBaseURL` - Auth0 tenant URL (required)

**Request Properties:**
- `req.oidc.isAuthenticated()` - Check if user is logged in
- `req.oidc.user` - User profile object
- `req.oidc.accessToken` - Access token for API calls
- `req.oidc.idToken` - ID token
- `req.oidc.refreshToken` - Refresh token

**Common Use Cases:**
- Protected routes → Use `requiresAuth()` middleware (see Step 4)
- Check auth status → `req.oidc.isAuthenticated()`
- Get user info → `req.oidc.user`
- Call APIs → [Integration Guide](reference\/integration.md#calling-apis)

---

## References

- [Express OpenID Connect Documentation](https:\/\/auth0.com\/docs\/libraries\/express-openid-connect)
- [Auth0 Express Quickstart](https:\/\/auth0.com\/docs\/quickstart\/webapp\/express)
- [SDK GitHub Repository](https:\/\/github.com\/auth0\/express-openid-connect)