Skip to content

Latest commit

 

History

History
191 lines (144 loc) · 9.85 KB

README.md

File metadata and controls

191 lines (144 loc) · 9.85 KB

KRDPASS Server Reference (Node.js)

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

Important Scope

This is a reference implementation, not a production-ready service.

  • Keep CLIENT_SECRET and 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.1 for local development safety.

Dependencies

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.

Prerequisites

  • Node.js 24+ (what CI builds on, and what engines requires)
  • Onboarding-approved credentials from KRDPASS

Onboarding

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.

Step-by-Step Setup

  1. Create local env file:
cp .env.example .env
  1. 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.

  1. 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 3650

openssl 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.pem
RSA_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
  1. Install and run:
npm install
npm start

For a watch-mode restart while editing, use npm run dev.

  1. Verify health:
curl http://localhost:3000/health

API Endpoints

  • POST /oauth/par
  • POST /oauth/token
  • POST /oauth/token/refresh (only when DEMO_UNAUTHENTICATED_TOKEN_ROUTES=true)
  • POST /oauth/token/revoke (only when DEMO_UNAUTHENTICATED_TOKEN_ROUTES=true)
  • GET /health

Driving the flow from a REST client

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 state check because the transaction belongs to your REST client, and the catcher never sees it.

A ready-made Postman collection for this is in ../postman.

Security and Policy Notes

  • POST /oauth/token/refresh and POST /oauth/token/revoke are 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 attach CLIENT_SECRET and act on it at CAS. Both routes are registered only when DEMO_UNAUTHENTICATED_TOKEN_ROUTES=true is 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_verifier and the CLIENT_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.1 for local development safety.
  • The ALLOWED_REDIRECT_HOSTS allowlist is required and fails closed. An empty or unset allowlist rejects every redirectUri rather than allowing any HTTPS host, and the server refuses to start without the variable.

Related Docs

  • Root guide: ../README.md
  • Integration guide: ../docs/INTEGRATION.md
  • Sample apps: ../android, ../ios, ../flutter, ../react-native, ../react-native-bare