Łączenie dodatku do Google Workspace z usługą innej firmy

Jeśli dodatek do Google Workspace łączy się z usługą lub interfejsem API innej firmy, które wymagają autoryzacji, może on poprosić użytkowników o zalogowanie się i autoryzację dostępu.

Na tej stronie dowiesz się, jak uwierzytelniać użytkowników za pomocą procesu autoryzacji (na przykład OAuth), który obejmuje następujące kroki:

1. Wykrywa konieczność autoryzacji.
2. Zwracanie interfejsu karty, który zachęca użytkowników do zalogowania się w usłudze.
3. Odśwież dodatek, aby użytkownicy mieli dostęp do usługi lub chronionego zasobu.

Jeśli dodatek wymaga tylko tożsamości użytkownika, możesz uwierzytelnić użytkowników bezpośrednio za pomocą ich identyfikatorów Google Workspace lub adresów e-mail. Informacje o tym, jak używać adresu e-mail do uwierzytelniania, znajdziesz w sekcji o weryfikowaniu żądań JSON. Jeśli dodatek został utworzony przy użyciu Google Apps Script, zapoznaj się z dokumentacją Apps Script, aby dowiedzieć się, jak go połączyć z usługą innej firmy.

Wykryj, że wymagana jest autoryzacja

Gdy korzystasz z dodatku, użytkownicy mogą nie mieć uprawnień dostępu do chronionego zasobu z różnych powodów, takich jak:

• Token dostępu umożliwiający połączenie z usługą innej firmy nie został jeszcze wygenerowany lub wygasł.
• Token dostępu nie pokrywa żądanego zasobu.
• Token dostępu nie pokrywa wymaganych zakresów żądania.

Dodatek powinien wykryć takie przypadki, aby użytkownicy mogli się zalogować i uzyskać dostęp do usługi.

Proś użytkowników o zalogowanie się w Twojej usłudze

Gdy dodatek wykryje, że wymagana jest autoryzacja, musi zwrócić interfejs karty, aby zachęcić użytkowników do zalogowania się w usłudze. Karta logowania musi przekierowywać użytkowników, aby ukończyli proces uwierzytelniania i autoryzacji zewnętrznego w Twojej infrastrukturze.

Zalecamy zabezpieczenie aplikacji docelowej za pomocą funkcji Logowanie przez Google i uzyskiwanie identyfikatora użytkownika za pomocą tokena tożsamości wydanego podczas logowania. Roszczenie podrzędne zawiera unikalny identyfikator użytkownika i można je powiązać z identyfikatorem z dodatku.

Tworzenie i zwracanie karty logowania

W przypadku karty logowania do usługi możesz użyć podstawowej karty autoryzacji Google lub dostosować kartę tak, aby wyświetlała dodatkowe informacje, np. logo organizacji. Jeśli publikujesz dodatek publicznie, musisz użyć karty niestandardowej.

Karta podstawowej autoryzacji

Poniższa ilustracja przedstawia przykład podstawowej karty autoryzacyjnej Google:

Aby użyć podstawowej karty autoryzacji, zwróć tę odpowiedź JSON:

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

Zastąp następujące elementy:

• AUTHORIZATION_REDIRECT: adres URL aplikacji internetowej obsługującej autoryzację.
• RESOURCE_DISPLAY_NAME: wyświetlana nazwa chronionego zasobu lub usługi. Ta nazwa jest wyświetlana w prośbie o autoryzację. Jeśli na przykład RESOURCE_DISPLAY_NAME to Example Account, zobaczysz komunikat „Ten dodatek chce wyświetlić dodatkowe informacje, ale potrzebuje do tego zgody na dostęp do Twojego przykładowego konta”.

Po zakończeniu autoryzacji użytkownik zostanie poproszony o odświeżenie dodatku, aby uzyskać dostęp do chronionego zasobu.

Niestandardowa karta autoryzacyjna

Aby zmodyfikować prośbę o autoryzację, możesz utworzyć niestandardową kartę na potrzeby logowania w usłudze.

Jeśli publikujesz dodatek publicznie, musisz użyć niestandardowej karty autoryzacyjnej. Więcej informacji o wymaganiach dotyczących publikowania w Google Workspace Marketplace znajdziesz w artykule Sprawdzanie aplikacji.

Poniższe obrazy przedstawiają przykładową niestandardową kartę autoryzacyjną na stronie głównej dodatku. Karta zawiera logo, opis i przycisk logowania:

Aby użyć tej przykładowej karty niestandardowej, zwróć tę odpowiedź JSON:

{
  "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"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Zastąp następujące elementy:

• LOGO_URL: adres URL logo lub obrazu. Musi to być publiczny adres URL.
• LOGO_ALT_TEXT: tekst alternatywny logo lub obrazu, np. Cymbal Labs Logo.
• DESCRIPTION: wezwanie do działania zachęcające użytkowników do zalogowania się, np. Sign in to get started.
• Aby zaktualizować przycisk logowania:
  • AUTHORIZATION_REDIRECT: adres URL aplikacji internetowej obsługującej autoryzację.
  • Opcjonalnie: aby zmienić kolor przycisku, zaktualizuj wartości zmiennoprzecinkowe RGBA w polu color.
• TEXT_SIGN_UP: tekst zachęcający użytkowników do utworzenia konta, jeśli jeszcze go nie mają. Na przykład: New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.