Skip to content
English
Submit a Request Self-Help Portal
Sign-In to ESGI Software
  • There are no suggestions because the search field is empty.

Enabling the ESGI & Google Classroom Integration

Overview

This guide is for your Google Workspace Super Administrator. It explains everything you need to do in the Google Admin console (and a few things on the ESGI side) before teachers in your district can sync their classes and rosters with Google Classroom through ESGI.

Allow about 30 minutes for the configuration itself, plus up to 24 hours for Google's policy changes to propagate (usually much faster).

Before You Start

What You Will Need:

  • A Google Workspace super-admin account for your district's domain (e.g. ‘admin@yourdistrict.org’).
  • The ESGI service account "Client ID" - Request this from ESGI support if you do not already have it. It looks like a long numeric string, e.g. ‘123456789012345678901’.
  • Permission to change Classroom and API settings in the Admin console.

What ESGI will need from you:  

  • The email address of the super-admin that should be used for the nightly sync (typically a service mailbox like ‘esgi-sync@yourdistrict.org’, but any super-admin works).
  • Confirmation that the steps below have been completed.

Setup Instructions

Step 1: Confirm that Google Classroom is enabled for your domain

1. Open [Admin console] → Apps → Google Workspace → Classroom.

2. Make sure the service is On for everyone (or at least on for the organizational units that contain your teachers and students).

Note: If Classroom is off, no teacher in your domain can use it — turn it on before continuing.  

Step 2: Allow teachers to create classes

1. Still under Apps → Google Workspace → Classroom, open General settings.

2. Find "Who can create classes" (sometimes labelled "Teacher permissions").

3. Set it to "Verified teachers" (recommended) or "Anyone in this domain".

4. If you chose Verified teachers, you must add each teacher's account to the ‘classroom-teachers@yourdistrict.org’ Google Group (created automatically by Google the first time you turn this setting on). To access this, go to Admin console → Directory → Groups → Classroom-teachers → Add members.

Note: Even after a teacher is in the group, Google does not create their Classroom profile until they log in to https://classroom.google.com at least once. Until that happens, the sync will fail for them with ‘@UserCannotCreateCourse’. Ask each new teacher to sign in once before the first sync runs against their account. 

Step 3: Allow students to be added to classes

This is the setting that most commonly blocks first-time syncs.

1. Apps → Google Workspace → Classroom → Class settings.

2. "Who can join classes in your domain” should be set to "Any Google Workspace user" (recommended). If you want to restrict it, choose "Allowlisted Google Workspace domains" and add every domain that contains students you intend to enroll.

3. "Classes your users can join" — same options. Mirror your choice from the previous setting.

Note: If students are in a different Workspace domain than your teachers, their admin must mirror these settings on their side. The integration cannot bypass policy from a domain that isn't yours.

Note: If you have students with ‘personal’@gmail.com accounts, they will receive an invitation email instead of being added directly. They must click Accept in Google Classroom for enrollment to complete. This is a Google restriction, so nothing on the ESGI side can change it.

Step 4: Grant the ESGI service account API access (Domain-wide delegation)

This is the most important step. It authorizes ESGI's service account to act on behalf of accounts in your domain, scoped to only the APIs listed below.

1. Go to Admin console → Security → Access and data control → API controls.

2. Click "Manage Domain-wide Delegation".

3. Click "Add new".

4. Paste the Client ID ESGI gave you.

5. In OAuth scopes (comma-delimited), paste exactly:

https://www.googleapis.com/auth/classroom.courses

https://www.googleapis.com/auth/classroom.rosters

https://www.googleapis.com/auth/classroom.profile.emails

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

      6. Click Authorize.

What Each Scope Is Used For

Scope

What ESGI Does with It

classroom.courses

Create new Google Classroom courses, rename existing ones, archive courses that no longer exist in ESGI

classroom.rosters

Add and remove students from course rosters

classroom.profile.emails

Read student email addresses when listing rosters so we can match them back to ESGI records

admin.directory.user.readonly

Look up a student's Google account ID by their email when ESGI doesn't already know it

Note: 'admin.directory.user.readonly' is read only. ESGI cannot create, modify, or delete users in your directory. 

Step 5: Enable Google APIs in the ESGI Google Cloud project (one-time, ESGI side)

