Skip to main content

Google Workspace single sign-on

This guide walks you through connecting Google Workspace as the identity provider for your Retrievy workspace. Once it is in place, your team signs in with their corporate Google accounts instead of email and password, and you get one place (your Google Admin console) to revoke access when someone leaves.

Plan availability

Single sign-on is available on the Advanced and Build Your Own plans. The Essentials plan does not include SSO. See the plan feature matrix for the full breakdown.

Why Google SSO​

Two reasons. First, you stop maintaining a parallel password list inside Retrievy. Every employee already has a Workspace account, your IT team already runs 2-Step Verification and context-aware access policies there, and offboarding is already a single Admin console suspension. Reusing that machinery for Retrievy logins is faster than reinventing it. Second, when you turn on Enforce SSO Only (covered below), passwords are disabled for the workspace and the only way in is through Google. Stolen Retrievy credentials become a non-event.

Before you start​

You need:

  • A Google Cloud project in the same Google organization as your Workspace, where you hold a role with the OAuth Client ID create permission (Project Owner, Editor, or a custom role with clientauthconfig.clients.create).
  • The OAuth consent screen for that project already set to Internal user type, so only people in your Workspace can authenticate. External consent screens trigger Google's app verification workflow and add weeks of delay; you do not need it for an internal sign-in app.
  • The Retrievy workspace subdomain you log into (for example acme-corp.retrievy.com). You need the exact host because the redirect URI is tenant-specific.
  • The Configure SSO providers and enforcement permission granted to your Retrievy role, under Settings: SSO in the role builder. The default Tenant Admin role already has it.
  • A Retrievy plan that includes SSO (Advanced or Build Your Own).

Allow about 10 minutes. Most of it is clicking through the Google Cloud Console.

Step 1. Create the OAuth client in Google Cloud​

You are creating a Web application OAuth 2.0 Client ID inside your Google Cloud project. Retrievy uses it to start the OIDC sign-in flow against your Workspace.

  1. Sign in to the Google Cloud Console with an account that holds Owner or Editor on the project you want to use.
  2. Pick the project from the top-bar project switcher. If you do not have one yet, create a new project named retrievy-sso. Keep this project dedicated to authentication; do not reuse it for unrelated services.
  3. In the left rail, open APIs & Services, then OAuth consent screen.
  4. Confirm User type is Internal. If you see External, switch it back. Internal is the only setting that limits sign-in to accounts in your Workspace.
  5. On the App information panel, set the App name to something your users will recognise on the consent screen. Retrievy is fine. Fill User support email with a real Workspace alias your team monitors.

You do not need to add any App domain or Authorized domains entries for an internal app. Retrievy's domain is implied once the redirect URI is registered on the client below.

1b. Confirm the OAuth scopes​

