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 du 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 environnement existant.

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 AtomPub (AtomPub). Les requêtes HTTP AtomPub utilisent la méthode de conception REST (Représentational Set Transfer) 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 capables de modifier et de récupérer des informations sur les domaines Google Workspace. Il fournit des exemples d'interactions de base de l'API Admin Settings au format XML et HTTP brut.

Dans ce document, nous partons du principe que vous comprenez les principes généraux du protocole d'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 des paramètres d'administration utilise les comptes Google. Si vous possédez déjà un compte sur un domaine Google Workspace, vous êtes donc prêt.

Remarque :Configurez les paramètres de votre domaine à l'aide de l'API Admin Settings et de 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 de paramètres de domaine suivantes:

Paramètres d'authentification unique

L'authentification unique (SSO) basée sur SAML permet aux utilisateurs d'utiliser les mêmes informations de connexion et le même mot de passe pour les services hébergés de Google Workspace que pour les autres services que vous hébergez dans votre organisation. Plus précisément, lorsque l'authentification unique est utilisée, une application Web hébergée comme Google Workspace redirige les utilisateurs vers le fournisseur d'identité de votre organisation afin qu'ils puissent 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 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 les liens auxquels 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 votre clé publique générée pour vérifier cette demande d'authentification unique auprès de votre fournisseur d'identité et s'assurer que la réponse SAML de la clé privée n'a pas été modifiée lors de la transmission réseau.

Pour obtenir un bref résumé concernant l'utilisation des paramètres d'authentification unique de l'API, procurez-vous le certificat de clé publique auprès de votre fournisseur d'identité, enregistrez la clé publique auprès de Google, puis configurez les paramètres de requête de l'authentification unique SAML. Pour les messages d'erreur, consultez la section 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 présente dans un certificat au format X.509. Pour en savoir plus sur les clés de signature à authentification unique SAML, consultez Générer des clés et des certificats pour le service d'authentification unique Google Workspace.
• S'inscrire à 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 afin de configurer les paramètres utilisés pour la 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 de routage

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

Les opérations d'acheminement des e-mails permettent aux administrateurs de définir les paramètres d'acheminement des e-mails au niveau du domaine. Cette fonctionnalité est semblable à la fonctionnalité d'acheminement 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.

Exemple de requête et de réponse XML dans 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 et HTTP brut. Cet exemple de langage par défaut montre la syntaxe XML et HTTP complète pour le 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 un PUT HTTP à l'URL de 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 AtomPub entry au format XML 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 aux opérations, 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. Elles sont communes à tous les corps de requêtes de l'API Admin Settings.

L'élément de réponse linguistique entry 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 leurs identifiants de connexion 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 de l'authentification unique du centre d'aide. Les sections suivantes illustrent 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 de flux général d'authentification unique, puis ajoutez 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

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

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

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 sont les suivantes:

samlSignonUri

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

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.

Activer l'authentification unique

Active l'authentification unique basée sur SAML pour ce domaine. Si vous avez déjà configuré les 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.

Liste blanche sso

Une ssoWhitelist est une adresse IP de masque de réseau au format CIDR (Classless Inter-Domain Routing). La liste blanche 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 via 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 SSO, elle est utile dans les grandes entreprises qui utilisent un seul fournisseur d'identité pour authentifier une organisation entière avec plusieurs sous-domaines. L'émetteur du domaine spécifique détermine le sous-domaine à associer à la demande. 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 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.

Mise à jour des paramètres d'authentification unique

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

Lors de la mise à jour des paramètres d'authentification unique, envoyez une requête HTTP PUT à l'URL de flux générale 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 SSO.

La réponse XML PUT est la suivante:

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

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 SSO, puis 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/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 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 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.

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

Pour mettre à jour la clé de signature SSO d'un domaine, récupérez-la à 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 SSO. Assurez-vous que la valeur <id> de votre entrée mise à jour correspond exactement à la <id> de l'entrée existante. Pour en savoir plus sur les clés de signature à authentification unique SAML, consultez Générer des clés et des certificats pour le service d'authentification unique Google Workspace.

Lorsque vous mettez à jour une clé de signature d'authentification 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 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 obligatoire pour cette requête.

Gérer la passerelle de messagerie et le routage

La section "Passerelle de messagerie sortante" indique comment l'API Admin Settings prend en charge l'acheminement des messages des utilisateurs de votre domaine. La section "Routage des e-mails" indique comment router 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 la passerelle en incluant 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

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

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

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:

hôte actif

Adresse IP ou nom d'hôte de votre serveur SMTP. Google Workspace achemine les e-mails sortants vers ce serveur.

Mode smtp

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 par Google Workspace.

Une réponse réussie renvoie un code d'état HTTP 200 OK, ainsi que le flux AtomPub et 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 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:

Destination de l'itinéraire

Cette destination est le nom d'hôte ou l'adresse IP du serveur de messagerie SMTP vers lequel l'e-mail est acheminé. Le nom d'hôte ou l'adresse IP doit être résolu pour Google. Pour savoir comment résoudre les 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_utilisateur@nom_destination) et le message est distribué à cette adresse d'utilisateur sur le serveur de messagerie de destination. Si la valeur est false, l'e-mail est distribué à l'adresse e-mail to: (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.

Notifications de non-distribution

Si la valeur est true, Google Workspace est activé pour envoyer des notifications de non-distribution à l'expéditeur en cas d'échec d'une distribution.

gestion du compte

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

• allAccounts : distribuer tous les e-mails à cette destination.
• provisionedAccounts : distribuer le courrier vers cette destination si l'utilisateur existe dans Google Workspace.
• unknownAccounts : distribuer le courrier vers cette destination si l'utilisateur n'existe pas dans Google Workspace. Cette option est similaire au paramètre "Adresses e-mail pour" de la console d'administration. Pour en savoir plus sur les conditions préalables et sur 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 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.

Abandon de Endpoints le 31 octobre 2018

Dans cette annonce, nous avons abandonné les points de terminaison suivants. 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