Skip to content
Udibo
Join the waitlist
On this page
View Markdown

Quickstart: run auth for your application

Run the Hono example to see login, an OAuth2 authorization server, a BFF, and a protected API working together. Everything runs locally; no Udibo account, external database, or email service is required.

If you want Udibo to host sign-in, use the managed-service guide. It requires a Udibo account; see udibo.com for how to get one.

Run the example

Install Node.js 24.2 or later, pnpm, and Git, then check out the public package repository. The example is a workspace member that uses the package's built output, so build once before starting it:

Shell
git clone https://github.com/udibo/oauth2.git
cd oauth2
pnpm install
pnpm build
pnpm --filter example-app-with-own-auth start

Open http://localhost:8001/. Use user / password for the regular demo user, or admin / password to exercise the admin scope. These credentials and all in-memory data belong only to this local demo.

Follow a sign-in

  1. Select Sign in. The browser visits the BFF's login route, which starts an authorization-code flow with state and PKCE.

  2. Enter a demo user's credentials at the app's login page.

  3. Review the consent page. The example limits the requested scopes to the user's allowed scopes.

  4. The callback exchanges the code on the server and creates an HttpOnly session cookie. Access and refresh tokens stay in the BFF.

  5. Call the API from the homepage. Requests without a session are rejected; the regular user cannot call the admin-scoped endpoint.

  6. Sign out and confirm the protected request is rejected again.

The example also has signup, password reset, and email-verification pages. Delivery hooks print links to the terminal in place of sending mail. Restarting the process resets users, sessions, codes, and tokens.

Read the implementation

Start with the example README, then follow these files:

FileWhat to learn
oauth2/server.tsClients, grants, token storage, and BFF configuration
main.tsEndpoint mounting, session lookup, and consent decisions
oauth2/identity.tsLogin, reset, verification, and delivery hooks
sessions.tsThe example's application session
main.test.tsSuccessful flows and refused requests

Run its tests from the repository root:

Shell
pnpm --filter example-app-with-own-auth test

Start your own application

For an existing Hono app, use host authorization for your app and add login. They explain which interfaces your database must implement and how to connect your existing session and login pages.

For a new React app, start with the React Router template. For an API without a browser frontend, use protect an API.

Before deployment, replace the demo stores, credentials, console delivery, and local HTTP settings. Follow the deployment guide and checklist; the demo is not a production configuration.