Descripción general de la API de configuración del administrador

La API de Admin Settings permite que los administradores de dominios de Google Workspace recuperen y cambien la configuración de sus dominios en forma de feeds de la API de datos de Google.

Esta configuración de dominio incluye muchas de las funciones disponibles en la Consola del administrador de Google Workspace. Algunos ejemplos de usos de esta API incluyen la creación de un panel de control personalizado o la integración de dominios de Google Workspace en un entorno heredado existente.

La API de Admin Settings implementa el protocolo de la API de datos de Google. La API de datos de Google cumple con el modelo de publicación y edición del protocolo de publicación Atom (AtomPub). Las solicitudes HTTP de AtomPub usan el enfoque de diseño de transferencia de conjunto representacional (RESTful) para los servicios web. Si deseas obtener más información, consulta la Guía para desarrolladores de datos de Google.

Público

Este documento está dirigido a desarrolladores que quieran escribir aplicaciones cliente que puedan modificar y recuperar información sobre dominios de Google Workspace. Se proporcionan ejemplos de interacciones básicas de la API de Admin Settings con XML y HTTP sin procesar.

En este documento, se supone que comprendes las ideas generales del protocolo de API de datos de Google y que conoces la Consola del administrador de Google Workspace. Para obtener más información sobre la Consola del administrador, consulte Cómo usar la Consola del administrador.

Getting Started

Cómo crear una cuenta

La API de Admin Settings está habilitada para las cuentas de Google Workspace. Regístrate para obtener una cuenta de Google Workspace y realizar pruebas. El servicio Configuración del administrador usa Cuentas de Google, por lo que, si ya tienes una cuenta en un dominio de Google Workspace, no necesitas hacer nada más.

Información sobre los tipos de feed de la API de Admin Settings

La API de Admin Settings te permite administrar estas categorías de configuración de dominio:

Configuración de inicio de sesión único

El inicio de sesión único (SSO) basado en SAML permite que los usuarios utilicen el mismo acceso y la misma contraseña para los servicios alojados en Google Workspace y para otros servicios que pueda alojar en su organización. Cuando se usa el SSO, una aplicación web alojada, como Google Workspace, redirecciona a los usuarios al proveedor de identidad de tu organización para autenticarlos cuando accedan. Para obtener información detallada, consulta Información sobre el SSO basado en SAML para Google Workspace.

Para configurar el SSO, debes ingresar la información necesaria para que el servicio de Google Workspace se comunique con el proveedor de identidad que almacena la información de acceso de los usuarios, así como configurar los vínculos a los que se debe enviar a los usuarios para acceder, salir y cambiar sus contraseñas. La API de Admin Settings te permite actualizar y recuperar estos parámetros de configuración de forma programática. Google usa la clave pública generada para verificar esta solicitud de SSO con tu proveedor de identidad y que la respuesta de SAML de clave privada no se modificó durante la transmisión de la red.

Para obtener un resumen breve específico de la API sobre el uso de la configuración de SSO, obtén el certificado de clave pública de tu proveedor de identidad, registra la clave pública con Google y establece la configuración de consulta de SSO basada en SAML. Para ver los mensajes de error, consulta Solución de problemas de SSO:

  • Genera tus claves: Con tu proveedor de identidad, genera un conjunto de claves públicas y privadas, ya sea mediante los algoritmos de DSA o de RSA. La clave pública está en un certificado con formato X.509. Si deseas obtener más información sobre las claves de firma de inicio de sesión único basado en SAML, consulta Genera claves y certificados para el servicio de inicio de sesión único de Google Workspace.
  • Regístrate con Google: utiliza la configuración de inicio de sesión único de la API de Admin Settings para registrar tu certificado de clave pública con Google.
  • Establece tu configuración de SSO: utiliza la configuración de inicio de sesión único de la API de Admin Settings para establecer la configuración utilizada para la comunicación con los servidores del proveedor de identidad del dominio.

