Wenn Ihr Google Workspace-Add-on eine Verbindung zu einem Dienst oder einer API eines Drittanbieters herstellt, für die eine Autorisierung erforderlich ist, kann das Add-on die Nutzer auffordern, sich anzumelden und den Zugriff zu autorisieren.
Auf dieser Seite wird erläutert, wie Nutzer mithilfe eines Autorisierungsvorgangs (z. B. OAuth) authentifiziert werden. Das umfasst die folgenden Schritte:
- Erkennen, wann eine Autorisierung erforderlich ist
- Gibt eine Kartenoberfläche zurück, die Nutzer dazu auffordert, sich beim Dienst anzumelden.
- Aktualisieren Sie das Add-on, damit Nutzer auf den Dienst oder die geschützte Ressource zugreifen können.
Wenn für Ihr Add-on nur die Nutzeridentität erforderlich ist, können Sie Nutzer direkt mit ihrer Google Workspace-ID oder E-Mail-Adresse authentifizieren. Informationen zum Verwenden der E-Mail-Adresse für die Authentifizierung finden Sie unter JSON-Anfragen validieren. Wenn Sie Ihr Add-on mit Google Apps Script erstellt haben, finden Sie in der Apps Script-Dokumentation Informationen zum Verbinden des Add-ons mit einem Drittanbieterdienst.
Erkennen, dass eine Autorisierung erforderlich ist
Wenn Nutzer Ihr Add-on verwenden, kann es aus verschiedenen Gründen nicht autorisiert sein, auf eine geschützte Ressource zuzugreifen, z. B.:
- Es wurde noch kein Zugriffstoken für die Verbindung zum Drittanbieterdienst generiert oder ist abgelaufen.
- Das Zugriffstoken deckt die angeforderte Ressource nicht ab.
- Das Zugriffstoken deckt nicht die für die Anfrage erforderlichen Bereiche ab.
Das Add-on sollte diese Fälle erkennen, damit sich Nutzer anmelden und auf Ihren Dienst zugreifen können.
Nutzer auffordern, sich bei Ihrem Dienst anzumelden
Wenn das Add-on erkennt, dass eine Autorisierung erforderlich ist, muss das Add-on eine Kartenschnittstelle zurückgeben, über die Nutzer aufgefordert werden, sich beim Dienst anzumelden. Die Anmeldeseite muss Nutzer weiterleiten, um den Drittanbieter-Authentifizierungs- und Autorisierungsprozess in Ihrer Infrastruktur abzuschließen.
Wir empfehlen, die Ziel-App mit Google Log-in zu schützen und die Nutzer-ID mithilfe des Identitätstokens abzurufen, das bei der Anmeldung ausgestellt wird. Die Unteranforderung enthält die eindeutige ID des Nutzers und kann mit der ID aus dem Add-on korreliert werden.
Anmeldekarte erstellen und zurückgeben
Für die Anmeldekarte Ihres Dienstes können Sie die Karte für eine grundlegende Autorisierung von Google verwenden oder eine Karte anpassen, um zusätzliche Informationen wie das Logo Ihrer Organisation anzuzeigen. Wenn Sie Ihr Add-on öffentlich veröffentlichen, müssen Sie eine benutzerdefinierte Karte verwenden.
Basisautorisierungskarte
In der folgenden Abbildung sehen Sie ein Beispiel für die Basisautorisierungskarte von Google:
Geben Sie die folgende JSON-Antwort zurück, um die Karte für die Basisautorisierung zu verwenden:
{
"basic_authorization_prompt": {
"authorization_url": "AUTHORIZATION_REDIRECT",
"resource": "RESOURCE_DISPLAY_NAME"
}
}
Ersetzen Sie Folgendes:
AUTHORIZATION_REDIRECT: Die URL für die Webanwendung, die die Autorisierung verarbeitet.RESOURCE_DISPLAY_NAME: Anzeigename für die geschützte Ressource oder den geschützten Dienst. Dieser Name wird dem Nutzer in der Autorisierungsaufforderung angezeigt. Wenn IhrRESOURCE_DISPLAY_NAMEbeispielsweiseExample Accountist, wird die Meldung „Dieses Add-on möchte zusätzliche Informationen anzeigen, es muss jedoch der Zugriff auf Ihr Beispielkonto genehmigt werden.“ angezeigt.
Nach Abschluss der Autorisierung wird der Nutzer aufgefordert, das Add-on zu aktualisieren, um auf die geschützte Ressource zuzugreifen.
Benutzerdefinierte Autorisierungskarte
Wenn Sie die Autorisierungsaufforderung ändern möchten, können Sie für die Anmeldung Ihres Dienstes eine benutzerdefinierte Karte erstellen.
Wenn Sie Ihr Add-on öffentlich veröffentlichen, müssen Sie eine benutzerdefinierte Autorisierungskarte verwenden. Weitere Informationen zu den Veröffentlichungsanforderungen für den Google Workspace Marketplace finden Sie unter App-Überprüfung.
Die folgenden Bilder zeigen ein Beispiel für eine benutzerdefinierte Autorisierungskarte für die Startseite eines Add-ons. Die Karte enthält ein Logo, eine Beschreibung und eine Anmeldeschaltfläche:
Geben Sie die folgende JSON-Antwort zurück, um dieses Beispiel für eine benutzerdefinierte Karte zu verwenden:
{
"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"
}
}
]
}
]
}
}
]
}
}
}
Ersetzen Sie Folgendes:
LOGO_URL: Die URL für ein Logo oder Bild. Muss eine öffentliche URL sein.LOGO_ALT_TEXT: Alt-Text für das Logo oder Bild, z. B.Cymbal Labs Logo.DESCRIPTION: Ein Call-to-Action für Nutzer zur Anmeldung, z. B.Sign in to get started.- So aktualisieren Sie die Anmeldeschaltfläche:
AUTHORIZATION_REDIRECT: Die URL für die Webanwendung, die die Autorisierung verarbeitet.- Optional: Wenn Sie die Farbe der Schaltfläche ändern möchten, aktualisieren Sie die RGBA-Gleitkommawerte im Feld
color.
TEXT_SIGN_UP: Ein Text, mit dem Nutzer aufgefordert werden, ein Konto zu erstellen, wenn sie noch keines haben. Beispiel:New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.