Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Single Sign-On (SSO)

Let your team sign in to klink.cloud through your company identity provider using OpenID Connect

Single Sign-On lets your team sign in to klink.cloud with the credentials they already use for work. Instead of a separate klink.cloud password, users authenticate against your company identity provider (IdP) — Okta, Microsoft Entra ID, Google Workspace, Zitadel, or any provider that supports OpenID Connect.

klink.cloud SSO uses OpenID Connect (OIDC) with the Authorization Code flow. Any IdP publishing a standard discovery document (/.well-known/openid-configuration) will work.

Only workspace members with the Owner or Admin role can view or change SSO settings.

How it works

  1. A user enters their work email at the login page.

  2. klink.cloud matches the email domain against your configured connections.

  3. On a match, the user is redirected to your identity provider.

  4. The user authenticates — including any MFA or conditional access you enforce.

  5. Your IdP returns the user to klink.cloud, and they are signed in.

Users never enter a klink.cloud password.

Before you begin

  • Owner or Admin access to your klink.cloud workspace

  • Administrator access to your IdP, with permission to create an OIDC application

  • Your company email domain, e.g. acme.com

  • The klink.cloud redirect URI: https://app.klink.cloud/auth/sso/callback

  • A test user who exists in both your IdP and your klink.cloud workspace

Keep a break-glass admin. Retain at least one administrator who can sign in with email and password, so a misconfiguration or IdP outage cannot lock you out.

Step 1 — Create an OIDC application in your IdP

Create a new application with these settings:

Setting
Value

Application type

Web application (confidential client)

Grant type

Authorization Code

Sign-in redirect URI

https://app.klink.cloud/auth/sso/callback

Scopes

openid, email, profile

Then copy three values from your IdP:

  • Discovery URL — your issuer URL plus /.well-known/openid-configuration

  • Client ID

  • Client secret — copy it immediately; most providers show it only once

Provider-specific paths are in Identity provider notes.

Step 2 — Add the connection in klink.cloud

  1. Go to Settings → SSO.

  2. Click Add connection.

  3. Fill in the dialog using the reference below.

  4. Click Create connection.

Field reference

Field
Required
Description

Display name

No

A label to identify this connection, e.g. Acme Okta. Visible to admins only.

OIDC discovery URL

Yes

Your provider's OpenID configuration URL, e.g. https://acme.okta.com/.well-known/openid-configuration. klink.cloud reads all endpoints from this document, so you don't enter them individually.

Client ID

Yes

The client identifier issued by your IdP.

Client secret

Yes

The client secret issued by your IdP. Stored encrypted and never displayed again after saving.

Email domain

No

The domain used to route logins automatically, e.g. acme.com. Users entering an email on this domain are sent to this connection.

Scopes

No

Defaults to openid email profile, which is correct for most deployments. Change only if your IdP needs extra scopes to release the user's email.

Enabled

—

When on, users can sign in through this connection. On by default.

Auto-provision users

—

When on, a member account is created automatically on a user's first successful SSO login. When off, only pre-invited users can sign in. Off by default.

Tip: Test with Auto-provision users off first. Once a pre-invited user can sign in successfully, turn it on if you want hands-off onboarding.

Step 3 — Test

  1. Open a private browser window.

  2. Go to the klink.cloud login page and enter a test user's work email.

  3. Confirm the redirect to your identity provider.

  4. Authenticate, and confirm you land back in klink.cloud signed in as the correct user.

Keep your break-glass admin active until this test passes. If it fails, see Troubleshooting.

Step 4 — Roll out

  1. Turn on Auto-provision users if new staff should be created on first login.

  2. Assign the klink.cloud application to the right groups in your IdP.

  3. Tell your team to sign in with their work email — no password needed.

Email domain and login routing

The Email domain field is what makes SSO automatic. When someone enters an email address at login, klink.cloud matches everything after the @ against your enabled connections.

  • Domain matches an enabled connection → the user is redirected to that identity provider.

  • No match → the user signs in with email and password as normal.

Multiple domains. Create one connection per domain. Each can reuse the same discovery URL, client ID, and client secret if they point at the same IdP application.

Subdomains are not matched automatically — mail.acme.com needs its own connection.

Guests and contractors on outside domains are unaffected and continue using email and password.

Provisioning and access

Auto-provision on. The first time someone authenticates through the connection, klink.cloud creates a member account from the email and name returned by your IdP. No invite needed. Use this when everyone assigned the app in your IdP should have access.

Auto-provision off. Only existing workspace members can sign in. Anyone else authenticates at the IdP but is refused by klink.cloud. Use this when you want to control the member list explicitly.

Removing access. Disabling a user in your IdP blocks future sign-ins immediately. It does not delete their klink.cloud member record or their historical data — to fully offboard someone, also remove them under Settings → Team.

Managing connections

Action
Effect

Edit

Changes apply at the next login. Re-enter the client secret if you rotate it in your IdP.

Disable (toggle Enabled off)

Logins stop immediately; users on that domain fall back to email and password. Configuration is retained.

Delete

Permanently removes the configuration. Member accounts remain, but can no longer sign in via SSO.

