Si votre module complémentaire Google Workspace se connecte à un service ou à une API 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.
- Affiche une interface de fiche qui invite les utilisateurs à se connecter au service.
- Actualisez le module complémentaire afin que les utilisateurs puissent accéder au service ou à la ressource protégée.
Si votre module complémentaire ne nécessite que l'identité de l'utilisateur, vous pouvez authentifier directement les utilisateurs à l'aide de leur ID Google Workspace ou de leur adresse e-mail. Si vous souhaitez 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 si une autorisation est requise
Lorsque vous utilisez 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.
Le module complémentaire doit détecter ces cas afin que les utilisateurs puissent se connecter et accéder au service.
Inviter les utilisateurs à se connecter à votre service
Lorsque votre module complémentaire détecte que une autorisation est requise, il doit renvoyer une interface de fiche pour inviter les utilisateurs à se connecter au service. La carte de connexion doit rediriger les utilisateurs afin qu'ils terminent le processus d'authentification et d'autorisation tiers 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'ID unique de l'utilisateur et peut être mise en corrélation avec l'ID de votre module complémentaire.
Créer et renvoyer une carte 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 présente 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 de la ressource ou du service protégé. Ce nom est visible par 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.
Carte d'autorisation personnalisée
Pour modifier l'invite d'autorisation, vous pouvez créer une fiche 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 pour Google Workspace Marketplace, consultez À propos de l'examen des applications.
Les images suivantes illustrent un exemple de carte 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 invitant l'utilisateur à créer un compte s'il n'en a pas. Exemple :New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.