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, être utilisée pour créer un panneau de configuration personnalisé ou intégrer des domaines Google Workspace dans un environnement hérité existant.

L'API Admin Settings implémente le protocole de l'API Google Data. Les API Google Data sont conformes 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 des API Google Data.

Audience

Ce document est destiné 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 code XML et HTTP bruts.

Dans ce document, nous partons du principe que vous comprenez les idées générales du the protocole de l'API Google Data 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

Pour commencer à utiliser l'API Admin Settings, configurez d'abord votre compte.

Créer un compte

L'API Admin Settings est activée pour les comptes Google Workspace. Inscrivez-vous à un compte Google Workspace à des fins de test. Le service Admin Settings utilise les comptes Google. Si vous disposez déjà d'un compte sur un domaine Google Workspace, vous n'avez rien à 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 le même identifiant et le même mot de passe pour les services hébergés Google Workspace et pour d'autres services que vous hébergez peut-être au sein de votre organisation. Plus précisément, lorsque vous utilisez l'authentification unique, une application Web hébergée, telle que Google Workspace, 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 implique la saisie des informations nécessaires pour que le service Google Workspace communique avec le fournisseur d'identité qui stocke les informations de connexion de vos utilisateurs, ainsi que la configuration des 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 que la réponse SAML de la clé privée n'a pas été modifiée lors de la transmission réseau.

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

  • 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 d'authentification unique basée sur SAML, consultez Générer des clés et des certificats pour le service d'authentification unique Google Workspace.
  • Inscrivez-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 d'authentification unique : 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. Cela est semblable à la fonctionnalité de routage des e-mails des 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 à l'aide de code XML et HTTP bruts. 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 du 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 PUT AtomPub XML entry de la langue par défaut du domaine 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 des valeurs spécifiques à l'opération, les éléments atom:property représentent une paire clé/valeur unique contenant des informations sur une propriété que vous souhaitez récupérer ou mettre à jour. Ces éléments sont communs à tous les corps de requête de l'API Admin Settings.

L'élément entry de la réponse de la langue par défaut du domaine 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 un identifiant et un 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 Authentification unique du Centre d'aide. Les sections suivantes présentent le format XML utilisé pour les paramètres d'authentification unique.

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 d'authentification unique et incluez un en-tête Authorization comme décrit dans S'authentifier auprès du service Admin Settings. Pour les messages d'erreur, consultez Résoudre les problèmes d'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 d'authentification unique du domaine.

Le XML de la 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>

Les propriétés incluent les éléments suivants :

samlSignonUri
URL du fournisseur d'identité vers laquelle Google Workspace envoie la requête SAML pour l'authentification de l'utilisateur.
samlLogoutUri
Adresse vers laquelle les utilisateurs sont redirigés lorsqu'ils se déconnectent de l'application Web.
changePasswordUri
Adresse vers laquelle les utilisateurs sont redirigés lorsqu'ils souhaitent modifier leur mot de passe d'authentification unique 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 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 adressée au fournisseur d'identité. Bien que cette fonctionnalité ne soit pas nécessaire pour la plupart des déploiements d'authentification unique, elle est utile dans les grandes entreprises qui utilisent un seul fournisseur d'identité pour authentifier l'ensemble d'une organisation comportant plusieurs sous-domaines. L'émetteur de domaine spécifique détermine le sous-domaine à associer à la requête. Pour en savoir plus, consultez Fonctionnement de l'élément Issuer dans la requête SAML ?

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

Modifier les paramètres d'authentification unique

Pour modifier les paramètres d'authentification unique d'un domaine, récupérez d'abord les paramètres d'authentification unique à 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 d'authentification unique. Assurez-vous que la <id> valeur de votre entrée modifiée correspond exactement à la <id> de l'entrée existante. Incluez un Authorization en-tête, comme décrit dans S'authentifier auprès du service de l'API Admin Settings. Pour les messages d'erreur, consultez Résoudre les problèmes d'authentification unique.

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

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 d'authentification unique.

Le 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 autre code d'état 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 actions. Les requêtes échouent avec errorCode="1811" et reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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

Pour récupérer la clé de signature d'authentification unique, envoyez une requête HTTP GET à l'URL du flux de la clé de signature d'authentification unique et incluez un en-tête Authorization, comme décrit dans S'authentifier auprès du service Admin Settings. Pour les messages d'erreur, consultez Résoudre les problèmes d'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 XML de la 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 autre code d'état est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Modifier la clé de signature d'authentification unique

Pour modifier la clé de signature d'authentification unique d'un domaine, récupérez d'abord la clé de signature à l'aide de l' opération Récupérer la clé de signature d'authentification unique, modifiez-la, puis envoyez une requête PUT à l'URL du flux de la clé de signature d'authentification unique. Assurez-vous que la valeur <id> de votre entrée modifiée correspond exactement à la <id> de l'entrée existante. Pour en savoir plus sur les clés de signature d'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 modifiez la clé de signature d'authentification unique, envoyez une requête HTTP PUT à l'URL du flux de la clé de signature d'authentification unique :

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

Le 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 actions. Les requêtes échouent avec errorCode="1811" et reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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

La section sur la passerelle de messagerie sortante explique 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 explique comment acheminer 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 passerelle et incluez un en-tête Authorization comme décrit dans S'authentifier auprès du service Admin Settings :

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 avec 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 Modifier 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 autre code d'état est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Modifier les paramètres de la passerelle de messagerie sortante

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

Le 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>

Les propriétés de la requête sont les suivantes :

smartHost
Adresse IP ou nom d'hôte de votre serveur SMTP. Google Workspace achemine 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 autre code d'état 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>

Les propriétés de la requête sont les suivantes :

routeDestination
Cette destination est le 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 doit être résolu pour Google. Pour en savoir plus sur la résolution des noms d'hôtes de messagerie, consultez Piloter 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 remis à cette adresse utilisateur sur le serveur de messagerie de destination. Si false, l'e-mail est remis à l'adresse e-mail to: d'origine (user@original hostname) sur le serveur de messagerie de destination. Cela est semblable au paramètre "Modifier l'enveloppe SMTP" de la console d'administration. 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 la valeur est true, Google Workspace est activé pour envoyer des notifications de rebond à l'expéditeur en cas d'échec de la remise.
accountHandling
Ce paramètre détermine l'impact du routage des e-mails sur les différents types d'utilisateurs du domaine :
  • allAccounts : remet tous les e-mails à cette destination.
  • provisionedAccounts : remet les e-mails à cette destination si l'utilisateur existe dans Google Workspace.
  • unknownAccounts : remet les e-mails à cette destination si l'utilisateur n'existe pas dans Google Workspace. Cela est semblable au paramètre "Remettre les e-mails pour" de la console d'administration. Pour en savoir plus sur les prérequis et 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 S'authentifier auprès du service Admin Settings :

    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 avec les informations d'archive.

Si votre requête échoue pour une raison quelconque, un autre code d'état 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. Ils ont été arrêtés 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