Skip to content
LogoLogo

End backend sessions

A backend ends the session that it holds for a user, and refuses that session's cookie.

Overview

With the backend plugin, the server's store holds each session, and the browser holds only its ID, in an HttpOnly session cookie. The logout route of accounts.handler ends each part:

PartAfter the logout route
Refresh tokenRevoked at Tempo ID
SessionDeleted from the store, with its tokens and access key
CookieDeleted. A request with the old cookie reads no session

The user's Tempo ID session in the browser stays, as after an app sign-out.

The demo signs a user in on this site's server, posts to the logout route, and then receives 401 from a route that needs the session.

End a backend sessionDemo
pnpx gitpick tempoxyz/accounts/tree/main/examples/backendSource

Walkthrough

The backend example runs these steps.

Serve the logout routeServer

accounts.handler of an instance with the backend plugin serves POST /api/auth/logout beside the sign-in routes.

import { Hono } from 'hono'
import { accounts } from './tempo.config.js'
 
const app = new Hono()
 
app.all('/api/*', (c) => accounts.handler.fetch(c.req.raw)) 
 
export default app

Post to the logout routeClient

The route answers 204. It answers 403 to a request from another origin, since a cross-site form post also sends the cookie. If the revocation or the store fails, it answers 503, and still deletes the cookie.

<button
  onclick="fetch('/api/auth/logout', { method: 'POST' }).then(() => location.reload())"
  type="button"
>
  Sign out
</button>

Refuse a request without a sessionServer

session.get returns undefined without a cookie, or for an ended session's cookie.

import { Hono } from 'hono'
import { accounts } from './tempo.config.js'
 
const app = new Hono()
 
app.all('/api/*', (c) => accounts.handler.fetch(c.req.raw))
 
app.get('/profile', async (c) => {
  const session = await accounts.session.get(c.req.raw) 
  if (session?.method !== 'tempo-id')
    return c.json({ error: 'signed_out' }, 401) 
 
  return c.json({ email: session.user.email })
})
 
export default app

Use cases

Each use case ends a session with another route or member of the backend plugin, or sets one of its options.

End a session in a route of the app

A backend with its own sign-in routes calls backend.end with its cookie's session ID, and deletes the cookie. With revoke: false, it deletes a session that Tempo ID ended already, with no request.

import { Hono } from 'hono'
import { deleteCookie, getCookie } from 'hono/cookie'
import { accounts } from './tempo.config.js'
 
const app = new Hono()
 
app.post('/auth/sign-out', async (c) => {
  const id = getCookie(c, 'session')
  if (id) await accounts.backend.end({ id }) 
 
  deleteCookie(c, 'session')
  return c.body(null, 204)
})
 
export default app

End a session after a logout token

If a Tempo ID session ends, such as at a sign-out of every app, Tempo ID posts a logout token (OpenID Connect Back-Channel Logout) to each registered app. The back-channel logout route of accounts.handler verifies it, and ends each session of the token's Tempo ID session.

import { Hono } from 'hono'
import { csrf } from 'hono/csrf'
import { accounts } from './tempo.config.js'
 
const app = new Hono()
 
// Tempo ID posts the token with no Origin header, so the route comes before the CSRF middleware.
app.post('/api/auth/backchannel-logout', (c) => accounts.handler.fetch(c.req.raw)) 
app.use(csrf())
app.all('/api/*', (c) => accounts.handler.fetch(c.req.raw))
 
export default app

Register the route's URL, such as https://app.example/api/auth/backchannel-logout, as the app's back-channel logout URI, with the session required. Tempo ID revoked the refresh tokens already, so the route ends each session without a revocation. A second revocation reads as a reuse, which revokes the user's other sessions at the app.

The route ends only the sessions that Tempo ID issued no later than the token. The backend plugin indexes each session by its Tempo ID session at the sign-in. The index keeps a session that fails to end, so the retry of the token ends it.

A session from a release before the index has no entry, so it ends at its next refresh. A sign-in of the same Tempo ID session that finishes after the token ends at once. The exception is a sign-in whose tokens Tempo ID issued after the token, such as a sign-in again after the app's disconnection.

The route answers a body above 64 KiB with 413, and stops reading it at the chunk that crosses 64 KiB.

Verify a logout token in a route of the app

A backend with routes of its own calls backend.logout with the token of the form body. It throws LogoutToken.InvalidError for a token that does not verify.

import { LogoutToken } from 'accounts'
import { Hono } from 'hono'
import { accounts } from './tempo.config.js'
 
const app = new Hono()
 
app.post('/auth/logout-token', async (c) => {
  const form = await c.req.formData()
  const ended = await accounts.backend
    .logout({ logoutToken: String(form.get('logout_token')) })
    .catch((error: unknown) => {
      if (error instanceof LogoutToken.InvalidError) return undefined
      throw error
    })
  if (!ended) return c.body(null, 400)
 
  return c.body(null, 200)
})
 
export default app

Reach Tempo ID at an internal address

logoutToken takes the options of the logout token's verifier. If the instance's url reaches Tempo ID at another address, its issuer names Tempo ID's public origin.

tempo.config.ts
import { Accounts, Store } from 'accounts'
import { backend } from 'accounts/plugins'
 
export const accounts = Accounts.create({
  chain: 'testnet',
  clientId: process.env.APP_URL,
  plugins: [
    backend({
      logoutToken: { issuer: 'https://id.tempo.xyz' }, 
      store: Store.memory(),
    }),
  ],
  url: 'http://tempo-id.internal',
})

Next steps