Configuración de puerta de enlace y enrutamiento

Este feed permite que los administradores de dominios controlen el enrutamiento del correo electrónico de sus dominios.

Las operaciones de enrutamiento de correo electrónico permiten a los administradores especificar la configuración de enrutamiento de correo electrónico del dominio. Esta función es similar a la de enrutamiento de correo electrónico de la configuración de Gmail de la Consola del administrador. Para obtener más información, consulte Enrutamiento de correo electrónico y configuración de entrega dual de la función de enrutamiento de correo electrónico.

Muestra de una solicitud y respuesta XML de la API de Admin Settings

En este documento, se proporcionan ejemplos de código de solicitudes y respuestas básicas a la API de Admin Settings con el uso de XML y HTTP sin procesar. Este ejemplo de lenguaje predeterminado del dominio muestra la sintaxis completa XML y HTTP para el cuerpo de una entrada de solicitud y respuesta, que es común a cada operación:

Para cambiar la configuración de la puerta de enlace de correo electrónico saliente del dominio, envía un HTTP PUT a la URL del feed de la puerta de enlace:

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

El idioma predeterminado del dominio PUT con la solicitud AtomPub entry XML es el siguiente:

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

Excepto por las propiedades y los valores específicos de la operación, los elementos atom:property representan un solo par clave-valor que contiene información sobre una propiedad que deseas recuperar o actualizar. Estas son comunes a todos los cuerpos de las solicitudes a la API de Admin Settings.

El elemento entry de la respuesta de idioma predeterminado del dominio muestra las propiedades smartHost y smtpMode junto con la sintaxis XML común a todos los cuerpos de respuesta de la API de 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>

Administración de la configuración de inicio de sesión único

La función de inicio de sesión único (SSO) de Google Workspace permite que los usuarios accedan a varios servicios con solo ingresar los datos de acceso y la contraseña una vez. El proveedor de identidad del dominio almacena esta contraseña, no Google Workspace. Para obtener más información, consulte la página de SSO del Centro de ayuda. En las siguientes secciones, se muestra el formato XML que se utiliza para los parámetros de configuración del inicio de sesión único.

Recuperar la configuración del inicio de sesión único

Para recuperar la configuración de inicio de sesión único, envía un GET de HTTP a la URL del feed general de SSO y, luego, incluye un encabezado Authorization como se describe en Autenticación en el servicio de configuración del administrador. Para ver los mensajes de error, consulta Solución de problemas de SSO:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Si la respuesta es correcta, se mostrará un código de estado HTTP 200 OK, junto con un feed de AtomPub con la configuración de SSO del dominio.

El XML de respuesta GET muestra las propiedades samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist y 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>

Las propiedades incluyen lo siguiente:

samlSignonUri
La URL del proveedor de identidad a la que Google Workspace envía la solicitud de SAML para la autenticación del usuario
samlLogoutUri
La dirección a la que se enviarán los usuarios cuando salgan de la aplicación web.
changePasswordUri
La dirección a la que se enviarán los usuarios cuando deseen cambiar su contraseña de SSO para la aplicación web.
enableSSO
Habilita el SSO basado en SAML para este dominio. Si ya configuraste la configuración de SSO y, luego, estableciste la configuración enableSSO en enableSSO=false, se seguirá guardando la configuración que ingresaste anteriormente.
ssoWhitelist
Una ssoWhitelist es una dirección IP de máscara de red en formato de enrutamiento entre dominios sin clases (CIDR). ssoWhitelist determina qué usuarios acceden con el SSO y cuáles lo hacen con la página de autenticación de la cuenta de Google Workspace. Si no se especifican máscaras, todos los usuarios accederán con el SSO. Para obtener más información, consulta Cómo funcionan las máscaras de red.
useDomainSpecificIssuer
Se puede usar una entidad emisora específica de un dominio en la solicitud SAML al proveedor de identidad. Aunque no es necesaria para la mayoría de las implementaciones de SSO, esta función es útil en las grandes empresas que usan un solo proveedor de identidad para autenticar toda una organización con varios subdominios. Cuando se otorga la entidad emisora del dominio específico, se determina qué subdominio asociar con la solicitud. Para obtener más información, consulte ¿Cómo funciona el elemento Entidad emisora en la solicitud de SAML?

