You must register at least one domain (for example, myuniversity.com) with Google Workspace for Education. Google Workspace for Education has web services exposed, which can be used to manage users and get data.
Note: Google Workspace 1.3 does not support @gmail.com addresses at this time. It requires the use of a Business or Educational Google Workspace domain.
Register domains with Google Workspace
The Google Workspace integration supports multiple domains. For example, by organizing a Google Workspace environment into sub-domains, schools within an organization can continue to use their own domain names for their email and logins. To add multiple domains, D2L recommends managing them with a single Google Workspace account. For more information, refer to Domain Best Practices.
Each domain must be registered with Google Workspace before you add them to Brightspace.
Add domains to Brightspace
When you add a domain, Brightspace verifies that the service account credentials provided have access to that domain. If the service account has not been set up or validation of the service account fails, you are prompted to enter or resolve your service account information.
- From the Admin Tools menu, or in the Organization Related section of the Admin Tools widget, click the Google Workspace Administration link.
- Click Manage Domains.
- Click Add Domain and enter the domain name, for example, myuniversity.com.
- Click Save. The new domain is added to the domain list.
To configure existing domains, select a domain from the domain list and choose an option: Remove Domain, Edit Domain, or Set as Default.
Configure provisioning API for Google Workspace
- Browse to https://admin.google.com and log in with your Google Workspace administrator account.
- For information on configuring provisioning API for Google Workspace, see Enable API access in the Admin console in the Google Workspace Administrator Help.
Configure 3-legged OAuth (OAuth 2.0) for Google Workspace
Only regenerate the consumer secret if this is a new Google Workspace account. Regenerating the consumer secret might interfere with other tools interacting with this Google Workspace account.
- Browse to https://admin.google.com and log in with your Google Workspace administrator account.
- For information on how to access the location where you can regenerate the consumer secret, see OAuth: Managing API client access in the Google Workspace Administrator Help. In Advanced settings, click Manage OAuth domain key.
Note: On the Manage OAuth key and secret for this domain page, ensure the Enable this consumer key and Allow access to all APIs options are selected. Then, click Regenerate OAuth consumer secret. For more information on consumer secrets, see the Google Workspace for Work Help Forum.
Set up an API project and service account for OAuth 2.0
To use OAuth 2.0 with the Google Workspace integration, you must set up the following:
- An API project - Google Workspace requires the configuration of an API project in order to leverage functionality and additional security.
- A service account - By using a service account's credentials, Brightspace can make authorized calls to Google APIs on behalf of users to perform authentication and authorization. This mechanism improves the security of the Google Workspace integration.
Note: If your instance is located on a private domain, the d2l.3rdParty.GoogleApps.IsPrivateDomain configuration variable must be turned on. This configuration variable is only visible to D2L Support and installation administrators. For more information, see Configuration of the API project for private domains in this section.
Step 1: Create an API project
These steps are for creating a new API Project. If you have an existing project that you want to use, skip this section.
- Browse to the Google Developers Console and log in with your Google administrator credentials.
- For information on how to create a project, see Create, shut down, and restore projects in the API Console Help.
- Enable the Drive API,Calendar API, Gmail API, and Admin SDK. For information on enabling APIs, see Enable and disable APIs in the API Console Help.
Step 2: Configure the authorization end point to work with your API project
In order for auto-authorization to work, you need to create a new Web Application client ID. This allows users to automatically authenticate their Google Workspace for Education account without needing any secondary intervention on the administrator's part. This is the standard configuration for Google Workspace.
If you are behind a private domain (D2L.3rdParty.GoogleApps.PrivateDomain is turned on), skip this section.
- Ensure your API project is open in the Google Developers Console.
- For information on how to create a new OAuth 2.0 client ID in the console, see the Web applications section in Setting up OAuth 2.0 in the API Console Help. Select the option to create a web application.
Note: You might be asked to configure your Google consent screen. Users might see this when initially configuring the connection between their Google accounts and Brightspace. See the User consent section in Setting up OAuth 2.0 and configure the consent screen as needed.
- Enter a name for your web application.
- In the field for authorized JavaScript origins, enter your D2L domain.
- In the field for authorized redirect URLs, change the end point to [D2L Domain]/d2l/im/gapps/pages/auth/Signin.
- Create the client ID.
- Make note of the following values:
- In Brightspace, on the Google Workspace Administration page, click Settings.
- Under Google Client IDs, add the Client ID and Client Secret values.
Step 3: Configuration of the API project for private domains
This step is only necessary if you have not installed the hotfix for Public Authentication (PRB0048743) or are behind a private domain (D2L.3rdParty.GoogleApps.PrivateDomain is turned on). If this step is unnecessary, proceed to the next step.
- Ensure your API project is open in the Google Developers Console.
- For information on how to create a new OAuth 2.0 client ID in the console, see the Installed applications section in Setting up OAuth 2.0 in the API Console Help. Select the option to create an application of type Other to create an installed application.
Note: You might be asked to configure your Google consent screen. Users might see this when initially configuring the connection between their Google accounts and Brightspace. See the User consent section in Setting up OAuth 2.0 and configure the consent screen as needed.
- Enter a name for your installed application.
- Create the client ID.
- Make note of the following values:
- In Brightspace, on the Google Workspace Administration page, click Settings.
- Under Google Client IDs, add the Client ID and Client Secret values.
-
If you selected the No service account option, follow the steps below to integrate multiple Google Workspaces. These steps must be followed for every Google Workspace you want to integrate.
-
Browse to your Google Admin console, located at http://admin.google.com , and sign in to your account.
-
Go to Security > API controls.
-
Under App access, select Manage Third-Party App Access.
-
Click Configure new app, and choose OAuth App Name or Client ID.
-
Enter the app's ClientID as noted above, and then click Search.
-
From the list of search results, click Select for the app that you want to manage.
Note: Select the check boxes for the client IDs that you want to configure, and then click Select.
-
Select Trusted: Can access all Google services.
-
Click Configure. On the apps page, the Access column displays the access status for the apps as Trusted.
-
Browse to the Developer Console (console.cloud.google.com). Click Make External, and then
set the Publishing Status to In Production
Note: The Developer Console may suggest that verification is required; however, you can skip the verification process if your app is solely used by Google Workspace users where the app is set to trusted. When the app is set to trusted, users from that Google Workspace domain don't count against the OAuth user cap of 100 users. The only limit that continues to be applied is a maximum of 10, 000 new logins per day.
Step 4: If you did not select the No Service account option from the Workspace Access area, configure the service account
To use the Admin SDK to perform administrator tasks, you need to configure a service account. The service account allows you to securely create, link, and deactivate users with the Google Workspace integration.
- Ensure your API project is open in the Google Developers Console.
- For information on how to configure a service account, see the Service accounts section in Setting up OAuth 2.0 in the API Console Help. For additional information, see Using OAuth 2.0 for Server to Server Applications and Service accounts in the Google Identity Platform.
- To easily identify your service account for the Brightspace web application, create a new service account.
- D2L recommends that you enter a service account name that is the same as the web application name.
- D2L recommends that you choose the Project Owner role.
- Choose to generate the key as a standard P12 file and save it to your local drive.
- Create the service account key.
- Make note of your private key's password and close the dialog box.
- In the Google Developers Console, click the link to take you to the area where you can manage your service accounts.
- From the more options button adjacent to your service account (the 3 vertical dots), select Edit.
- Ensure that the domain-wide delegation option is enabled and save.
- For the service account you created, click the link to view the client ID and make note of the following:
- Service account (email address), which is entered on the Google Workspace Service Account page in Brightspace, in the Service account email field.
- Client ID, which is entered into the domain security settings for the API scopes access.
Step 5: Allow the service account to access your Google Domain
For the service account to perform user actions against your domain, you must grant it access.
- Browse to https://admin.google.com and log in with your Google Workspace administrator account.
- For information on how to allow the service account to access your Google Domain, see OAuth: Managing API client access in the Google Workspace Administrator Help. Go to the Manage API client access area.
- In the Client Name field, enter your service account Client ID. Your Client ID is from the Service Account Client where you generated the P12 key.
- Before changing Read-only Access to Google Directory API, review your organization policy.
- Do one of the following:
- If you have enabled Read-only access to Google Directory API in Google Workspace Administration settings, then add the following API scopes to the One or More API Scopes field as a comma separated list:
https://www.googleapis.com/auth/admin.directory.user.readonly, https://apps-apis.google.com/a/feeds/domain/, https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/drive.readonly
Note: The Scope for only retrieving users or user aliases (view-only) is: https://www.googleapis.com/auth/admin.directory.user.readonly. - If you have not enabled Read-only access to Google Directory API in Google Workspace Administration settings, then add the following API scopes to the One or More API Scopes field as a comma separated list:
https://apps-apis.google.com/a/feeds/domain/, https://www.googleapis.com/auth/admin.directory.user,
https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/drive.readonly
Note: The Global scope for access to all user and user alias operations (view and manage) is: https://www.googleapis.com/auth/admin.directory.user
- Click Authorize.
Step 6: Configure a service account in Brightspace
- From the Admin Tools, or in the Organization Related section of the Admin Tools widget, click the Google Workspace Administration link.
- Click Service Account.
- Enter your Google Workspace domain administrator's login name.
- Enter your Service account email.
- Enter your P12 Password.
- In Upload P12 Key File, click Choose file and attach the P12 file you saved to your local computer.
- Click Save.