Autorización

Las apps autorizan llamadas a la API del cliente de inscripción automática mediante OAuth. En este documento, se explica la autorización de la API para los proveedores de administración de movilidad empresarial (EMM) y los desarrolladores de TI empresariales. Después de leer este documento, sabrás cómo autorizar las solicitudes a la API en tu app y explicarles los requisitos de la cuenta a sus usuarios.

Guía de inicio rápido para la autorización

• Para configurar un proyecto de Google Cloud Platform con la API de inscripción automática y los secretos del cliente de OAuth, ejecuta este asistente.
• Compila el código de muestra de la guía de inicio rápido para Java, .NET o Python. Usa las bibliotecas cliente de la API de Google para admitir otros lenguajes.

Descripción general

1. Uno o más administradores de TI son usuarios de una cuenta de cliente con inscripción automática.
2. Los administradores de TI usan una Cuenta de Google para autenticarse.
3. Las solicitudes a la API pasan un token OAuth2 para autorizar las solicitudes a la API en nombre de un administrador de TI.

Cuentas de clientes

La configuración, los dispositivos y los usuarios (administrador de TI) de una organización pertenecen a una cuenta de cliente. Una cuenta de cliente es similar a un grupo y no es un usuario individual. Un revendedor configura un cliente cuando la organización compra dispositivos por primera vez para la inscripción automática. Los administradores de TI gestionan a otros usuarios de su organización mediante el portal de inscripción automática.

La API utiliza los ID de cliente numéricos para identificar las cuentas. El ID de cliente se pasa como parte de la ruta de URL cuando llamas a los métodos de la API. Tu app debe obtener el ID de cliente de un usuario antes de llamar a cualquier método de API.

En el siguiente ejemplo, se muestra cómo obtener las cuentas de los clientes del usuario que autoriza la llamada a la API:

Java

AndroidProvisioningPartner.Customers.List accountRequest = service.customers().list();
accountRequest.setPageSize(100);
CustomerListCustomersResponse accountResponse = accountRequest.execute();

List<Company> customers = accountResponse.getCustomers();
if (customers == null || customers.isEmpty()) {
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    System.out.println("No zero-touch enrollment account found.");
} else {
    // Print the customers in this page.
    for (Company customer : customers) {
        System.out.format("%s\tcustomers/%d\n",
              customer.getCompanyName(), customer.getCompanyId());
    }
}

.NET

CustomersResource.ListRequest accountRequest = service.Customers.List();
accountRequest.PageSize = 100;
CustomerListCustomersResponse accountResponse = accountRequest.Execute();
IList<Company> customers = accountResponse.Customers ?? new List<Company>();
if (customers.Count == 0)
{
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    Console.WriteLine("No zero-touch enrollment account found.");
}
foreach (Company customer in customers)
{
    Console.WriteLine("{0}\tcustomers/{1}",
                      customer.CompanyName,
                      customer.CompanyId);
}

Python

response = service.customers().list(pageSize=100).execute()
if 'customers' not in response:
  # No accounts found for the user. Confirm the Google Account
  # that authorizes the request can access the zero-touch portal.
  print('No zero-touch enrollment account found.')
  response['customers'] = []

for customer in response['customers']:
  print('{0}\tcustomers/{1}'.format(
      customer['companyName'], customer['companyId']))

En tu app, deberás navegar por las páginas de resultados de la cuenta porque el ejemplo anterior solo imprime las primeras 100 cuentas. Para aprender a hacerlo, consulta Resultados paginados.

Una organización suele tener una cuenta de cliente, pero las organizaciones más grandes pueden usar cuentas de clientes diferentes para cada división. Debido a que un administrador de TI puede ser miembro de diferentes cuentas de clientes, tu app debe ayudar a los usuarios a encontrar y usar cuentas de clientes nuevas. En tu app, etiqueta cada cuenta de cliente con el valor companyName.

empresariales

Los administradores de TI autorizan las solicitudes a la API que tu app envía en su nombre. Para autorizar las solicitudes a la API, el usuario de tu app debe hacer lo siguiente:

1. Asocia una Cuenta de Google a su dirección de correo electrónico.
2. Únete a una cuenta de cliente con la misma dirección de correo electrónico.
3. Acepta las Condiciones del Servicio de la inscripción automática del cliente.

A fin de ayudar a los usuarios de tu app a configurar, reutiliza nuestra guía para administradores de TI en Comenzar y Asocia una Cuenta de Google en tu propia documentación.

Administración de usuarios

Los administradores de TI gestionan los usuarios de las cuentas de sus clientes en el portal de inscripción automática. Los usuarios de una cuenta de cliente tienen una función que es Propietario o Administrador. Ambas funciones tienen el mismo acceso a la API del cliente, pero un propietario puede administrar a otros usuarios.

Aceptación de las Condiciones del Servicio

Para que los usuarios de tu app puedan autorizar llamadas a la API, deben aceptar las Condiciones del Servicio más recientes. Esto sucede cuando los administradores de TI usan la inscripción automática por primera vez o cuando actualizamos las Condiciones del Servicio. Cuando un usuario no aceptó las Condiciones del Servicio más recientes, la API muestra un código de estado HTTP 403 Forbidden, y el cuerpo de la respuesta contiene un TosError.

