Skip to main content
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 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. 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:

​
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

​
Sources