Visão geral da API Admin Settings

A API Admin Settings permite que os administradores de domínios do Google Workspace recuperem e alterem as configurações dos domínios no formato de feeds da API Google Data.

Essas configurações de domínio incluem muitos dos recursos disponíveis no Admin Console do Google Workspace. Os usos de exemplo dessa API incluem a criação de um painel de controle personalizado ou a integração de domínios do Google Workspace em um ambiente legado.

A API Admin Settings implementa o protocolo da API Google Data. As APIs Google Data estão em conformidade com o modelo de publicação e edição do Atom Publishing Protocol (AtomPub). As solicitações HTTP do AtomPub usam a abordagem de design de transferência de estado representacional (RESTful) para serviços da Web. Para mais informações, consulte o Guia para desenvolvedores das APIs Google Data.

Público-alvo

Este documento é destinado a desenvolvedores que querem escrever aplicativos cliente que possam modificar e recuperar informações sobre domínios do Google Workspace. Ele fornece exemplos das interações básicas da API Admin Settings usando XML e HTTP brutos.

Este documento pressupõe que você entenda as ideias gerais por trás do o protocolo da API Google Data e que esteja familiarizado com o Admin Console do Google Workspace. Para mais informações sobre o Admin Console, consulte Usar o Admin Console.

Começar

Para começar a usar a API Admin Settings, primeiro configure sua conta.

Criar uma conta

A API Admin Settings está ativada para contas do Google Workspace. Inscreva-se em uma conta do Google Workspace para fins de teste. O serviço Admin Settings usa Contas do Google. Portanto, se você já tiver uma conta em um domínio do Google Workspace, tudo estará pronto.

Observação: configure as configurações de domínio usando a API Admin Settings e use a API Email Settings para configurar as configurações de e-mail dos usuários.

Sobre os tipos de feed da API Admin Settings

A API Admin Settings permite gerenciar estas categorias de configurações de domínio:

Configurações de Logon único

O Logon único (SSO) baseado em SAML permite que os usuários usem o mesmo login e senha para serviços hospedados do Google Workspace e outros serviços que você possa hospedar na sua organização. Especificamente ao usar o SSO, um aplicativo da Web hospedado, como o Google Workspace, redireciona os usuários para o provedor de identidade da sua organização para autenticar os usuários quando eles fazem login. Para informações detalhadas, consulte Entender o SSO baseado em SAML para o Google Workspace.

A configuração do SSO envolve inserir as informações necessárias para que o serviço do Google Workspace se comunique com o provedor de identidade que armazena as informações de login dos usuários, além de configurar os links para os quais os usuários devem ser enviados para fazer login, sair e mudar as senhas. A API Admin Settings permite atualizar e recuperar essas configurações de maneira programática. O Google usa a chave pública gerada para verificar essa solicitação de SSO com o provedor de identidade e que a resposta SAML da chave privada não foi modificada durante a transmissão de rede.

Para um resumo específico da API sobre como usar as configurações de SSO, receba o certificado de chave pública do provedor de identidade, registre a chave pública no Google e configure as configurações de consulta de SSO baseadas em SAML. Para mensagens de erro, consulte Solução de problemas de SSO:

• Gerar chaves: com o provedor de identidade, gere um conjunto de chaves públicas e privadas usando os algoritmos DSA ou RSA. A chave pública está em um certificado formatado X.509. Para mais informações sobre chaves de assinatura de Logon único baseadas em SAML, consulte Gerar chaves e certificados para o serviço de Logon único do Google Workspace.
• Registrar no Google: use as configurações de Logon único da API Admin Settings para registrar o certificado de chave pública no Google.
• Configurar as configurações de SSO: use as configurações de Logon único da API Admin Settings para configurar as configurações usadas para comunicação com os servidores do provedor de identidade do domínio.

Observação: para protocolos que não usam um fluxo de login baseado na Web, como alguns clientes de e-mail POP/IMAP, os usuários fazem login diretamente com o nome de usuário e a senha do Google Workspace.

Configurações de gateway

Esse feed permite que os administradores de domínio controlem o roteamento de e-mails para os domínios.