Add another

Multiple connections can be active at once — useful for multiple domains or migrating between providers.

Rotating a client secret. Generate the new secret in your IdP, then edit the connection and paste it in. Do this during a maintenance window — sign-ins between the two steps will fail.

Identity provider notes

Okta

Applications → Create App Integration → OIDC – OpenID Connect → Web Application. Add the redirect URI, assign groups, then copy the Client ID and secret from the General tab.

Discovery URL: https://<your-org>.okta.com/.well-known/openid-configuration With a custom authorization server: https://<your-org>.okta.com/oauth2/<server-id>/.well-known/openid-configuration

Microsoft Entra ID (Azure AD)

Microsoft Entra ID → App registrations → New registration. Set the redirect URI type to Web. Copy the Application (client) ID and Directory (tenant) ID from Overview, then create a secret under Certificates & secrets and copy the Value immediately. Confirm openid, email, and profile are granted under API permissions.

Discovery URL: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

Entra ID client secrets expire on a fixed schedule. Set a reminder before the expiry date — an expired secret breaks SSO for everyone on that domain.

Google Workspace

Set the OAuth consent screen to Internal, then Credentials → Create Credentials → OAuth client ID → Web application. Add the redirect URI and copy the Client ID and secret.

Discovery URL: https://accounts.google.com/.well-known/openid-configuration

Zitadel

  1. In the Zitadel Management Console, open an existing Project (or create one), then in the Applications section click New.

  2. Give the application a name, e.g. klink.cloud.

  3. For Type of application, choose Web.

  4. For Authentication Method, choose Code. This issues a client secret, which klink.cloud requires — do not choose PKCE.

  5. Under Redirect URIs, enter https://app.klink.cloud/auth/sso/callback. Optionally add your login page as the Post Logout URI.

  6. Review the summary and click Create. The Client ID and Client Secret are shown once — copy them now. You can regenerate the secret later if you lose it.

  7. Open the application's Token Settings tab and enable User Info inside ID Token. Without this, Zitadel may not return the user's email address and login will fail.

Discovery URL: https://<your-instance>.zitadel.cloud/.well-known/openid-configuration Self-hosted or with a custom domain: https://<your-domain>/.well-known/openid-configuration

You can also find this under URLs in the console's left sidebar, listed as the Discovery Endpoint.

If your Zitadel project requires authorization on authentication, make sure your users are granted access to the project — otherwise they will authenticate successfully but be rejected before returning to klink.cloud.

Other OIDC providers

You need a discovery URL, a client ID, and a client secret for a confidential web client using the Authorization Code grant, with the klink.cloud redirect URI registered. Everything else is read from the discovery document. To check your discovery URL, open it in a browser — you should see JSON containing issuer, authorization_endpoint, token_endpoint, and jwks_uri.

Signing in with SSO (for end users)

  1. Go to the klink.cloud login page.

  2. Enter your work email address.

  3. You'll be redirected to your company sign-in page.

  4. Sign in as you would for any other company application, completing MFA if prompted.

  5. You'll be returned to klink.cloud, signed in.

If you're asked for a klink.cloud password, your email domain may not be configured for SSO — contact your workspace administrator.

Security notes

  • Client secrets are encrypted at rest and never shown again after saving. If you lose one, generate a new secret in your IdP and update the connection.

  • MFA is enforced by your IdP, not by klink.cloud. Configure it in your provider's policies.

  • Email is the identity key. klink.cloud matches users on the email address returned by your IdP. If a user's email changes in your directory, update it in klink.cloud too, or they'll be treated as a new user.

  • Signing out of your IdP does not automatically end an active klink.cloud session.

  • Restrict who can manage SSO. Only Owners and Admins can view or edit connections. Review these role assignments periodically.

Troubleshooting

Symptom
Likely cause
Fix

redirect_uri_mismatch at the IdP

The redirect URI doesn't exactly match

Re-enter https://app.klink.cloud/auth/sso/callback in your IdP. Check for a trailing slash, http vs https, or a typo in the host.

User is asked for a password instead of being redirected

Domain not configured, or connection disabled

Confirm Email domain matches the user's domain exactly and Enabled is on.

"Unable to load provider configuration" when saving

Discovery URL unreachable or invalid

Open the URL in a browser. It must return a valid OpenID configuration document and be publicly reachable — internal-only URLs won't work.

invalid_client

Wrong client ID, or an incorrect or expired secret

Re-copy both values. If the secret was rotated or expired, generate a new one and update the connection.

Authentication succeeds but klink.cloud says no account exists

Auto-provision users is off and the user wasn't invited

Invite the user under Settings → Team, or turn on Auto-provision users.

Login loops back to the sign-in page

The IdP isn't returning an email claim

Confirm the email scope is requested and that your IdP releases the email claim. Some providers require this in claims mapping.

SSO suddenly stopped working for everyone

Expired client secret

Check the secret's expiry in your IdP, generate a new one, and update the connection.

Still stuck? Contact support with the connection's display name, the exact error text, and the approximate time of the failed attempt.

Last updated