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. Vous pouvez par exemple utiliser cette API pour créer un panneau de contrôle personnalisé ou intégrer des domaines Google Workspace à un ancien environnement.

L'API Admin Settings implémente le protocole de l'API Google Data. L'API Google Data est conforme au modèle de publication et de modification du protocole Atom Publishing Protocol (AtomPub). Les requêtes HTTP AtomPub utilisent l'approche de conception REST (Representational State 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 pouvant modifier et 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 brut et de HTTP.

Ce document part du principe que vous comprenez les idées générales derrière le 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

Création d'un compte

L'API Admin Settings 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 à faire.

Remarque :Configurez les paramètres de votre domaine à l'aide de l'API Admin Settings et utilisez l'API Email Settings pour configurer les paramètres de messagerie de vos utilisateurs.

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

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

Paramètres d'authentification unique

L'authentification unique SAML permet aux utilisateurs d'utiliser les mêmes identifiants et mot de passe pour les services hébergés Google Workspace et d'autres services que vous hébergez peut-être dans 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.

Pour configurer l'authentification unique, vous devez saisir les informations nécessaires pour que le service Google Workspace puisse communiquer avec le fournisseur d'identité qui stocke les informations de connexion de vos utilisateurs. Vous devez également configurer les liens vers lesquels les utilisateurs doivent être redirigés pour se connecter, se déconnecter et modifier leurs mots de passe. L'API Admin Settings vous permet de mettre à jour et de récupérer ces paramètres par programmation. Google utilise votre clé publique générée pour vérifier cette requête SSO 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écapitulatif spécifique à l'API sur l'utilisation des paramètres SSO, obtenez le certificat de votre 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 SSO basés sur SAML. Pour les messages d'erreur, consultez Dépannage de l'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ées sur SAML, consultez Générer des clés et des certificats pour le service d'authentification unique Google Workspace.
• Enregistrer 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.

Remarque :Pour les protocoles qui n'utilisent pas de flux de connexion sur le Web, comme certains clients de messagerie POP/IMAP, les utilisateurs se connectent directement avec leur nom d'utilisateur et leur mot de passe Google Workspace.

Paramètres de la passerelle et du 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 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 pour les requêtes et les réponses de base de l'API Admin Settings à l'aide de XML brut et de HTTP. Cet exemple de langue par défaut du domaine montre la syntaxe XML et HTTP complète du corps d'une entrée de requête et de réponse, qui est commune à chaque opération:

Pour modifier le paramètre de la passerelle de messagerie sortante du domaine, envoyez un PUT HTTP à l'URL du flux de la passerelle:

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

Le code XML AtomPub entry de la requête PUT de la langue par défaut du domaine 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>

À 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. Ils 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 sans avoir à saisir leur nom d'utilisateur et leur mot de passe qu'une seule fois. 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 l'authentification unique. Les sections suivantes présentent le format XML utilisé pour les paramètres d'authentification unique.

Récupération des paramètres d'authentification unique

Pour récupérer les paramètres d'authentification unique, envoyez un GET HTTP à l'URL du flux général de l'authentification unique et incluez un en-tête Authorization, comme décrit dans la section S'authentifier auprès du service de paramètres d'administration. Pour les messages d'erreur, consultez Résoudre les problèmes liés à 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 d'authentification unique du domaine.

La réponse XML 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:

samlSignonUri

URL du fournisseur d'identité vers laquelle Google Workspace envoie la requête SAML pour l'authentification des utilisateurs.

samlLogoutUri

Adresse à 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 voudront 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 précédemment saisis sont toujours enregistrés.

ssoWhitelist

Une ssoWhitelist est une adresse IP de masque de réseau au format CIDR (Classless Inter-Domain Routing). 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 connectent à 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 qu'elle ne soit pas nécessaire pour la plupart des déploiements SSO, cette fonctionnalité est utile dans les grandes entreprises qui utilisent un seul fournisseur d'identité pour authentifier l'ensemble d'une organisation avec plusieurs sous-domaines. Indiquer l'émetteur de domaine spécifique permet de déterminer le sous-domaine à associer à la requête. Pour en savoir plus, consultez la section 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 la section Codes d'état HTTP.

Modifier les paramètres de l'authentification unique

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

Lorsque vous mettez à jour les paramètres d'authentification unique, envoyez une requête HTTP PUT à l'URL du flux général de l'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 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 autre code d'état est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez la section 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 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 un GET HTTP à l'URL du flux de clé de signature de l'authentification unique, et incluez un en-tête Authorization, comme décrit dans la section S'authentifier auprès du service de paramètres d'administration. Pour les messages d'erreur, consultez Résoudre les problèmes liés à 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.

La réponse XML 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 la section 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 la récupérer à l'aide de l'opération Récupérer la clé de signature d'authentification unique, puis modifiez-la, puis envoyez une requête PUT à l'URL du flux de clé de signature SSO. Assurez-vous que la valeur <id> de votre entrée mise à jour correspond exactement à celle de l'entrée existante.<id> Pour en savoir plus sur les clés de signature d'authentification unique basées 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 d'authentification unique, envoyez un PUT HTTP à l'URL du flux de clé de signature d'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>

Remarque :La propriété signingKey est requise pour cette requête.

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 errorCode="1811" et reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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

La section "Passerelle de messagerie sortante" explique comment l'API Admin Settings prend en charge le routage sortant du courrier des utilisateurs de votre domaine. La section "Acheminement des e-mails" explique comment router les messages vers un autre serveur de messagerie.

Récupération des paramètres de la passerelle de messagerie sortante

Pour récupérer les paramètres de la passerelle de messagerie sortante, envoyez un GET HTTP à l'URL du flux de la passerelle et incluez un en-tête Authorization, comme décrit dans la section 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.

Remarque :Vous devez disposer d'une édition Google Workspace éligible pour utiliser la fonctionnalité de passerelle sortante Google Workspace.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub contenant les informations d'é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 autre code d'état est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez la section Codes d'état HTTP.

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

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

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

Remarque :Vous devez disposer d'une édition Google Workspace éligible pour utiliser la fonctionnalité de passerelle sortante Google Workspace.

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>

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 le courrier sortant vers ce serveur.

smtpMode

La valeur par défaut est SMTP. Une autre valeur, SMTP_TLS, sécurise une connexion avec TLS lors de l'envoi du message.

Remarque :Suivez les instructions de votre MTA pour configurer les e-mails relayés envoyés depuis Google Workspace.

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.

Remarque :Envoyez un e-mail depuis Google Workspace à un utilisateur en dehors de votre domaine pour vérifier que le courrier sortant envoyé via votre passerelle fonctionne après vos modifications.

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 la section 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 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 par 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 (nom d'hôte user@destination) et le message est distribué à cette adresse utilisateur sur le serveur de messagerie de destination. Si la valeur est false, l'e-mail est distribué à l'adresse e-mail to: du message d'origine (user@nom d'hôte d'origine) sur le serveur de messagerie de destination. Cela ressemble 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 autorisé à envoyer des notifications de retour à l'expéditeur en cas d'échec de la distribution.

accountHandling

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

• allAccounts : tous les e-mails sont envoyés à cette destination.
• provisionedAccounts : permet de distribuer le courrier à cette destination si l'utilisateur existe dans Google Workspace.
• unknownAccounts : envoyez les e-mails à cette destination si l'utilisateur n'existe pas dans Google Workspace. Il s'agit d'une option semblable à celle de la console d'administration intitulée "Adresse e-mail de diffusion pour". Pour en savoir plus sur les conditions préalables 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 un POST HTTP à l'URL du flux de routage des e-mails et incluez un en-tête Authorization, comme décrit dans la section S'authentifier 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 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 la section 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