SSO Setup

​

🔐 What is SSO?

Single Sign-On (SSO) lets your team sign in to GC AI using your organization’s existing identity provider (IdP). GC AI supports SSO through WorkOS, which is compatible with any IdP that supports SAML or OIDC protocols.

​

📋 Prerequisites

Before you begin SSO setup:

• You must be an Admin in your GC AI organization
• Your organization must use an IdP that supports SAML or OIDC (e.g. Okta, Azure AD, OneLogin, Google Workspace, JumpCloud)
• You need access to your IdP’s admin console to create a new application
• Domain verification must be completed before SSO can be enabled

You can also invite your IT admin into your organization on a trial seat to complete the SSO setup. Just provide their email to support@gc.ai and we will add them.

​

🌐 Step 1: Verify Your Domain

1. Navigate to Organization Settings.
2. Scroll down to Domain verification.
3. Select Generate Link and open the link. It directs you to the domain verification process.
4. Complete domain verification by following the on-screen instructions.

​

🔗 Step 2: Generate the SSO Configuration Link

1. Navigate back to Organization Settings.
2. Select SSO Setup from the dropdown menu.
3. Select Generate Link and open the link.

​

🏢 Step 3: Select Your Identity Provider

Select your IdP from the list (Okta, Azure AD, OneLogin, etc.) and follow the on-screen instructions to connect it.

​

Custom SAML or OIDC

If your IdP is not listed, select Custom OIDC or Custom SAML depending on the protocol your organization uses. For Custom OIDC:

1. Provide an IdP name.
2. Copy the Redirect URI from the “Create an Application” step and add it to your IdP.
3. Add the required claims to your auth token as shown on screen.
4. Enter your Client ID, Client Secret, and Discovery Endpoint from your IdP.

For Custom SAML:

1. Provide an IdP name.
2. Copy the ACS URL and SP Entity ID from the setup screen into your IdP’s SAML application configuration.
3. Configure the required attribute mappings in your IdP. At minimum, these attributes must be included in the SAML assertion:
   • id - A unique user identifier
   • email - The user’s email address
   • firstName - The user’s first name
   • lastName - The user’s last name
4. Upload your IdP’s metadata XML or manually enter the SSO URL and X.509 certificate.

​

✅ Step 4: Test the Connection

After completing the configuration, select Test Connection to verify everything works. A successful test confirms that your IdP and GC AI can communicate properly. If the test fails, see the troubleshooting section below.

​

🔧 Common Setup Issues

​

SAML Test Connection Fails

If you run a test of your SAML SSO connection and it does not pass, the most common causes are: Missing or incorrect attribute mappings Your IdP must send the required attributes (id, email, firstName, lastName) in the SAML assertion. If any are missing or mapped to the wrong field names, the connection test fails. How to fix:

1. Open your IdP’s admin console and navigate to the GC AI SAML application.
2. Check the attribute statements (sometimes called “attribute mappings” or “parameters”).
3. Verify each required attribute is mapped to the correct user field in your directory.
4. Save and re-run the test.

Incorrect ACS URL or Entity ID If the ACS URL or SP Entity ID in your IdP does not match what GC AI provided during setup, the SAML handshake fails. How to fix:

1. Go back to the SSO configuration link in GC AI and copy the ACS URL and SP Entity ID exactly as shown.
2. Paste them into your IdP’s SAML application settings, replacing any previous values.
3. Save and re-run the test.

Certificate or metadata issues An expired or incorrect X.509 certificate prevents GC AI from validating the SAML response. How to fix:

1. Download a fresh copy of your IdP’s metadata XML or X.509 certificate.
2. Re-upload it in the GC AI SSO configuration.
3. Save and re-run the test.

​

OIDC Test Connection Fails

Invalid Client ID or Client Secret If the credentials entered during setup don’t match what your IdP issued, authentication fails. How to fix:

1. Open your IdP’s admin console and locate the GC AI OIDC application.
2. Copy the Client ID and Client Secret directly from your IdP.
3. Re-enter them in the GC AI SSO configuration.
4. Save and re-run the test.

Incorrect Discovery Endpoint The discovery endpoint URL must point to your IdP’s OpenID Connect discovery document (usually ending in /.well-known/openid-configuration). How to fix:

1. Verify the discovery endpoint URL in your IdP’s documentation.
2. Confirm it is accessible by opening it in a browser. You should see a JSON document.
3. Update the URL in the GC AI SSO configuration and re-run the test.

​

Domain Verification Not Completing

If domain verification stalls or fails:

1. Confirm you added the required DNS TXT record to your domain’s DNS settings.
2. DNS changes can take up to 48 hours to propagate. Wait and try again.
3. Verify the TXT record value matches exactly what GC AI provided (no extra spaces or characters).

​

Still Having Trouble?

If you’ve worked through the steps above and the connection test still fails, email support@gc.ai with:

• Your organization name
• The IdP you are using (e.g. Okta, OneLogin, Azure AD)
• A screenshot of the test result or error message

Our team can review your configuration and help resolve the issue.