Reference backend for server-mediated KRDPASS OAuth.
This server demonstrates:
- PAR request handling
- Authorization code exchange
- Optional refresh and revoke endpoints
- Transaction-bound state, redirect, environment, scope, nonce, and PKCE validation
- OIDC ID-token signature and claim validation through the selected CAS discovery/JWKS endpoints
This is a reference implementation, not a production-ready service.
- Keep
CLIENT_SECRETand private keys server-side only. - Replace the demo-only in-memory transaction store with durable, shared storage in production. It must support bounded expiry and atomic get-and-delete so a state cannot be exchanged twice across BFF instances.
- Apply proper auth, rate limits, observability, and secret management before production use.
- Default bind host is
127.0.0.1for local development safety.
None. This reference installs zero packages, production or dev. The HTTP
server, HTTP client, JSON body parsing, RSA signing and verification, file
watching, and .env loading all come from the Node 24 standard library: a sample
every integrator installs should not drag a dependency tree of advisories along
with it. npm install here creates no node_modules.
- Node.js 24+ (what CI builds on, and what
enginesrequires) - Onboarding-approved credentials from KRDPASS
This reference is the confidential half of the flow, so it needs CLIENT_ID,
CLIENT_SECRET, the RSA private key matching the X.509 certificate you registered at
onboarding, your approved scopes and environment, and your registered HTTPS redirect URI.
See the integration guide.
- Create local env file:
cp .env.example .env- Fill required variables in
.env:
| Variable | Required | Description |
|---|---|---|
CLIENT_ID |
Yes | OAuth client ID issued during onboarding |
CLIENT_SECRET |
Yes | OAuth client secret issued during onboarding |
RSA_PRIVATE_KEY |
Yes | Full PEM private key, escaped with \\n in .env. Must be the key inside the X.509 certificate registered at onboarding |
ALLOWED_REDIRECT_HOSTS |
Yes | Comma-separated host allowlist for redirectUri (e.g. auth.myapp.gov.krd). The server refuses to start without it, and an unlisted host is rejected at /oauth/par. .env.example ships a placeholder so a fresh clone starts; replace it with your registered redirect host. When using scripts/sync-secrets.sh, the REDIRECT_URI host is auto-appended. |
HOST |
No | Bind host, defaults to 127.0.0.1 |
PORT |
No | Server port, defaults to 3000 |
DEFAULT_SCOPE |
No | Default scope used when /oauth/par request omits scope (default: openid profile) |
AUTH_TRANSACTION_TTL_MS |
No | BFF transaction lifetime in ms (default 5 minutes, clamped to 30 seconds to 10 minutes and never longer than CAS PAR expiry) |
OIDC_METADATA_CACHE_TTL_MS |
No | CAS discovery metadata cache lifetime in ms (default 1 hour) |
CAS_HTTP_TIMEOUT_MS |
No | Hard timeout on every call to CAS, in ms (default 10 seconds) |
DEMO_EXTRAS |
No | Set true only if serving AASA/assetlinks from this server |
DEMO_IOS_APP_IDS |
If DEMO_EXTRAS=true |
Comma-separated iOS app IDs (TEAM_ID.bundle.id) |
DEMO_IOS_TEAM_ID + DEMO_IOS_BUNDLE_ID |
If DEMO_EXTRAS=true |
Single-app fallback for iOS |
DEMO_ANDROID_APP_LINKS |
If DEMO_EXTRAS=true |
Comma-separated `package |
DEMO_ANDROID_PACKAGE_NAME + DEMO_ANDROID_SHA256 |
If DEMO_EXTRAS=true |
Single-app fallback for Android |
DEMO_UNAUTHENTICATED_TOKEN_ROUTES |
No | Set true to register /oauth/token/refresh and /oauth/token/revoke. Off by default; see the warning below. |
Refresh, revoke and sign-out return 404 until you opt in. DEMO_UNAUTHENTICATED_TOKEN_ROUTES
is false by default, and with it unset the two routes are not registered at all. Every
sample's Refresh and Revoke buttons, and the revoke half of Sign Out, fail with a 404 until
you set it to true in .env. That default is deliberate: both routes attach CLIENT_SECRET
to whatever token a caller posts, with no session, cookie, bearer check, or CSRF protection
in front of them. Turn them on for a local demo, never for anything reachable from a network.
See the full warning under "Security and Policy Notes".
DEMO_EXTRAS=true is the same shape of switch for the app-link documents. It serves
/.well-known/apple-app-site-association and /.well-known/assetlinks.json from this
server, which is what iOS Universal Links and Android App Links need during onboarding
tests. Off by default, and it needs the DEMO_IOS_* / DEMO_ANDROID_* values below.
- Generate the signing key and its certificate if needed:
openssl genrsa -out private-key.pem 2048
openssl req -new -x509 -key private-key.pem -out client-cert.pem -days 3650openssl asks for a subject. CAS reads none of it, so answer however suits you or pass
-subj to skip the questions. -days is worth setting: the default is 30 days.
CAS verifies your signed authorization requests (JAR, RFC 9101) against an X.509
certificate registered on your client, so client-cert.pem is what onboarding needs. Send
the certificate rather than the public key on its own.
Keep private-key.pem on the server and put it into .env as one escaped line. This prints
it in the form .env wants, with literal \n rather than real line breaks:
awk 'NF {sub(/\r/,""); printf "%s\\n",$0;}' private-key.pemRSA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"To check the key in .env and the certificate you sent are a pair, these must match:
openssl x509 -in client-cert.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256
openssl pkey -in private-key.pem -pubout -outform der | openssl dgst -sha256- Install and run:
npm install
npm startFor a watch-mode restart while editing, use npm run dev.
- Verify health:
curl http://localhost:3000/healthPOST /oauth/parPOST /oauth/tokenPOST /oauth/token/refresh(only whenDEMO_UNAUTHENTICATED_TOKEN_ROUTES=true)POST /oauth/token/revoke(only whenDEMO_UNAUTHENTICATED_TOKEN_ROUTES=true)GET /health
The sample apps are not the only way to exercise this server. A REST client can
run every step except the one that needs a person: PKCE and state generation,
POST /oauth/par, and POST /oauth/token. What it cannot do is produce the
authorization code, which only exists once someone authenticates in KRDPASS.
npm run catcher closes that gap. It starts a second process on port 3001 that
listens at the path of your registered redirect URI, which is where KRDPASS
sends the browser after sign-in. It renders the code and state on a plain
page and parks them in memory; GET /_krdpass/demo/last-callback returns them
as JSON:
It is a separate process on purpose, and it imports nothing from this server. This server is
the part integrators copy, and nothing in it should hand out an authorization code without
authentication. The catcher does not read .env either: it is the one component meant to be
reachable from the internet, so it never loads the client secret or the signing key.
Configure it on its own command line, for example CATCHER_PORT=3001 npm run catcher.
{ "pending": false, "code": "...", "state": "...", "iss": "...", "receivedAt": 1758326400000 }The JSON route hands a capture out once. A second read answers
{ "pending": true }, as does a capture older than AUTH_TRANSACTION_TTL_MS.
That is deliberate: a leftover code from an abandoned attempt must not be
exchanged by accident. Loading the page does not consume the capture.
Two things have to be true for the redirect to arrive:
- Your registered redirect URI must resolve to the catcher. It is an HTTPS URL
registered during onboarding, and the catcher binds to
127.0.0.1, so a local run needs a tunnel whose hostname is that registered host, pointed at the catcher's port rather than this server's. - No app on the phone may claim that host. An installed sample app takes the
redirect through Universal Links or App Links, fails its own
statecheck because the transaction belongs to your REST client, and the catcher never sees it.
A ready-made Postman collection for this is in ../postman.
POST /oauth/token/refreshandPOST /oauth/token/revokeare unauthenticated in this reference. There is no session, cookie, bearer check, or CSRF protection in front of either. Anyone who can reach them can post any refresh token or token and this server will attachCLIENT_SECRETand act on it at CAS. Both routes are registered only whenDEMO_UNAUTHENTICATED_TOKEN_ROUTES=trueis set.- The callback catcher is unauthenticated. Anyone who can reach it can read the last captured authorization code. That code alone buys an attacker nothing, because the exchange also needs the PKCE
code_verifierand theCLIENT_SECRET, but it is still a credential sitting in memory behind no auth. It runs only when you start it, never as part of this server. - In-memory transaction storage is capped and expires entries to limit local-dev growth. It is intentionally not suitable for production, restarts, horizontal scaling, or audit retention.
- Default bind host is
127.0.0.1for local development safety. - The
ALLOWED_REDIRECT_HOSTSallowlist is required and fails closed. An empty or unset allowlist rejects everyredirectUrirather than allowing any HTTPS host, and the server refuses to start without the variable.
- Root guide:
../README.md - Integration guide:
../docs/INTEGRATION.md - Sample apps:
../android,../ios,../flutter,../react-native,../react-native-bare