Présentation de l'API Admin Settings

L'API Admin Settings permet aux administrateurs de domaines Google Workspace de récupérer et de modifier les paramètres de leurs domaines sous la forme de flux d'API Google Data.

Ces paramètres de domaine incluent de nombreuses fonctionnalités disponibles dans la console d'administration Google Workspace. Cette API peut, par exemple, servir à créer un panneau de configuration personnalisé ou à intégrer des domaines Google Workspace dans un ancien environnement existant.

L'API Admin Settings implémente le protocole Google Data API. L'API Google Data est conforme au modèle de publication et de modification du protocole de publication Atom (AtomPub). Les requêtes HTTP AtomPub utilisent l'approche de conception RESTful (Representational Set Transfer) pour les services Web. Pour en savoir plus, consultez le guide du développeur Google Data.

Audience

Ce document s'adresse aux développeurs qui souhaitent écrire des applications clientes capables de modifier et de récupérer des informations sur les domaines Google Workspace. Il fournit des exemples d'interactions de base avec l'API Admin Settings à l'aide de XML et HTTP bruts.

Ce document part du principe que vous comprenez les idées générales du protocole Google Data API et que vous connaissez la console d'administration Google Workspace. Pour en savoir plus sur la console d'administration, consultez Utiliser votre console d'administration.

Premiers pas

Création d'un compte

L'API Paramètres d'administration est activée pour les comptes Google Workspace. Créez un compte Google Workspace à des fins de test. Le service Paramètres d'administration utilise des comptes Google. Si vous possédez déjà un compte sur un domaine Google Workspace, vous n'avez rien d'autre à faire.

À propos des types de flux de l'API Admin Settings

L'API Admin Settings vous permet de gérer les catégories de paramètres de domaine suivantes :

Paramètres d'authentification unique

L'authentification unique (SSO) basée sur SAML permet aux utilisateurs d'utiliser les mêmes identifiant et mot de passe pour les services hébergés Google Workspace et pour les autres services que vous hébergez peut-être dans votre organisation. Plus précisément, lorsqu'une application Web hébergée, telle que Google Workspace, utilise l'authentification unique, elle redirige les utilisateurs vers le fournisseur d'identité de votre organisation pour les authentifier lorsqu'ils se connectent. Pour en savoir plus, consultez Comprendre l'authentification unique basée sur SAML pour Google Workspace.

La configuration de l'authentification unique consiste à saisir les informations nécessaires pour que le service Google Workspace communique avec le fournisseur d'identité qui stocke les informations de connexion de vos utilisateurs. Elle consiste également à configurer les liens vers lesquels les utilisateurs doivent être redirigés pour se connecter, se déconnecter et modifier leur mot de passe. L'API Admin Settings vous permet de mettre à jour et de récupérer ces paramètres de manière programmatique. Google utilise la clé publique que vous avez générée pour vérifier cette requête d'authentification unique auprès de votre fournisseur d'identité et s'assurer que la réponse SAML de la clé privée n'a pas été modifiée lors de la transmission sur le réseau.

Pour obtenir un bref résumé spécifique à l'API sur l'utilisation des paramètres d'authentification unique, récupérez le certificat de clé publique auprès de votre fournisseur d'identité, enregistrez la clé publique auprès de Google et configurez vos paramètres de requête d'authentification unique basée sur SAML. Pour les messages d'erreur, consultez Résoudre les problèmes liés au SSO :

  • Générez vos clés : avec votre fournisseur d'identité, générez un ensemble de clés publiques et privées à l'aide des algorithmes DSA ou RSA. La clé publique se trouve dans un certificat au format X.509. Pour en savoir plus sur les clés de signature de l'authentification unique basée sur SAML, consultez Générer des clés et des certificats pour le service d'authentification unique Google Workspace.
  • Enregistrez-vous auprès de Google : utilisez les paramètres d'authentification unique de l'API Admin Settings pour enregistrer votre certificat de clé publique auprès de Google.
  • Configurez vos paramètres SSO : utilisez les paramètres d'authentification unique de l'API Admin Settings pour configurer les paramètres utilisés pour communiquer avec les serveurs du fournisseur d'identité du domaine.

Paramètres de passerelle et de routage

