BoxLang πŸš€ A New JVM Dynamic Language Learn More...

BoxExpressAuth

v0.3.0 BoxLang Modules

boxlang-express-auth

Pluggable third-party login for BoxExpress apps: a generic OAuth2 authorization-code core (always PKCE S256), a generic OpenID Connect provider, presets for GitHub, Google, Microsoft, GitLab and Apple, and a test provider for your own specs. Your app decides who a provider identity is; this module runs the flow, guards routes (WebSocket upgrades included), links extra accounts, and keeps the session honest.

  • Requires BoxLang β‰₯ 1.15 and the boxexpress module (0.2.26+; 0.2.27+ to guard WebSockets).
  • Not included: refresh tokens, token storage, an account-linking UI (the route is here, the settings page is yours), password login, API tokens, ID-token algorithms other than RS256/384/512 and ES256/384/512.

Install

box install boxlang-express-auth

Install boxlang-express too, if the app doesn't already have it β€” this module builds its routes with boxExpressRouter() but doesn't install BoxExpress for you. Both land in the app's boxlang_modules/.

Quickstart

app = boxExpress()
app.set( "trust proxy", 1 )

auth = boxExpressAuth( {
	// Required. Map the provider identity to your own user.
	// Return a struct with at least { id }, or null to refuse the login.
	verify: ( identity, tokens, req ) => users.findOrCreateFromIdentity( identity ),
	// Optional. Turns the stored id back into req.user on guarded routes.
	// Without it, req.user is { id }.
	loadUser: ( id ) => users.get( id ),
	successRedirect: "/",          // after login (unless returnTo) and after browser logout
	failureRedirect: "/login",     // gets ?error=<code>
	loginPath: "/login"            // where required() sends anonymous browsers
} )

auth.provider( "github", boxExpressAuthGitHub( {
	clientId: getSystemSetting( "GITHUB_CLIENT_ID" ),
	clientSecret: getSystemSetting( "GITHUB_CLIENT_SECRET" ),
	callbackUrl: "https://tracker.example.com/auth/github/callback",
	scopes: [ "read:user", "user:email" ]     // the default
} ) )

app.use( boxExpressSession( { resave: false, saveUninitialized: false } ) )   // required, and first
app.use( boxExpressUrlencoded() )
app.use( boxExpressCsrf() )                       // optional; guards POST /auth/logout too
app.use( "/auth", auth.routes() )

app.get( "/dashboard", auth.required(), ( req, res ) => res.json( { user: req.user } ) )
app.get( "/", auth.optional(), ( req, res ) => res.render( "home", { user: req.user ?: "" } ) )

Link to /auth/github to sign in, or /auth/github?returnTo=/projects/7 to come back somewhere specific. examples/server.bxs is a complete runnable demo (GITHUB_CLIENT_ID=… GITHUB_CLIENT_SECRET=… boxlang examples/server.bxs).

Routes

Mounted wherever you app.use() the router β€” the callback URLs you register with providers have to point at the same place.

Route
GET /auth/:provider Starts a login. ?returnTo= takes a relative path only.
GET /auth/:provider/callback Where the provider sends the user back.
POST /auth/:provider/callback Only for providers that come back with a form post (Apple). Answers 303 to the GET callback; see Apple. Otherwise 404.
POST /auth/:provider/link A signed-in user attaching another provider account. Only with a link option; see Linking accounts.
POST /auth/logout Destroys the session. Redirects to successRedirect when Accept includes text/html, otherwise 204. If the user signed in through an OIDC provider with postLogoutRedirectUrl, it sends them on to the issuer's logout instead (below). There is no GET logout β€” a link or an <img> on another site must not be able to sign people out. Use a form.

An unknown provider name is a 404.

Guards

  • auth.required() β€” passes logged-in requests with req.user set. An anonymous request whose Accept includes text/html is redirected to loginPath?returnTo=<the original URL>; anything else gets 401 { error: true, code: "unauthenticated" }. Point loginPath at /auth/github to skip a login page when GitHub is your only provider.
  • auth.optional() β€” sets req.user if logged in, never blocks. Fine to mount globally; loadUser still runs once per request.

