If you have not completed initial onboarding, start with the Onboarding guide first. Your designated admin must accept the WorkOS invitation before SSO can be configured.
Where setup happens
SSO configuration spans two interfaces:| Interface | What you do there |
|---|---|
| WorkOS dashboard | Configure your IdP connection (SAML/OIDC credentials, redirect URIs, certificates) |
| Cline dashboard (app.cline.bot) | Sign in, verify SSO works, and manage your organization |
Configuring your IdP connection in WorkOS
Open the WorkOS dashboard
Open the WorkOS invitation email sent to your designated admin during onboarding and follow the link to your organization’s WorkOS dashboard.
Add an IdP connection
- In the WorkOS dashboard, go to AuthKit → Connections.
- Click Add Connection.
- Select your identity provider from the list.
Okta
SAML 2.0 or OIDC. Follow the WorkOS Okta guide for the required app settings and attribute mappings.
Microsoft Entra ID (Azure AD)
SAML 2.0 or OIDC. You will need your Entra tenant ID, client ID, and client secret.
Google Workspace
SAML 2.0. Requires a Google Workspace admin account to create the SAML app.
Generic SAML / OIDC
Use for Keycloak or any other SAML 2.0 or OIDC-compatible provider not listed above.
Complete provider-specific configuration
WorkOS displays provider-specific instructions and required fields after you select your IdP. The configuration details vary by provider but generally include:For the exact fields and screenshots for each provider, follow the WorkOS SSO documentation.
- SAML
- OIDC
- SP Entity ID: Provided by WorkOS — enter this in your IdP’s SAML app.
- ACS URL (Assertion Consumer Service URL): Provided by WorkOS — enter this as the redirect/callback URL in your IdP.
- IdP SSO URL: Your IdP’s SAML endpoint — enter this in WorkOS.
- IdP Certificate: Your IdP’s signing certificate — upload or paste into WorkOS.
- Attribute mappings: Map your IdP’s user attributes (email, first name, last name) to the fields WorkOS expects.
Keycloak
Keycloak is not listed as a named provider in WorkOS, but it is fully supported as a Generic SAML or Generic OIDC connection. Use the Keycloak realm’s SAML or OIDC metadata to fill in the required WorkOS fields.Verifying the SSO connection
After saving the connection in WorkOS:- Navigate to app.cline.bot and attempt an SSO sign-in.
- You are redirected to your IdP’s login page.
- Authenticate with valid credentials.
- Confirm you are redirected back to Cline and your account details are correct.
Troubleshooting
Redirect URI mismatch
Redirect URI mismatch
The redirect or callback URL configured in your IdP must exactly match what WorkOS provided during setup (including protocol, domain, and path). A single character difference causes this error.Fix: Copy the ACS URL or Redirect URI directly from the WorkOS dashboard and paste it into your IdP without modification.
SAML certificate errors
SAML certificate errors
An expired or incorrect certificate causes authentication failures.Fix: Download the current signing certificate from your IdP and re-upload it to WorkOS. Verify the certificate expiry date in your IdP.
Attribute mapping failures
Attribute mapping failures
If users are created without a name or email, or with an incorrect role, the IdP is not sending the expected attributes.Fix: In WorkOS, verify that the attribute mappings for email, first name, and last name match the attribute names your IdP sends in the SAML assertion or OIDC token.
Connection shows as inactive
Connection shows as inactive
WorkOS marks a connection inactive if it cannot reach your IdP’s metadata endpoint or the credentials are invalid.Fix: Verify that the issuer URL (OIDC) or IdP SSO URL (SAML) is reachable from the public internet, and that the client secret or certificate has not expired.