# Add students through their school Google accounts

For new deployments without a student portal, use [managed student mode](managed-students.md). The GoogleAutoEnrollment setup below remains available for older deployments and can require a student confirmation; managed student mode never opens that prompt.

If your school uses Google Workspace, ClassGuard can use those student accounts and selected Google Classroom lists. You do not need to enter students one at a time or hand out personal ClassGuard setup codes.

**Your school’s IT person connects Google once.** Teachers only need the school ClassGuard address, their individual staff account, and their saved class list.

## The one-time school setup

1. **Install ClassGuard for students.** IT uses Google Admin, the tool your school already uses to manage Chrome. Choose the student accounts; keep staff accounts separate.
2. **Connect the school’s Google student list.** IT lets ClassGuard read the chosen student accounts and class lists. ClassGuard does not create or change Google accounts or Google Classroom courses.
3. **Turn on school Google sign-in.** This lets ClassGuard confirm which student is using the device. Google may ask the student to sign in or confirm access once.
4. **Review the student list.** In **Student lists**, connect with the administrator account and click **Review Google students**. Check the names and classes, then click **Save Google student list**.
5. **Turn on automatic classroom viewing.** Follow [BROWSER-VIEWING.md](automatic-browser-viewing.md). Students then connect when their teacher starts the saved class, without clicking Join or Share.

Google Admin’s student folders are called **organizational units**, or **OUs**. They decide which accounts belong to students. They are not lesson class lists. Include the real Google Classroom courses, or add classes using [the student spreadsheet](bulk-enrollment.md). Each live class can have up to 30 students.

## What teachers and students do afterward

Administrators assign imported groups to saved classrooms in **Staff & classrooms**. Teachers sign in, open **My classrooms**, and start their assigned class.

Students open Chrome with their school account. ClassGuard tries to handle sign-in automatically. If Google asks for confirmation, students use **Sign in with your school Google account** in the extension’s Student setup page. That is account setup, not a screen-sharing button. Once set up, automatic browser viewing needs no per-class Join or Share action.

## Keeping the list current

Review and save Google updates from **Student lists**. IT can also enable scheduled updates after checking the first list. A successful update removes class access for students no longer included in the selected Google accounts. Failed or empty updates keep the saved list. Records are kept for the school to review rather than automatically deleted.

The remaining instructions are for IT. They include the exact Google permissions and connection settings; teachers do not need to fill these in.

## Exact setup for school IT