If loadUser returns null (the account was deleted), the request is treated as anonymous and the stale id is cleared from the session.

Both work as WebSocket upgrade middleware (BoxExpress 0.2.27+). Pass the same session middleware instance you gave app.use(), then the guard:

sessions = boxExpressSession()
app.use( sessions )

app.ws( "/live", ( connection, req ) => {
	connection.onMessage( ( text ) => feed.publish( req.user.id, text ) )
}, { use: [ sessions, auth.required() ] } )

A signed-in user's socket opens with req.user set. Anyone else gets a plain 401 β€” never the login redirect, whatever the upgrade's Accept says, since a socket can't follow one.

What happens on the callback

  1. The pending login is removed from the session β€” whatever happens next, that state can't be used again.
  2. state is compared, in constant time, with the one minted at the start; it must also be under 10 minutes old (stateTtlSeconds).
  3. The code is exchanged (with the PKCE verifier), then the profile fetched.
  4. verify( identity, tokens, req ) runs. Null, or no id, refuses the login.
  5. The session is regenerated (new id, old one deleted β€” no session fixation), then req.session.auth.userId is set.
  6. Redirect to returnTo, or successRedirect.

Provider tokens are handed to verify() and then dropped: they're never written to the session or logged. If your app needs one later (say, to call the GitHub API for repositories), store it yourself β€” encrypted β€” in verify(). tokens is { accessToken, tokenType, scope }.

If verify() or loadUser() throws, that goes to your error handler as a 500 β€” it means your code or your database failed, not the login.

Failure codes

failureRedirect gets ?error= with one of these, and nothing else β€” a provider's own error text is never echoed:

Code Meaning
access_denied The user declined on the provider's consent screen.
provider_error The provider sent back any other error or no code β€” or, on GET /auth/:provider, an OIDC issuer's discovery document couldn't be read.
invalid_state State missing, wrong, already used, or no login was pending in this session.
expired_state Took longer than 10 minutes.
token_exchange_failed The provider refused the code (GitHub: HTTP 200 with an error body).
profile_failed The profile couldn't be read, or an OIDC ID token failed validation (the log says which check).
login_denied verify() returned null.
link_denied A link was refused: link() returned false or null, or the user who started it is no longer the one signed in. Sent to linkFailureRedirect.

The reason is logged server-side ([BoxExpressAuth] github login failed: …), never with codes, tokens or the client secret.

Errors you'll see while wiring it up

Type When
BoxExpressAuth.SessionRequired A request reached the auth routes or a guard without boxExpressSession() in front.
BoxExpressAuth.InvalidConfig No verify function, or loadUser or link isn't one.
BoxExpressAuth.InvalidProvider Missing clientId/clientSecret/callbackUrl, a relative callbackUrl, a bad provider name, an authorizeParams key the flow owns, or (OIDC) a missing or plain-http issuer or no openid scope.
BoxExpressAuth.DuplicateProvider Two providers registered under one name.

Options

Option Default
verify β€”Required. ( identity, tokens, req ) => user struct or null
loadUser none( id ) => user struct or null
successRedirect "/"
failureRedirect "/login" ?error= (or &error=) is appended
loginPath "/login"
sessionKey "auth" Key under req.session this module owns
stateTtlSeconds 600
link none( identity, user, tokens, req ) => true/false. Turns on POST /auth/:provider/link
linkRedirect successRedirect After a link (unless returnTo)
linkFailureRedirect failureRedirect After a failed link, with ?error=

Every provider takes clientId, clientSecret, callbackUrl (all required), scopes, authorizeParams (extra authorize-URL parameters such as { prompt: "select_account" }; the flow's own β€” state, nonce, scope, redirect_uri, PKCE β€” can't be overridden), userAgent (default boxlang-express-auth) and httpClient. The OIDC providers (generic, Google, Microsoft, GitLab) add the options in their sections below.