Si, por algún motivo, tu solicitud falla, se devuelve un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulta los códigos de estado de HTTP.

Actualización de la configuración del inicio de sesión único

Para actualizar la configuración de SSO de un dominio, primero recupera la configuración de SSO por medio de la operación Recuperar la configuración de inicio de sesión único, modifícala y, luego, envía una solicitud PUT a la URL del feed de SSO. Asegúrate de que el valor <id> de tu entrada actualizada coincida exactamente con el <id> de la entrada existente. Incluye un encabezado Authorization como se describe en Autenticación en el servicio de la API de Configuración del administrador. Para ver los mensajes de error, consulta Solución de problemas de SSO.

Cuando actualices la configuración de inicio de sesión único, envía un PUT HTTP a la URL del feed general de SSO:

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

El cuerpo XML de la solicitud PUT es el siguiente:

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

Si la respuesta es correcta, se mostrará un código de estado HTTP 200 OK, junto con un feed de AtomPub con la configuración de SSO.

El XML de la respuesta de PUT es el siguiente:

<?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, por algún motivo, tu solicitud falla, se devuelve un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulta los códigos de estado de HTTP.

Recupera la clave de firma de inicio de sesión único

Para recuperar la clave de firma de inicio de sesión único, envía un GET de HTTP a la URL del feed de la clave de firma de SSO y, luego, incluye un encabezado Authorization como se describe en Autenticación en el servicio de configuración de administrador. Para ver los mensajes de error, consulta Solución de problemas de SSO:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Si la respuesta es correcta, se mostrará un código de estado HTTP 200 OK, junto con un feed de AtomPub con la clave de firma.

El XML de respuesta GET muestra la propiedad 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, por algún motivo, tu solicitud falla, se devuelve un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulta los códigos de estado de HTTP.

Cómo actualizar la clave de firma de inicio de sesión único

Para actualizar la clave de firma SSO de un dominio, primero debes recuperarla mediante la operación Recuperar clave de firma de inicio de sesión único, modificarla y luego enviar una solicitud PUT a la URL del feed de la clave de firma de SSO. Asegúrate de que el valor <id> de tu entrada actualizada coincida exactamente con el <id> de la entrada existente. Si deseas obtener más información sobre las claves de firma de inicio de sesión único basado en SAML, consulta Genera claves y certificados para el servicio de inicio de sesión único de Google Workspace.

Cuando actualices la clave de firma de inicio de sesión único, envía un PUT HTTP a la URL del feed de la clave de firma de SSO:

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

El XML de la solicitud PUT es el siguiente:

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

Administrar el enrutamiento y la puerta de enlace de correo electrónico

La sección de puerta de enlace de correo electrónico saliente muestra cómo la API de Admin Settings admite el enrutamiento saliente del correo electrónico de los usuarios de su dominio. La sección de enrutamiento de correo electrónico muestra cómo enrutar mensajes a otro servidor de correo electrónico.

Recuperando la configuración de la puerta de enlace de correo electrónico saliente

Para recuperar la configuración de la puerta de enlace de correo electrónico saliente, envía un GET HTTP a la URL del feed de la puerta de enlace y, luego, incluye un encabezado Authorization como se describe en Autenticación en el servicio de configuración del administrador:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Si la respuesta es correcta, se mostrará un código de estado HTTP 200 OK, junto con un feed de AtomPub con la información de estado de la puerta de enlace de correo electrónico.

La respuesta GET muestra las propiedades smartHost y smtpMode. Para obtener más información sobre estas propiedades, consulta Actualiza la configuración de la puerta de enlace de correo electrónico saliente.

