> ## Documentation Index
> Fetch the complete documentation index at: https://developers.useqx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO login with Google Workspace

> How the IT team connects Google Workspace to QX: the OAuth client, the company domain, two-step verification and required SSO.

This guide is for the Google Workspace administrator of your company. It shows how to connect Google Workspace to one QX organization. The work has two parts: the IT team creates the OAuth client in Google Cloud, and the owner of the organization configures QX. The [SSO login guide](/en/sso) explains the rules that apply to every identity provider.

## What QX offers

* A person signs in to QX with the SSO login in Google, through the OIDC protocol. QX never sees the password.
* QX accepts only the accounts of the company domain. The owner types the domain in the SSO connection, and QX checks the `hd` claim at each login.
* QX does not receive user provisioning from Google Workspace. Google documents user provisioning only for the apps of its catalog.
* The Google token carries no groups. The role comes from QX: a new person signs in as an operator, and the owner changes the role in **Users**.
* The owner can turn on the e-mail binding. With it, the first SSO login links the person to the QX user with the same e-mail.
* The owner can turn on the creation at the first login. With it, the first SSO login of a person of the domain with no QX user creates an operator.
* The owner turns on required SSO for the whole organization. With the rule on, nobody in the organization signs in with a password, including the owner.
* When the organization requires two-step verification, the person types the code of the QX authenticator app after the login in Google.
* A session that starts with the SSO login expires at the time that the owner chooses, from 1 to 8 hours after the login. It does not extend.
* The owner removes the SSO connection to change the OAuth client or the domain, and then configures a new one.

QX does not offer SAML.

## The order of the work

Do the steps in this order:

1. The IT team creates the OAuth client in Google Cloud.
2. The owner configures the SSO connection in QX.
3. The owner does the login test.
4. The owner enables SSO login.
5. The owner turns on required SSO.

Before you start, check two things:

* The Google account of the owner has the same e-mail as the QX user of the owner.
* The owner knows the domain of the company accounts in Google Workspace, such as `company.com`. The value of `hd` for an account of a secondary domain of the company: not checked against an official source.

## The QX addresses

The owner sees the addresses in **Settings › SSO**, in the box **Addresses for the identity provider**. Each address has a **Copy** button.

| Address in QX | Field in Google |
| - | - |
| Redirect URI | **Authorized redirect URIs**, in the OAuth client |
| Login URL | No field. The person keeps the login URL in the bookmarks of the browser. |

The login URL shows only after the owner saves the SSO connection. The box does not show the user provisioning base URL, because Google Workspace does not use user provisioning. The redirect URI is this:

```text theme={null}
https://app.useqx.com/sso/callback
```

## 1. Create the OAuth client in Google Cloud

Do these steps in the Google Cloud console, in a project of the Google Cloud organization of the company:

1. Set the audience of the app to the user type **Internal**. With this type, Google accepts only the accounts of the organization of the company.
2. Open the **Clients** page and click **Create Client**.
3. Select the type **Web application**.
4. In **Authorized redirect URIs**, paste the QX redirect URI.
5. Click **Create**.
6. Open the client. The client ID and the client secret are at the top of the page. Copy both.

QX asks for the scopes `openid`, `email` and `profile`. An app that only the people of the Google Workspace organization of the company use needs no Google verification.

Give the client ID and the client secret to the owner through a safe channel, such as a password manager.

## 2. Configure the SSO connection in QX

The owner does these steps in QX:

1. Open **Settings › SSO** and click **Configure SSO connection**.
2. Select **Google Workspace** and click **Continue**.
3. In **Identity provider address**, the form shows `https://accounts.google.com`. This address is the same for every company.
4. In **Company domain**, type the domain of the company accounts, such as `company.com`. QX keeps the domain in lower case and without spaces. The domain stays fixed after the owner saves the connection.
5. In **Client ID** and **Client secret**, paste the values of step 1.
6. In **Client authentication**, keep **Basic (client\_secret\_basic)**. Google also accepts **Post (client\_secret\_post)**.
7. In **Two-step verification**, the form shows only **Through the QX authenticator app**. The section **Two-step verification** of this guide explains the option.
8. In **SSO session duration**, select from 1 to 8 hours. The default is 8 hours. Prefer a short duration, as the section **Session duration** explains.
9. If the QX users already exist, select **Link QX users by e-mail**.
10. For the first login to create the user of a new person of the domain, select **Create the user at the first login**.
11. Click **Save SSO connection**. If the login of the owner is older than 15 minutes, QX asks for the password.

