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

Estos parámetros de configuración del dominio incluyen muchas de las funciones disponibles en la Consola del administrador de Google Workspace. Algunos 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 Google Data. Las APIs de Google Data cumplen 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 estado representacional (RESTful) para los servicios web. Para obtener más información, consulta la Guía para desarrolladores de las APIs de Google Data.

Público

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

En este documento, se da por sentado que comprendes las ideas generales detrás del el protocolo de la API de Google Data y que estás familiarizado con la Consola del administrador de Google Workspace. Para obtener más información sobre la Consola del administrador, consulta Usa la Consola del administrador.

Comenzar

Para comenzar a usar la API de Admin Settings, primero configura tu cuenta.

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 con fines de prueba. El servicio de Admin Settings usa Cuentas de Google, por lo que, si ya tienes una cuenta en un dominio de Google Workspace, ya tienes todo listo.

Nota: Configura los parámetros de configuración de tu dominio con la API de Admin Settings y usa la API de Email Settings para configurar los parámetros de configuración de correo electrónico de tus usuarios.

Acerca de los tipos de feeds de la API de Admin Settings

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

Configuración de inicio de sesión único

El inicio de sesión único (SSO) basado en SAML permite que los usuarios usen el mismo acceso y contraseña para los servicios alojados de Google Workspace y otros servicios que puedas alojar en tu organización. Específicamente 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 acceden. Para obtener información detallada, consulta Información sobre el SSO basado en SAML para Google Workspace.

La configuración del SSO implica 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 tus 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 tu clave pública generada para verificar esta solicitud de SSO con tu proveedor de identidad y que la respuesta de SAML de la clave privada no se haya modificado durante la transmisión de red.

Para obtener un breve resumen 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 en Google y configura los parámetros de configuración de consulta de SSO basados en SAML. Para obtener mensajes de error, consulta Solución de problemas del SSO:

• Genera tus claves: Con tu proveedor de identidad, genera un conjunto de claves públicas y privadas con los algoritmos DSA o RSA. La clave pública está en un certificado con formato X.509. Para obtener más información sobre las claves de firma de inicio de sesión único basadas en SAML, consulta Genera claves y certificados para el servicio de inicio de sesión único de Google Workspace.
• Regístrate en Google: Usa la configuración de inicio de sesión único de la API de Admin Settings para registrar tu certificado de clave pública en Google.
• Configura tus parámetros de configuración de SSO: Usa la configuración de inicio de sesión único de la API de Admin Settings para configurar los parámetros de configuración que se usan para la comunicación con los servidores del proveedor de identidad del dominio.

Nota: En el caso de los protocolos que no usan un flujo de acceso basado en la Web, como algunos clientes de correo electrónico POP/IMAP, los usuarios acceden directamente con su nombre de usuario y contraseña de Google Workspace.

Configuración de la puerta de enlace

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

Las operaciones de enrutamiento de correo electrónico permiten que los administradores especifiquen los parámetros de configuración de enrutamiento de correo electrónico a nivel del dominio. Esto es similar a la funcionalidad de enrutamiento de correo electrónico de la configuración de Gmail de la Consola del administrador. Para obtener más información, consulta Enrutamiento de correo electrónico y Configuración de entrega doble de la función de enrutamiento de correo electrónico.

Ejemplo 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 de la API de Admin Settings con XML y HTTP sin procesar. En este ejemplo de idioma predeterminado del dominio, se muestra la sintaxis completa de 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 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 entry AtomPub de la solicitud PUT de idioma predeterminado del dominio 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>

A excepción de 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. Estos son comunes a todos los cuerpos de solicitud a la API de Admin Settings.

El elemento entry de 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>

Administra 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 un acceso y una contraseña una vez. El proveedor de identidad del dominio almacena esta contraseña, no Google Workspace. Para obtener más información, consulta la página de SSO del Centro de ayuda. En las siguientes secciones, se muestra el formato XML que se usa para la configuración de inicio de sesión único.

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

Para recuperar la configuración de inicio de sesión único, envía un HTTP GET a la URL del feed general de SSO y, luego, incluye un encabezado Authorization como se describe en Autenticación en el servicio de Admin Settings. Para obtener mensajes de error, consulta Solución de problemas del 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.

