This article is for Agilix partners with their own URL or deployments.
This is an advanced for deployment admins, only.
Buzz end-users frequently create and store documents in their personal Google Drive accounts and later want to reference these documents in assignment submissions, grading feedback, or course content.
This document describes how Agilix partners with their own URL or deployments can configure Buzz and Google to allow end-users to seamlessly access Google Drive from within Buzz.
Why configure a Google Drive integration?
Integrating Buzz with Google Drive requires you to configure things in both Buzz and Google. As part of their ongoing efforts to ensure security and privacy, Google displays a warning message (see https://support.google.com/cloud/answer/7454865?hl=en for more details) when accessing Google Drive from an unverified app:
As an Agilix partner with your own deployment, this means:
- You will verify your app (your branded version of Buzz) with Google, so your end-users will not receive the "app isn't verified" warning (instructions included in this document).
- You will configure your Google Drive integration at the top-most domain, and all subdomains will inherit it (instructions included in this document).
- Your end-users will still have to complete Google's one-time consent form, giving your app permission to open their Google Drive documents.
1. Create a new Buzz "gdrive" subdomain
You must set up a new Buzz subdomain for Google Drive access.
Create a new Buzz subdomain. This domain is set up specifically for the Google Drive integration and should have no subdomains of its own. We recommend naming it something like [yourdomain]-gdrive for ease.
2. Create an app homepage
To comply with Google's requirements, you must have an application homepage separate from the login page (see https://support.google.com/cloud/answer/9110914). In that article, Google explains that your homepage should show content associated with your brand, accurately show your app's identity, and clearly describe what your app does.
Buzz allows you to add a homepage feature:
- Open Domain settings > Text (XML) editor > Application settings for your new "gdrive" subdomain
- Add a homepage setting pointing to a URL where you've described your branded version of Buzz (including https://):
<settings>
<homepage url="[INSERT URL TO YOUR HOMEPAGE CONTENT]" />
</settings>
- Save changes and refresh your browser.
- Verify the page loads and renders correctly by changing the path in your browser address bar to /homepage, for example: https://gdrive.agilixbuzz.com/homepage or https://yourdomain-gdrive.yourcustomdomain.org/homepage.
3. Define your privacy policy
Google requires your app to have a privacy policy that discloses how it uses Google data (see https://support.google.com/cloud/answer/9110914?hl=en&ref_topic=3473162#zippy=%2Csteps-to-prepare-for-verification).
You can borrow the language we use to describe Buzz’s use of Google Drive data from the Agilix Buzz Privacy Policy.
Buzz allows you to display your existing privacy policy directly within Buzz (which is required by Google). You must configure Buzz to display your privacy policy:
- Open Domain settings > Text (XML) editor > Application settings for your new "gdrive" subdomain.
- Add a privacy setting pointing to your privacy policy's URL (including https://):
<settings>
<privacy url="[INSERT URL TO YOUR PRIVACY POLICY]" />
</settings>
- Save changes and refresh your browser.
- Verify your privacy policy loads and renders correctly from Buzz's home page choosing Privacy policy from the Main menu on any page in the app. We recommend checking it from the homepage you created above as this is where Google will access it.
4. Create a Web app in the Google Console
In the Google Developer Console, configure a web application and OAuth consent screen with information about your branded version of Buzz and how it will access Google Drive:
- Sign into your Google account.
- Follow these directions: https://support.google.com/cloud/answer/6158849
- For step 5: OAuth 2.0 is the correct client ID.
- For step 6: Follow the directions in the Create Credentials section below.
- Google may prompt you to create a consent screen. Cancel that prompt for now; you'll set up the consent screen after you have configured Buzz.
4.1. Create Credentials
- Choose the Web application radio button.
- In the Authorized JavaScript origins fields, add the URL for the subdomain you created for the Google integration (including https://:).
- For example: https://[YOURDOMAIN]-gdrive.[YOURAPP].com
- Click Create and save the Client ID Google provides.
5. Configure your Google Drive subdomain
- In your new "gdrive" subdomain, open Domain settings > Text (XML) editor > Application settings.
- Adding the following:
<googledriveshared clientid="[INSERT GOOGLE CLIENT ID]"
launchurl="https://[INSERT YOUR GDRIVE SUBDOMAIN URL].com" />
- Save.
- Test the integration by adding an activity to a course in this subdomain. Choose the assignment activity type and choose Google document as the Content. Since your app isn't verified yet, Google will display the unverified app prompt, which you should accept and continue so that you can verify that you have correctly set up the integration. If the integration doesn't work, review steps and/or contact your Agilix support.
6. Verify site ownership with Google
Part of verifying your app with Google includes verifying that you own the site using the Google Search Console (see https://support.google.com/webmasters/answer/9008080?hl=en):
- Sign into Google and visit https://search.google.com/search-console/welcome.
- In the URL prefix card, enter your full "gdrive" subdomain URL.
- For example: https://[YOURDOMAIN]-gdrive.[YOURAPP].com
- Click Continue.
- In the Verify ownership prompt, choose HTML tag.
- Copy the meta tag provided and save it somewhere:
- If Agilix hosts your deployment, send it to your Agilix account manager so that we can add it to your site and jump to step 7) Configure the OAuth Consent Screen in Google.
- If you host your own deployment, follow the Add the google-site-verification tag steps, below.
- Once you've added the google-site-verification tag, click Verify.
6.1. Add the google-site-verification tag
Follow these steps to add the google-site-verification tag to your site.
6.1.1. Configure your Buzz deployment in Zeus
Open Zeus and edit the configuration for your Buzz deployment:
- Log in to Zeus.
- In the Installations section, click the entry for the appropriate installation
- In the Applications section, find the entry for the Buzz application to update and click the Edit icon in the Actions column to open the Update dialog box.
- In the Deployment Parameters field, which should already contain parameters for this deployment, add a new parameter named googleSiteVerification, and set its value to the Google-supplied value. (Ensure you add a trailing comma to the prior entry if adding at the end of the list!)
- For example:
module.exports = {
xli: '[INSERT BUZZ URL]',
cookieName: '[INSERT COOKIE NAME]',
logId: '[INSERT LOG ID]',
googleTrackingId: '[INSERT GOOGLE TRACKING ID]',
googleSiteVerification: '[INSERT GOOGLE SITE VERIFICATION TAG]'
};
- Click Update to save the configuration.
6.1.2. Deploy Buzz
Deploy Buzz using the normal deployment procedure (not documented here).
Note: Re-deploying the same version of Buzz that is already deployed does NOT invalidate the AWS CloudFront cache, even though Zeus adds the new Google Site Verification code into the deployed Buzz files. You must use the AWS console to create an invalidation of the current deployed Buzz to flush the AWS cache and see your updated google-site-verification tag.
6.1.3. Inspect your code
After successful deployment, inspect the HTML of Buzz’s login screen and verify that the <head> element contains a <meta> tag named google-site-verification, and verify that the content attribute contains YOUR google-site-verification code:
<meta name="google-site-verification" content="[YOUR GOOGLE CODE] ">
7. Configure the OAuth Consent Screen in Google
Follow Google's instructions for configuring the OAuth consent screen for your branded version of Buzz.
- Sign into your Google account, and open https://console.cloud.google.com/start.
- Open the main menu (upper-left corner).
- Select APIs & Services > OAuth consent screen.
- Click Edit App to edit your app settings.
- Enter values for all form fields:
- Application home page: Enter your "gdrive" subdomain's homepage URL (e.g., https://[your-domain]-gdrive.[yourdomain].org/homepage).
- Application privacy policy link: Enter your "gdrive" subdomain's privacy URL, (e.g., https://[your-domain]-gdrive.[yourdomain].org/privacy).
- Add your email address to Developer contact information so that Google can contact you directly with notifications about your app verification.
- Click Save and Continue to move to the Scopes step
- Buzz does not use restricted or sensitive scopes. Buzz requires the Google Drive non-sensitive scope https://www.googleapis.com/auth/drive.file. Click Add or remove scopes to add the non-sensitive scope https://www.googleapis.com/auth/drive.file
- Click through the remainder of the screens and submit your app for verification with Google. .
8. Update top-most domain configuration
Once Google approves your app and you have verified that the new integration works in your "gdrive" subdomain, you are ready to make it live for your top-level domain and all of its subdomains:
- Copy all XML domain settings from your "gdrive" subdomain into your top-most domain's XML domain settings:
<settings>
<homepage url="[INSERT URL TO YOUR HOMEPAGE CONTENT]" />
<privacy url="[INSERT URL TO YOUR PRIVACY POLICY]" />
<googledriveshared clientid="[INSERT GOOGLE CLIENT ID]"
launchurl="[INSERT YOUR GDRIVE SUBDOMAIN URL]" />
</settings>
- Save.
Your Google Drive integration is now active for your top-level domain and all its subdomains.
