Follow these simple steps to set up Civic Auth with a backend (a working example is available in our ).
1. Install dependencies
npm install @civic/auth
yarn add @civic/auth
pnpm install @civic/auth
bun add @civic/auth
2. Configure your App
Your app will need the following configuration:
const config = {
clientId: // Client ID from auth.civic.com
redirectUrl: 'http://localhost:3000/auth/callback', // change to your domain when deploying
postLogoutRedirectUrl: 'http://localhost:3000/' // The postLogoutRedirectUrl is the URL where the user will be redirected after successfully logging out from Civic's auth server.
};
Note: redirectUrl and postLogoutRedirectUrl must be absolute URLs.
3. Set up Cookies
Civic Auth uses cookies for storing the login state by default
import { Context } from 'hono';
import { getCookie, setCookie } from 'hono/cookie';
import { CookieStorage, CivicAuth } from '@civic/auth/server';
class HonoCookieStorage extends CookieStorage {
constructor(private c: Context) {
super();
}
async get(key: string) {
return getCookie(this.c, key) ?? null;
}
async set(key: string, value: string): void {
setCookie(this.c, key, value);
}
}
// Middleware to attach CookieStorage and civicAuth API to each request
app.use('*', async (c, next) => {
const storage = new HonoCookieStorage(c)
c.set('storage', storage);
c.set('civicAuth', new CivicAuth(storage, config));
return next();
});
4. Create a Login Endpoint
This endpoint will handle login requests, build the Civic login URL and redirect the user to it.
import { isLoggedIn } from '@civic/auth/server';
// Apply authentication middleware to any routes that need it
app.use('/admin/*', async (c, next) => {
if (!c.get('civicAuth').isLoggedIn()) return c.text('Unauthorized', 401);
return next();
});
8. Use the Session
If needed, get the logged-in user information.
import { user } from '@civic/auth/server';
app.get('/admin/hello', async (c) => {
const user = await c.get('civicAuth').getUser();
return c.text(`Hello, ${user?.name}!`);
});
PKCE and Client Secrets
When using the Civic Auth SDK, PKCE is handled entirely by the library.
Civic Auth uses , to protect users and clients from unauthorized access to user information. This, alongside domain registration for apps in production environments, mean that you don't need to provide a client secret in your backend.