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 Google Data API.

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 Google Data API. L'API Google Data est conforme au modèle de publication et d'édition AtomPub (Atom). Les requêtes HTTP AtomPub utilisent l'approche de conception Representational Set Transfer (RESTful) pour les services Web. Pour en savoir plus, consultez le guide du développeur de données Google.

Audience

Ce document est destiné aux développeurs qui souhaitent créer des applications clientes pouvant modifier et récupérer des informations sur les domaines Google Workspace. Elle fournit des exemples d'interactions de base avec l'API Admin Settings à l'aide de fichiers XML et HTTP bruts.

Dans ce document, nous partons du principe que vous avez compris les concepts généraux 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.

Getting Started

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 administrateur utilise des comptes Google. Par conséquent, 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 suivantes de paramètres du 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 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 authentifier les utilisateurs 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 communique avec le fournisseur d'identité qui stocke les informations de connexion de vos utilisateurs, et configurer les liens vers lesquels les utilisateurs doivent être envoyé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 la clé publique générée pour vérifier cette requête SSO auprès de votre fournisseur d'identité et vérifier 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 d'utilisation des paramètres SSO concernant une API, obtenez un 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 SSO 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 présente sous la forme d'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 avec Google : utilisez les paramètres d'authentification unique de l'API Admin Settings pour enregistrer votre certificat de clé publique auprès de Google.
  • Configuration de 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 la communication avec les serveurs du fournisseur d'identité du domaine.

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 à celle utilisée pour le routage des e-mails dans les paramètres Gmail de la console d'administration. Pour plus d'informations, consultez les articles 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 au format XML et HTTP brut. Cet exemple de langage par défaut du domaine montre la syntaxe XML et HTTP complète pour le corps d'une requête et d'une entrée de réponse, 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 la passerelle:

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

La langue par défaut du domaine PUT pour la requête 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 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. Ils sont communs à tous les corps de requête de l'API Admin Settings.

L'élément entry de la réponse en 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>

Gestion des 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 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 du centre d'aide. 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 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 la section Authentification auprès du service Paramètres d'administration. Pour les messages d'erreur, consultez la page 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.

Les appels réussis renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les paramètres d'authentification unique du domaine.

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

Ces propriétés sont les suivantes:

samlSignonUri
URL du fournisseur d'identité à laquelle Google Workspace envoie la requête SAML pour l'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 ensuite défini enableSSO sur enableSSO=false, les paramètres précédemment saisis sont toujours enregistrés.
ssoWhitelist
Une liste blanche est une adresse IP de masque réseau au format CIDR (Classless Inter-Domain Routing). La liste blanche d'associations identifie les utilisateurs qui se connectent à l'aide de l'authentification unique et ceux qui se connectent via la page d'authentification des comptes 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 la section 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 l'ensemble d'une organisation avec plusieurs sous-domaines. Le fait d'indiquer à l'émetteur de domaine spécifique détermine le sous-domaine à associer à la requête. Pour en savoir plus, consultez la section Comment fonctionne l'élément "Émetteur" de la requête SAML ?

Si votre demande é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 page Codes d'état HTTP.

Mise à jour des paramètres d'authentification unique

Pour mettre à jour les paramètres d'authentification unique 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> de votre entrée mise à jour 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 page 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 du flux d'authentification unique:

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>

Les appels réussis renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les paramètres d'authentification unique.

Le fichier XML de 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 demande é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 page Codes d'état HTTP.

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

Pour récupérer la clé de signature unique, envoyez une requête HTTP GET à l'URL du flux de la clé de signature SSO et incluez un en-tête Authorization, comme décrit dans la section S'authentifier auprès du service des paramètres de l'administrateur. Pour les messages d'erreur, consultez la page 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.

Les appels réussis renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec la clé de signature.

Le code 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 demande é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 page Codes d'état HTTP.

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

Pour mettre à jour la clé de signature SSO d'un domaine, récupérez-la d'abord à l'aide de l'opération Récupérer une clé de signature d'authentification unique, 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 à 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 Google Workspace.

Lors de la mise à jour d'une 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 fichier XML de 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>

Gérer la passerelle de messagerie et le routage

La section "Passerelle de messagerie sortante" indique comment l'API Admin Settings prend en charge le routage sortant des e-mails 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ération des paramètres de 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 la section Authentification auprès du service Paramètres d'administration:

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.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec 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 l'article 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 demande é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 page 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 la passerelle:

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

Le fichier XML de 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 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 la distribution 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 demande é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 page 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-In vers lequel les e-mails sont routés. Le nom d'hôte ou l'adresse IP doit être résolu pour Google. Pour savoir comment résoudre les noms d'hôte 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 de la destination utilisateur@), et le message est distribué à l'adresse de l'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 (utilisateur@nom d'hôte d'origine) sur le serveur de messagerie de destination. Ce paramètre est similaire 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 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 : permet de distribuer le courrier à cette destination si l'utilisateur existe dans Google Workspace.
  • unknownAccounts : permet de distribuer le courrier à cette destination si l'utilisateur n'existe pas dans Google Workspace. Ce paramètre est similaire au paramètre "Envoyer un e-mail pour" dans la console d'administration. Pour plus d'informations 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 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 la section Authentification auprès du service Paramètres d'administration:

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

Les appels réussis renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les informations d'archive.

Si votre demande é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 page Codes d'état HTTP.

Abandon 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é abandonné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