Admin Settings API – Übersicht

Mit der Admin Settings API können Administratoren von Google Workspace-Domains die Einstellungen ihrer Domains in Form von Google Data API-Feeds abrufen und ändern.

Diese Domaineinstellungen umfassen viele der Funktionen, die in der Admin-Konsole von Google Workspace verfügbar sind. Beispiele für die Verwendung dieser API sind das Erstellen einer benutzerdefinierten Steuerkonsole oder das Einbinden von Google Workspace-Domains in eine vorhandene Legacy-Umgebung.

Die Admin Settings API implementiert das Google Data API-Protokoll. Die Google Data API entspricht dem Veröffentlichungs- und Bearbeitungsmodell des Atom Publishing Protocol (AtomPub). Die AtomPub-HTTP-Anfragen verwenden den RESTful-Ansatz (Representational State Transfer) für Webdienste. Weitere Informationen finden Sie im Entwicklerhandbuch für die Google Data APIs.

Zielgruppe

Dieses Dokument richtet sich an Entwickler, die Clientanwendungen schreiben möchten, mit denen Informationen zu Google Workspace-Domains geändert und abgerufen werden können. Es enthält Beispiele für die grundlegenden Interaktionen der Admin Settings API mit unformatiertem XML und HTTP.

In diesem Dokument wird davon ausgegangen, dass Sie die allgemeinen Konzepte des the Google Data API-Protokolls kennen und mit der Admin-Konsole von Google Workspace vertraut sind. Weitere Informationen zur Admin Konsole finden Sie unter Admin Konsole nutzen.

Jetzt starten

Richten Sie zuerst Ihr Konto ein, um die Admin Settings API zu verwenden.

Konto erstellen

Die Admin Settings API ist für Google Workspace-Konten aktiviert. Registrieren Sie sich für ein Google Workspace-Konto für Testzwecke. Der Admin Settings-Dienst verwendet Google Konten. Wenn Sie also bereits ein Konto in einer Google Workspace-Domain haben, sind Sie bereit.

**Hinweis**: Konfigurieren Sie Ihre Domaineinstellungen mit der Admin Settings API und verwenden Sie die Email Settings API, um die E‑Mail-Einstellungen Ihrer Nutzer zu konfigurieren.

Feedtypen der Admin Settings API

Mit der Admin Settings API können Sie die folgenden Kategorien von Domaineinstellungen verwalten:

Einstellungen für die Einmalanmeldung (SSO)

Mit der SAML-basierten Einmalanmeldung (SSO) können Nutzer denselben Anmeldenamen und dasselbe Passwort sowohl für gehostete Google Workspace-Dienste als auch für andere Dienste verwenden, die Sie möglicherweise in Ihrer Organisation hosten. Bei der Verwendung von SSO werden Nutzer von einer gehosteten Webanwendung wie Google Workspace zu dem Identitätsanbieter Ihrer Organisation weitergeleitet, um sich anzumelden. Ausführliche Informationen finden Sie unter SAML-basierte Einmalanmeldung (SSO) für Google Workspace.

Bei der Konfiguration von SSO müssen Sie die erforderlichen Informationen eingeben, damit der Google Workspace-Dienst mit dem Identitätsanbieter kommunizieren kann, der die Anmeldeinformationen Ihrer Nutzer speichert. Außerdem müssen Sie die Links einrichten, an die Nutzer weitergeleitet werden sollen, wenn sie sich anmelden, abmelden oder ihr Passwort ändern möchten. Mit der Admin Settings API können Sie diese Einstellungen programmatisch aktualisieren und abrufen. Google verwendet Ihren generierten öffentlichen Schlüssel, um diese SSO-Anfrage bei Ihrem Identitätsanbieter zu bestätigen und zu prüfen, ob die private Schlüssel-SAML-Antwort während der Netzwerkübertragung nicht geändert wurde.

Eine kurze API-spezifische Zusammenfassung zur Verwendung der SSO-Einstellungen: Rufen Sie das Zertifikat Ihres öffentlichen Schlüssels von Ihrem Identitätsanbieter ab, registrieren Sie den öffentlichen Schlüssel bei Google und richten Sie die Einstellungen für die SAML-basierte SSO-Abfrage ein. Fehlermeldungen finden Sie unter Fehlerbehebung bei der Einmalanmeldung (SSO):

