> For the complete documentation index, see [llms.txt](https://help.solar-archive.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.solar-archive.com/docs/msp-onboarding-guide/google-workspace-onboarding/google-workspace-oauth.md).

# Google Workspace OAuth

[Setting up OAuth 2.0 - Google Cloud Platform Console Help](https://support.google.com/cloud/answer/6158849?hl=en)

**KEY POINT:** A Google API Project sits outside of a Google Workspace. You could create a Project that any number of other Google Customers could utilise - like a new address book app. In this scenario, you are creating an API Project just for your own usage – to allow your workspace users to be able to login to the Email Archive, and to provide the Email Archive authenticated access to each Workspace Email account. If you have multiple Workspace domains, then then you only need to create a SINGLE API PROJECT TO ACCESS ALL OF YOUR CHOSEN WORKSPACES.

There are two parts to the setup process. First to create a Google ‘API Project’, where you specify the scope of permissions that you wish this App to access. For the purpose of Login only, the permission is just to access the user’s own account details. And we specify the URL which your “Application” comes from – this is the link to the YOUR ARCHIVE system. The second part is to connect your new API Project (which we could call an ‘App’) to your Workspace. But when the user first connects, a “Consent” panel will be displayed to the user – showing the scope of this ‘App’ along with the details of the App developer. In this case – it is yourself! So please complete this task with this in mind.

## **Create a Google API Project:**

1. Go to the Google Cloud Console (<https://console.developers.google.com/apis>).
2. Create a new project or select an existing one.

   <figure><img src="/files/UuGK4TkcQRRr0YcoLbNd" alt=""><figcaption></figcaption></figure>
3. Adding a New Project is very straight forward – just give it a meaningful project name. The remaining details will default, or you can enter your Organisation (URL hostname).

   <figure><img src="/files/tKsl1uORHJuXIMZZvAdH" alt=""><figcaption></figcaption></figure>
4. All subsequent web panels will relate to the created / selected project. Check the top of the web page to confirm this.

   <figure><img src="/files/I8Lqbr2UKbrkdEDgVcyx" alt=""><figcaption></figcaption></figure>
5. Can’t See the “APIs and services” area?\
   The Google Developers Web area covers many areas. If you find yourself in a different area, then use the “hamburger” icon to open the Menu to move to different panels. You will need to access the API Credentials next:

   <figure><img src="/files/GFcuAj9jEaqPTPPnyTJa" alt=""><figcaption></figcaption></figure>

## **Creating the OAuth client ID:**

* Here we will be creating an OAuth 2.0 Client ID.
* From the “APIs and Services” area select the “Credentials” menu.

  <figure><img src="/files/VfqxdmZQ4Rd3fp9ecdst" alt=""><figcaption></figcaption></figure>
* Click the + CREATE CREDENTIALS option, and select OAuth client ID.

  <figure><img src="/files/4O1EKp05n5JfJtPlwUyS" alt=""><figcaption></figcaption></figure>
* As it says here – the first task is to configure a “Consent Screen”.

  <figure><img src="/files/LS0ZO7LiYuGcYxbJtwOQ" alt=""><figcaption></figcaption></figure>

## **Configure Consent Screen:**

* [Setting up your OAuth consent screen - Google Cloud Platform Console Help](https://support.google.com/cloud/answer/10311615?hl=en)
* A Consent Screen is just a panel that pops-up to end users when they first try to use YOUR API Application. It simply says WHO YOU ARE to give confidence to the end user that you are a legitimate organization.
* REMEMBER: A Google API Application could be published for the global community to use. In our case – it is just for yourselves. So just complete the consent screen with that in mind.
* The following screen shots show some of the Consent setup. As you can see, it provides you with many ways to personalise the information that will be presented to users when they first access the App defined for this OAuth service.
* As this is not an app that you are going to publish to the World – it is just used INTERNALLY. So, you can leave most things blank or enter basic details about YOUR organisation.
* The remaining Consent screens are to convey to your users what this App is for – in this case it is representing your Email Archive service (YOUR ARCHIVE) so enter values as needed.

  <figure><img src="/files/sdnJllRcRrEfXvzdLQDC" alt=""><figcaption></figcaption></figure>
* App Information: Enter details that you feel are appropriate for your usage with the email archive. For Example:\
  App Name: Email Archive\
  Support Email: Your IT department email
* App Logo: leave blank

  <figure><img src="/files/yTNn6cVhsLPEIA62B1Hj" alt=""><figcaption></figcaption></figure>
* App Domain:\
  Here we add in some URLs of your company. These details are displayed to users when the app tries to access their account.\
  You can leave the Privacy and Terms of Service URLs blank.
* Authorised Domains:\
  Enter in your email domain. If you have multiple domains, then enter all of them.

  <figure><img src="/files/YzLcHLPxFhJMBzqseIPc" alt=""><figcaption></figcaption></figure>
* Scopes can be left to default – the system should automatically select the first 3 entries – userinfo.email / userinfo.profile and openid. These would be required to support the Login phase.

  <figure><img src="/files/nEGx9iuOLnxNi0HpZiQV" alt=""><figcaption></figcaption></figure>
* Once the Consent screen has been configured, we can return to the **Create OAuth client ID** setup.\
  The next steps will require copy-pasting details between the Email Archive and Google…

## Google OAuth / YOUR ARCHIVE SSO setup

The initial usage of OAuth is to allow each Google Workspace user to login and access their YOUR ARCHIVE archived mail

* Login to YOUR ARCHIVE as an administrator, then open the Advanced Configuration > SSO – OAuth panel.

  <figure><img src="/files/PvG0WdaAhSJxA7f0yDPE" alt=""><figcaption></figcaption></figure>
* Click Create New Connection, and select the Provider Type of Google OpenId Connect.

  <figure><img src="/files/NbSbktZCK9gHvaGsTtwA" alt=""><figcaption></figcaption></figure>
* Enter a meaningful Connection Name – the name that you enter here will be used on the login page on a new button with the words “Login using \<connection name>”. E.g. “Login using Google”
* Now back on the Google side: On the “Create OAuth client ID” panel, start by selecting type “Web application”:

  <figure><img src="/files/vOnFDAGUlsacW0PQVXLE" alt=""><figcaption></figcaption></figure>
* Give your OAuth client a sensible name. For the Redirect URI: Here you can enter the redirect URIs as displayed by the YOUR ARCHIVE “SSO OAuth” panel. Press “ADD URI” to also enter the second Redirect URI. Both are nessecary.

  <figure><img src="/files/BmgCiY8NvXoQUPGC920K" alt=""><figcaption></figcaption></figure>
* NOTE: You can add any other REDIRECT URI’s (which are just Web addresses) for which you wish to provide OAuth access. E.g. You will need to do this for the Outlook Add-In App url. You may not know what these other URI’s are now – but Google will show an error when you try connecting to other services (which we see later in this guide). Just find this Google panel again and click the \[+ ADD URI] button and enter the URI that had errored.
* Now press “**Create**” – and a Client ID & secret value will be generated like this:

  <figure><img src="/files/4tob6tY8eJeOm9fpk72V" alt=""><figcaption></figcaption></figure>
* Copy these values to the YOUR ARCHIVE.

  <figure><img src="/files/b85N5okiUVDSfVauBK43" alt=""><figcaption></figcaption></figure>
* We can now complete the YOUR ARCHIVE settings as follows:

| Authorization URL: | <https://accounts.google.com/o/oauth2/v2/auth>  |
| ------------------ | ----------------------------------------------- |
| Access Token URL:  | <https://oauth2.googleapis.com/token>           |
| User Detail URL:   | <https://www.googleapis.com/oauth2/v1/userinfo> |

{% hint style="info" %}
Please Note these values can be obtained from this link: <https://accounts.google.com/.well-known/openid-configuration>
{% endhint %}

* The screen should look like this:

  <figure><img src="/files/z2o34UhEPCCBCc4zBNuM" alt=""><figcaption></figcaption></figure>