Actagate
Sign in

For administrators

Set up SSO with Google

This page is for organization owners and admins who want members to sign in to Actagate with their Google account. The deployment that runs Actagate holds one Google OAuth client. On the organization settings screen you only allow sign-in and choose the allowed Google Workspace domains.

The operator who runs Actagate creates the OAuth client and sets the environment variables (steps 1 and 2). The product vendor does not provide a shared OAuth app.

1. Create the OAuth client in Google Cloud

  1. In the Google Cloud console, set up the OAuth consent screen. If only your Google Workspace organization will use it, choose "Internal"
  2. Add the scopes openid, email and profile
  3. Under Credentials, create an OAuth client ID with the application type "Web application". Google shows the client ID and client secret
  4. Leave Authorized redirect URIs empty until step 3 shows the value to enter

Official documentation: Google OpenID Connect

2. Set the environment variables

  1. Set the Web app environment variables GOOGLE_OIDC_CLIENT_ID and GOOGLE_OIDC_CLIENT_SECRET to the values from step 1
  2. Restart the Web app. "Google" appears in the Single sign-on list under Settings > Security

Keep the secret in the deployment's secret store, not in the repository. If either variable is missing, Google does not appear on the settings screen or the login screen. Set WEB_BASE_URL to the public HTTPS origin that users open.

3. Add the Google connection in Actagate

  1. Open Settings > Security (/ws/settings/security). Under Single sign-on, in "Pick a provider to add a connection", open "Google". The Google form opens
  2. Fill in "Allowed Google Workspace domains" and press "Add connection". Google appears under "Connections" marked "Disabled" and "Not tested", with the "Redirect URI to register in Google Cloud"

An organization has one Google connection. Once you add it, "Google" in the provider list reads "Added". Save it, run a connection test, then enable it after the test passes.

4. Register the redirect URI

  1. Copy the https://<host>/api/auth/sso/callback/<connection ID> shown on the connection with the "Copy" button next to it
  2. Paste it into Authorized redirect URIs of the OAuth client in Google Cloud and save. Match the displayed value exactly, including the connection ID

5. Test and activate

  1. Press "Test" on the connection and sign in with an admin account from an allowed domain. Back on the settings screen, confirm the connection reads "Test passed". The test keeps your admin session and does not link a login method
  2. Press "Activate" on the connection. Its status becomes "Active" and the login screen shows a "Sign in with Google" button

Separate the "Allowed Google Workspace domains" with newlines or commas. With domains set, a Google account whose ID token hd (Workspace domain) is not in the list cannot sign in. Personal Gmail accounts have no hd and are rejected too. With the field empty, personal accounts are accepted as well.

To change the allowed domains, edit "Allowed Google Workspace domains" on the connection and press "Save". Run the test again after changing the allowed domains, or the deployment client ID or secret. A disabled connection requires a passing test of its current settings before you can enable it. Existing active connections stay active.

6. Check sign-in

  1. An invited member who is not an admin presses "Sign in with Google" on the login screen and signs in with Google. The Actagate screen opens
  2. Check that an account from a domain you did not allow sees "This Google account’s domain is not allowed."

On the first sign-in, Actagate matches the email address verified by Google against the invited member's email address. From the second sign-in on, the Google sub identifies the person. The account stays the same when the email address changes. Owners and admins sign in with an existing method first, then link Google with "Add Google" under Settings > Login methods.

7. Troubleshooting

  • Google is not in the list: check that both GOOGLE_OIDC_CLIENT_ID and GOOGLE_OIDC_CLIENT_SECRET are set and that the Web app was restarted
  • Google shows redirect_uri_mismatch: check that the authorized redirect URI matches the settings screen exactly
  • "Your Google email address is not verified." (email_unverified): verify the email address in Google, then sign in again
  • "This Google account’s domain is not allowed." (hosted_domain_forbidden): add the domain to "Allowed Google Workspace domains", or sign in with an organization account

Other reason codes are listed in SSO troubleshooting.

Open on docs.actagate.com