What it does
An authorisation-code flow for Google and GitHub. The server sends the browser to the provider, exchanges the returned code, reads the account email and signs the user in. The client id and secret for each provider are supplied by the deployment through environment variables.
How it works
A GET to /auth/v1/authorize with provider=google or provider=github, and an optional redirect_to, stores a short-lived random state value and redirects the browser to the provider. The state lasts ten minutes and is removed when the callback uses it. The callback address is KYNETRA_PUBLIC_URL followed by /auth/v1/callback, and it must be registered with the provider.
At the callback the server checks the state, exchanges the code for a provider access token, fetches the profile and requires an email address. It then finds or creates a passwordless account with that email in the pool chosen when the flow began: the platform pool, or the project pool recorded in the state. A new account takes the viewer role, or admin when it is the first in an empty pool. The browser is redirected to redirect_to, or to the public URL, with the access token, refresh token, token type and lifetime in the URL fragment.
A platform account that has MFA enabled, or whose organisation requires it, does not receive tokens at the redirect. It receives a pending-token challenge in the fragment and completes sign-in through the MFA step.
If the provider reports an error, returns no code, or the state is missing, unknown or expired, the callback is refused with an error and no account is created. A project that is suspended, being deprovisioned or purged refuses the flow, and creating an account in a project pool goes through the same status and quota checks as any other sign-up. Provider endpoints can be overridden for testing with KYNETRA_OAUTH_GOOGLE_AUTH_URL, KYNETRA_OAUTH_GOOGLE_TOKEN_URL and KYNETRA_OAUTH_GOOGLE_USERINFO_URL, and the same three names with GITHUB in place of GOOGLE.
Where you reach it
- HTTP
GET /auth/v1/authorize?provider=google|github&redirect_to=<url> - HTTP
GET /auth/v1/callback - Config
KYNETRA_OAUTH_GOOGLE_ID, KYNETRA_OAUTH_GOOGLE_SECRET - Config
KYNETRA_OAUTH_GITHUB_ID, KYNETRA_OAUTH_GITHUB_SECRET - Config
KYNETRA_PUBLIC_URL
Limits
- The provider round trip is not covered by automated tests in the engine repository, which is why this capability is beta.
- Google and GitHub are the supported providers. Other OpenID Connect providers are not available.
- Tokens are delivered in the URL fragment of the redirect. Use a redirect target you control, served over HTTPS, and clear the fragment after reading it.
- Accounts are matched by the email address the provider returns, so enable providers whose email addresses you trust to be verified, and no others.
- The callback address defaults to a local address unless KYNETRA_PUBLIC_URL is set.
Evidence
- On this siteAPI reference: authentication endpoints
- TestsNo automated test of the provider round trip exists in the engine repository.
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.