Identity & access

Sign in with Google or GitHub

Lets users sign in with an existing Google or GitHub account instead of creating a new password.

BetaEngine edition 5f8ea3af

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

  • HTTPGET /auth/v1/authorize?provider=google|github&redirect_to=<url>
  • HTTPGET /auth/v1/callback
  • ConfigKYNETRA_OAUTH_GOOGLE_ID, KYNETRA_OAUTH_GOOGLE_SECRET
  • ConfigKYNETRA_OAUTH_GITHUB_ID, KYNETRA_OAUTH_GITHUB_SECRET
  • ConfigKYNETRA_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

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.