As operações de roteamento de e-mail permitem que os administradores especifiquem as configurações de roteamento de e-mail no nível do domínio. Isso é semelhante à funcionalidade de roteamento de e-mail das configurações do Gmail do Admin Console. Para mais informações, consulte Roteamento de e-mail e configuração de entrega dupla do recurso de roteamento de e-mail.

Exemplo de uma solicitação e resposta XML da API Admin Settings

Este documento fornece exemplos de código de solicitações e respostas básicas da API Admin Settings usando XML e HTTP brutos. Este exemplo de idioma padrão do domínio mostra a sintaxe XML e HTTP completa para o corpo de uma entrada de solicitação e resposta, que é comum a cada operação:

Para mudar a configuração do gateway de e-mail de saída do domínio, envie um HTTP PUT para o URL do feed do gateway:

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

O XML entry AtomPub da solicitação PUT do idioma padrão do domínio é:

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

Exceto pelas propriedades e valores específicos da operação, os elementos atom:property representam um único par de chave-valor que contém informações sobre uma propriedade que você quer recuperar ou atualizar. Esses são comuns a todos os corpos de solicitação de API Admin Settings.

O elemento entry de resposta do idioma padrão do domínio retorna as propriedades smartHost e smtpMode, além da sintaxe XML comum a todos os corpos de resposta da 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>

Gerenciar configurações de Logon único

O recurso de Logon único (SSO) do Google Workspace permite que os usuários façam login em vários serviços, precisando inserir um login e uma senha apenas uma vez. Essa senha é armazenada pelo provedor de identidade do domínio, não pelo Google Workspace. Para mais informações, consulte a página de SSO da Central de Ajuda. As seções a seguir demonstram o formato XML usado para as configurações de Logon único.

Recuperar configurações de Logon único

Para recuperar as configurações de Logon único, envie um HTTP GET para o URL do feed geral de SSO e inclua um cabeçalho Authorization conforme descrito em Autenticação no serviço Admin Settings. Para mensagens de erro, consulte Solução de problemas de SSO:

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

Essa operação não tem parâmetros no corpo da solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de um feed AtomPub com as configurações de SSO do domínio.

O XML de resposta GET retorna as propriedades samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist e 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>

As propriedades incluem:

samlSignonUri

O URL do provedor de identidade em que o Google Workspace envia a solicitação SAML para autenticação do usuário.

samlLogoutUri

O endereço para o qual os usuários serão enviados quando saírem do aplicativo da Web.

changePasswordUri

O endereço para o qual os usuários serão enviados quando quiserem mudar a senha de SSO do aplicativo da Web.

enableSSO

Ativa o SSO baseado em SAML para esse domínio. Se você já tiver configurado as configurações de SSO e tiver definido enableSSO como enableSSO=false, as configurações inseridas anteriormente ainda serão salvas.

ssoWhitelist

Uma ssoWhitelist é um endereço IP de máscara de rede no formato de roteamento entre domínios sem classe (CIDR). A ssoWhitelist determina quais usuários fazem login usando o SSO e quais fazem login usando a página de autenticação da conta do Google Workspace. Se nenhuma máscara for especificada, todos os usuários farão login usando o SSO. Para mais informações, consulte Como as máscaras de rede funcionam.

useDomainSpecificIssuer

Um emissor específico do domínio pode ser usado na solicitação SAML para o provedor de identidade. Embora não seja necessário para a maioria das implantações de SSO, esse recurso é útil em grandes empresas que usam um único provedor de identidade para autenticar uma organização inteira com vários subdomínios. Fornecer o emissor de domínio específico determina qual subdomínio associar à solicitação. Para mais informações, consulte Como o elemento Issuer na solicitação SAML funciona?

Se a solicitação falhar por algum motivo, um código de status diferente será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Atualizar configurações de Logon único

Para atualizar as configurações de SSO de um domínio, primeiro recupere as configurações de SSO usando a operação Recuperar configurações de Logon único, modifique-as e envie uma solicitação PUT para o URL do feed de SSO. Verifique se o <id> valor na entrada atualizada corresponde exatamente ao <id> da entrada atual. Inclua um cabeçalho Authorization, conforme descrito em Autenticação no serviço da API Admin Settings. Para mensagens de erro, consulte Solução de problemas de SSO.

Ao atualizar as configurações de Logon único, envie um HTTP PUT para o URL do feed geral de SSO:

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

