Google

You must create and add your own Google APIs Project and OAuth credential to your CloudSponge account before you can access Google Contacts. This is because Google has asked us to ensure that any app that is consuming their data has a registered developer account with Google. This has the added benefit of providing a better experience for your users, who will see your product consistently through the OAuth flow.

In over your head?

At any point, if you would rather let us take care of setting up Google OAuth and preparing for their verification, we’re happy to do it! Just start with our OAuth Concierge service by completing our questionnaire.

Important: Google needs to verify your application before they will allow strangers to approve your OAuth permission requests. Google warns that the verification may take up to a week. However, in our experience the verification may be as fast as one business day if you meet Google’s approval criteria. We’ve prepared some background and directions to help you navigate the new process successfully. You can still develop and test your integration before Google has verified it.

These are the actions required to set up your Google OAuth:

1. If you haven’t already done so, create a Proxy URL on your application’s domain.
2. Create a Google APIs Project and OAuth 2.0 Credentials.
3. Configure your CloudSponge account with your Google OAuth credentials.
4. Request verification from Google, if your APIs Project is for HTTPS.

Create a Google APIs Project and Get your OAuth 2.0 Credentials

There are two types of Google APIs Project that you can create, an APIs Project for HTTPS or an APIs Project for non-HTTPS.

Before you can access Google Contacts in your live site, you’ll need to create a Google APIs Project for HTTPS. CloudSponge customers typically create a single APIs Project for HTTPS because it usually can be used with CloudSponge in all of your environments.

You will need to configure OAuth for at least one Google APIs Project, depending on how your production, staging and development environments are hosted. Each Google APIs Project can be used on registered domains (and sub-domains) hosted on either HTTPS or non-HTTPS. The one useful exception to this rule is for http://localhost[:port] and http://127.0.0.1[:port]. These URLs are always valid for any Google APIs project.

Creating an APIs Project for HTTPS

You’ll need to create an APIs Project for HTTPS for your live/production environment. As the name implies, your server must be hosted on HTTPS. Before your setup is complete, you’ll need to create an HTTPS Google APIs Project and have it verified by Google.

An HTTPS project can be verified by Google so that your users don’t see the egregious warning screen when asked to share their address books with your application. This project can be used on any sub-domains that also use HTTPS, as well as for localhost development. Your production site must use an HTTPS Google APIs Project.

Prerequisites

You need a Proxy URL to be hosted on your HTTPS server on the same domain or sub-domain as your production site. For example, if your root application domain is example.com, your Proxy URL could be hosted at https://example.com/path/to/proxy, https://www.example.com/path/to/proxy or https://subdomain.example.com/path/to/proxy.

Setting up Google OAuth for an HTTPS environment

Armed with your Proxy URL hosted in a public HTTPS environment, you are able to complete the setup of the Google APIs Project.

Check out these walkthrough videos we made for you or follow the steps below.

How to prepare for Google OAuth

How to make a Demo Video for Google OAuth

Step-by-step instructions

1. Sign in to the Google APIs Platform.
2. Create a new project and enable the necessary APIs:
   1. Create a new project, possibly from the Manage resources page. Give it a descriptive name like “MyCompany Invitations”.
   2. Wait a moment for Google to create your new project. Then select the project from the notifications menu.
   3. From your Project’s dashboard, click Enable APIs and then search for people. Here’s a handy pre-populated link.
   4. Enable the People API from here.
   5. Return to your project dashboard and verify that the People API appears in the list at the bottom of the page.
3. Configure the OAuth consent screen settings:
   1. Visit the OAuth consent screen settings for your new project.
   2. If prompted, choose External for the user type and then click Create.
   3. Enter your Application name. Your users will see this name when asked for permission to access their address book. It should match your brand name.
   4. Pick a Support email from the list. Users will see this email if they look for it on the OAuth permission page.
   5. Upload an Application Logo. This step is optional but recommended. A logo gives users a visual cue that they can trust the application asking for permission so it’s very important for live apps.
   6. Fill in the Application Homepage link. This URL must be publicly available and hosted on one of your Authorized domains.
   7. Fill in the Application Privacy Policy link. This URL must be publicly available and hosted on one of your Authorized domains.
   8. Optionally, fill in the Application Terms of Service link. This step is recommended if you have a ToS for your users. This URL must be hosted on one of your Authorized domains.
   9. Add your Application domain. Google will guess what domain needs to be added. Remove any subdomain from it, e.g. use mydomain.com not www.mydomain.com. You will need to verify ownership of this domain.
   10. Add a Developer email address. This address it used by Google to contact you about your OAuth settings. Make sure it is being actively monitored.
   11. Click Save and continue.
