Wenn Ihr Google Workspace-Add-on eine Verbindung zu einem Dienst oder einer API eines Drittanbieters herstellt, für die bzw. die eine Autorisierung erforderlich ist, kann das Add-on Nutzer dazu auffordern, sich anzumelden und den Zugriff zu autorisieren.
Auf dieser Seite wird erläutert, wie Nutzer mithilfe eines Autorisierungsvorgangs (z. B. OAuth) authentifiziert werden. Dies umfasst die folgenden Schritte:
- Erkennen, wenn eine Autorisierung erforderlich ist
- Eine Kartenoberfläche zurückgeben, in der Nutzer aufgefordert werden, 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 zur Authentifizierung finden Sie unter JSON-Anfragen validieren. Wenn Sie Ihr Add-on mit Google Apps Script erstellt haben, lesen Sie in der Apps Script-Dokumentation nach, wie Sie Ihr Add-on mit einem Drittanbieterdienst verbinden können.
Erkennen, dass eine Autorisierung erforderlich ist
Wenn Sie Ihr Add-on verwenden, kann es vorkommen, dass Nutzer aus verschiedenen Gründen nicht berechtigt sind, 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 erforderlichen Bereiche der Anfrage 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 es eine Kartenschnittstelle zurückgeben, in der die Nutzer aufgefordert werden, sich beim Dienst anzumelden. Die Anmeldekarte 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 User-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
Die folgende Abbildung zeigt ein Beispiel für die Basisautorisierungskarte von Google:
Geben Sie die folgende JSON-Antwort zurück, um die Karte für die einfache Autorisierung 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: Der Anzeigename für die geschützte Ressource oder den geschützten Dienst. Dieser Name wird dem Nutzer bei der Autorisierungsaufforderung angezeigt. Wenn IhrRESOURCE_DISPLAY_NAMEbeispielsweiseExample Accountist, wird folgende Meldung angezeigt: „Dieses Add-on möchte zusätzliche Informationen anzeigen, aber es muss der Zugriff auf Ihr Beispielkonto genehmigt werden.“
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 eine benutzerdefinierte Karte für die Anmeldung Ihres Dienstes 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 Abbildungen 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:
Um dieses Beispiel für eine benutzerdefinierte Karte zu verwenden, geben Sie die folgende JSON-Antwort zurück:
{
"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. Dies muss eine öffentliche URL sein.LOGO_ALT_TEXT: Alt-Text für das Logo oder Bild, z. B.Cymbal Labs LogoDESCRIPTION: 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, falls sie noch keines haben. Beispiel:New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.