The form does not show **Role of the people**, because the role comes from QX. After the save, the box **Addresses for the identity provider** shows the login URL.

A change to the e-mail binding or to the creation at the first login ends the sessions that started with SSO. Make the change outside working hours.

## 3. Do the login test

1. In **Settings › SSO**, the owner clicks **Test login**.
2. QX opens Google. The owner signs in with their own Google Workspace account.
3. QX shows "The login test passed. The SSO connection is verified."

The test links the Google account of the owner to the QX user of the owner. The test needs two things:

* The account belongs to the domain of the connection. With an account of another domain, the test fails with "The account that you used at the identity provider belongs to another company."
* The e-mail of the Google account equals the e-mail of the owner in QX.

## 4. Enable SSO login

1. In **Settings › SSO**, the owner clicks **Enable SSO login**. If the login of the owner is older than 15 minutes, QX asks for the password.
2. A person who is not an owner opens the QX login URL and checks the login.

A person signs in to QX through the login URL. The URL goes to Google and comes back to QX with the person identified. Keep the URL in the bookmarks of the browser. Google documents the shortcut in the app launcher only for a custom SAML app. A shortcut for the QX OIDC app: not checked against an official source.

## 5. Turn on required SSO

1. In **Settings › SSO**, the owner clicks **Turn on required SSO**.
2. The owner reads the warning and clicks **Turn on required SSO** again. If the login of the owner is older than 15 minutes, the warning asks for the password.

Each session that started with a password in the organization ends, including the session of the owner. From then on, each user of the organization signs in with the SSO login.

## Two-step verification

The Google Workspace SSO connection has one option only: **Through the QX authenticator app**. The option applies when the organization requires two-step verification.

* After the login in Google, the person types the code of the QX authenticator app. At the first login, the person sets up the app.
* The person has 15 minutes to finish. After that time, the person signs in again through Google.

A person who signs in with SSO can also set up the authenticator app in **Account security**. Before the setup, QX asks for a login in Google with the same account. Google can accept the session that the person already has in Google, with no new password. To change the app, the person asks another owner or QX support for a reset of the second factor.

Google does not accept a request for a new login. So, when the SSO login is older than 15 minutes, the identity confirmation before a sensitive act asks for the code of the QX authenticator app. The confirmation by code needs an app that the person already set up. A person with no app sets up the app first, in **Account security**.

## Session duration

The owner chooses the SSO session duration in **Edit SSO connection**, from 1 to 8 hours. After that time, the person signs in again through Google. A shorter time also shortens the open sessions, counted from the login. A longer time applies to the next logins only. The identity confirmation does not change the time.

Google does not tell QX when it suspends or deletes a person. The session length rules of Google also do not apply to an app that signs in through OAuth, such as QX. A suspended person loses access to the Google services of the company and keeps the open QX session until the session expires. That Google refuses a new SSO login of this person: not checked against an official source. So choose a short duration.

## How QX treats each person

* QX recognizes the person by the Google `sub`. Google never reuses or changes this identifier.
* QX accepts only an account whose `hd` claim equals the domain of the connection. A personal account with an e-mail of the company domain has no `hd`, and QX refuses it.
* With **Create the user at the first login**, the first login of a person of the domain with no QX user creates an operator. Google must confirm the e-mail, with `email_verified` `true` or `"true"`.
* With **Link QX users by e-mail**, the first login links the person to the user of the organization with the same e-mail, when Google confirms the e-mail. QX never links an owner by e-mail. The owner runs the login test.
* With neither option, QX refuses a person with no link, with "QX did not find your user."
* The owner changes the role in **Users**, and the SSO login does not change the role.
* To deactivate a person, the owner deactivates the user in **Users**. All sessions of the user end at the same moment. A suspension of the person in Google does not deactivate the user in QX.
* After the binding, a new e-mail in Google does not block the SSO login. The user page shows the Google e-mail when it differs from the e-mail in QX.

