App sign-in library

@groundfloorcloud/app-auth checks, in your backend, that a request comes from a user signed in to your app, and gives your front end its standalone app's sign-in settings. It's for your app's users, not your team.

npm install @groundfloorcloud/app-auth

It's open source under the MIT licence. It needs Node.js 20.19 or later and works with ESM and CommonJS. Its one dependency is jose; the browser entry, @groundfloorcloud/app-auth/browser, doesn't include it.

Check tokens in your backend

import { requireAppUser, verifyAppToken, AppAuthError } from "@groundfloorcloud/app-auth";

app.use("/api", requireAppUser()); // 401 without a valid app token
app.post("/api/posts", requireAppUser({ roles: ["editor"] }), handler); // 403 without the role

try {
  const user = await verifyAppToken(token);
} catch (err) {
  if (err instanceof AppAuthError) res.status(err.status).json({ error: err.code });
}

An app token is accepted only if it's signed with RS256 by a key from the JWKS URL, iss equals the issuer exactly, aud contains the app's client ID, azp equals it (a token without azp is refused), exp hasn't passed (with 30 seconds of clock leeway by default, at most 60; nbf and iat, when present, get the same leeway), typ (when present) is Bearer, sub is present, and there's no x-client-key or x-userid claim. Those claims mark Groundfloor's own Coderunner management and developer tokens, which are refused with wrong_token_type. The keys are cached for 10 minutes and fetched again, at most every 30 seconds, when a token names a key the cache doesn't have.

The user

Any user of the workspace can sign in to any of its apps, so always check roles. With Multi-tenant on, a role applies in every company the user belongs to: filter reads and writes by organization too, or use requireOrganization.

Options

Options you pass win over environment variables.

requireAppUser also takes roles (the user needs at least one), shell: true to check Shell site tokens instead, and onError(err, req) for logging. Never log the token itself.

Environment variables

Groundfloor sets these on a standalone app's running main Service when it deploys, unless you set them yourself, while app sign-in is switched on. They're your backend's runtime environment, not variables in your front end's build. See Find your issuer and client ID.

Errors

AppAuthError has a code and the HTTP status to answer with:

Get sign-in settings in the browser

import { getAppAuthConfig } from "@groundfloorcloud/app-auth/browser";

const cfg = await getAppAuthConfig({ controlPlaneUrl: "https://platform.groundfloor.cloud" });
// { issuer, clientId, realm, redirectUri: "https://<this host>/auth/callback" }, or null

getAppAuthConfig asks Groundfloor for the sign-in settings of the standalone app on the page's own host, and resolves to null when that host has no app sign-in. Pass controlPlaneUrl, for example from your build config. The lookup accepts calls from any web address, so it works on your custom domains. Hand the result to an OpenID Connect library with PKCE; see Sign users in from the browser.

getAppToken() is for Shell apps, once per-app tokens for Shell apps arrive. Until then it throws "not available yet".

Next steps

• Standalone app sign-in — set up sign-in for a standalone app.
• Who can reach your Service — what your backend must check, with a Python example.