View source for Using your own Google OAuth client

[[Category:Integration Functions]]
{{ReleaseBar}}

{{Release|1=7.2|2=|3=
When the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]] of [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] connects to Google, Analytica identifies itself to Google as an application named '''Analytica''', registered by Lumina Decision Systems. That needs no setup and is the right arrangement for nearly everyone.

This page is for the few organizations that would rather have Analytica identify itself as an application registered by '''them'''. It describes what that does and does not change, when it is worth the trouble, and how to set it up.

== What the application identity is, and is not ==

The client ID and client secret that Analytica sends to Google say ''which program is asking''. They say nothing about ''who you are'', and nothing about ''which spreadsheets'' it may touch. In particular, using Lumina's registration does '''not''' restrict Analytica to non-confidential spreadsheets:

* Analytica asks Google for one permission, <code>drive.file</code>, which lets it see only the spreadsheets you yourself select in Google's file chooser, plus ones it creates. A confidential spreadsheet is no different from any other: select it in the chooser and Analytica can read and write it.
* No spreadsheet content and no Google credential ever passes through Lumina. Your browser talks to Google, your computer exchanges tokens with Google directly, and the resulting connection is kept in the Windows Credential Manager under your Windows account. Registering your own application changes none of that.
* Your own registration does not remove the browser step, and does not change which spreadsheets the chooser offers you.

== Why you might want your own ==

* '''Your organization controls which third-party applications may use its Google Workspace data.''' A Workspace administrator can allow or block individual applications (Admin console, under Security, API controls). If Analytica has not been allowed, connecting fails, or Google's chooser offers nothing you can select. An application registered inside your own organization is under your administrator's control from the start, instead of needing an exception made for an outside one.
* '''You want the consent screen, the grants and the audit trail inside your own organization.''' The browser names ''your'' application, the grants appear in your own Google Cloud project, and an administrator can review or revoke them centrally.
* '''You want your own API quota.''' Google counts Drive and Sheets API usage per Cloud project. Your own project gets its own quota, rather than sharing a pool with other Analytica users.
* '''You would rather Analytica's access to your data not depend on an application registered by another company at all.'''

If none of these apply to you, use the built-in registration and ignore this page.

== Registering the application with Google ==

You need a Google Cloud project, which is free.

# In the [https://console.cloud.google.com/ Google Cloud console], create a project, or choose one your organization already uses.
# Enable three APIs for it (APIs and services, then Enable APIs and services): '''Google Drive API''', '''Google Sheets API''' and '''Google Picker API'''. The Picker API is the one that presents the file chooser; without it the connection cannot finish.
# Configure the OAuth consent screen (Google Auth Platform, then Branding). Give it an application name -- this is the name the person sees in the browser, so use one they will recognize -- a user-support e-mail address, and a developer contact address.
#* Choose the '''Internal''' user type if your organization uses Google Workspace and only its own members need to connect. Internal applications skip Google's verification process entirely.
#* '''External''' also works. Because Analytica asks only for the non-sensitive <code>drive.file</code> permission, an External application can be published without a Google review. While it is left in ''Testing'', though, only the accounts listed as test users can connect, and their connections stop working after seven days.
# Create the credential: APIs and services, Credentials, Create credentials, '''OAuth client ID''', application type '''Desktop app'''. Copy the '''Client ID''' and the '''Client secret''' that Google shows. There is no redirect URI to fill in -- a desktop client may use the local loopback address that Analytica uses.

Google calls the second value a secret, but for a desktop application it is not a true secret: it is distributed inside the program, and Google's own documentation treats installed applications as unable to keep it confidential. Look after it as you would any configuration value, but it is not a password, and on its own it grants access to nothing.

== Telling Analytica to use it ==

Set two values in the registry, under

:<code>HKEY_CURRENT_USER\Software\Lumina Decision Systems\Analytica</code>

for one Windows user, or under

:<code>HKEY_LOCAL_MACHINE\SOFTWARE\Lumina Decision Systems\Analytica</code>

for everyone on the computer. When a value appears in both, the HKEY_CURRENT_USER one wins. The key has no release number in it, so the setting applies to every installed Analytica release.

{| class="wikitable"
! Value name !! Type !! Contents
|-
| <code>GoogleOAuthClientId</code> || REG_SZ || The full client ID, ending in <code>.apps.googleusercontent.com</code>
|-
| <code>GoogleOAuthClientSecret</code> || REG_SZ || The client secret
|}

Set both. If the ID is given without the secret, Google refuses the connection. As a .reg file:

 Windows Registry Editor Version 5.00
 
 [HKEY_CURRENT_USER\Software\Lumina Decision Systems\Analytica]
 "GoogleOAuthClientId"="123456789012-examplexample.apps.googleusercontent.com"
 "GoogleOAuthClientSecret"="GOCSPX-exampleexampleexample"

Removing both values restores the built-in registration.

The change takes effect at the next connection; there is no need to restart Analytica. Connections are remembered separately for each client ID, so the first spreadsheet you open after the change asks you to connect once more. Your earlier connection is left untouched, and is used again if you remove the two values.

== Checking that it worked, and disconnecting ==

Open any Google Sheets link with [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]]. The browser page that asks for permission should now name ''your'' application rather than Analytica. Afterwards:

:<code>SysLib_Internal::GoogleAccountEmail()</code> -- the Google account now connected, or Null when there is none.
:<code>SpreadsheetInfo(wb, 'Account')</code> -- the account an open workbook was opened with.

To disconnect -- which revokes the access at Google and forgets the stored connection -- evaluate

:<code>SysLib_Internal::DisconnectGoogleAccount()</code>

from a button's OnClick, or in the [[Typescript Window|Typescript window]]. It is a side effect, so it is refused inside a variable's Definition. It returns the e-mail address of the account that was disconnected, or Null when none was connected. You can also revoke Analytica's access at any time from [https://myaccount.google.com/permissions your Google account's permissions page].

== Notes and limits ==

* One Google connection is remembered at a time for a given client ID, for the Windows user who made it. [[Analytica Decision Engine|ADE]] scripts running as the same Windows user share that connection, which is why connecting once in Analytica is enough for them.
* Analytica asks for the <code>drive.file</code> permission with your registration exactly as it does with Lumina's. Registering your own application does not let it open spreadsheets that were never selected in the chooser.
* A model published to the [[Analytica Cloud Platform]] does not use these settings. There, each person connects their own Google account through the ACP server's own registration, and the settings on the author's computer play no part.
}}

== See Also ==

* [[Functions To Read Excel Worksheets]] -- [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] and the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]]
* [[Functions to Write Data to Excel Worksheets]]
* [[SpreadsheetInfo]]
* [[Analytica Cloud Platform]]