Skip to content
Paylent Docs

Hono OIDC

Build a minimal web app that authenticates users with Paylent using the @hono/oidc-auth middleware. This is the fastest way to add login — the middleware handles discovery, token exchange, and session management automatically.

Using OIDC middleware is the fastest path to adding authentication. You don’t need to understand the details of authorization codes, token exchange, or session management — the middleware handles it all. This makes it ideal for first-party web apps where you just need to know who the user is.

Because the middleware uses a confidential client, the client_secret is stored on the server and never exposed to the browser. This is the most secure option for server-rendered apps. The middleware also handles token refresh and session expiry automatically, so you don’t need to write any token lifecycle code.

What you’ll build

Section titled “What you’ll build”

A Hono web server that:

  • Shows a “Log in with Paylent” link on the home page
  • Redirects to Paylent for authentication
  • Displays the authenticated user’s profile after login

Prerequisites

Section titled “Prerequisites”

Configure in the dashboard

Section titled “Configure in the dashboard”

This example needs a confidential OAuth client. Here’s how to create one in the dashboard:

  1. Open the dashboard

    Go to http://dashboard.localhost:4000 and log in. Select the examples-dev environment from the environment switcher.

    Dashboard environment switcher

  2. Register an OAuth client

    Navigate to Clients in the sidebar, then click Register Application.

    Clients list

    Fill in the form:

    • Name: My Hono App
    • Client Type: Confidential
    • Grant Types: Authorization Code, Refresh Token
    • Redirect URIs: http://localhost:3000/callback

    Register application form

  3. Copy the client secret

    After saving, you’ll see the client secret. Copy it — this is the only time it’s shown.

    Client secret modal

    Add the client_id and client_secret to the example’s .env file.

Run the example

Section titled “Run the example”

  1. Install dependencies

    Terminal window
    cd examples/hono-oidc
    npm install

  2. Start the app

    Terminal window
    npm run dev

    The server starts at http://localhost:3000.

  3. Open the app and log in

    Open http://localhost:3000 in your browser. You’ll see a simple page with a “Log in with Paylent” link.

    Hono OIDC home page

    Click it. You’ll be redirected to the Paylent login page at http://examples-dev.localhost:4000/login.

    Paylent login page

  4. Enter credentials

    Log in with the test user:

  5. View the result

    After login, you’re redirected back to the app. The page now shows your authenticated user’s email and the full OIDC auth object:

    Authenticated user view

How it works

Section titled “How it works”

The key is the @hono/oidc-auth middleware, which handles the entire OIDC flow:

import { initOidcAuthMiddleware } from "@hono/oidc-auth";


app.use(
  "/*",
  initOidcAuthMiddleware({
    OIDC_AUTH_SECRET: process.env.PAYLENT_AUTH_SECRET!,
    OIDC_ISSUER: process.env.PAYLENT_ISSUER!,
    OIDC_CLIENT_ID: process.env.PAYLENT_CLIENT_ID!,
    OIDC_CLIENT_SECRET: process.env.PAYLENT_CLIENT_SECRET!,
    OIDC_REDIRECT_URI: process.env.PAYLENT_REDIRECT_URI,
  })
);

The middleware:

  1. Discovers Paylent’s endpoints via /.well-known/openid-configuration
  2. Redirects unauthenticated users to the authorization endpoint
  3. Handles the callback and exchanges the authorization code for tokens
  4. Stores the session and makes the auth object available in route handlers

Next steps

Section titled “Next steps”