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 permet par exemple de créer un panneau de configuration personnalisé ou d'intégrer des domaines Google Workspace dans un ancien environnement existant.

L'API Admin Settings met en œuvre le protocole de l'API Google Data. L'API Google Data est conforme au modèle de publication et d'édition du protocole AtomPub (Atom Publishing). 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 de données Google.

Public visé

Ce document est destiné aux développeurs qui souhaitent développer des applications clientes capables de modifier et de récupérer des informations sur les domaines Google Workspace. Elle fournit des exemples d'interactions de base de l'API Admin Settings au format XML brut et HTTP.

Dans ce document, nous partons du principe que vous comprenez les concepts généraux sous-jacents au protocole de l'API Google Data et que vous connaissez la console d'administration Google Workspace. Pour plus d'informations 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. Par conséquent, si vous possédez déjà un compte dans un domaine Google Workspace, vous n'avez rien d'autre à 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 ces catégories de paramètres de domaine:

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 par Google Workspace et pour les 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 authentifier les utilisateurs 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 de 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, ainsi que la configuration des liens vers lesquels les utilisateurs doivent être envoyé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 par programmation. Google utilise la clé publique générée pour vérifier cette demande SSO 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 réseau.

Pour obtenir un bref résumé de l'utilisation des paramètres SSO spécifiques à l'API, obtenez votre 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 SAML. Pour les messages d'erreur, consultez la section Résoudre les problèmes liés à 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 de Google Workspace.
• S'inscrire 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.
• Configurer vos paramètres d'authentification unique : utilisez les paramètres d'authentification unique de l'API Admin Settings pour configurer les paramètres de communication avec les serveurs du fournisseur d'identité du domaine.

Remarque :Pour les protocoles qui n'utilisent pas de flux de connexion Web, tels que 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 passerelle et d'itinéraire

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 à la fonctionnalité de routage des e-mails dans les paramètres Gmail de la console d'administration. Pour en savoir plus, consultez les articles Routage des e-mails et Configuration de la double distribution pour la fonctionnalité de routage des e-mails.

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

Ce document fournit des exemples de code des requêtes et réponses de base de l'API Admin Settings au format XML brut et HTTP. Cet exemple de langage par défaut associé au domaine montre la syntaxe XML et HTTP complète du corps d'une entrée de requête et de réponse, commune à 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 langue par défaut du domaine PUT pour le fichier XML AtomPub entry est:

<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 propres aux opérations, 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 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>

Gestion des paramètres d'authentification unique

La fonctionnalité d'authentification unique (SSO) de Google Workspace permet aux utilisateurs de se connecter à plusieurs services en saisissant leur identifiant et leur mot de passe 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 sur l'authentification unique dans le Centre d'aide. Les sections suivantes décrivent 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 générale du flux SSO et incluez un en-tête Authorization comme décrit dans la section Authentification auprès du service Admin Settings. Pour les messages d'erreur, consultez la section Dépannage de l'authentification unique:

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

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Une réponse positive 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>

Ces propriétés sont les suivantes:

samlSignonUri

URL du fournisseur d'identité à laquelle Google Workspace envoie la requête SAML d'authentification de l'utilisateur.

samlLogoutUri

Adresse à laquelle les utilisateurs sont redirigés lorsqu'ils se déconnectent de l'application Web.

changePasswordUri

Adresse à laquelle les utilisateurs sont redirigés lorsqu'ils souhaitent 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 par la suite défini enableSSO sur enableSSO=false, les paramètres précédemment saisis sont toujours enregistrés.

ssoWhitelist

Une ssoListe est une adresse IP de masque réseau au format CIDR (Classless Inter-Domain Routing). La liste blanche ssoliste détermine quels utilisateurs se connectent à l'aide de l'authentification unique et quels utilisateurs 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 réseau.

useDomainSpecificIssuer

Un émetteur spécifique au domaine peut être utilisé dans la requête SAML adressé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 une organisation entière avec plusieurs sous-domaines. Indiquer 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 "Émetteur" de 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.

Mise à jour des paramètres d'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, modifiez-les, puis envoyez une requête PUT à l'URL du flux SSO. Assurez-vous que la valeur <id> se trouve dans votre entrée mise à jour et correspond exactement à la valeur <id> de l'entrée existante. Incluez un en-tête Authorization comme décrit dans la section S'authentifier auprès du service de l'API Admin Settings. Pour les messages d'erreur, consultez la section Dépannage de l'authentification unique.

Lors de la mise à jour des paramètres d'authentification unique, envoyez une requête HTTP PUT à l'URL générale du flux SSO:

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

Le corps XML de la requête PUT se présente comme suit:

<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 positive 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 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.

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

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

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

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Une réponse positive 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 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.

Mise à jour de la clé de signature d'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 SSO, modifiez-la, puis envoyez une requête PUT à l'URL du flux de la clé de signature SSO. Assurez-vous que la valeur <id> se trouve dans votre entrée mise à jour et correspond exactement à la valeur <id> de l'entrée existante. 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 de Google Workspace.

Lors de la mise à jour de la clé de signature unique, envoyez une requête HTTP PUT à l'URL du flux de la clé de signature SSO:

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

Le code XML de la requête PUT se présente comme suit:

<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 obligatoire pour cette requête.

Gestion de la passerelle et du routage de messagerie

La section "Passerelle de messagerie sortante" indique comment l'API Admin Settings prend en charge le routage sortant des messages provenant des utilisateurs de votre domaine. La section "Routage des e-mails" indique comment acheminer les messages vers un autre serveur de messagerie.

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

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

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

Le corps de la requête ne comporte aucun paramètre pour cette opération.

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

Une réponse positive 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 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 la section Codes d'état HTTP.

Mise à jour des paramètres de 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

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

Le code XML de la requête PUT se présente comme suit:

<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 messages 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 distribution du message.

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

Une réponse positive 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 externe à 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 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.

Gestion des 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 vers lequel l'e-mail est routé. 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 Pilote Google Workspace avec 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 de destination utilisateur@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 envoyé à l'adresse to: du message d'origine (utilisateur@nom d'hôte d'origine) sur le serveur de messagerie de destination. Cette option est semblable au paramètre "Modifier l'enveloppe SMTP" de la console d'administration. Pour en savoir plus, consultez Paramètres du 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 non-distribution à l'expéditeur en cas d'échec de la distribution.

accountHandling

Ce paramètre détermine la manière dont le routage des e-mails affecte les différents types d'utilisateurs du domaine:

• allAccounts : distribue tous les e-mails à cette destination.
• provisionedAccounts : distribue les messages à cette destination, si l'utilisateur existe dans Google Workspace.
• unknownAccounts : distribue les messages à cette destination si l'utilisateur n'existe pas dans Google Workspace. Ce paramètre est semblable au paramètre "Distribution de l'e-mail à" de la console d'administration. Pour en savoir plus sur les conditions préalables et l'utilisation du routage des e-mails, consultez Paramètres du 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 Admin Settings:

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

Une réponse positive 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 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.

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