Retrievy reads three claims from Google after sign-in: openid (to receive an ID token), email, and profile (to populate the user's name and email in the Team Members list). These three scopes are the standard OpenID Connect defaults, and Google treats them as non-sensitive when the consent screen is Internal, so you do not need to add them to the Scopes table explicitly.

If your organization has tightened the project to require scope pre-registration, add exactly these three on the Scopes panel:

openid
.../auth/userinfo.email
.../auth/userinfo.profile

Do not add any other Google API scope. Retrievy's SSO path is sign-in only. It does not call Gmail, Drive, Directory API, or any other Google surface.

1c. Create the Web application Client ID​

  1. In the left rail, open APIs & Services, then Credentials.
  2. Click + Create Credentials at the top, then pick OAuth client ID.
  3. Application type: Web application. Other types (Desktop, Android, etc.) do not work for a server-side OIDC code flow.
  4. Name: Retrievy SSO. This name only appears inside Google Cloud and is for your own bookkeeping.
  5. Leave Authorized JavaScript origins empty. Retrievy does not call the Google OAuth endpoints from the browser; the code exchange happens server-side.
  6. Leave Authorized redirect URIs empty for now. You will fill it in step 1d so you can paste the exact value Retrievy generates.
  7. Click Create.

Google shows a dialog with the new Client ID and Client secret. Both are long opaque strings. Click the copy button next to each and stash them somewhere safe for a minute. The Client secret can be re-displayed later from the Credentials page, but the Client ID is the more important value to record now.

1d. Register the Retrievy redirect URI​

Retrievy needs to tell Google where to send the user after sign-in. The redirect URI is workspace-specific, so the value is generated for you inside the Retrievy wizard.

  1. In a new browser tab, open Retrievy and go to Settings, then Single Sign-On.
  2. Click Setup SSO.
  3. On the wizard's first step (CORE SELECTION), pick Google Workspace and click Configure Integrations.
  4. On the AUTHENTICATION step, look at the Authorized Redirect URI panel on the right side of the form. The exact URL is shown in a copy-ready box. It looks like https://acme-corp.retrievy.com/tenant-auth/google/callback, with your own subdomain in front. Copy it.

Now switch back to the Google Cloud tab:

  1. On APIs & Services, Credentials, click the Retrievy SSO client in the OAuth 2.0 Client IDs table.
  2. Scroll to Authorized redirect URIs and click + Add URI.
  3. Paste the redirect URI from Retrievy. Do not modify it. The path must match exactly, including the trailing /callback and the tenant-auth segment.
  4. Click Save at the bottom of the page.

Google enforces redirect URI changes after a short propagation delay. If your first test sign-in fails with a redirect mismatch immediately after saving, wait a minute and retry.

Match the URI exactly

A trailing slash, a missing tenant-auth segment, or the wrong subdomain will cause Google to refuse the sign-in with Error 400: redirect_uri_mismatch. Copy the value from Retrievy; do not retype it.

Step 2. Paste the credentials into Retrievy​

You should still have the Retrievy wizard open on the AUTHENTICATION step from earlier. If not: Settings, then Single Sign-On, click Setup SSO, pick Google Workspace, click Configure Integrations.

Fill the two fields on the left side of the wizard:

FieldValue
Client IDThe Client ID from the Google Cloud Credentials page. It ends in .apps.googleusercontent.com.
Client SecretThe Client secret you copied in step 1c. The field masks the value; click the eye icon to verify what you pasted.

Below the credential fields, set the Default User Role. This is the Retrievy role assigned to any new user who signs in through SSO for the first time. Pick from the dropdown. If you select No Default Role, the user is created with no role and an existing Tenant Admin has to assign them one before they can see any module.

Click Authorize Vault at the bottom of the wizard. The wizard saves the settings, closes, and the Single Sign-On page now shows a card titled Google Workspace with a green Connected badge.

Step 3. Verify the sign-in flow​

You verify with a fresh browser session so you are not riding on an existing Retrievy cookie.

  1. Open a private window (Incognito, InPrivate, etc.) and go to https://[your-subdomain].retrievy.com/login.
  2. Click Sign in with Google. The login page shows that button because SSO is configured.
  3. Google prompts you to pick an account and run 2-Step Verification if your Workspace policies require it. Use a Workspace account that already exists in your Retrievy workspace, or any account in your Workspace if you have set a Default User Role and want to test just-in-time provisioning.
  4. After consent, Google redirects back to https://[your-subdomain].retrievy.com/tenant-auth/google/callback, which lands you on the Retrievy dashboard.

Check the user list at Settings, then Team Members. The signed-in user appears with the role you set as the default (or their existing role if the account was already there).

Step 4. Optional: enforce SSO​

Until you flip this switch, users can still sign in with their original Retrievy email and password. SSO is an additional option, not the only option.

To make SSO mandatory for everyone:

  1. On the Single Sign-On page, find the Enforce SSO Only card at the top.
  2. Toggle the switch on. Retrievy shows the success message SSO is now enforced. Passwords disabled.

Once enforced, the email and password fields disappear from the login page for your workspace. Only the Sign in with Google button is shown. Any user without a linked Google account is locked out.

Lock-out risk

Before you enforce SSO, make sure at least one Tenant Admin has signed in once via Google, so their account is linked. If every admin loses access at the same time, recovery requires support intervention. Test the SSO flow end-to-end with at least one admin account before flipping the switch.

You can turn enforcement off later from the same toggle. Disconnecting the Google provider entirely is done with the Disconnect button on the provider card; that action also clears the enforcement flag automatically.

Troubleshooting​

Symptom: Sign-in fails with Error 400: redirect_uri_mismatch. Fix: The redirect URI on the OAuth client does not match the one Retrievy generates. Open the client in APIs & Services, Credentials, and confirm Authorized redirect URIs contains exactly the URL the Retrievy wizard shows in the Authorized Redirect URI panel. Watch for trailing slashes, typos in the subdomain, and missing tenant-auth in the path. Wait a minute after saving for changes to propagate.

Symptom: Sign-in fails with Error 401: invalid_client or Unauthorized. Fix: The Client ID or Client Secret in Retrievy does not match what is in Google Cloud. Open the client in the Credentials page, click Reset secret to generate a new one, then in Retrievy click Disconnect on the Google Workspace card and re-run the wizard with the fresh Client ID and Client Secret.

Symptom: Sign-in fails with Error 403: org_internal or This app is blocked and the user's email is from a different domain. Fix: The OAuth consent screen is set to Internal, which is correct, but the user signing in belongs to a different Google organization. Either add the user as a member of your Workspace, or, if you genuinely need to allow guests, change the consent screen to External and put the app through Google's verification process. Keep it Internal unless you have a hard reason not to.

Symptom: Sign-in completes but Retrievy shows Please use your original login method. Fix: The user account already exists in Retrievy and is locked to a different sign-in method. Each user is bound to the first provider they ever signed in with (email-and-password, Google, or Microsoft). To migrate a user to Google SSO, a Tenant Admin must delete the user from Team Members and re-invite them; their next sign-in via Google will create a fresh, Google-linked account.

Symptom: First-time SSO user gets in but lands on a near-empty dashboard with no modules visible. Fix: The wizard's Default User Role was set to No Default Role, so just-in-time provisioning created the user with no permissions. Open Settings, Team Members, find the new user, and assign a role. Update the wizard's Default User Role so the next user is provisioned correctly.