4. Configure your Scopes:
   1. Click Add or remove scopes. There are three scopes you may select here:
      1. Required: ../auth/contacts.readonly You must add this scope.
      2. Recommended: ../auth/contacts.other.readonly This provides access to the “Other contacts” in Gmail. Most of people’s contacts are here.
      3. Optionally: ../auth/directory.readonly This provides access to GSuite contacts. It may be useful only if your customers are businesses.
   2. Finally, click Save and continue.
   3. Skip adding Users, click Save and continue.
   4. Review the settings so far and click Back to dashboard.Click Save (You’ll Submit for verification later, after creating the OAuth credentials).
5. Create credentials:
   1. Visit the credentials tab and click Create credentials > OAuth client ID.
   2. Under Application type, select Web application.
   3. Name your credential however you like; users don’t see this label.
   4. Leave Authorized JavaScript origins blank. This field should not be used.
   5. In Authorized redirect URIs, enter your Proxy URL.
   6. Click Create.
   7. Make a note of your Client ID and Client secret. You will add these values to your CloudSponge account.

Configure your CloudSponge account with your Google OAuth credentials

1. Sign in to your CloudSponge account and visit your credentials page.
2. Click the Add OAuth Credential button.
3. Select “Google Contacts” and click Next.
4. Select your Proxy URL from the list or click “Add new Proxy URL” to add and verify a new one. Click Next.
5. Enter a Name to help identify this credential, the Client ID and Client secret values from Google.
6. Select People API.
7. For API Scopes, select the additional scopes you want to access:
   1. Recommended: Select “Other Contacts” if you are requesting the ../auth/contacts.other.readonly scope.
   2. Optional: Select “Directory Contacts” if you are requesting the ../auth/directory.readonly scope which provides access to GSuite contacts. This may be useful if your users are businesses.
8. Select Default Google Client checkbox if this credential will be used in your production and development environments. If you don’t select the Default checkbox, you’ll also need to assign this credential to the sites that should use it.
9. Select Live if this OAuth credential will be used in your production environment. Our system will monitor “live” credentials and alert you if they stop working for any reason.
10. When you are satisfied with the values, click on Save & Close button.

Optionally, you may assign the newly created credential to one or more sites explicitly. When you assign a credential with a site, this overrides the “Default” setting for your account. Usually, this is not required, since you can use your production credential in your development environments. However, if you support multiple sites with different OAuth credentials, then you’ll need to make the assignments as follows.

1. Open your sites page.
2. Click the Assign OAuth button for the site to which you’d like to assign a credential.
3. Select the credential by name from the list of credentials for your account.
4. You are done. Go ahead and test an address book import to confirm that the correct credential is used on your site.

NB If you observe a 400 error with a message of “Error: invalid_scope” when you attempt to complete the OAuth flow, then your OAuth account needs to be reviewed before Google will let you request access to people’s address books. This is a new requirement that they introduced on May 11, 2017. We’ve prepared some background and directions for navigating the new review process.

Request a Verification from Google

Only projects that are on HTTPS can be verified by Google. Projects that are not verified by Google display a strong warning to the user and can only be used by 100 users before being disabled. You must host your live application on HTTPS and successfully pass Google’s verification.

Before you request a verification from Google, you should:

• Verify your domain with Google.
• Read about App verification.
• Finally, review Google’s list to ensure approval.

Read our background and directions for a quick turnaround from the review process.

When you are ready to request a review, visit your Project’s consent settings and click the Submit for verification button. Fill in the form, explaining how you are using the People API.

Here you can review the status of the Google Gmail Contacts API

If you have any questions, reach out to us. We’re happy to help however we can.