Si votre module complémentaire Google Workspace se connecte à une API ou à un service tiers nécessitant une autorisation, il peut inviter les utilisateurs à se connecter et à autoriser l'accès.
Cette page explique comment authentifier les utilisateurs à l'aide d'un flux d'autorisation (tel que OAuth), qui comprend les étapes suivantes:
- Permet de détecter les cas où une autorisation est requise.
- Affichez une interface de carte qui invite les utilisateurs à se connecter au service.
- Actualisez-le afin que les utilisateurs puissent accéder au service ou à la ressource protégée.
Si votre module complémentaire ne requiert que l'identité de l'utilisateur, vous pouvez les authentifier directement à l'aide de leur ID Google Workspace ou de leur adresse e-mail. Pour utiliser l'adresse e-mail pour l'authentification, consultez la section Valider des requêtes JSON. Si vous avez créé votre module complémentaire à l'aide de Google Apps Script, consultez la documentation Apps Script pour savoir comment le connecter à un service tiers.
Détecter qu'une autorisation est requise
Lors de l'utilisation de votre module complémentaire, les utilisateurs peuvent ne pas être autorisés à accéder à une ressource protégée pour diverses raisons, par exemple:
- Un jeton d'accès permettant de se connecter au service tiers n'a pas encore été généré ou a expiré.
- Le jeton d'accès ne couvre pas la ressource demandée.
- Le jeton d'accès ne couvre pas les champs d'application requis pour la requête.
Votre module complémentaire doit détecter ces cas de figure afin que les utilisateurs puissent se connecter et accéder au service.
Inviter les utilisateurs à se connecter à votre service
Lorsque le module complémentaire détecte qu'une autorisation est requise, il doit renvoyer une interface card pour inviter les utilisateurs à se connecter au service. La carte de connexion doit rediriger les utilisateurs afin qu'ils suivent la procédure d'authentification et d'autorisation tierce sur votre infrastructure.
Nous vous recommandons de protéger l'application de destination avec Google Sign-In et d'obtenir l'ID utilisateur à l'aide du jeton d'identité émis lors de la connexion. La sous-revendication contient l'identifiant unique de l'utilisateur et peut être mise en corrélation avec l'ID de votre module complémentaire.
Créer et renvoyer une fiche de connexion
Pour la carte de connexion à votre service, vous pouvez utiliser la carte d'autorisation de base de Google ou personnaliser une carte afin d'afficher des informations supplémentaires, telles que le logo de votre organisation. Si vous publiez votre module complémentaire publiquement, vous devez utiliser une fiche personnalisée.
Carte d'autorisation de base
L'image suivante illustre un exemple de carte d'autorisation de base de Google:
Pour utiliser la carte d'autorisation de base, renvoyez la réponse JSON suivante:
{
"basic_authorization_prompt": {
"authorization_url": "AUTHORIZATION_REDIRECT",
"resource": "RESOURCE_DISPLAY_NAME"
}
}
Remplacez les éléments suivants :
AUTHORIZATION_REDIRECT: URL de l'application Web qui gère les autorisations.RESOURCE_DISPLAY_NAME: nom à afficher pour la ressource ou le service protégé. Ce nom est présenté à l'utilisateur dans l'invite d'autorisation. Par exemple, si votreRESOURCE_DISPLAY_NAMEestExample Account, l'invite indique "Ce module complémentaire souhaite afficher des informations supplémentaires, mais il a besoin de votre autorisation pour accéder à votre compte XXX".
Une fois l'autorisation terminée, l'utilisateur est invité à actualiser le module complémentaire pour accéder à la ressource protégée.
Fiche d'autorisation personnalisée
Pour modifier l'invite d'autorisation, vous pouvez créer une carte personnalisée pour l'expérience de connexion de votre service.
Si vous publiez votre module complémentaire publiquement, vous devez utiliser une carte d'autorisation personnalisée. Pour en savoir plus sur les exigences de publication sur Google Workspace Marketplace, consultez À propos de l'examen des applications.
Les images suivantes illustrent un exemple de fiche d'autorisation personnalisée pour la page d'accueil d'un module complémentaire. La fiche comprend un logo, une description et un bouton de connexion:
Pour utiliser cet exemple de carte personnalisée, renvoyez la réponse JSON suivante:
{
"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"
}
}
]
}
]
}
}
]
}
}
}
Remplacez les éléments suivants :
LOGO_URL: URL d'un logo ou d'une image. Il doit s'agir d'une URL publique.LOGO_ALT_TEXT: texte alternatif du logo ou de l'image, par exempleCymbal Labs Logo.DESCRIPTION: incitation à l'action incitant les utilisateurs à se connecter, par exempleSign in to get started.- Pour mettre à jour le bouton de connexion :
AUTHORIZATION_REDIRECT: URL de l'application Web qui gère les autorisations.- Facultatif: Pour modifier la couleur du bouton, mettez à jour les valeurs flottantes RVBA du champ
color.
TEXT_SIGN_UP: texte qui invite les utilisateurs à créer un compte s'ils n'en ont pas. Exemple :New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.