Google sign-in and Workspace setup

Status: checked against official Google documentation on November 6, 2026. The hosted pilot implements Google-only portal sign-in and a separate, optional Google Workspace administrator-authorization flow. Provider responses are covered by mocked tests; neither flow has been tested with real Google credentials. The client ID and client secret are still absent, so portal sign-in is unavailable until you configure them. Directory synchronization, automatic extension identity enrollment, policy writes, and certificate provisioning are not implemented; adding scopes does not enable those features by itself.

The app is hosted on ChatGPT Sites infrastructure, but ChatGPT is not the portal's login provider. A school may later choose Google Workspace or Skyward as its roster source. That choice is separate from Google portal sign-in.

1. Create the Google Cloud application

• Create a Google Cloud project owned by the organization that operates Blodco.
• Basic portal sign-in requests only openid email; it does not require Admin SDK Directory or Chrome Policy permissions. Enable Admin SDK API only if the school later chooses the Google Workspace roster connection. Enable Chrome Policy API only for the future optional managed-extension/policy integration.
• Configure Google Auth Platform branding, support contact, audience, and Data Access scopes. Use an External app for independent customer districts; an Internal app is limited to the project's own Google Workspace organization. Start with test users. Sensitive scopes and external production use can require Google's verification process.
• Verify control of blodco.org. Supply the actual application homepage, privacy notice, terms, and support contact. District review and a truthful production privacy policy must precede a student rollout; a consent checkbox is not Google verification or a district agreement.
• Create one OAuth client of type Web application. Add both exact authorized redirect URIs below to that client:

- https://protect.blodco.org/api/auth/google/callback — Google portal sign-in, requesting only openid email.

- https://protect.blodco.org/api/google/callback — the later, optional Workspace administrator connection, requesting read-only directory access after school-admin consent.

• The two callbacks are implemented but require the same Google client credentials before real use. Do not use a ChatGPT sign-in callback as either Google callback. For this server-side flow, adding a JavaScript origin is not a substitute for adding the exact redirect URIs.
• Keep the client secret in the hosted application's secret store as BLODCO_GOOGLE_CLIENT_SECRET; store the client ID as BLODCO_GOOGLE_CLIENT_ID. Never put it in the extension, source repository, blocked URL, or a chat message. The client ID is not secret.

Official instructions: web-server OAuth, configure consent, Chrome Policy setup.

2. Portal sign-in first; optional roster access later

At the portal's sign-in screen, request only openid email. Do not request Workspace administrator or Chrome Policy scopes there. Google sign-in verifies an account; it does not authorize roster access or prove school membership.

The configured super administrator is matched to BLODCO_OWNER_EMAIL and then pinned to Google's verified stable sub. Other users must match an existing assigned account or redeem an unused, unexpired invitation whose server-assigned email matches their verified Google email. There is no arbitrary public account registration and no role promotion from a client-supplied email. Portal sessions use secure HttpOnly cookies; access-key sign-in forms are not part of the portal.

After sign-in and school privacy/terms acceptance, a school administrator can select Google Workspace as the roster provider and start the separate administrator consent flow. A school selecting Skyward does not need Workspace directory scopes; see SKYWARD_SETUP.md. Request only what the implemented feature needs. These are separate grants; do not ask for all of them merely because they are available.

The consenting account must also have the relevant Workspace administrator privileges. An OAuth scope does not grant an ordinary user administrator privileges. Each independent district must authorize its own tenant connection. Store the verified Google customer ID, administrator identity, authorized scopes, and explicit OU/group-to-school mappings. Do not guess a school from an email suffix.

The portal sign-in and optional Workspace connection use separate anti-CSRF state, secure state cookies, PKCE, and server-side code exchange. Portal identity is verified with Google and bound to server-authorized accounts; Workspace credentials are encrypted at rest. Production still needs complete token lifecycle, incremental grants, audit operations, and strict tenant isolation. Google tokens must not be sent to students. The current single-school snapshot backend must be replaced or isolated before multiple districts are connected. Start the optional Workspace connection only after portal sign-in on protect.blodco.org, select the Google Workspace roster provider, accept the pilot notice, and use a Workspace administrator test account. The current Workspace flow requests only the two directory read scopes shown above, not the optional group, OU, or Chrome policy scopes.

Official reference: Directory authorization scopes.

3. Optional: install the same extension for managed students and teachers

Google OAuth's consent dialog does not have a universal "force extension" option. A future Deploy extension step can explain the requested policy change, obtain a separate administrator confirmation, and perform the supported Chrome Policy write.

• Request https://www.googleapis.com/auth/chrome.management.policy only for policy changes. The separate https://www.googleapis.com/auth/chrome.management.policy.readonly scope cannot install extensions.
• Use a real, stable Chrome Web Store extension ID. The current ZIP is an unpacked development extension, not a published/unlisted Web Store listing.
• Read the applicable schema and existing policy before writing. Google's app-policy example uses chrome.users.apps.InstallType, appInstallType: "FORCED", an orgunits/<id> target, and an app_id target key of chrome:<extension-id> with customers.policies.orgunits.batchModify.
• Choose the intended student/teacher OUs or groups and show the exact target and change before applying it. Confirm licensing, platform support, and that Chrome profiles/devices are managed by that organization. This cannot silently manage arbitrary personal browsers.
• Use the one extension's managed configuration or authenticated enrollment to provide the correct server and district assignment. Policy/configuration updates do not require new extension code; extension-code or permission changes still follow the normal Web Store update process.

Official references: policy authorization/setup, app installation examples, batchModify, Chrome enterprise policies.

4. Automatic student identity has limits

Chrome's identity.getProfileUserInfo() can return the primary signed-in profile's email and obfuscated Google account ID if the extension declares identity.email; otherwise the result is empty. It is not the account of whichever Google page is open and does not guarantee that a personal or unsigned-in browser has a school identity.

Use profile information as a hint, not proof sent from an untrusted client. The future backend must validate Google identity and tenant/roster membership, then issue a device-bound enrollment credential. Use managed profile deployment and explicit assignment to reduce student linking steps. Never promote a role from a client-supplied email. The current extension uses enrollment codes and does not request Google identity permissions.

Official reference: Chrome identity API.

5. Certificates are a separate device-management project

There is no single "certificate scope" that creates a private key and enrolls every student's device. Certificate purpose and platform determine the mechanism.

Chrome Policy has customers.policies.networks.defineCertificate, authorized with https://www.googleapis.com/auth/chrome.management.policy, for defining a supplied certificate at an OU. That operation does not create a certificate authority, issue a unique client identity certificate/key per device, or enroll an unmanaged Windows device. Trusted network/root certificates and client identity certificates have different roles.

For device identity, design the key generation, enrollment proof, CA/SCEP or other managed provisioning, private-key protection, renewal, revocation, and removal workflow first. Use the district's supported ChromeOS/Windows/MDM infrastructure. Do not distribute a shared private key or install a root CA merely to identify a user. The current pilot issues bearer enrollment credentials, not certificates.

Official references: defineCertificate, Chrome policy network examples.

6. Before authorizing real student data

Verify directory synchronization and role mappings in a test district; tenant isolation; revocation; extension deployment and uninstall behavior; accurate observation indicators; chat retention and access controls; and the published privacy/terms disclosures. Directory data may support account creation and assignment, while chat/activity data has additional classroom purposes that need separate, truthful disclosure. "No sale" does not mean hosting providers or authorized school staff never process the data.

Return to Blodco Protect