Registering a GitHub OAuth app

  1. GitHub β†’ Settings β†’ Developer settings β†’ OAuth Apps β†’ New OAuth App (or the same under an organization's settings).
  2. Homepage URL: your app, e.g. https://tracker.example.com.
  3. Authorization callback URL: exactly the provider's callbackUrl β€” the mount path plus /github/callback: https://tracker.example.com/auth/github/callback. For local development, register a second OAuth app with http://localhost:3000/auth/github/callback rather than widening the production one.
  4. Leave Enable Device Flow off.
  5. Copy the Client ID, generate a client secret, and put both in the environment (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET). Never commit them.

GitHub supports PKCE for OAuth apps (S256 only); this module always sends it. The default scopes are read:user and user:email β€” the latter is what lets the provider see private addresses and whether they're verified.

Google

auth.provider( "google", boxExpressAuthGoogle( {
	clientId: getSystemSetting( "GOOGLE_CLIENT_ID" ),
	clientSecret: getSystemSetting( "GOOGLE_CLIENT_SECRET" ),
	callbackUrl: "https://tracker.example.com/auth/google/callback",
	hostedDomain: "example.com"        // optional β€” see below
} ) )

Link to /auth/google. Scopes default to openid email profile. The identity's id is Google's sub (a long numeric string); username is always "" because Google has none; avatarUrl is the picture claim.

hostedDomain limits sign-in to one Google Workspace domain. It's sent as Google's hd parameter β€” which only pre-selects the account and can be removed by the user β€” and then enforced against the hd claim inside the signed ID token. "*" accepts any Workspace account but no consumer @gmail.com one. Don't restrict by the email's domain instead: Google says to use hd for that.

Registering a Google OAuth client

  1. Google Cloud console β†’ pick or create a project β†’ APIs & Services β†’ OAuth consent screen. Choose Internal (Workspace users only) or External, add the openid, email and profile scopes, and add test users while the app is in testing.
  2. APIs & Services β†’ Credentials β†’ Create credentials β†’ OAuth client ID, application type Web application.
  3. Authorized redirect URIs: exactly the provider's callbackUrl β€” https://tracker.example.com/auth/google/callback. Add http://localhost:3000/auth/google/callback to a separate dev client rather than the production one.
  4. Put the client ID and secret in the environment (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET).

Any OpenID Connect provider (Keycloak, Authelia, …)

auth.provider( "keycloak", boxExpressAuthOIDC( {
	name: "keycloak",
	issuer: "https://sso.example.com/realms/tracker",
	clientId: getSystemSetting( "OIDC_CLIENT_ID" ),
	clientSecret: getSystemSetting( "OIDC_CLIENT_SECRET" ),
	callbackUrl: "https://tracker.example.com/auth/keycloak/callback"
} ) )

The provider reads <issuer>/.well-known/openid-configuration on the first login (not at startup, so the app boots while the IdP is down), sends a nonce with every login, and validates the ID token before verify() sees anything:

  • the signature, against the issuer's JWKS β€” RS256/384/512 with an RSA key of at least 2048 bits, or ES256/384/512 with a P-256/P-384/P-521 key; none and HMAC are refused. The key set is cached and refetched once when a token names an unknown kid (a key rotation), at most every jwksMinRefreshSeconds (default 60).
  • iss is the configured issuer, and the discovery document names that same issuer.
  • aud contains clientId; azp, when present (or when there are several audiences), is clientId.
  • exp hasn't passed and iat isn't in the future, give or take clockSkewSeconds (default 60).
  • nonce is the one minted for this login.

The identity's id is sub; username is preferred_username; emailVerified is email_verified (the string "true" counts). When the ID token has no email, the userinfo endpoint is read as well β€” its sub must match, and it never overrides a signed ID-token claim.

Option Default
issuer β€”Required. https, or http on localhost/127.0.0.1/[::1] only
name "oidc" Register under the same name you use here
scopes [ "openid", "email", "profile" ] Must include openid
userinfo "auto" "auto" (when the ID token lacks an email), "always", "never"
clockSkewSeconds 60
jwksMinRefreshSeconds 60
acceptedIssuers [ issuer ] Extra iss spellings (Google uses this)
algorithms RS256/384/512, ES256/384/512Narrow it, never widen it
postLogoutRedirectUrl noneTurns on logout at the issuer
logoutIdTokenHint false Keep the ID token in the session to send as id_token_hint
authorizeUrl, tokenUrl, jwksUri, userinfoUrl, endSessionUrl discoveredGive the first three to skip discovery

tokens passed to verify() includes idToken for OIDC providers. It isn't stored, unless logoutIdTokenHint asks for it.

Keycloak: create a confidential client (Client authentication on, Standard flow on), set the redirect URI, and use https://<host>/realms/<realm> as the issuer. Authelia: register the client under identity_providers.oidc.clients with authorization_policy, redirect_uris, scopes: [ openid, email, profile ] and require_pkce: true, pkce_challenge_method: S256; the issuer is Authelia's own URL. Authelia often leaves email out of the ID token, which is what userinfo: "auto" covers.

Logging out at the issuer

POST /auth/logout ends the session in your app; the user is still signed in at Keycloak, Authelia or Microsoft, and the next login goes straight through. For single sign-on that's rarely what "Sign out" should mean. Give the provider a postLogoutRedirectUrl (registered with the issuer as a post-logout redirect URI) and logout continues at the issuer's end_session_endpoint:

auth.provider( "keycloak", boxExpressAuthOIDC( {
	…,
	postLogoutRedirectUrl: "https://tracker.example.com/"
} ) )
  • A form post (Accept: text/html) gets a 303 to <end_session_endpoint>?client_id=…&post_logout_redirect_uri=….
  • A fetch() gets 200 { logoutUrl } β€” set location.href to it.
  • The local session is destroyed first either way. If the issuer has no end_session_endpoint (GitLab, Google), or discovery fails, it's a normal local logout.

Without an id_token_hint, most issuers show a "do you want to sign out?" page. logoutIdTokenHint: true keeps the login's ID token in the session (req.session.auth.logout.idToken) so it can be sent, and the issuer skips the question. It's off by default because it's the one token this module would otherwise never store: an ID token isn't an API credential, but it is a signed statement of who the user is, sitting in your session store.

Microsoft

auth.provider( "microsoft", boxExpressAuthMicrosoft( {
	clientId: getSystemSetting( "MICROSOFT_CLIENT_ID" ),
	clientSecret: getSystemSetting( "MICROSOFT_CLIENT_SECRET" ),
	callbackUrl: "https://tracker.example.com/auth/microsoft/callback",
	tenant: "organizations"
} ) )

Entra ID (the v2.0 endpoints), as an OIDC preset. tenant decides who can sign in:

tenant
"common" (default)Any work/school account, and personal Microsoft accounts
"organizations" Work/school accounts only
"consumers" Personal Microsoft accounts only
a tenant id or domainThat one tenant ("72f988bf-…" or "contoso.onmicrosoft.com")

The multi-tenant endpoints publish a templated issuer (https://login.microsoftonline.com/{tenantid}/v2.0) and every token carries its own tenant's iss. The preset checks iss against the token's tid claim and tid against tenant; with allowedTenants: [ "<tenant id>", … ], only those tenants get in β€” how a multi-tenant SaaS app limits sign-in to the customers it has onboarded.

identity.emailVerified is always false. Microsoft doesn't verify the email claim (a tenant admin can set it to anything), so it must never decide who someone is. identity.id is sub; identity.tenantId is the tid; identity.username is preferred_username (usually the UPN, which can change). Userinfo is off (userinfo: "never") β€” the ID token already has everything userinfo would add.

Register the app under Microsoft Entra ID β†’ App registrations: add a Web redirect URI of <origin>/auth/microsoft/callback (and, for logout at Microsoft, your postLogoutRedirectUrl as a redirect URI too), and create a client secret under Certificates & secrets. The Supported account types choice has to agree with tenant.

GitLab

auth.provider( "gitlab", boxExpressAuthGitLab( {
	clientId: getSystemSetting( "GITLAB_CLIENT_ID" ),
	clientSecret: getSystemSetting( "GITLAB_CLIENT_SECRET" ),
	callbackUrl: "https://tracker.example.com/auth/gitlab/callback",
	baseUrl: "https://gitlab.com"      // or your self-managed instance
} ) )

GitLab is an OIDC issuer at its own base URL, so this is the generic provider with that issuer. identity.username is the GitLab username; emailVerified comes from GitLab's email_verified. Create the application under User settings β†’ Applications (or an instance-wide one under Admin β†’ Applications) with the openid, email and profile scopes. GitLab has no end_session_endpoint, so logout is local only.

Apple

auth.provider( "apple", boxExpressAuthApple( {
	clientId: getSystemSetting( "APPLE_SERVICES_ID" ),        // the Services ID, e.g. com.example.tracker.web
	teamId: getSystemSetting( "APPLE_TEAM_ID" ),
	keyId: getSystemSetting( "APPLE_KEY_ID" ),
	privateKey: fileRead( getSystemSetting( "APPLE_PRIVATE_KEY_PATH" ) ),   // the .p8 file
	callbackUrl: "https://tracker.example.com/auth/apple/callback"
} ) )

app.use( boxExpressUrlencoded() )
app.use( boxExpressSession( { resave: false, saveUninitialized: false } ) )
app.use( "/auth", auth.formPostRoutes() )      // before CSRF β€” see below
app.use( boxExpressCsrf() )
app.use( "/auth", auth.routes() )

There's no clientSecret: Apple's is a JWT signed (ES256) with your key, and the provider mints a fresh one, valid for five minutes, for each code exchange. The key never leaves the process, and errors never quote it.

The callback is a POST. When you ask for name or email (the default scopes), Apple sends the user back with a form post from appleid.apple.com. Two things follow:

  • A SameSite=Lax session cookie isn't sent on a cross-site POST, so the login couldn't be matched to its session there. POST /auth/apple/callback doesn't try: it answers 303 to GET /auth/apple/callback?code=…&state=…, a top-level navigation the cookie is sent with, and the usual checks run there. Keep sameSite: "Lax"; don't loosen it to None for Apple's sake.
  • boxExpressCsrf() would refuse that POST (no token, no session). Mount auth.formPostRoutes() β€” only that one route β€” at the same path before the CSRF middleware, as above, and boxExpressUrlencoded() before both. Without the body parser the POST arrives empty and the login fails with provider_error (the log says why).

With scopes: [] Apple uses a plain GET callback and none of that applies β€” but then there's no email in the ID token.

The name comes once. Apple never puts the name in the ID token; it posts it as a user field on the user's first authorization of your app only. The provider holds it in memory, keyed by a hash of that login's state, until the GET callback hands it to verify() as identity.name. Save it then β€” later logins have name: "". With several app instances and no sticky sessions the GET can land elsewhere and the name is lost (the login still works); the user can get Apple to send it again by removing your app under Sign in with Apple in their Apple account settings. The email in that user field is ignored; identity.email comes from the signed ID token.

identity.id is Apple's sub, stable for your developer team. identity.email may be a private relay address (…@privaterelay.appleid.com) β€” identity.isPrivateEmail says so β€” and emailVerified is Apple's email_verified. Apple has no userinfo endpoint and no end_session_endpoint, so logout is local only.

To register: in the Apple developer account create an App ID with Sign in with Apple, then a Services ID (its identifier is clientId) with your domain and the return URL <origin>/auth/apple/callback β€” Apple requires https and a real domain, so local development needs a tunnel. Under Keys, create a key with Sign in with Apple; download the .p8 once (privateKey) and note its Key ID (keyId) and your Team ID (teamId).

Behind a proxy, and cookies

The callback is a top-level GET from github.com back to your site, so the session cookie must be sent on a cross-site navigation: the default sameSite: "Lax" works; sameSite: "Strict" makes every login fail with invalid_state . Set secure: true on the session cookie once TLS is in front, and app.set( "trust proxy", … ) as BoxExpress's docs describe.

With a database-backed session store, keep boxExpressSession()'s resave: false, saveUninitialized: false.

Consider rate-limiting the auth routes: app.use( "/auth", boxExpressRateLimit( { max: 30, windowMs: 60000 } ) ) before mounting them.

Storing users: key on the provider id, never on email

The identity passed to verify():

{ provider: "github", id: "583231", email: "[email protected]", emailVerified: true,
  name: "The Octocat", username: "octocat", avatarUrl: "https://…", raw: { …the provider's profile… } }

id is the provider's stable user id, as a string β€” for GitHub, the numeric id, not the login (logins can be renamed, and then claimed by someone else); for Google, Microsoft, GitLab, Apple and OIDC, the sub claim. Store identities in their own table, linked to your users:

CREATE TABLE users (
	id           INT IDENTITY PRIMARY KEY,
	display_name NVARCHAR(200) NOT NULL,
	email        NVARCHAR(320) NULL,
	created_at   DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME()
);

CREATE TABLE user_identities (
	id               INT IDENTITY PRIMARY KEY,
	user_id          INT NOT NULL REFERENCES users ( id ),
	provider         VARCHAR(32) NOT NULL,
	provider_user_id VARCHAR(255) NOT NULL,
	email            NVARCHAR(320) NULL,
	email_verified   BIT NOT NULL DEFAULT 0,
	created_at       DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME(),
	last_login_at    DATETIME2 NULL,
	CONSTRAINT uq_user_identities UNIQUE ( provider, provider_user_id )
);

In verify(): look up ( identity.provider, identity.id ). Found β†’ that's the user. Not found β†’ create a user and an identity row. Never look a user up by email to decide who someone is: an address can be unverified, reassigned, or typed into another provider by someone else. If you want to attach a new provider to an existing account automatically by email, only do it when identity.emailVerified is true β€” and prefer an explicit "link account" step for a signed-in user β€” next.

Linking accounts

Matching a new provider login to an existing user by email is the shortcut the section above warns against. The safe version is explicit: a user who is already signed in proves they also own the other account.

auth = boxExpressAuth( {
	verify: …,
	loadUser: …,
	link: ( identity, user, tokens, req ) => {
		var owner = identities.find( identity.provider, identity.id )
		if ( !isNull( owner ) && owner.userId != user.id ) {
			return false                 // already someone else's
		}
		identities.attach( user.id, identity )
		return true
	},
	linkRedirect: "/settings/accounts",
	linkFailureRedirect: "/settings/accounts"
} )
<form method="post" action="/auth/google/link">
	<input type="hidden" name="_csrf" value="…req.csrfToken()…">
	<input type="hidden" name="returnTo" value="/settings/accounts">
	<button>Connect Google</button>
</form>

POST /auth/:provider/link runs the same flow as a login β€” same callback URL, same state, PKCE and ID-token checks β€” but the callback calls link( identity, user, tokens, req ) instead of verify(), with user the signed-in user. It doesn't regenerate the session or change who is signed in.

  • It's POST so another site can't start it with a link or an image; keep boxExpressCsrf() in front.
  • Anonymous: 401, or a 303 to loginPath for a browser.
  • If the user signed out, or someone else signed in, between the start and the callback, it's refused with link_denied.
  • Return false (or null) from link() to refuse β€” say, an identity that already belongs to another user. Throws go to your error handler.
  • Without a link option the route is a 404.

Testing your app

boxExpressAuthTestProvider() logs in through the real /auth routes β€” state, PKCE, your verify(), session regeneration β€” as whatever identity a spec names, with no provider account and no network:

testLogin = boxExpressAuthTestProvider( { identity: { id: "u1", email: "[email protected]" } } )
auth.provider( "test", testLogin )      // only when building the app for tests

var login = testLogin.login( app )                              // β†’ { response, location, cookies, started }
expect( app.inject( { url: "/dashboard", cookies: login.cookies } ).statusCode ).toBe( 200 )

testLogin.login( app, { identity: { id: "u2", emailVerified: false }, returnTo: "/settings" } )
testLogin.login( app, { deny: "access_denied" } )               // the user clicked Cancel
testLogin.login( app, { fail: "profile_failed" } )              // or "token_exchange_failed"
testLogin.link( app, { cookies: login.cookies, form: { _csrf: token } } )

Its default identity is { id: "test-user", email: "[email protected]", emailVerified: true, name: "Test User", username: "test" }, merged with the identity you pass. Its callbackUrl defaults to http://localhost/auth/<name>/callback; set it if you mount the routes elsewhere. For a step at a time, approve( location, identity ) and deny( location, error ) turn the Location of GET /auth/test into the callback path to inject.

It can't log anyone in from a browser β€” GET /auth/test redirects to auth.test.invalid, which never resolves, and a code only exists once test code calls approve() β€” but register it only when building the app for tests all the same.

Tests

box install                # testbox + boxlang-express into boxlang_modules/
boxlang setup-tests.bxs    # once per checkout
boxlang run-tests.bxs

Specs drive the app with app.inject(); provider APIs are a FakeHttpClient that fails the test on any unscripted URL, and ID tokens are signed by real RSA and EC keys generated per run. The only sockets any spec opens are on loopback: HttpClientSpec's in-process server, and WebSocketGuardSpec's app (port 38742) for real upgrade requests.

Writing a provider

See docs/providers.md.

License

MIT

Changelog

0.3.0

  • A test provider for apps' own specs (boxExpressAuthTestProvider(), models/providers/TestProvider.bx). login( app, { identity } ) runs the real routes β€” state, PKCE, verify(), session regeneration β€” through app.inject() and hands back the cookies; deny and fail simulate a refusal or a broken provider. Its authorize URL is under .invalid and codes only exist once test code calls approve(), so registering it by mistake doesn't open a login.
  • Logout at the issuer for OIDC providers (RP-initiated logout). With postLogoutRedirectUrl, POST /auth/logout destroys the session and then sends the browser to the discovered end_session_endpoint (a 303, or 200 { logoutUrl } for a fetch()). The ID token is kept for id_token_hint only with logoutIdTokenHint: true, so by default the session still holds no provider token at all. req.session.auth.provider now records which provider a login came through.
  • Microsoft (Entra ID) preset (boxExpressAuthMicrosoft()), with tenant (common, organizations, consumers, a tenant id or domain) and allowedTenants. The multi-tenant endpoints' templated issuer is handled by checking each token's iss against its own tid. The email is never reported as verified: Microsoft doesn't verify it.
  • GitLab preset (boxExpressAuthGitLab()), for gitlab.com or a self-managed baseUrl.
  • Account linking: with a link( identity, user, tokens, req ) option, POST /auth/:provider/link lets a signed-in user attach another provider account. POST only (so it sits behind CSRF protection), same callback and checks as a login, refused with link_denied if the signed-in user changed in between. linkRedirect and linkFailureRedirect options.
  • ES256/ES384/ES512 ID tokens (models/Jwt.bx), verified against EC JWKs on the curve the algorithm names, for issuers that sign with ECDSA.
  • Sign in with Apple (boxExpressAuthApple()). Apple's ID tokens are ordinary RS256; what's different is everything around them:
    • The client secret is an ES256 JWT signed with the team's .p8 key (teamId, keyId, privateKey), minted fresh with a five-minute lifetime for every code exchange.
    • Asking for name or email makes Apple return with a cross-site form POST, which a SameSite=Lax session cookie doesn't ride along on. The new POST /auth/:provider/callback answers it with a 303 to the usual GET callback β€” a top-level navigation, which does carry the cookie β€” so every state, PKCE and ID-token check runs unchanged. Only code, state and error go into that URL.
    • The user's name, which Apple posts once on first authorization and never in the ID token, is held in memory under a hash of the state until the GET callback collects it. The posted email and id_token are ignored in favour of the signed token from the token endpoint.
    • auth.formPostRoutes() mounts just that POST route ahead of boxExpressCsrf(), which would refuse Apple's tokenless POST.
  • Providers can now override clientSecretValue() (what's sent as client_secret) and receive state in fetchProfile()'s context.
  • Guards on WebSocket upgrades: auth.required() in app.ws( path, handler, { use: [ sessions, auth.required() ] } ) (BoxExpress 0.2.27+) answers an anonymous upgrade with a plain 401, never a login redirect, whatever its Accept header says. Covered by a spec against a real listening server.
  • OIDC subclasses can override discoveryIssuerMatches() and tokenIssuerAllowed() for issuers whose iss isn't a fixed string.

0.2.0

  • Google sign-in (models/providers/Google.bx, boxExpressAuthGoogle()), built as a preset of a new generic OpenID Connect provider (models/providers/OIDCProvider.bx, boxExpressAuthOIDC()) rather than a Google-only class: Google needs nearly everything OIDC does (discovery, a nonce, ID-token validation), and the tracker's self-hosted Keycloak and Authelia need exactly the same code.
    • The ID token's signature is checked against the issuer's JWKS even though it arrives straight from the token endpoint, where OIDC Core and Google's docs both allow skipping it. It's cheap, and it means a misrouted or intercepted token endpoint can't mint a login.
    • iss, aud/azp, exp/iat and the nonce are all checked; none and HMAC algorithms and RSA keys under 2048 bits are refused. The discovery document must name the configured issuer, or it could point validation at someone else's keys. Plain http is allowed only for loopback issuers, for local Keycloak/Authelia.
    • The JWKS is cached and refetched once for an unknown kid (how a key rotation shows up), throttled by jwksMinRefreshSeconds.
    • Userinfo is read only when the ID token has no email (Authelia's default), must describe the same sub, and can't override signed claims.
    • Google's hostedDomain is enforced against the signed hd claim, not just sent as the hd parameter: Google documents the parameter as a UI hint a user can strip.
    • Only RS256/RS384/RS512 ID tokens for now (models/Jwt.bx), which covers Google, Keycloak and Authelia defaults.
  • Pending logins and identities are keyed by the name a provider is registered under (models/Auth.bx), not the provider's own name. Two generic OIDC providers share a class; keyed by name, they'd have overwritten each other's pending state.
  • GET /auth/:provider builds the authorize URL before storing anything, and a failure there is a provider_error redirect instead of a 500 β€” an OIDC provider may fetch its discovery document at that point, and an IdP outage shouldn't look like a crash.
  • authorizeParams on every provider passes extra authorize-URL parameters (prompt, login_hint, …). The parameters the flow's security rests on (state, nonce, PKCE, redirect_uri, scope) are refused, so configuration can't quietly weaken it.
  • exchangeCode() also returns idToken when the provider sends one, so verify() can keep it (for RP-initiated logout) β€” it's still never stored by this module.

0.1.0

  • First release: third-party login for BoxExpress apps, built for a developer-facing issue tracker that needs "Sign in with GitHub" now and self-hosted OIDC (Keycloak/Authelia) and Google next.
  • Core (models/Auth.bx, boxExpressAuth()): routes() for GET /:provider, GET /:provider/callback and POST /logout; required()/optional() guards. The app supplies verify() to map an identity to its own user, because only the app knows how its users are stored β€” the module never creates or stores users itself.
  • Security choices, each because the naive version is exploitable:
    • state is 32 CSPRNG bytes, single-use (deleted before it's checked, so a failed attempt spends it too), expires after 10 minutes, and is compared in constant time.
    • PKCE S256 on every login, so an intercepted code is useless without the verifier held in the session.
    • The session is regenerated before the user id is written, so a session id planted before login never becomes an authenticated one.
    • returnTo accepts only relative paths and rejects //, /\, any backslash and any control character. Browsers strip tab/CR/LF from URLs, so /<TAB>/evil.com would otherwise pass a prefix check and resolve as //evil.com.
    • Provider tokens go to verify() and nowhere else: not the session, not the logs. Failure redirects carry only a fixed set of codes, never provider-supplied text.
    • Logout is POST-only, so another site can't sign users out with a link, and it works under boxExpressCsrf().
    • A verify()/loadUser() that throws reaches the app's error handler as a 500 instead of being reported as a failed login, so a database outage isn't mistaken for bad credentials.
  • Providers (models/providers/OAuth2Provider.bx, GitHub.bx, boxExpressAuthGitHub()): the base class owns the authorize URL, code exchange, and option checks, so adding a provider is mostly fetchProfile(). GitHub identities use the numeric id (logins can be renamed and re-registered) and take the email from /user/emails, since /user often has none and never says whether it's verified. The provider interface already takes a nonce so OIDC can be added without changing it.
  • Outbound HTTP is injectable (models/HttpClient.bx, httpClient option): specs run the whole flow against a fake that fails on any unexpected URL, so none of them touch GitHub. The default client treats bx:http's synthetic "502 Connection Failure" as an error rather than a response, since it means nothing answered.

$ box install boxlang-express-auth

No collaborators yet.
 
  • {{ getFullDate("2026-11-15T09:28:21-06:00") }}
  • {{ getFullDate("2026-11-15T14:06:58-06:00") }}
  • 29
  • 8