> For the complete documentation index, see [llms.txt](https://docs.silkline.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkline.ai/configuration/sso-configuration/google-workspace.md).

# Google Workspace

Configure a Google Workspace OIDC web application, register the Silkline callback, and test sign-in

## Overview

**Time to complete:** about 15 minutes

**What this does:** This configuration allows your users to login to Silkline using their Google Workspace account.

{% hint style="info" %}
Start with a setup link from **Settings → Single sign-on**. Open the link, choose **Google Workspace**, and use the callback shown on its setup page. Your organization admin can share the link with your IdP administrator. See [Self-service SSO setup](https://docs.silkline.ai/configuration/sso-configuration/self-service-sso.md).
{% endhint %}

## Steps

{% stepper %}
{% step %}

#### Register App

Open a Google Cloud project managed by your organization, then open **Google Auth Platform**. If it is not configured, select **Get started**, provide the app name and support/developer contacts, and have an authorized owner review the required Google API Services User Data Policy.

Choose the audience deliberately:

* **Internal** limits authorization to the project's parent Google Cloud organization. This option requires a project associated with a Cloud organization.
* **External** allows other Google accounts, subject to app status and Workspace policies. Silkline still checks the returned email against its verified organization domains.

Under **Clients → Create client**, select **Web application**. The legacy **APIs & Services → Credentials** entry also links to OAuth client setup. Register your organization's exact callback under **Authorized redirect URIs**:

Production:

* **Authorized redirect URIs**
  * `https://auth.silkline.ai/realms/silkline/broker/<org-id>/endpoint`

Test / Gov:

* **Authorized redirect URIs**
  * `https://dev-auth-gov.silkline.ai/realms/silkline/broker/<org-id>/endpoint`

{% hint style="info" %}
`<org-id>` is specific to your organization. Generate a setup link from **Settings → Single sign-on**, then copy the full callback from the setup page.
{% endhint %}

Silkline uses Google's server-side authorization-code flow. Authorized JavaScript origins are not required for this connection. See Google's [web-server OAuth guide](https://developers.google.com/identity/protocols/oauth2/web-server).

Copy the Client ID and save the client secret securely when Google creates it. The full secret is shown only at creation; the masked display is not the value to enter. If the value is unavailable, create a replacement secret for that client and update the Silkline connection through a new setup link. See Google's [OAuth client management](https://support.google.com/cloud/answer/15549257?hl=en).

Silkline requests only `openid profile email`. Google's **External / Testing** mode has an exception for these basic identity scopes: a test-user entry, unverified-app warning, and seven-day authorization expiry do not apply when only this scope family is requested. Additional scopes change those rules. Internal audience and Workspace app-access policies still apply. See Google's [app audience guidance](https://support.google.com/cloud/answer/15549945?hl=en).

Use a company account whose returned email is on one of your verified Silkline domains. Ask the Workspace admin to review an `admin_policy_enforced` denial; do not request unrelated Google API access to repair sign-in.
{% endstep %}

{% step %}

#### Connect the identity provider

Return to the setup page and enter the Client ID, Client secret, and Workspace domain. Enter a plain domain such as `example.com`, without a URL scheme or email address.

The Workspace domain field does not restrict Google account selection. The current connection does not forward that hint to Google, so choose the intended company account manually. The returned email must match Silkline's verified domains. This check does not validate Google's signed `hd` Workspace-membership claim; an email suffix alone is not proof of Workspace organization membership. If that proof is required, contact Silkline support and review the Internal audience restriction. Google documents the distinction between the [domain hint and token claim](https://developers.google.com/identity/openid-connect/openid-connect).

Select **Connect identity provider**, then test sign-in.
{% endstep %}

{% step %}

#### Test SSO Configuration

Open [Silkline](https://app.silkline.ai/landing) in a fresh browser session, choose the intended company Google account, and complete the required consent and verification. Confirm that the dashboard opens with the intended account and organization.

A connected setup page means the connection settings were saved. The setup preflight uses a grant Google does not support for this Web client, so even fabricated credentials can reach that page. Only a real user sign-in tests the client secret, callback, Google access policy, and returned identity together. If an incorrect configuration consumed the link, issue a new link to correct it.

For `invalid_client`, `redirect_uri_mismatch`, policy errors, or an email-domain denial, see [Troubleshooting](#troubleshooting).
{% endstep %}
{% endstepper %}

## Troubleshooting

For setup-link, browser-session, and shared account/domain errors, see [shared SSO troubleshooting](https://docs.silkline.ai/configuration/sso-configuration/troubleshooting.md).

| Error or symptom                                                                       | Check and common solution                                                                                                                                                                                                                                                                                       |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_client` with `The OAuth client was not found`                                 | Recopy the Client ID from the intended Google Cloud project's **Web application** OAuth client. A saved Silkline connection does not prove that Google recognizes that client.                                                                                                                                  |
| `invalid_client` at the token endpoint                                                 | Check the client ID and active secret from the same Web client. Save the full secret when created; Google does not reveal it again after the creation dialog closes. Replace an unavailable or invalid secret securely, then use a fresh Silkline setup link.                                                   |
| `redirect_uri_mismatch`                                                                | Compare the actual request's complete callback with that client's **Authorized redirect URIs**, including scheme, case, path, and trailing slash. Authorized JavaScript origins are not callback registrations.                                                                                                 |
| `Unexpected error when authenticating with identity provider`                          | This is a generic broker error. Ask support for the underlying Google token response. If it is HTTP 401 `invalid_client` / `The provided client secret is invalid`, correct the client secret through a fresh setup link. Other underlying errors need their own diagnosis.                                     |
| `invalid_grant` during callback/code exchange                                          | Start one fresh login and complete it in the same browser. Do not replay a callback or reuse an authorization code. Support should inspect the full description, code redemption, and matching redirect context; this broad code does not establish a bad secret.                                               |
| `invalid_grant` during refresh                                                         | Reauthenticate if the refresh grant is expired, revoked, or otherwise invalid. Distinguish this from a newly rejected authorization code before changing the connection.                                                                                                                                        |
| `unsupported_grant_type` / `Invalid grant_type: client_credentials` during setup       | Google's token endpoint does not support the setup probe's grant. The wizard can still save the connection, including incorrect credentials. Complete a real sign-in; do not create a service account or request broader scopes to make this probe succeed.                                                     |
| `unauthorized_client`                                                                  | Identify the request stage and full description. A grant rejected during setup preflight is distinct from user sign-in. For an actual callback failure, confirm a Web OAuth client and ask support to inspect the authorization-code exchange.                                                                  |
| `admin_policy_enforced`                                                                | Ask the Workspace admin to review the OAuth client and requested `openid profile email` scopes under **Security → Access and data control → API controls**. Follow the organization's approved app-access policy; do not grant unrelated Google API access as a generic fix.                                    |
| `org_internal`                                                                         | The account is outside the OAuth project's parent Cloud organization. Use an intended organization account or have the project owner review the authorized audience. Adding a test user does not change an Internal app's audience.                                                                             |
| `access_denied`                                                                        | Inspect the full response. The user may have declined consent, a non-interactive request may lack a usable session/consent, or another access restriction may apply. Start an interactive login and distinguish explicit Workspace policy errors from this broad code.                                          |
| App is **External / Testing**                                                          | With only the basic `openid profile email` scope family, Google's Testing exception removes the test-user-list requirement, unverified-app warning, and seven-day authorization expiry. Check additional scopes, Internal audience, account restrictions, and Workspace policies before blaming Testing status. |
| Google selects an unexpected account                                                   | Choose the intended company account manually. The current connection does not forward the configured Workspace-domain hint to Google. Eligibility is checked against the returned email, not that form field.                                                                                                   |
| Google succeeds but Silkline rejects the email                                         | Check the returned email against the organization's verified domains. An alias, subdomain, or different company domain may need separate verification. The Workspace hint and an email-shaped username do not replace the returned-email check.                                                                 |
| A log shows `password_rejected` / `invalidPasswordMinLengthMessage` after Google login | Identify whether Keycloak is requesting a local password or required action. Support should review the linked identity and expected authentication flow. This message does not mean Google's password policy rejected the account; do not change the Google password to repair a local required action.         |

Google's setup credential preflight uses `client_credentials`; actual sign-in uses the server-side authorization-code flow. A connected setup page is not proof that Google accepted the client credentials. If a bad configuration was saved, a new setup link is required to replace it.

Silkline's current Google connection checks the returned email domain. It does not validate the signed `hd` Workspace-membership claim. Google documents that a domain hint or email suffix alone is not proof of Workspace organization membership. If strict Workspace membership is required, ask support to review that requirement and the OAuth app's Internal audience.

Google can display errors before returning to Silkline, so a missing Keycloak error event does not rule out a Google-side failure. Send the full visible Google error, timestamp, client ID, and callback to support, with session values removed.

Provider references: [Google web-server OAuth](https://developers.google.com/identity/protocols/oauth2/web-server), [OIDC errors](https://developers.google.com/identity/openid-connect/reference), [OpenID Connect claims](https://developers.google.com/identity/openid-connect/openid-connect), [OAuth client management](https://support.google.com/cloud/answer/15549257?hl=en), and [app audience and Testing exception](https://support.google.com/cloud/answer/15549945?hl=en).
