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 Learning Environment 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.

  1. Browse to the Google Developers Console and log in with your Google administrator credentials.
  2. For information on how to create a project, see Create, shut down, and restore projects in the API Console Help.
  3. 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.

  1. Ensure your API project is open in the Google Developers Console.
  2. 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 Learning Environment. See the User consent section in Setting up OAuth 2.0 and configure the consent screen as needed.
  3. Enter a name for your web application.
  4. In the field for authorized JavaScript origins, enter your D2L domain.
  5. In the field for authorized redirect URLs, change the end point to [D2L Domain]/d2l/im/gapps/pages/auth/Signin.
  6. Create the client ID.
  7. Make note of the following values:
    • client ID
    • client secret
  8. In Brightspace Learning Environment, on the Google Workspace Administration page, click Settings.
  9. 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.

  1. Ensure your API project is open in the Google Developers Console.
  2. 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 Learning Environment. See the User consent section in Setting up OAuth 2.0 and configure the consent screen as needed.
  3. Enter a name for your installed application.
  4. Create the client ID.
  5. Make note of the following values:
    • client ID
    • client secret
  6. In Brightspace Learning Environment, on the Google Workspace Administration page, click Settings.
  7. Under Google Client IDs, add the Client ID and Client Secret values.
  8. 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.

  1. In your Google Admin console (at http://admin.google.com )...Sign in to your Google Admin console.

  2. Go to Security > API controls.

  3. Under App access control, select Manage Third-Party App Access.

  4. Click Configure new app, and choose OAuth App Name or Client ID.

  5. Enter the app's ClientID as noted above, and then click Search.

  6. 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.

  7. Select Trusted: Can access all Google services.

  8. Click Configure. On the apps page, the Access column displays the access status for the apps as Trusted.

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.

  1. Ensure your API project is open in the Google Developers Console.
  2. 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.
  3. 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.
  4. Choose to generate the key as a standard P12 file, and save it to your local drive.
  5. Create the service account key.
  6. Make note of your private key's password and close the dialog box.
  7. In the Google Developers Console, click the link to take you to the area where you can manage your service accounts.
  8. From the more options button adjacent to your service account (the 3 vertical dots), select Edit.
  9. Ensure that the domain-wide delegation option is enabled and save.
  10. 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 Learning Environment, 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.

  1. Browse to https://admin.google.com and log in with your Google Workspace administrator account.
  2. 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.
  3. 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.
  4. Before changing Read-only Access to Google Directory API, review your organization policy.
  5. 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 theOne 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
  6. Click Authorize.

Step 6: Configure a service account in Brightspace Learning Environment

  1. From the admintools_navbar_icon Admin Tools, or in the Organization Related section of the Admin Tools widget, click the Google Workspace Administration link.
  2. Click Service Account.
  3. Enter your Google Workspace domain administrator's login name.
  4. Enter your Service account email.
  5. Enter your P12 Password.
  6. In Upload P12 Key File, click Choose file and attach the P12 file you saved to your local computer.
  7. Click Save.