Ce flux permet aux administrateurs de domaine de contrôler le routage des e-mails pour leurs domaines.

Les opérations de routage des e-mails permettent aux administrateurs de spécifier les paramètres de routage des e-mails au niveau du domaine. Cette fonctionnalité est semblable à celle de routage des e-mails disponible dans les paramètres Gmail de la console d'administration. Pour en savoir plus, consultez Routage des e-mails et Configuration de la double distribution de la fonctionnalité de routage des e-mails.

Exemple de requête et de réponse XML de l'API Admin Settings

Ce document fournit des exemples de code de requêtes et de réponses de base de l'API Admin Settings utilisant le format XML brut et HTTP. Cet exemple de langue par défaut du domaine montre la syntaxe XML et HTTP complète pour le corps d'une entrée de requête et de réponse, qui est commun à chaque opération :

Pour modifier le paramètre de passerelle de messagerie sortante d'un domaine, envoyez une requête HTTP PUT à l'URL du flux de passerelle :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

La requête AtomPub entry XML pour la langue par défaut du domaine PUT est la suivante :

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:apps='http://schemas.google.com/apps/2006'>
  <apps:property name='smartHost' value='smtp.out.domain.com' />
  <apps:property name='smtpMode' value='SMTP' />
</atom:entry>

À l'exception des propriétés et valeurs spécifiques à l'opération, les éléments atom:property représentent une seule paire clé/valeur contenant des informations sur une propriété que vous souhaitez récupérer ou mettre à jour. Ces champs sont communs à tous les corps de requête de l'API Admin Settings.

L'élément de réponse de la langue par défaut du domaine entry renvoie les propriétés smartHost et smtpMode, ainsi que la syntaxe XML commune à tous les corps de réponse de l'API Admin Settings :

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<id>https://apps-apis.google.com/a/feeds/domain/2.0/domainName/email/gateway</id>
<updated>2008-12-17T23:59:23.887Z</updated>
<link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</entry>

Gérer les paramètres d'authentification unique

La fonctionnalité d'authentification unique (SSO) de Google Workspace permet aux utilisateurs de se connecter à plusieurs services en ne saisissant qu'une seule fois leur identifiant et leur mot de passe. Ce mot de passe est stocké par le fournisseur d'identité du domaine, et non par Google Workspace. Pour en savoir plus, consultez la page du Centre d'aide sur le SSO. Les sections suivantes présentent le format XML utilisé pour les paramètres du Single Sign-On.

Récupérer les paramètres d'authentification unique

Pour récupérer les paramètres d'authentification unique, envoyez une requête HTTP GET à l'URL du flux général SSO et incluez un en-tête Authorization comme décrit dans Authentification auprès du service de paramètres d'administration. Pour les messages d'erreur, consultez Dépannage de l'authentification unique :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les paramètres SSO du domaine.

Le fichier XML de réponse GET renvoie les propriétés samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist et useDomainSpecificIssuer :

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
...
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='true'/>
<apps:property name='ssoWhitelist' value='CIDR formatted IP address'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

Voici les propriétés :

samlSignonUri
URL du fournisseur d'identité à laquelle Google Workspace envoie la requête SAML pour l'authentification des utilisateurs.
samlLogoutUri
Adresse vers laquelle les utilisateurs seront redirigés lorsqu'ils se déconnecteront de l'application Web.
changePasswordUri
Adresse à laquelle les utilisateurs seront redirigés lorsqu'ils souhaiteront modifier leur mot de passe SSO pour l'application Web.
enableSSO
Active l'authentification unique basée sur SAML pour ce domaine. Si vous avez déjà configuré des paramètres d'authentification unique et que vous avez ensuite défini enableSSO sur enableSSO=false, les paramètres que vous avez saisis précédemment sont toujours enregistrés.
ssoWhitelist
Une ssoWhitelist est une adresse IP de masque de réseau au format CIDR (Classless Inter-Domain Routing). La liste ssoWhitelist détermine les utilisateurs qui se connectent à l'aide de l'authentification unique et ceux qui se connectent à l'aide de la page d'authentification du compte Google Workspace. Si aucun masque n'est spécifié, tous les utilisateurs se connecteront à l'aide de l'authentification unique. Pour en savoir plus, consultez Fonctionnement des masques de réseau.
useDomainSpecificIssuer
Un émetteur spécifique au domaine peut être utilisé dans la requête SAML envoyée au fournisseur d'identité. Bien que cette fonctionnalité ne soit pas nécessaire pour la plupart des déploiements SSO, elle est utile dans les grandes entreprises qui utilisent un seul fournisseur d'identité pour authentifier une organisation entière avec plusieurs sous-domaines. L'émetteur de domaine spécifique détermine le sous-domaine à associer à la demande. Pour en savoir plus, consultez Comment fonctionne l'élément "Émetteur" dans la requête SAML ?

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Mettre à jour les paramètres de l'authentification unique

