Server web sign-in

Use a confidential client when your server handles a person’s sign-in and can protect a client secret. The browser visits Oathvera’s hosted login; the server exchanges the returned code and keeps tokens out of browser JavaScript.

New integration? Follow the first-login walkthrough for the shortest runnable path.

Configure and run

1. Create a Server web application client. Register http://localhost:3000/callback for this example.
2. Enable the workspace authentication methods you intend to exercise and allow the user into the application.
3. Copy the issuer, client ID and one-time secret. For an initial sign-in-only test, use the registered openid scope. For verified email and optional name, register/request email profile too and apply the profile checks below. Add an API resource and granted permissions only when testing API access.
4. Follow example setup. Run npm run web from that directory and open http://localhost:3000/login.
5. Complete hosted authentication, and expect Signed in successfully after the callback. The sample’s logout revokes the grant and clears its own session; it does not call the hosted logout endpoint.

The example checks state, callback issuer, PKCE, ID-token signature, issuer, audience, expiry and nonce. It issues a new local session identifier after authentication and protects logout with an origin and CSRF check. Its ID-token verification uses the maintained jose implementation.

Protocol sequence

1. Pin the exact issuer and client in server configuration. The reference loads GET <issuer>/.well-known/openid-configuration?client_id=<client-id> at startup and checks issuer/endpoints. In a product, derive the documented authorize path from the pinned issuer so discovery does not block showing the form; validate metadata and keys before accepting the callback, with bounded caching.
2. Generate independent cryptographically random state, nonce and PKCE verifier values. Store them server-side in a short-lived transaction bound to a browser cookie.
3. Redirect to <issuer>/oauth2/authorize with response_type=code, the client ID, exact callback, scope, state, nonce, and an S256 challenge. Include one resource if requesting a granted API.
4. On callback, accept exactly one code, state and iss. Match state to the pending transaction and iss to the configured issuer. Handle errors without creating a session. Consume the transaction once.
5. Exchange the code server-side using HTTP Basic client authentication:

POST <issuer>/oauth2/token
Authorization: Basic <encoded-client-id-and-secret>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<url-encoded-callback>&code_verifier=<verifier>

The Basic header is base64 of the form-encoded client ID, :, and form-encoded secret. The example constructs it for you. Do not send client_secret in the request body or an Origin header. A confidential client must use both PKCE and its credential.

6. Validate the ID token with the discovered JWKS and expected ES256 algorithm, exact issuer, client ID audience, times and original nonce. If your product needs profile claims, validate the scoped email, email_verified and optional name; match UserInfo sub to the ID token when fetching it. Establish your own session only after validation and admission. Persist identity by (iss, sub), never automatically merge by email.
7. For API work, send the opaque access token to your backend API. The API performs its own permission check; successful login is not sufficient authorization.

The HTTP reference defines the currently accepted parameters. Some OIDC libraries automatically send prompt, response_mode or logout hints; the current endpoint rejects unsupported parameters. Configure the library accordingly rather than disabling validation.

Make it part of your product

The reference application uses an in-memory session store, a loopback HTTP listener and a five-minute access-token session. It deliberately does not implement product-specific persistence or refresh. It also does not implement ongoing online session checks. See the full application guide and production handoff. Before deployment:

• Put the application behind HTTPS, configure its trusted public origin, and use Secure, HttpOnly session cookies with an appropriate SameSite policy.
• Replace the Map with a bounded, expiring server-side store shared by your instances. Protect stored tokens and prevent session fixation.
• Implement serialized refresh and revocation. An uncertain code exchange or refresh must not be retried blindly.
• Bound outbound network calls and request bodies; use safe error messages and exclude credentials, codes and tokens from logs.
• Verify current human-session authority with /oidc/session before granting protected access; do not cache successful checks across requests.
• Perform API authorization and product record-ownership checks for every protected action. Add rate limiting, CSRF protection for mutations and your normal operational controls.
• Test callback rejection, expiration, restart behavior, parallel requests, logout and revocation with your actual server framework.

This is a runnable integration reference, not a completed production session framework or an Oathvera SDK.