• Schlüssel generieren: Generieren Sie mit Ihrem Identitätsanbieter ein Paar aus öffentlichen und privaten Schlüsseln mit dem DSA- oder RSA-Algorithmus. Der öffentliche Schlüssel befindet sich in einem Zertifikat im X.509-Format. Weitere Informationen zu Signaturschlüsseln für die SAML-basierte Einmalanmeldung (SSO) finden Sie unter Schlüssel und Zertifikate für den Google Workspace-Dienst für die Einmalanmeldung (SSO) generieren.
• Bei Google registrieren: Verwenden Sie die Einstellungen für die Einmalanmeldung (SSO) der Admin Settings API, um Ihr Public-Key-Zertifikat bei Google zu registrieren.
• SSO-Einstellungen einrichten: Verwenden Sie die Einstellungen für die Einmalanmeldung (SSO) der Admin Settings API, um die Einstellungen zu konfigurieren, die für die Kommunikation mit den Servern des Identitätsanbieters der Domain verwendet werden.

Hinweis: Bei Protokollen, die keinen webbasierten Anmeldevorgang verwenden, z. B. bei einigen POP/IMAP-E‑Mail-Clients, melden sich Nutzer direkt mit ihrem Google Workspace Nutzernamen und ‑Passwort an.

Gateway-Einstellungen

Mit diesem Feed können Domainadministratoren das E‑Mail-Routing für ihre Domains steuern.

Mit den E‑Mail-Routing-Vorgängen können Administratoren die E‑Mail-Routing-Einstellungen auf Domainebene festlegen. Dies ähnelt der E‑Mail-Routing-Funktion der Gmail-Einstellungen in der Admin-Konsole. Weitere Informationen finden Sie unter E‑Mail Routing und Konfiguration der doppelten Zustellung der E‑Mail-Routing Funktion.

Beispiel für eine XML-Anfrage und ‑Antwort der Admin Settings API

Dieses Dokument enthält Codebeispiele für grundlegende Anfragen und Antworten der Admin Settings API mit unformatiertem XML und HTTP. In diesem Beispiel für die Standardsprache der Domain wird die vollständige XML- und HTTP-Syntax für den Text eines Anfrage- und Antwort-Eintrags gezeigt, die für jeden Vorgang gleich ist:

Wenn Sie die Einstellung für das Ausgangsgateway für E‑Mails der Domain ändern möchten, senden Sie eine HTTP-PUT-Anfrage an die Gateway-Feed-URL:

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

Die PUT-Anfrage für die Standardsprache der Domain im AtomPub-entry-XML-Format sieht so aus:

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

Abgesehen von den vorgangsspezifischen Attributen und Werten stellt das atom:property-Element ein einzelnes Schlüssel/Wert-Paar dar, das Informationen zu einem Attribut enthält, das Sie abrufen oder aktualisieren möchten. Diese sind für alle API-Anfragen der Admin Settings API gleich.

Das entry-Element der Antwort für die Standardsprache der Domain gibt die Attribute smartHost und smtpMode zusammen mit der XML-Syntax zurück, die für alle Antworttexte der Admin Settings API gleich ist:

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

Einstellungen für die Einmalanmeldung (SSO) verwalten

Mit der Funktion für die Einmalanmeldung (SSO) von Google Workspace können sich Nutzer bei mehreren Diensten anmelden, ohne Anmeldename und Passwort mehr als einmal eingeben zu müssen. Dieses Passwort wird vom Identitätsanbieter der Domain und nicht von Google Workspace gespeichert. Weitere Informationen finden Sie auf der SSO-Seite in der Hilfe. In den folgenden Abschnitten wird das XML-Format für die Einstellungen für die Einmalanmeldung (SSO) beschrieben.

Einstellungen für die Einmalanmeldung (SSO) abrufen

Wenn Sie die Einstellungen für die Einmalanmeldung (SSO) abrufen möchten, senden Sie eine HTTP GET an die allgemeine SSO-Feed URL und fügen Sie einen Authorization Header ein, wie unter Authentifizierung beim Admin Settings-Dienst beschrieben. Fehlermeldungen finden Sie unter Fehlerbehebung bei der Einmalanmeldung (SSO):

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

Dieser Vorgang hat keine Parameter im Anfragetext.

Bei einer erfolgreichen Antwort wird der Statuscode 200 OK zurückgegeben, zusammen mit einem AtomPub-Feed mit den SSO-Einstellungen der Domain.

Das XML der `GET`-Antwort gibt die Attribute samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist und useDomainSpecificIssuer zurück:

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

Die Attribute umfassen:

samlSignonUri

Die URL des Identitätsanbieters, an die Google Workspace die SAML-Anfrage zur Nutzerauthentifizierung sendet.

samlLogoutUri

Die Adresse, an die Nutzer weitergeleitet werden, wenn sie sich von der Webanwendung abmelden.

changePasswordUri

Die Adresse, an die Nutzer weitergeleitet werden, wenn sie ihr SSO-Passwort für die Webanwendung ändern möchten.

enableSSO

