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. Save the Google settings 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. Leave “Allow Google sign-in” cleared, fill in “Allowed Google Workspace domains” and press “Save”. “Redirect URI to register in Google Cloud” appears below the form

An organization has one Google connection. Unlike OIDC connections, it has no test stage.

4. Register the redirect URI

1. Copy the displayed https://<host>/api/auth/sso/callback/<connection ID>
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. Allow Google sign-in

1. Select “Allow Google sign-in” and press “Save”. The login screen shows a “Continue 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.

6. Check sign-in

1. An invited member who is not an admin presses “Continue 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.