## Replace the client secret

1. In the Google Cloud console, the IT team opens the OAuth client and creates a new client secret (not checked against an official source).
2. The owner opens **Edit SSO connection**, pastes the new secret into **Client secret** and clicks **Save SSO connection**.

A new client secret ends all sessions that started with SSO in the organization. Make the change outside working hours.

## When Google is down

With required SSO on, nobody signs in to QX while Google is down. The open sessions continue until they expire.

1. If an owner still has an open session, the owner clicks **Turn off required SSO** in **Settings › SSO**. QX asks for no confirmation, so this works while Google is down.
2. If no owner has an open session, ask QX support. Support turns off required SSO and writes the reason in the audit log.
3. A person with no password clicks **Forgot your password?** on the login page and sets a password.
4. When Google is back, the owner clicks **Turn on required SSO**.

The identity confirmation by the code of the authenticator app does not go through Google, so it works while Google is down.

## Remove the SSO connection

To change the OAuth client or the domain, the owner removes the SSO connection and configures a new one. The new connection has another login URL.

1. In **Settings › SSO**, the owner clicks **Remove connection**. If the login of the owner is older than 15 minutes, QX asks for the password or for the identity confirmation.
2. The owner reads the warning and clicks **Remove connection** again.

The removal has these effects:

* The sessions that started with SSO end, including the session of the owner.
* SSO login and required SSO stop. People sign in with a password.
* QX deletes the external identities.
* The users stay in QX. A person who only signed in with SSO creates a password with **Forgot your password?**, on the login page.

If no owner can sign in, ask QX support. Support removes the connection and writes the reason in the audit log.

## Refusal messages

| Message that the person sees | What the IT team checks |
| - | - |
| The time to finish the login ran out. Sign in again through the identity provider. | The person types the code of the QX authenticator app within 15 minutes after the login in Google. |
| Your QX user is an owner. To use the SSO login, run the login test in Settings > SSO. | The owner runs the login test. QX never links an owner by e-mail. |
| Your access to QX is turned off. | The state of the user in **Users**, in QX. |
| QX did not find your user. | The domain of the Google account and the **Company domain** of the connection. The e-mail of the person in Google and in QX. The options **Link QX users by e-mail** and **Create the user at the first login**. |
| The account that you used at the identity provider belongs to another company. | In the login test, the owner signs in with an account of the domain of the connection. |
| The identity provider did not answer. | The Google status. Try again in a few minutes. |
| We could not sign you in with SSO. | The client ID, the client secret, the **Client authentication** and the redirect URI of the OAuth client. |

## Sources

* Google, [OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect).
* Google, [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server).
* Google, [Manage app audience](https://support.google.com/cloud/answer/15549945).
* Google, [When verification is not needed](https://support.google.com/cloud/answer/13464323).
* Google, [Security bundle](https://developers.google.com/identity/siwg/security-bundle).
* Google Workspace, [Find and add unmanaged users](https://knowledge.workspace.google.com/admin/users/find-and-add-unmanaged-users).
* Google Workspace, [About automated user provisioning](https://knowledge.workspace.google.com/admin/users/advanced/about-automated-user-provisioning).
* Google Workspace, [Suspend a user temporarily](https://knowledge.workspace.google.com/admin/users/suspend-a-user-temporarily).
* Google Workspace, [Set session length for Google services](https://knowledge.workspace.google.com/admin/security/set-session-length-for-google-services).
* Google Workspace, [Set up your own custom SAML app](https://knowledge.workspace.google.com/admin/apps/set-up-your-own-custom-saml-app).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.