Gmail
Connecting to Gmail
The connector supports connecting to Gmail using the modern REST API and the IMAP protocol. Control how to connect by using AuthScheme. The REST API is the default.
Authenticating to Gmail
Available authentication schemes include:
Basic (IMAP only)
OAuth
OAuthJWT
GCP Instance Accounts
Basic (IMAP only)
If you plan to use IMAP, you need to enable it so the driver can communicate with Gmail through the IMAP protocol. IMAP enables all your client devices to work with the same, remote data, instead of individual copies. Follow the steps below to enable access to Gmail over IMAP:
Open the Gmail Web interface and click the Settings button (the icon is a gear).
On the Forwarding and POP/IMAP tab, select Enable IMAP.
Save your changes.
Deprecation notice: As of May 30, 2022, Google no longer supports the use of third-party apps or devices that ask you to sign into your Google Account using only your username and password. There are alternatives that still allow you to use this authentication method, for example, App Passwords. Considering this, the Basic AuthScheme is marked as deprecated. We recommend switching to OAuth because it is a more secure method of authentication.
Set the AuthScheme to Basic and Schema to IMAP for this authentication method. This approach is suitable if you need to access your own data. Set the User and Password properties to valid Gmail user credentials.
User Accounts (OAuth)
AuthScheme must be set to OAuth in all user account flows. In addition, all user account flows require that you create and register a custom OAuth application with Gmail. You can then use the provider to acquire and manage the OAuth token values.
NOTE: the connector supports both IMAP and REST schema for OAuth authentication. The only difference is the IMAP requires the User connection property. REST does not.
After setting the following connection properties, you are ready to connect:
InitiateOAuth: Set this to GETANDREFRESH, which instructs the provider to automatically attempt to get and refresh the OAuth access token.
OAuthClientId: Set this to the Client Id in your custom OAuth application settings.
OAuthClientSecret: Set this to the Client Secret in the custom OAuth application settings.
User: (IMAP only) Set this to the Gmail user account used to authenticate.
When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process as follows:
Extracts the access token from the callback URL.
Obtains a new access token when the old one expires.
Saves OAuth values in OAuthSettingsLocation. These values persist across connections.
Service Accounts (OAuthJWT)
To authenticate using a service account, you must create a new service account and have a copy of the accounts certificate. If you do not already have a service account, you can create one by following the procedure in Creating a Custom Azure OAuth App. NOTE: The OAuth JWT authentication method requires delegation. This is only possible if you are using a Google Workspace account.
For a JSON file, set these properties:
AuthScheme: Set this to OAuthJWT.
InitiateOAuth: Set this to GETANDREFRESH.
OAuthJWTCertType: Set this to GOOGLEJSON.
OAuthJWTCert: Set this to the path to the .json file provided by Google.
OAuthJWTSubject: (optional) Only set this value if the service account is part of a GSuite domain and you want to enable domain-wide delegation. The value of this property should be the email address of the user whose data you want to access. See the Google Workshop Admin help for information about implementing domain-wide delegation.
For a PFX file, set these properties:
AuthScheme: Set this to OAuthJWT.
InitiateOAuth: Set this to GETANDREFRESH.
OAuthJWTCertType: Set this to PFXFILE.
OAuthJWTCert: Set this to the path to the .pfx file provided by Google.
OAuthJWTCertPassword: (optional) Set this to the .pfx file password. In most cases you must provide this since Google encrypts PFX certificates.
OAuthJWTCertSubject: (optional) Set this only if you are using a OAuthJWTCertType which stores multiple certificates. This should not be set for PFX certificates generated by Google.
OAuthJWTIssuer: Set this to the email address of the service account. This address will usually include the domain iam.gserviceaccount.com.
OAuthJWTSubject: (optional) Only set this value if the service account is part of a GSuite domain and you want to enable domain-wide delegation. The value of this property should be the email address of the user whose data you want to access. See the Google Workshop Admin help for information about implementing domain-wide delegation.
User: Set this to the user of the Gmail account you are connecting to.
GCP Instance Accounts
When running on a GCP virtual machine, the provider can authenticate using a service account tied to the virtual machine. To use this mode, set AuthScheme to GCPInstanceAccount.
Last updated