O corpo XML da solicitação PUT é:

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de um feed AtomPub com as configurações de SSO.

O XML de resposta PUT é:

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

Se a solicitação falhar por algum motivo, um código de status diferente será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

As mudanças nas configurações de Logon único não são permitidas quando o cliente de destino ativou a aprovação de várias partes para ações sensíveis. As solicitações vão falhar com errorCode="1811" e reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Recuperar a chave de assinatura de Logon único

Para recuperar a chave de assinatura de Logon único, envie um HTTP GET para o URL do feed da chave de assinatura de SSO e inclua um cabeçalho Authorization, conforme descrito em Autenticação no serviço Admin Settings. Para mensagens de erro, consulte Solução de problemas de SSO:

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

Essa operação não tem parâmetros no corpo da solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de um feed AtomPub com a chave de assinatura.

O XML de resposta GET retorna a propriedade 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>

Se a solicitação falhar por algum motivo, um código de status diferente será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Atualizar a chave de assinatura de Logon único

Para atualizar a chave de assinatura de SSO de um domínio, primeiro recupere a chave de assinatura usando a operação Recuperar chave de assinatura de Logon único , modifique-a e envie uma solicitação PUT para o URL do feed da chave de assinatura de SSO. Verifique se o valor <id> na entrada atualizada corresponde exatamente ao <id> da entrada atual. Para mais informações sobre chaves de assinatura de Logon único baseadas em SAML, consulte Gerar chaves e certificados para o serviço de Logon único do Google Workspace.

Ao atualizar a chave de assinatura de Logon único, envie um HTTP PUT para o URL do feed da chave de assinatura de SSO:

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

O XML de solicitação PUT é:

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

Observação: A propriedade signingKey é obrigatória para essa solicitação.

As mudanças nas configurações de Logon único não são permitidas quando o cliente de destino ativou a aprovação de várias partes para ações sensíveis. As solicitações vão falhar com errorCode="1811" e reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Gerenciar gateway de e-mail

A seção de gateway de e-mail de saída mostra como a API Admin Settings oferece suporte ao roteamento de e-mails de saída de usuários no seu domínio.

Recuperar configurações de gateway de e-mail de saída

Para recuperar as configurações de gateway de e-mail de saída, envie um HTTP GET para o URL do feed do gateway e inclua um cabeçalho Authorization conforme descrito em Autenticação no serviço Admin Settings:

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

Essa operação não tem parâmetros no corpo da solicitação.

Observação: é necessário ter uma edição qualificada do Google Workspace para usar o recurso de gateway de saída do Google Workspace.

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de um feed AtomPub com as informações de status do gateway de e-mail.

A resposta GET retorna as propriedades smartHost e smtpMode. Para mais informações sobre essas propriedades, consulte Atualizar configurações de gateway de e-mail de saída settings.

Um exemplo de resposta possível é:

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

Se a solicitação falhar por algum motivo, um código de status diferente será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Atualizar configurações de gateway de e-mail de saída

Para atualizar a configuração do gateway de e-mail de saída de um domínio, envie uma solicitação HTTP PUT para o URL do feed do gateway:

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

Observação: é necessário ter uma edição qualificada do Google Workspace para usar o recurso de gateway de saída do Google Workspace.

O XML de solicitação PUT é:

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

As propriedades da solicitação são:

smartHost

O endereço IP ou o nome do host do servidor SMTP. O Google Workspace encaminha e-mails de saída para esse servidor.

smtpMode

O valor padrão é SMTP. Outro valor, SMTP_TLS, protege uma conexão com TLS ao entregar a mensagem.

Observação: Siga as instruções do agente de transferência de e-mail para configurar o e-mail retransmitido enviado do Google Workspace.

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além do feed AtomPub com o status das configurações do gateway de e-mail.

Observação: envie um e-mail do Google Workspace para um usuário fora do seu domínio para verificar se o e-mail de saída enviado pelo gateway está funcionando após as mudanças.

Se a solicitação falhar por algum motivo, um código de status diferente será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Endpoints desativados em 31 de outubro de 2018

Descontinuamos os endpoints a seguir como parte deste anúncio. Eles foram desativados em 31 de outubro de 2018 e não estão mais disponíveis.

• 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