Connect your Google Workspace Add-on to a third-party service

A sign-in card interface for an add-on that previews links from a third-party service.

If your Google Workspace Add-on connects to a third-party service or API that requires authorization, the add-on can prompt users to sign in and authorize access.

This page explains how to authenticate users using an authorization flow (such as OAuth), which includes the following steps:

Detect when authorization is required.
Return a card interface that prompts users to sign in to the service.
Refresh the add-on so that users can access the service or protected resource.

If your add-on only requires the user identity, you can directly authenticate users by using their Google Workspace ID or email address. To use the email address for authentication, see validating JSON requests. If you've built your add-on using Google Apps Script, visit the Apps Script documentation to learn about connecting your add-on to a third-party service.

Detect that authorization is required

When using your add-on, users might not be authorized to access a protected resource for a variety of reasons, such as the following:

An access token to connect to the third-party service hasn't been generated yet or is expired.
The access token doesn't cover the requested resource.
The access token doesn't cover the request's required scopes.

Your add-on should detect these cases so that users can sign in and access your service.

Prompt users to sign in to your service

When your add-on detects that authorization is required, the add-on must return a card interface to prompt users to sign in to the service. The sign-in card must redirect users to complete the third-party authentication and authorization process on your infrastructure.

We recommend that you guard the destination app with Google Sign-in, and get the user ID by using the identity token issued during sign-in. The sub-claim contains the user's unique ID and can be correlated with the ID from your add-on.

Build and return a sign-in card

For your service's sign-in card, you can use Google's basic authorization card, or you can customize a card to display additional information, such as your organization's logo. If you're publishing your add-on publicly, you must use a custom card.

Basic authorization card

The following image shows an example of Google's basic authorization card:

Basic authorization prompt for Example Account. The
prompt says that the add-on would like to show
additional information, but it needs the user's approval to
access the account.

To use the basic authorization card, return the following JSON response:

{
  "basic_authorization_prompt": {
    "authorization_url": "AUTHORIZATION_REDIRECT",
    "resource": "RESOURCE_DISPLAY_NAME"
  }
}

Replace the following:

AUTHORIZATION_REDIRECT: The URL for the web app that handles authorization.
RESOURCE_DISPLAY_NAME: The display name for the protected resource or service. This name is displayed to the user on the authorization prompt. For example, if your RESOURCE_DISPLAY_NAME is Example Account, the prompt says "This add-on would like to show additional information, but it needs approval to access your Example Account."

After completing authorization, the user is prompted to refresh the add-on to access the protected resource.

Custom authorization card

To modify the authorization prompt, you can create a custom card for your service's sign-in experience.

If you're publishing your add-on publicly, you must use a custom authorization card. To learn more about publishing requirements for the Google Workspace Marketplace, see About app review.

The following images shows an example custom authorization card for an add-on's homepage. The card includes a logo, description, and sign-in button:

To use this custom card example, return the following JSON response:

{
  "custom_authorization_prompt": {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "sections": [
              {
                "widgets": [
                  {
                    "image": {
                      "imageUrl": "LOGO_URL",
                      "altText": "LOGO_ALT_TEXT"
                    }
                  },
                  {
                    "divider": {}
                  },
                  {
                    "textParagraph": {
                      "text": "DESCRIPTION"
                    }
                  },
                  {
                    "buttonList": {
                      "buttons": [
                        {
                          "text": "Sign in",
                          "onClick": {
                            "openLink": {
                              "url": "AUTHORIZATION_REDIRECT",
                              "onClose": "RELOAD",
                              "openAs": "OVERLAY"
                            }
                          },
                          "color": {
                            "red": 0,
                            "green": 0,
                            "blue": 1,
                            "alpha": 1,
                          }
                        }
                      ]
                    }
                  },
                  {
                    "textParagraph": {
                      "text": "TEXT_SIGN_UP"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Replace the following:

LOGO_URL: The URL for a logo or image. Must be a public URL.
LOGO_ALT_TEXT: Alt text for the logo or image, such as Cymbal Labs Logo.
DESCRIPTION: A call to action for users to sign in, such as Sign in to get started.
To update the sign-in button:
- AUTHORIZATION_REDIRECT: The URL for the web app that handles authorization.
- Optional: To change the button color, update the color field's RGBA float values.
TEXT_SIGN_UP: A text that prompts users to create an account if they don't have one. For example, New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.