L'API S/MIME de Gmail fournit un accès programmatique pour gérer les certificats de messagerie S/MIME pour les utilisateurs d'un domaine Google Workspace .
Un administrateur doit activer S/MIME pour le domaine pour que les certificats fonctionnent.
La norme S/MIME fournit des spécifications pour le chiffrement par clé publique et la signature des données MIME. Lorsque vous configurez des certificats S/MIME dans le compte d'un utilisateur, Gmail utilise ce certificat comme suit:
- Gmail utilise le certificat et la clé privée de l'utilisateur pour signer les messages sortants.
- Gmail déchiffre les messages entrants à l'aide de la clé privée de l'utilisateur.
- Gmail utilise le certificat et la clé publique du destinataire pour chiffrer les messages sortants.
- Gmail vérifie les messages entrants à l'aide du certificat et de la clé publique de l'expéditeur.
Vous générez des certificats S/MIME individuels et les importez à l'aide de l'API. Chaque certificat S/MIME correspond à un alias spécifique d'un compte de messagerie d'utilisateur. Les alias incluent l'adresse e-mail principale ainsi que les adresses "Envoyer en tant que" personnalisées. Un seul certificat S/MIME est marqué comme valeur par défaut pour chaque alias.
Autoriser l'accès à l'API
Il existe deux formes d'autorisation d'accès à l'API:
- Vous pouvez utiliser un compte de service avec délégation au niveau du domaine. Pour en savoir plus sur ces termes, consultez la section Termes de présentation de l'authentification et des autorisations. Pour en savoir plus sur l'activation de cette option, consultez la page Créer un compte de service avec délégation au niveau du domaine.
- Vous pouvez utiliser un flux OAuth2 standard exigeant le consentement de l'utilisateur final pour obtenir un jeton d'accès OAuth2. Pour en savoir plus, consultez la section Présentation de l'authentification et de l'autorisation. Pour utiliser cette option, l'administrateur de domaine doit cocher la case "Accès de l'utilisateur final à l'API S/MIME activé" dans le panneau de configuration du domaine.
Champs d'application des LCA
Cette API repose sur les mêmes champs d'application de la LCA que les méthodes Gmail sendAs:
- gmail.settings.basic
- Ce champ d'application est requis pour mettre à jour le S/MIME principal SendAs.
- gmail.settings.sharing
- Ce champ d'application est requis pour la mise à jour personnalisée à partir de S/MIME.
Utiliser l'API
La ressource users.settings.sendAs.smimeInfo fournit les méthodes que vous utilisez pour gérer les certificats S/MIME. Chaque certificat est associé à un alias d'envoi pour un utilisateur.
Importer une clé S/MIME
Utilisez la méthode smimeInfo.insert() pour importer une nouvelle clé S/MIME pour un alias appartenant à un utilisateur. Vous identifiez l'alias cible à l'aide des paramètres suivants:
- userId
- Adresse e-mail de l'utilisateur. Vous pouvez utiliser la valeur spéciale
me
pour indiquer l'utilisateur actuellement authentifié. - sendAsEmail
- Alias pour lequel vous importez la clé. Il s'agit de l'adresse e-mail qui apparaît dans l'en-tête "De" des e-mails envoyés avec cet alias.
Le certificat et la clé privée S/MIME doivent être présents dans le champ pkcs12
dans ce format. Aucun autre champ ne doit être défini dans la requête. Le champ PKCS12 doit contenir à la fois la clé S/MIME de l'utilisateur et la chaîne du certificat de signature. L'API effectue des validations standards sur ce champ avant de l'accepter, en vérifiant les éléments suivants:
- L'objet correspond à l'adresse e-mail spécifiée.
- Les délais d'expiration sont valides.
- L'autorité de certification (CA) émettrice figure dans notre liste d'organismes de confiance.
- Les certificats respectent les contraintes techniques de Gmail.
Si la clé est chiffrée, le mot de passe doit se trouver dans le champ encryptedKeyPassword
. Les appels insert() réussis renverront l'ID de smimeInfo, qui pourra être utilisé pour faire référence à la clé à l'avenir.
Lister les clés S/MIME d'un utilisateur
Utilisez la méthode smimeInfo.list() pour renvoyer la liste des clés S/MIME de l'utilisateur donné pour l'alias donné. Vous identifiez l'alias cible à l'aide des paramètres suivants:
- userId
- Adresse e-mail de l'utilisateur. Vous pouvez utiliser la valeur spéciale
me
pour indiquer l'utilisateur actuellement authentifié. - sendAsEmail
- Alias pour lequel répertorier les clés. Il s'agit de l'adresse e-mail qui apparaît dans l'en-tête "De" des e-mails envoyés avec cet alias.
Récupérer les clés S/MIME d'un alias
Utilisez la méthode smimeInfo.get() pour renvoyer les clés S/MIME spécifiques d'un alias d'envoi spécifique à un utilisateur. Vous identifiez l'alias cible à l'aide des paramètres suivants:
- userId
- Adresse e-mail de l'utilisateur. Vous pouvez utiliser la valeur spéciale
me
pour indiquer l'utilisateur actuellement authentifié. - sendAsEmail
- Alias pour lequel vous récupérez les clés. Il s'agit de l'adresse e-mail qui apparaît dans l'en-tête "De" des e-mails envoyés avec cet alias.
Supprimer une clé S/MIME
Utilisez la méthode smimeInfo.delete() pour supprimer la clé S/MIME spécifiée d'un alias. Vous identifiez l'alias cible à l'aide des paramètres suivants:
- userId
- Adresse e-mail de l'utilisateur. Vous pouvez utiliser la valeur spéciale
me
pour indiquer l'utilisateur actuellement authentifié. - sendAsEmail
- Alias pour lequel vous récupérez les clés. Il s'agit de l'adresse e-mail qui apparaît dans l'en-tête "De" des e-mails envoyés avec cet alias.
- id
- ID immuable pour SmimeInfo.
Définir la clé S/MIME par défaut pour un alias
Utilisez la méthode smimeInfo.setDefault() pour marquer la clé S/MIME spécifiée comme clé par défaut pour l'alias spécifié. Vous identifiez l'alias cible à l'aide des paramètres suivants:
- userId
- Adresse e-mail de l'utilisateur. Vous pouvez utiliser la valeur spéciale
me
pour indiquer l'utilisateur actuellement authentifié. - sendAsEmail
- Alias pour lequel vous récupérez les clés. Il s'agit de l'adresse e-mail qui apparaît dans l'en-tête "De" des e-mails envoyés avec cet alias.
- id
- ID immuable pour SmimeInfo.
Exemple de code
Les exemples de code suivants illustrent l'utilisation de l'API pour gérer les certificats S/MIME pour une organisation comptant plusieurs utilisateurs.
Créer une ressource SmimeInfo pour un certificat S/MIME
L'exemple de code suivant montre comment lire un certificat à partir d'un fichier, l'encoder dans une chaîne base64url et l'attribuer au champ pkcs12
de la ressource smimeInfo
:
Java
Python
Importation d'un certificat S/MIME
Pour importer un certificat, appelez smimeInfo.insert
et fournissez la ressource smimeInfo
dans le corps de la requête:
Java
Python
Exemples de gestion des certificats de nombreux utilisateurs
Vous pouvez avoir besoin de gérer les certificats de plusieurs utilisateurs à la fois dans l'organisation. Les exemples suivants montrent comment gérer les certificats de plusieurs utilisateurs dans un appel groupé.
Insérer des certificats à partir d'un fichier CSV
Supposons que vous disposiez d'un fichier CSV listant les ID utilisateur et le chemin d'accès au certificat de chaque utilisateur:
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
Java
Vous pouvez utiliser les appels createSmimeInfo
et insertSmimeInfo
précédemment utilisés pour importer les certificats comme spécifié dans le fichier CSV:
Python
Vous pouvez utiliser les appels create_smime_info
et insert_smime_info
précédemment utilisés pour importer les certificats comme spécifié dans le fichier CSV:
Gestion des certificats
Cet exemple combine plusieurs appels de l'API smimeInfo
pour vous montrer comment gérer les certificats pour votre organisation. Il répertorie les certificats de l'utilisateur. Si le certificat par défaut a expiré ou n'est pas défini, il importe le certificat se trouvant dans le fichier spécifié. Ensuite, il définit par défaut le certificat dont l'expiration est la plus éloignée dans le futur.
Elle est ensuite appelée à partir d'une fonction qui traite un fichier CSV, comme dans l'exemple précédent.