Aktiviert die SAML-basierte Einmalanmeldung (SSO) für diese Domain. Wenn Sie zuvor SSO-Einstellungen konfiguriert und anschließend enableSSO auf enableSSO=false gesetzt haben, werden die zuvor eingegebenen Einstellungen weiterhin gespeichert.

ssoWhitelist

Eine ssoWhitelist ist eine Netzwerkmasken-IP-Adresse im CIDR-Format (Classless Inter-Domain Routing). Die ssoWhitelist bestimmt, welche Nutzer sich mit SSO anmelden und welche Nutzer die Authentifizierungsseite des Google Workspace-Kontos verwenden. Wenn keine Masken angegeben sind, melden sich alle Nutzer mit SSO an. Weitere Informationen finden Sie unter Funktionsweise von Netzwerkmasken.

useDomainSpecificIssuer

In der SAML-Anfrage an den Identitätsanbieter kann ein domainspezifischer Aussteller verwendet werden. Diese Funktion ist für die meisten SSO-Bereitstellungen nicht erforderlich, aber in großen Unternehmen nützlich, die einen einzelnen Identitätsanbieter verwenden, um eine gesamte Organisation mit mehreren Subdomains zu authentifizieren. Wenn Sie den spezifischen Domainaussteller angeben, wird festgelegt, welche Subdomain mit der Anfrage verknüpft werden soll. Weitere Informationen finden Sie unter Funktionsweise des Aussteller Elements in der SAML-Anfrage arbeitet?

Wenn Ihre Anfrage aus irgendeinem Grund fehlschlägt, wird ein anderer Statuscode zurückgegeben. Weitere Informationen zu den Statuscodes der Google Data API finden Sie unter HTTP-Status codes.

Einstellungen für die Einmalanmeldung (SSO) aktualisieren

Wenn Sie die SSO-Einstellungen einer Domain aktualisieren möchten, rufen Sie zuerst die SSO-Einstellungen mit dem Vorgang Einstellungen für die Einmalanmeldung (SSO) abrufen ab, ändern Sie sie und senden Sie dann eine PUT-Anfrage an die SSO-Feed-URL. Der Wert <id> in Ihrem aktualisierten Eintrag muss genau mit dem <id> des vorhandenen Eintrags übereinstimmen. Fügen Sie einen Authorization-Header ein, wie unter Authentifizierung beim Admin Settings API -Dienst beschrieben. Fehlermeldungen finden Sie unter Fehlerbehebung bei der Einmalanmeldung (SSO).

Wenn Sie die Einstellungen für die Einmalanmeldung (SSO) aktualisieren, senden Sie eine HTTP-`PUT`-Anfrage an die allgemeine SSO-Feed-URL:

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

Der XML-Text der PUT-Anfrage sieht so aus:

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

Bei einer erfolgreichen Antwort wird der Statuscode 200 OK zurückgegeben, zusammen mit einem AtomPub-Feed mit den SSO-Einstellungen.

Das XML der PUT-Antwort sieht so aus:

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

Wenn Ihre Anfrage aus irgendeinem Grund fehlschlägt, wird ein anderer Statuscode zurückgegeben. Weitere Informationen zu den Statuscodes der Google Data API finden Sie unter HTTP-Status codes.

Änderungen an den Einstellungen für die Einmalanmeldung (SSO) sind nicht zulässig, wenn der Zielkunde die mehrseitige Genehmigung für vertrauliche Aktionen aktiviert hat. Anfragen schlagen mit errorCode="1811" und reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" fehl.

Signaturschlüssel für die Einmalanmeldung (SSO) abrufen

Wenn Sie den Signaturschlüssel für die Einmalanmeldung (SSO) abrufen möchten, senden Sie eine HTTP-GET-Anfrage an die SSO -Signaturschlüssel-Feed-URL und fügen Sie einen Authorization-Header ein, wie unter Authentifizierung beim Admin Settings -Dienst beschrieben. Fehlermeldungen finden Sie unter Fehlerbehebung bei der Einmalanmeldung (SSO):

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

Dieser Vorgang hat keine Parameter im Anfragetext.

Bei einer erfolgreichen Antwort wird der Statuscode 200 OK zurückgegeben, zusammen mit einem AtomPub-Feed mit dem Signaturschlüssel.

Das XML der GET-Antwort gibt das Attribut signingKey zurück:

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

Wenn Ihre Anfrage aus irgendeinem Grund fehlschlägt, wird ein anderer Statuscode zurückgegeben. Weitere Informationen zu den Statuscodes der Google Data API finden Sie unter HTTP-Status codes.

Signaturschlüssel für die Einmalanmeldung (SSO) aktualisieren