This is usually handled by ESGI, but for completeness, the project tied to the service account must have these APIs enabled:

  • Google Classroom API
  • Admin SDK API

      You don't need to do anything here unless ESGI support tells you they're seeing ‘SERVICE_DISABLED’ errors.

      Step 6: Give ESGI the admin email for the sync

      In ESGI, open Account Settings → Integrations → Google Classroom:

      1. Enter the admin email that ESGI should impersonate. This account must be a super-admin in the domain set up in Step 4.

      2. (Optional) Schedule a recurring sync to run automatically. If left off, the sync only runs when a district admin clicks "Sync now".

      3. Save.

      Once saved, click "Sync now" to verify that everything works. The first sync may take several minutes depending on the number of teachers and classes.

      Step 7: Have teachers log in to Google Classroom once

      Feel free to copy and paste the message below to send to your teachers who do not use Classroom regularly:

      Before our first ESGI ↔ Google Classroom sync runs, please sign in to classroom.google.com once with your district account. You don't need to do anything once you're in — just signing in is enough. This activates your Classroom profile so ESGI can create your classes for you.

      Note: You can skip this for teachers who already use Classroom regularly.

      What to Expect After the First Sync

      ESGI shows a sync log per district. You'll see one of these statuses:

      Status

      What It Means

      Completed

      Every class, course, and roster change applied successfully.

      CompletedWithErrors

      Most operations succeeded but some students or classes had problems. Open the log file for per-item details.

      StoppedByThreshold

      More than 5 errors in a single run. ESGI stops to avoid making the situation worse. Fix the underlying issue and re-sync.

      InProgress

      The sync is still running.

      Download the sync log from the Google Classroom Integration page. Each line tells you which teacher, course, or student was affected and what happened.

      Troubleshooting Potential Issues

      Sync cannot run for district: admin email is not configured on the sync schedule
      • Cause: No admin email saved in ESGI yet.
      • Fix: Go to ESGI Account Settings → Integrations → Google Classroom, enter the admin email, and save.
      • Cause: The teacher's Google account doesn't have an active Classroom profile yet.
      • Fix: Ask the teacher to sign in to classroom.google.com once, then re-run the sync. This is by design in Google's API — there is no programmatic workaround.
      • Cause: Google's policy doesn't allow the admin to add this student directly. Almost always one of:
        • The student is in a different Workspace domain that hasn't allowlisted yours.
        • The student is on a ‘personal’@gmail.com account.
      • Fix:
        • For cross-domain students: ask the other domain's admin to repeat Step 3 on their side, allowlisting your domain.
        • For personal accounts: there is no fix. The student must accept the invitation in Google Classroom for enrollment to complete. Send them a reminder.
      • Cause: Usually one of three things:
      • Fix: Re-verify Step 4, then re-verify Step 3 on both your and the student's domain.
      • Cause: The Google Classroom course was created by — or its ownership was transferred to — a different Google account than the teacher who owns the class in ESGI. ESGI will not change ownership automatically (this is a destructive operation for the existing students).
      • Fix: In Google Classroom, manually transfer the course back to the correct teacher (Classroom → Class → ⋮ → Make class owner), or update the teacher's account in ESGI to match the current Google owner.
      • Cause: The student's email in ESGI doesn't match any account in the admin's Google Workspace.
      • Fix: Check that the student's ESGI email is correct and that the student exists in your Workspace directory. Students on personal ‘@gmail.com’ accounts will never resolve via the directory lookup — they can still join via invitation, but ESGI cannot create their roster entry until they do.
      • Cause: More than 5 errors hit in a single run. This is a safeguard so a misconfiguration doesn't cascade into hundreds of bad operations.
      • Fix: Open the sync log, fix the most common issue, re-sync. Repeat until the count drops below 5.
      • Cause: Google's policy changes propagate gradually.
      • Fix: Wait. Google quotes up to 24 hours, but most settings take a few minutes. If it's been more than a day, double-check the setting actually saved (browser back button, verify the value), then re-run the sync.
      • The teacher was removed from the ‘classroom-teachers’ Google Group.
      • The teacher's account was suspended or moved to a non-Classroom OU.
      • The teacher's password was reset and they haven't signed in since (rare).
      • ESGI cannot read student grades, coursework, classroom messages, or files. The scopes are limited to course metadata, roster membership, student email, and a read-only directory lookup.
      • ESGI cannot create, modify, or delete users in your directory.
      • Revoking access is one click: Admin console → Security → API controls → Manage Domain-wide Delegation → Delete the row with ESGI's Client ID. The next sync will fail with ‘403 unauthorized’, but no data on the Google side is changed.
      • The sync runs from ESGI's secured environment. The service account's private key never leaves ESGI's infrastructure.

          @UserCannotCreateCourse’ in the sync log

              Student appears as ‘Invited (pending acceptance)’ instead of ‘Added’

                          [403 forbidden] The caller does not have permission

                            1. The Client ID / scopes weren't added in Step 4. Double-check the Client ID matches what ESGI provided and that all four scopes are listed.

                            2. The admin email used by ESGI is not a super-admin in your domain.

                            3. The student's domain restricts cross-domain class membership (see Invited (pending acceptance) above).

                              Course owner mismatch — 'skipping’ in the sync log

                                  Student not found in Google directory

                                      Sync stops with `StoppedByThreshold`

                                          Changes I made in the Admin console aren't taking effect

                                              A teacher who used to sync fine suddenly fails

                                              Cause: Usually one of:

                                                    Fix: Verify the teacher's account is still active in the directory and still in the right group/OU.

                                                    Security Notes

                                                            • ESGI cannot read student grades, coursework, classroom messages, or files. The scopes are limited to course metadata, roster membership, student email, and a read-only directory lookup.
                                                            • ESGI cannot create, modify, or delete users in your directory.
                                                            • Revoking access is one click: Admin console → Security → API controls → Manage Domain-wide Delegation → Delete the row with ESGI's Client ID. The next sync will fail with ‘403 unauthorized’, but no data on the Google side is changed.
                                                            • The sync runs from ESGI's secured environment. The service account's private key never leaves ESGI's infrastructure.