Un ejemplo de una respuesta posible es:

<?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, por algún motivo, tu solicitud falla, se devuelve un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulta los códigos de estado de HTTP.

Actualizando la configuración de la puerta de enlace de correo electrónico saliente

Para actualizar la configuración de la puerta de enlace de correo electrónico saliente de un dominio, envía una solicitud PUT HTTP a la URL del feed de la puerta de enlace:

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

El XML de la solicitud PUT es el siguiente:

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

Las propiedades de la solicitud son las siguientes:

smartHost
Es la dirección IP o el nombre de host de tu servidor SMTP. Google Workspace enruta el correo electrónico saliente a este servidor.
smtpMode
El valor predeterminado es SMTP. Otro valor, SMTP_TLS, protege la conexión con TLS cuando se entrega el mensaje.

Si la respuesta es correcta, se mostrará un código de estado HTTP 200 OK, junto con el feed de AtomPub con el estado de configuración de la puerta de enlace de correo electrónico.

Si, por algún motivo, tu solicitud falla, se devuelve un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulta los códigos de estado de HTTP.

Cómo administrar la configuración de enrutamiento de correo electrónico

Primero, crea una solicitud 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>

Las propiedades de la solicitud son las siguientes:

routeDestination
Este destino es el nombre de host o la dirección IP del servidor de correo SMTP-In al que se enruta el correo electrónico. El nombre de host o la dirección IP se deben resolver para Google. Para obtener más detalles sobre cómo resolver los nombres de host de correo electrónico, consulta Prueba piloto de Google Workspace con el enrutamiento de correo electrónico.
routeRewriteTo
Si es verdadero, el campo to: del sobre SMTP del mensaje se cambiará por el nombre de host de destino (nombre de host del usuario@destino) y el mensaje se entregará a esta dirección del usuario en el servidor de correo electrónico de destino. Si es false, el correo electrónico se entrega a la dirección de correo electrónico to: del mensaje original (usuario@nombre de host original) en el servidor de correo electrónico de destino. Es similar al parámetro de configuración "Cambiar el sobre SMTP" de la Consola del administrador. Para obtener más información, consulta Configuración de dominio para el enrutamiento de correo electrónico.
routeEnabled
Si se establece el valor true, la funcionalidad de enrutamiento de correo electrónico está habilitada. Si es false, la funcionalidad está inhabilitada.
bounceNotifications
Si el valor es true, Google Workspace está habilitado para enviar notificaciones de rebote al remitente cuando falla una entrega.
accountHandling

Este parámetro de configuración determina cómo el enrutamiento de correo electrónico afecta los diferentes tipos de usuarios del dominio:

  • allAccounts: Envía todos los correos electrónicos a este destino.
  • provisionedAccounts: entrega el correo electrónico a este destino si el usuario existe en Google Workspace.
  • unknownAccounts: entrega el correo electrónico a este destino si el usuario no existe en Google Workspace. Es similar al parámetro de configuración “Correo electrónico de entrega para” de la Consola del administrador. Para obtener más información sobre los requisitos previos y cómo usar el enrutamiento de correo electrónico, consulte Configuración de dominios para el enrutamiento de correo electrónico. ~ Para publicar esta solicitud, envía un POST HTTP a la URL del feed de enrutamiento de correo electrónico y, luego, incluye un encabezado Authorization como se describe en Autenticación en el servicio de configuración del administrador:

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

Si la respuesta es correcta, se mostrará un código de estado HTTP 200 OK, junto con un feed de AtomPub con la información del archivo.

Si, por algún motivo, tu solicitud falla, se devuelve un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulta los códigos de estado de HTTP.

Desactivación de Endpoints el 31 de octubre de 2018

Como parte de este anuncio, dimos de baja los siguientes extremos. Se desactivaron el 31 de octubre de 2018 y ya no están 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