1. Establish a supported managed Chrome distribution method with a stable ClassGuard extension ID. The kit contains source for testing, not a published Chrome Web Store listing or signed update service. Use your actual distribution ID in all settings below.
2. Force-install ClassGuard in the student OUs through Google Admin. Configure the extension’s managed `SchoolServerURL` to your school-controlled HTTPS server, `GoogleAutoEnrollment` to `true`, `AutomaticBrowserViewing` to `true`, and `LockConfiguration` to `true` if students must not edit local policies. Select student OUs carefully; keep staff accounts separate. [Google’s current force-install instructions](https://support.google.com/chrome/a/answer/6306504?hl=en).
3. Run `npm ci --omit=dev` inside `classguard-server/` to install Google’s official authentication library. Set up the existing teacher/admin keys, HTTPS, extension origin, and private persistent roster storage as described in README.md.

## Read-only directory and classroom access

Enable Google’s Admin SDK API in your school’s Google Cloud project. Create a service account and authorize domain-wide delegation for only:

```text
https://www.googleapis.com/auth/admin.directory.user.readonly
```

If importing Google Classroom memberships, also enable the Classroom API and authorize:

```text
https://www.googleapis.com/auth/classroom.courses.readonly
https://www.googleapis.com/auth/classroom.rosters.readonly
```

Use a delegated school administrator with access to the selected directory and courses. Keep the service-account key file outside the distribution and any public web directory. The server uses Google’s official `google-auth-library`; it does not write Google accounts, courses, or rosters.

Configure these server environment variables:

| Variable | Value |
| --- | --- |
| `CLASSGUARD_GOOGLE_DOMAIN` | School Workspace domain, such as `students.your-school.example`. |
| `CLASSGUARD_GOOGLE_STUDENT_OUS` | Comma-separated student OU paths, such as `/Students/Middle School,/Students/High School`. Descendants are included; `/` includes every active account in the domain and should be chosen only intentionally. |
| `CLASSGUARD_GOOGLE_SERVICE_ACCOUNT_FILE` | Absolute private service-account JSON file path. |
| `CLASSGUARD_GOOGLE_DELEGATED_ADMIN` | Delegated administrator email for the read-only calls. |
| `CLASSGUARD_GOOGLE_COURSE_IDS` | Optional comma-separated explicit Google Classroom course IDs, up to 100. The delegated administrator must have permission to read each selected course. |
| `CLASSGUARD_GOOGLE_SYNC_MINUTES` | Optional integer 15–1440. Unset/0 leaves sync manual. After a reviewed initial sync, this periodically previews and applies updates while the server runs. |

The directory query reads the configured domain with minimal fields and filters the result to selected student OUs. Suspended and archived users are excluded. Classroom groups use active selected courses; course IDs make their group names distinct. OU placement identifies which accounts are students; it does not itself define lesson-sized class memberships. Import real Classroom courses or assign groups through CSV when needed. The directory fetch has a 100,000-account bound; roster storage has a 100,000-student bound. Live rooms retain the existing 30-student limit.

Read the official [Directory users.list reference](https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list) and [domain-wide delegation guide](https://developers.google.com/identity/protocols/oauth2/service-account) when granting access.

## Verified school sign-in

Create a Google OAuth **Web application** client in your district project. Register this exact redirect URI for the stable extension ID:

```text
https://YOUR-STABLE-EXTENSION-ID.chromiumapp.org/google
```

Configure the consent screen/audience for your district and permit the app’s `openid email profile` sign-in scopes through the school’s Google policy. Apply the relevant Google age/access restrictions for student accounts. The app requests these identity scopes only; roster API permissions are separately granted to the server’s service account.

Set on the server:

| Variable | Value |
| --- | --- |
| `CLASSGUARD_GOOGLE_CLIENT_ID` | OAuth client ID. |
| `CLASSGUARD_GOOGLE_CLIENT_SECRET` | OAuth client secret, kept on the server. |
| `CLASSGUARD_GOOGLE_EXTENSION_IDS` | Comma-separated real stable extension IDs authorized for redirects. |

No client secret, service-account key, staff key, or admin key belongs in Chrome managed policy. The extension’s `identity`/`identity.email` permissions support the Google flow and a profile-email hint. The hint alone never proves identity. The server exchanges the authorization code, verifies Google’s signed ID token with the official library, and checks audience, issuer, expiry, nonce, hosted domain, verified email, immutable Google account ID, and current synced student membership. PKCE and one-use state protect the exchange. An email typed into a form cannot enroll a student.

With managed auto-enrollment enabled, the extension tries a non-interactive Google sign-in on installation/startup and renews when needed. Silent sign-in requires Google session/consent and district policy to permit it. If interaction is necessary, the student selects **Sign in with your school Google account** on the extension’s Student setup page. It may show Google’s normal account/consent flow. No personal ClassGuard code is needed. This is not a promise of zero prompts on every device.

Google device credentials last up to one hour, stay in Chrome session storage, are cleared from the device on browser exit/account sign-in changes, and are renewed through Google. The server holds their hashed tokens only in memory; a restart requires re-enrollment. The manual code route retains its separate local-storage behavior. Enrollment makes the device eligible for administrator-controlled browser previews when AutomaticBrowserViewing is enabled and a teacher starts its roster class. No per-class Join or Share action is required for browser previews.

Official references: [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect), [Chrome identity API](https://developer.chrome.com/docs/extensions/reference/api/identity).

## Preview and apply

Open **Student lists**, connect with the private administrator key, and select **Review Google students**. Review the active count, created/updated rows, class groups, and disabled count, then **Save Google student list**. Existing CSV entries remain. Google records are matched by their immutable ID and preserved across email changes. Matching CSV records can be linked to the imported Google identity. Google-managed memberships replace their prior Google memberships while manually assigned groups are retained.

A successful sync disables Google accounts missing from the selected active student set and revokes future enrollment; current live roster memberships removed by that sync are ended. Records are retained with a disabled flag for operator review, rather than deleted. No automatic retention purge is implemented. Old CSV-only records are not disabled by Google sync. Deleted/inactive courses remove their Google group assignments on a successful sync.

Failed, incomplete, empty, or stale syncs do not replace the saved roster. Automatic sync refuses to disable more than 20% of previously active Google students at once; review and manually apply such a change. The initial sync should be reviewed manually. Google credentials never appear in the admin UI or source download.

## Validation and remaining deployment work

Tests used 1,200 synthetic directory accounts and mocked Google API/token exchanges. They verify pagination, OU filtering, Classroom groups, identity checks, one-use state, PKCE, renewal, and disabled-account rejection. A browser test exercised the actual preview/apply interface against a synthetic directory adapter.

No real district Google tenant, delegation, OAuth consent flow, managed Chromebook, Chrome Web Store deployment, or 1,200-device live rollout was connected in this workspace. Your district must finish that configuration and test it on managed test accounts before deployment. The public ClassGuard.org site distributes the kit; rosters and credentials belong on your school server.

## Automatic browser viewing

After enrollment, managed devices can join teacher-started roster classes and show browser previews automatically, without a student Share action. Set SchoolServerURL and AutomaticBrowserViewing in the extension managed policy; the teacher selects a roster group. See [BROWSER-VIEWING.md](automatic-browser-viewing.md).

## No student portal

For managed Google Chrome profiles, enable [managed student mode](managed-students.md). IT preapproves the Google connection and force-deploys the extension; student identity is verified against the active primary Chrome profile. No setup code, login portal, account picker or consent prompt is opened for students. Classroom viewing notices remain visible. Force installation alone does not configure Google authorization.