Pour mettre à jour les paramètres SSO d'un domaine, commencez par récupérer les paramètres SSO à l'aide de l'opération Récupérer les paramètres d'authentification unique, modifiez-les, puis envoyez une requête PUT à l'URL du flux SSO. Assurez-vous que la valeur <id> de votre entrée modifiée correspond exactement à celle de l'entrée existante.<id> Incluez un en-tête Authorization, comme décrit dans S'authentifier auprès du service API Admin Settings. Pour les messages d'erreur, consultez Résoudre les problèmes liés au SSO.

Lorsque vous mettez à jour les paramètres d'authentification unique, envoyez une requête HTTP PUT à l'URL du flux général SSO :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

Le corps XML de la requête PUT est le suivant :

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='enableSSO' value='false' />
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon' />
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout' />
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword' />
<apps:property name='ssoWhitelist' value='127.0.0.1/32' />
<apps:property name='useDomainSpecificIssuer' value='false'/>
</atom:entry>

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les paramètres SSO.

Le code XML de la réponse PUT est le suivant :

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='false'/>
<apps:property name='ssoWhitelist' value='127.0.0.1/32'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Les modifications apportées aux paramètres d'authentification unique ne sont pas autorisées lorsque le client cible a activé l'approbation multipartite pour les actions sensibles. Les requêtes échoueront avec les codes d'erreur errorCode="1811" et reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Récupérer la clé de signature de l'authentification unique

Pour récupérer la clé de signature de l'authentification unique, envoyez une requête HTTP GET à l'URL du flux de clés de signature de l'authentification unique et incluez un en-tête Authorization, comme décrit dans S'authentifier auprès du service de paramètres d'administration. Pour les messages d'erreur, consultez Dépannage de l'authentification unique :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec la clé de signature.

Le fichier XML de réponse GET renvoie la propriété signingKey :

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</entry>

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Mettre à jour la clé de signature de l'authentification unique

Pour mettre à jour la clé de signature SSO d'un domaine, commencez par récupérer la clé de signature à l'aide de l'opération Récupérer la clé de signature de l'authentification unique, modifiez-la, puis envoyez une requête PUT à l'URL du flux de clés de signature SSO. Assurez-vous que la valeur <id> de votre entrée modifiée correspond exactement à celle de l'entrée existante.<id> Pour en savoir plus sur les clés de signature de l'authentification unique basée sur SAML, consultez Générer des clés et des certificats pour le service d'authentification unique Google Workspace.

Lorsque vous mettez à jour la clé de signature de l'authentification unique, envoyez une requête HTTP PUT à l'URL du flux de clés de signature de l'authentification unique :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

Le code XML de la requête PUT est le suivant :

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</atom:entry>

Les modifications apportées aux paramètres d'authentification unique ne sont pas autorisées lorsque le client cible a activé l'approbation multipartite pour les actions sensibles. Les requêtes échoueront avec les codes d'erreur errorCode="1811" et reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Gérer la passerelle et le routage des e-mails

La section sur la passerelle de messagerie sortante montre comment l'API Admin Settings prend en charge le routage sortant des e-mails des utilisateurs de votre domaine. La section sur le routage des e-mails indique comment router les messages vers un autre serveur de messagerie.

Récupérer les paramètres de la passerelle de messagerie sortante

Pour récupérer les paramètres de la passerelle de messagerie sortante, envoyez une requête HTTP GET à l'URL du flux de la passerelle et incluez un en-tête Authorization comme décrit dans S'authentifier auprès du service de paramètres d'administration :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub contenant les informations sur l'état de la passerelle de messagerie.

