Setting Up Google Sign-In (OIDC) | Square 9 Documentation Hub

This guide shows how to let users sign in to GlobalForms with their Google account (Google Workspace or personal Gmail) using OpenID Connect (OIDC).

Note: This feature requires GlobalForms version 10.17.1 or greater.

Before you begin

You will need:

A Google account that can create projects in the Google Cloud Console.
The public URL of your GlobalForms server, for example https://forms.example.com.
Access to edit the GlobalForms server configuration files (config/*.json) and restart the service.
A GlobalForms user resource whose submissions contain each user's Google email address. Google can only sign in people who already have a matching GlobalForms user record.

Part 1: Create the OAuth client in Google

1. Select or create a project

Go to https://console.cloud.google.com/.
Use the project picker at the top of the page to select an existing project or choose New Project.

Open APIs & Services → OAuth consent screen (in newer consoles: Google Auth Platform → Branding).
Choose the User type:
- Internal: only users in your Google Workspace organization can sign in (recommended for company use).
- External: any Google account can attempt to sign in.
Enter the app name, support email, and developer contact email, then save.
Make sure the scopes openid, email, and profile are included. These are the default basic scopes and need no extra approval.

3. Create the client ID

Open APIs & Services → Credentials (or Google Auth Platform → Clients).
Click Create Credentials → OAuth client ID.
Set Application type to Web application.
Give it a name, such as GlobalForms.
Under Authorized redirect URIs, click Add URI and enter your GlobalForms callback URL: https://forms.example.com/oidc/callback
Click Create.

The redirect URI must match exactly what you put in the GlobalForms configuration (Part 2), including https, host name, port, and path.

4. Record your credentials

Google displays a Client ID and Client secret. Copy both. Treat the secret like a password: don't email it or store it in shared documents.

You will also use Google's issuer URL: https://accounts.google.com

Part 2: Configure GlobalForms

1. Edit the server configuration

In your GlobalForms config/*.json file, add or update the top-level oidc block:

JSON

"oidc": {
  "issuer": "https://accounts.google.com",
  "clientId": "<Client ID from Google>",
  "clientSecret": "<Client secret from Google>",
  "redirectUrl": "https://forms.example.com/oidc/callback",
  "resources": [],
  "usernameField": "email",
  "claimField": "email",
  "scopes": "openid email profile",
  "responseMode": "query",
  "prompt": "",
  "stateTimeout": 300,
  "returnUrl": ""
}

Setting	What to enter
`issuer`	`https://accounts.google.com`
`clientId`	The Client ID from Google (required)
`clientSecret`	The Client secret from Google (required)
`redirectUrl`	The exact redirect URI you registered in Google (required)
`usernameField`	The field in your GlobalForms user submissions that holds the email address (default `email`)
`claimField`	The Google claim used to find the user (default `email`)
`scopes`	Leave as `openid email profile`
`returnUrl`	Optional. The page users are sent to after login

Only issuer, clientId, clientSecret, and redirectUrl are required. Other values use sensible defaults.

2. Restart GlobalForms

Restart the GlobalForms service so it picks up the new configuration.

GlobalForms starts the Google sign-in when a login form runs the OIDC Login action.

In GlobalForms, open your login form (for example user/login) in the form builder.
Add a button labeled Sign in with Google (or OIDC Login). Set its custom button logic to:
```
data.name="oidc";
data.password="oidc";
data.oidc=true
```
Open the form's Actions tab and add the OIDC Login action.
In Resources, select the user resource(s) GlobalForms should search for the signing-in user.
Set the action to run only when the OIDC button was used (oidc is true), and keep the standard Login action for when it is not. This lets both sign-in methods coexist.
Save the form.

Part 4: Make sure users can be matched

After Google confirms who the user is, GlobalForms looks for a submission in the selected resource(s) where the usernameField equals the Google claimField value. By default, that means:

The email on the GlobalForms user record must exactly match the user's Google account email.

If no match is found, sign-in fails. Create or update user records before asking people to sign in.

Open your GlobalForms login page in a private/incognito window.
Click Sign in with Google.
Choose a Google account and approve access.
You should be returned to GlobalForms, signed in as the matching user.

Troubleshooting

Symptom	Likely cause and fix
Google shows `redirect_uri_mismatch`	The redirect URI in Google doesn't exactly match `redirectUrl` in GlobalForms. Compare protocol, host, port, and path.
Google shows `access_denied` or "app not verified"	For External apps in testing mode, add the user under OAuth consent screen → Test users, or publish the app.
`invalid_client`	Client ID or secret is wrong or has stray spaces. Re-copy from Google.
Sign-in completes but the user isn't logged in	No user submission matches. Check `usernameField`/`claimField` and that the email is spelled identically.
Clicking the button does nothing	The OIDC Login action isn't on the form, or no Resource is selected in the action.
Login takes too long and fails	The sign-in must finish within `stateTimeout` (default 300 seconds). Start again.
Wrong Google account is used automatically	Set `prompt` to `select_account` to always show the account chooser.

Security notes

Use Internal user type if all your users are in one Google Workspace.
NEVER run production workloads in GlobalForms without HTTPS. Sign-in tokens and user data travel between the browser and the server, and without HTTPS they can be intercepted. Google also requires HTTPS redirect URIs for production apps (plain http is only accepted for localhost).