Wenn Sie den SSO-Signaturschlüssel einer Domain aktualisieren möchten, rufen Sie zuerst den Signaturschlüssel mit dem Vorgang Signaturschlüssel für die Einmalanmeldung (SSO) abrufen ab, ändern Sie ihn und senden Sie dann eine PUT Anfrage an die SSO-Signaturschlüssel-Feed URL. Der Wert <id> in Ihrem aktualisierten Eintrag muss genau mit dem <id> des vorhandenen Eintrags übereinstimmen. Weitere Informationen zu Signaturschlüsseln für die SAML-basierte Einmalanmeldung (SSO) finden Sie unter Schlüssel und Zertifikate für den Google Workspace-Dienst für die Einmalanmeldung (SSO) generieren.

Wenn Sie den Signaturschlüssel für die Einmalanmeldung (SSO) aktualisieren, senden Sie eine HTTP-PUT-Anfrage an die SSO-Signaturschlüssel-Feed-URL:

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

Das XML der PUT-Anfrage sieht so aus:

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

Hinweis: Das Attribut signingKey ist für diese Anfrage erforderlich.

Änderungen an den Einstellungen für die Einmalanmeldung (SSO) sind nicht zulässig, wenn der Zielkunde die mehrseitige Genehmigung für vertrauliche Aktionen aktiviert hat. Anfragen schlagen mit errorCode="1811" und reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" fehl.

E‑Mail-Gateway verwalten

Im Abschnitt zum Ausgangsgateway für E‑Mails wird beschrieben, wie die Admin Settings API das ausgehende E‑Mail-Routing von Nutzern in Ihrer Domain unterstützt.

Einstellungen für das Ausgangsgateway für E‑Mails abrufen

Wenn Sie die Einstellungen für das Ausgangsgateway für E‑Mails abrufen möchten, senden Sie eine HTTP-GET an die Gateway Feed-URL und fügen Sie einen Authorization Header ein, wie unter Authentifizierung beim Admin Settings-Dienst beschrieben:

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

Dieser Vorgang hat keine Parameter im Anfragetext.

Hinweis: Sie benötigen eine berechtigte Google Workspace-Version, um die Funktion für das Ausgangsgateway von Google Workspace zu verwenden.

Bei einer erfolgreichen Antwort wird der Statuscode `200 OK` zurückgegeben, zusammen mit einem AtomPub-Feed mit den Statusinformationen zum E‑Mail-Gateway.

Die GET-Antwort gibt die Attribute smartHost und smtpMode zurück. Weitere Informationen zu diesen Attributen finden Sie unter Einstellungen für das Ausgangsgateway für E‑Mails aktualisieren.

Ein Beispiel für eine mögliche Antwort:

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

Wenn Ihre Anfrage aus irgendeinem Grund fehlschlägt, wird ein anderer Statuscode zurückgegeben. Weitere Informationen zu den Statuscodes der Google Data API finden Sie unter HTTP-Status codes.

Einstellungen für das Ausgangsgateway für E‑Mails aktualisieren

Wenn Sie die Einstellung für das Ausgangsgateway für E‑Mails einer Domain aktualisieren möchten, senden Sie eine HTTP-PUT-Anfrage an die Gateway-Feed-URL:

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

Hinweis: Sie benötigen eine berechtigte Google Workspace-Version, um die Funktion für das Ausgangsgateway von Google Workspace zu verwenden.

Das XML der PUT-Anfrage sieht so aus:

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

Die Anfrageattribute sind:

smartHost

Entweder die IP-Adresse oder der Hostname Ihres SMTP-Servers. Google Workspace leitet ausgehende E‑Mails an diesen Server weiter.

smtpMode

Der Standardwert ist SMTP. Ein anderer Wert, SMTP_TLS, sichert eine Verbindung mit TLS, wenn die Nachricht zugestellt wird.

Hinweis: Folgen Sie der Anleitung Ihres Mail Transfer Agent, um weitergeleitete E‑Mails zu konfigurieren, die von Google Workspace gesendet werden.

Bei einer erfolgreichen Antwort wird der Statuscode 200 OK zurückgegeben, zusammen mit dem AtomPub-Feed mit dem Status der Einstellungen für das E‑Mail-Gateway.

Hinweis: Senden Sie nach den Änderungen eine E‑Mail von Google Workspace an einen Nutzer außerhalb Ihrer Domain, um zu prüfen, ob die über Ihr Gateway gesendeten ausgehenden E‑Mails funktionieren.

Wenn Ihre Anfrage aus irgendeinem Grund fehlschlägt, wird ein anderer Statuscode zurückgegeben. Weitere Informationen zu den Statuscodes der Google Data API finden Sie unter HTTP-Status codes.

Endpunkte am 31. Oktober 2018 eingestellt

Im Rahmen dieser Ankündigung haben wir die folgenden Endpunkte eingestellt. Sie wurden am 31. Oktober 2018 eingestellt und sind nicht mehr verfügbar.

• 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