La réponse GET renvoie les propriétés smartHost et smtpMode. Pour en savoir plus sur ces propriétés, consultez Mettre à jour les paramètres de la passerelle de messagerie sortante.

Voici un exemple de réponse possible :

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='smartHost' value='smtpout.domain.com'/>
<apps:property name='smtpMode' value='SMTP'/>
</entry>

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Mettre à jour les paramètres de la passerelle de messagerie sortante

Pour mettre à jour le paramètre de passerelle de messagerie sortante d'un domaine, envoyez une requête HTTP PUT à l'URL du flux de passerelle :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Le code XML de la requête PUT est le suivant :

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>

Voici les propriétés de la requête :

smartHost
 Adresse IP ou nom d'hôte de votre serveur SMTP. Google Workspace route les e-mails sortants vers ce serveur.
smtpMode
La valeur par défaut est SMTP. Une autre valeur, SMTP_TLS, sécurise une connexion avec TLS lors de la remise du message.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi que le flux AtomPub avec l'état des paramètres de la passerelle de messagerie.

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Gérer les paramètres de routage des e-mails

Commencez par créer une requête XML :

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='routeDestination' value='route-smtp.domain.com'/>
<apps:property name='routeRewriteTo' value='true'/>
<apps:property name='routeEnabled' value='true'/>
<apps:property name='bounceNotifications' value='true'/>
<apps:property name='accountHandling' value='can be either allAccounts | provisionedAccounts | unknownAccounts'/>
</atom:entry>

Voici les propriétés de la requête :

routeDestination
Cette destination correspond au nom d'hôte ou à l'adresse IP du serveur de messagerie SMTP-In vers lequel l'e-mail est acheminé. Le nom d'hôte ou l'adresse IP doivent être résolus pour Google. Pour en savoir plus sur la résolution des noms d'hôte de messagerie, consultez Tester Google Workspace avec le routage des e-mails.
routeRewriteTo
Si la valeur est "true", le champ to: de l'enveloppe SMTP du message est remplacé par le nom d'hôte de destination (user@destination's hostname), et le message est distribué à cette adresse utilisateur sur le serveur de messagerie de destination. Si la valeur est false, l'e-mail est envoyé à l'adresse e-mail to: (user@nom d'hôte d'origine) du message d'origine sur le serveur de messagerie de destination. Ce paramètre est semblable à celui de la console d'administration "Modifier l'enveloppe SMTP". Pour en savoir plus, consultez Paramètres de domaine pour le routage des e-mails.
routeEnabled
Si la valeur est true, la fonctionnalité de routage des e-mails est activée. Si la valeur est false, la fonctionnalité est désactivée.
bounceNotifications
Si true, Google Workspace est activé pour envoyer des notifications d'échec de remise à l'expéditeur lorsqu'un message n'a pas pu être remis.
accountHandling

Ce paramètre détermine l'impact du routage des e-mails sur les différents types d'utilisateurs du domaine :

  • allAccounts : distribue tous les e-mails à cette destination.
  • provisionedAccounts : distribue les e-mails à cette destination si l'utilisateur existe dans Google Workspace.
  • unknownAccounts : distribue les e-mails à cette destination si l'utilisateur n'existe pas dans Google Workspace. Cela correspond au paramètre "Adresse e-mail de livraison pour" de la console d'administration. Pour en savoir plus sur les prérequis et sur l'utilisation du routage des e-mails, consultez Paramètres de domaine pour le routage des e-mails. ~ Pour publier cette requête, envoyez une requête HTTP POST à l'URL du flux de routage des e-mails et incluez un en-tête Authorization comme décrit dans Authentification auprès du service de paramètres d'administration :

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/emailrouting

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub contenant les informations sur l'archive.

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Arrêt des points de terminaison le 31 octobre 2018

Nous avons abandonné les points de terminaison suivants dans le cadre de cette annonce. Elles ont été abandonnées le 31 octobre 2018 et ne sont plus disponibles.

  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguage
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationName
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsers
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsers
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPIN
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPIN
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmail
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/edition
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTime
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCode
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogo
  • https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx