Guides

Set up Google sign-in

Let people sign in to Telark with their Google account, with or without internet egress from the cluster.

Google sign-in (OIDC) is off by default. Once it is on, anyone with a Google account whose email Google has verified can sign in; a new account starts with the ReadOnly role. You configure it in the dashboard, with no Helm value to change.

You need: a Google Cloud project, the dashboard served on its final HTTPS hostname, and the bootstrap admin's account. Whoever controls sign-in trust can sign in as anyone, so only the bootstrap admin can change these settings: everyone else, Admins on ALL included, sees them read-only.

1. Create the OAuth client in Google Cloud

  1. In Google Cloud Console, open APIs & Services → Credentials.

  2. Choose Create credentials → OAuth client ID, application type Web application.

  3. Under Authorized redirect URIs, add your dashboard's callback URL exactly (scheme, host, port, no trailing slash):

    https://telark.example.com/auth/google/callback
  4. Copy the Client ID. Telark does not use the client secret.

To limit sign-in to your Google Workspace organization, make the OAuth consent screen Internal.

2. Decide where Google's signing keys come from

The auth service verifies each Google ID token against Google's public keys.

  • Fetch them (connected clusters): the auth pod needs egress to Google. Keys refresh automatically.
  • Pin them (air-gapped clusters): paste the JSON served at https://www.googleapis.com/oauth2/v3/certs into the settings. You must paste it again when Google rotates its keys.

3. Turn it on

  1. Open Settings → Authentication.
  2. Turn on Enable single sign-on.
  3. Paste the Client ID.
  4. Leave Fetch signing keys from the provider on, or turn it off and paste the key set into Pinned signing keys (JWK set).
  5. Save.

Settings, Authentication: the single sign-on and self-registration toggles

The auth service refuses a configuration that could not sign anyone in (no client ID, no key source, or keys it cannot reach or parse). The change applies at the next sign-in, with no restart.

The settings are stored under spec.oidc of the TelarkConfig named default. A pinned key set is stored in the Secret telark-oidc-trust-secret. Both are protected by the CRD write guard, so change them in the dashboard, not with kubectl. With a GitOps render, create the Secret yourself as in Install Telark for production.

4. Check that it works

  1. Sign out.
  2. On the sign-in page you should see Continue with Google.
  3. Sign in with a Google account.

You should land on the dashboard. Settings → Security → Active sessions lists the new session.

On the first Google sign-in, Telark looks for an account with the same email. With none, it creates a new ReadOnly account. If that account has no sign-in method yet, it attaches the Google identity to it. It refuses the sign-in when the account is the bootstrap admin, which signs in with its passkey only, or already signs in another way; see Troubleshooting.

Give Google users the Admin role

Google sign-in never grants Admin, not even to the bootstrap admin's email. The bootstrap admin enrolls a passkey with break-glass --enroll (see the Quickstart), then grants the Admin role to at least two Google users under Administration, directly or through a group.

Troubleshooting

MessageCause and fix
redirect_uri_mismatch on Google's pageThe OAuth client does not list https://<dashboard-host>/auth/google/callback exactly. Fix it in Google Cloud.
OIDC is not configured (503)Single sign-on is off, the client ID is empty, or no key source is set.
OIDC login requires a verified email addressGoogle has not verified the account's email. Telark refuses unverified emails.
OIDC nonce is invalid or has already been usedThe sign-in took too long or the callback was replayed. Start again.
"Google login failed" with nothing in the auth logsThe dashboard's state check failed. Start and finish the sign-in in the same browser tab.
this email belongs to an account that already signs in another way (409)An account with that email already has a passkey or another identity, so Telark will not attach Google to it.
the bootstrap administrator signs in with a passkey (403)The Google account resolves to the bootstrap admin, which signs in with a passkey only.
only the bootstrap administrator can change how people sign in (403)Only the bootstrap admin can save these settings. Sign in with its passkey.

Auth service logs: kubectl logs -n telark deploy/telark-auth-service | grep -i oidc.

Next