El portal les solicita automáticamente a los usuarios que acepten las Condiciones del Servicio más recientes cuando accedan. Para ver los enfoques sugeridos que podría incluir tu app, lee Administra las Condiciones del Servicio en la guía de integración de EMM.

Cómo agregar autorización a tu app

Cada solicitud que tu app envía a la API del cliente debe incluir un token de autorización. El token también identifica tu aplicación ante Google. Debido a que la API del cliente accede a los datos del usuario, la autorización debe provenir del propietario de los datos. Tu app delega la autorización de la API a los administradores de TI mediante el protocolo OAuth 2.0.

Punto clave: Para facilitar la configuración de la autorización y la autenticación, Google proporciona bibliotecas cliente que pueden reducir la cantidad de código que necesitas escribir y hacer que tu código sea más sólido. Recomendamos usar una biblioteca cliente para llamar a la API del cliente. Consulta las guías de inicio rápido para Java, .NET y Python.

Instrucciones

Proporcionamos guías de inicio rápido para las apps de Java, .NET y Python. Si usas un idioma diferente, sigue los dos pasos que se indican a continuación para configurar la autorización de la app.

Paso 1: Activa la API de inscripción automática

1. Usa este asistente para crear o seleccionar un proyecto en Google Developers Console y activar automáticamente la API. Haz clic en Continuar y, luego, en Ir a Credenciales.
2. Haz clic en Cancelar en Crear credenciales.
3. En la parte superior de la página, seleccione la pestaña OAuth consent screen. Selecciona una dirección de correo electrónico, ingresa un Nombre del producto si aún no lo hiciste y haz clic en el botón Guardar.
4. Selecciona la pestaña Credenciales, haz clic en el botón Crear credenciales y selecciona ID de cliente de OAuth.
5. Selecciona un Tipo de aplicación en función del tipo de app que estés creando.
6. Configura Name como el nombre de tu app.
7. Haz clic en Crear.
8. Haz clic en Download JSON.
9. Mueve el archivo a tu directorio de trabajo y cámbiale el nombre a client_secret.json.

Paso 2: Instala la biblioteca cliente

Si quieres instalar la biblioteca cliente para tu lenguaje, sigue estos pasos:

1. Ve a las bibliotecas cliente de la API de Google y selecciona tu idioma de la lista de lenguajes compatibles.
2. Sigue las instrucciones para instalar la biblioteca cliente.

Si deseas obtener más información sobre la autorización, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Permisos de autorización

Usa el alcance de autorización de la API https://www.googleapis.com/auth/androidworkzerotouchemm en tu app para solicitar un token de acceso de OAuth 2.0.

Un parámetro de alcance controla el conjunto de recursos y operaciones a los que un token de acceso permite llamadas. Los tokens de acceso solo son válidos para el conjunto de operaciones y recursos descritos en el alcance de la solicitud del token. La API abarca todos los métodos y recursos con el alcance único de la inscripción automática que se mostró anteriormente.

Para ver un ejemplo del alcance de la inscripción automática que se usa con la biblioteca cliente de la API de Google, consulta las guías de inicio rápido para Java, .NET y Python. Si quieres obtener más información sobre el uso de los alcances de la API de Google, consulta Usa OAuth 2.0 para acceder a las API de Google.

Prácticas recomendadas para las claves de API

Cuando usas claves de API en tus aplicaciones, ten cuidado de mantenerlas seguras. Si expones tus credenciales en público, puedes comprometer tu cuenta y generar cargos inesperados. Para mantener tus claves de API seguras, sigue estas prácticas recomendadas:

No incorpores claves de API directamente en el código

Las claves de API incorporadas en el código pueden exponerse accidentalmente al público, por ejemplo, si te olvidas de quitar las claves del código que compartes. En lugar de incorporar tus claves de API en las aplicaciones, almacénalas en variables de entorno o en archivos fuera del árbol fuente de tu aplicación.

No almacenes claves de API en archivos dentro del árbol fuente de tu aplicación

Si almacenas claves de API en archivos, mantenlos fuera del árbol fuente de tu aplicación para asegurarte de que las claves no terminen en tu sistema de control de código fuente. Esto es muy importante si usas un sistema de administración de código fuente público como GitHub.

Restringe tus claves de API para que solo las usen las direcciones IP, las URLs de referencia y las apps para dispositivos móviles que las necesiten.

Si restringes las direcciones IP, URLs de referencia y apps para dispositivos móviles que pueden usar cada clave, puedes reducir el impacto de una clave de API vulnerada. Puedes especificar los hosts y las apps que pueden usar cada clave desde la Consola de API de Google. Para ello, abre la página de Credenciales y crea una clave de API nueva con la configuración que desees, o bien edita la configuración de una clave de API.

Borra las claves de API innecesarias

Para minimizar la exposición a los ataques, borra las claves de API que ya no necesites.

Regenera tus claves de API de forma periódica

Para volver a generar las claves de API desde la Consola de API de Google, abre la página Credenciales, selecciona una clave de API y haz clic en Volver a generar clave para cada una. Luego, actualiza tus aplicaciones para que usen las claves recién generadas. Tus claves anteriores seguirán funcionando durante 24 horas después de que generes las claves de reemplazo.

Revisa el código antes de lanzarlo de forma pública

Asegúrate de que tu código no contenga claves de API ni ninguna otra información privada antes de hacer que esté disponible públicamente.