Una respuesta correcta devuelve 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

Es la URL del proveedor de identidad a la que Google Workspace envía la solicitud de SAML para la autenticación del usuario.

samlLogoutUri

Es la dirección a la que se enviará a los usuarios cuando salgan de la aplicación web.

changePasswordUri

Es la dirección a la que se enviará a los usuarios cuando quieran cambiar su contraseña de SSO para la aplicación web.

enableSSO

Habilita el SSO basado en SAML para este dominio. Si ya configuraste los parámetros de configuración de SSO y, posteriormente, estableciste enableSSO en enableSSO=false, los parámetros de configuración que ingresaste anteriormente se guardan.

ssoWhitelist

Una ssoWhitelist es una dirección IP de máscara de red en formato de enrutamiento entre dominios sin clases (CIDR). La ssoWhitelist determina qué usuarios acceden con 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 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 del dominio en la solicitud de SAML al proveedor de identidad. Aunque no es necesario para la mayoría de las implementaciones de SSO, esta función es útil en empresas grandes que usan un solo proveedor de identidad para autenticar a toda una organización con varios subdominios. Si se proporciona la entidad emisora de dominio específica, se determina qué subdominio se asociará con la solicitud. Para obtener más información, consulta ¿Cómo funciona el elemento Issuer en la solicitud de SAML ?

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

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

Para actualizar la configuración de SSO de un dominio, primero recupera la configuración de SSO con 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 <id> valor de la 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 Admin Settings. Para obtener mensajes de error, consulta Solución de problemas del 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>

Una respuesta correcta devuelve un código de estado HTTP 200 OK, junto con un feed de AtomPub con la configuración de SSO.

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

No se permiten los cambios en la configuración de inicio de sesión único cuando el cliente objetivo ha habilitado la aprobación de varias partes para acciones sensibles. Las solicitudes fallarán con errorCode="1811" y reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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 HTTP GET 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 Admin Settings. Para obtener mensajes de error, consulta Solución de problemas del 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.

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

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

Para actualizar la clave de firma de SSO de un dominio, primero recupera la clave de firma con la operación Recuperar la clave de firma de inicio de sesión único , modifícala y, luego, envía una solicitud PUT a la URL del feed de la clave de firma de SSO. Asegúrate de que el valor <id> de la entrada actualizada coincida exactamente con el <id> de la entrada existente. Para obtener más información sobre las claves de firma de inicio de sesión único basadas 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 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>

Nota: La propiedad signingKey es obligatoria para esta solicitud.

No se permiten los cambios en la configuración de inicio de sesión único cuando el cliente objetivo ha habilitado la aprobación de varias partes para acciones sensibles. Las solicitudes fallarán con errorCode="1811" y reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Administra la puerta de enlace de correo electrónico

En la sección de la puerta de enlace de correo electrónico saliente, se muestra cómo la API de Admin Settings admite el enrutamiento saliente del correo de los usuarios de tu dominio.

Recupera 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 HTTP GET 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 Admin Settings:

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.

Nota: Debes tener una edición de Google Workspace apta para usar la función de puerta de enlace saliente de Google Workspace.

Una respuesta correcta devuelve 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 settings.

Este es un ejemplo de una posible respuesta:

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

Actualiza 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

Nota: Debes tener una edición de Google Workspace apta para usar la función de puerta de enlace saliente de Google Workspace.

El XML de 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 saliente a este servidor.

smtpMode

El valor predeterminado es SMTP. Otro valor, SMTP_TLS, protege una conexión con TLS cuando se entrega el mensaje.

Nota: Sigue las instrucciones de tu agente de transferencia de correo para configurar el correo electrónico retransmitido que se envía desde Google Workspace.

Una respuesta correcta devuelve un código de estado HTTP 200 OK, junto con el feed de AtomPub con el estado de la configuración de la puerta de enlace de correo electrónico.

Nota: Envía un correo electrónico desde Google Workspace a un usuario fuera de tu dominio para verificar que el correo saliente que se envía a través de tu puerta de enlace funcione después de los cambios.

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

Extremos retirados el 31 de octubre de 2018

Como parte de este anuncio, retiramos los siguientes extremos. Se retiraron 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