En este documento, se explica cómo usar certificados de correo electrónico S/MIME con la API de Gmail.
La API de Gmail proporciona acceso programático para administrar los certificados de correo electrónico S/MIME de los usuarios en un dominio de Google Workspace.
Para que los certificados funcionen, el administrador debe activar S/MIME alojado para el dominio.
El estándar S/MIME proporciona una especificación para la firma y la encriptación de clave pública de los datos MIME. Cuando configuras certificados S/MIME para una cuenta de usuario, Gmail los usa de las siguientes maneras:
Firma el correo saliente con el certificado de usuario y la clave privada.
Desencriptar el correo entrante con la clave privada del usuario
Encripta el correo saliente con el certificado y la clave pública del destinatario.
Verifica el correo entrante con el certificado del remitente y la clave pública.
Puedes generar certificados S/MIME individuales y subirlos con la API de Gmail. Cada certificado de S/MIME es para un alias específico de una cuenta de correo electrónico del usuario. Los alias incluyen la dirección de correo electrónico principal y las direcciones personalizadas de enviar como. La API marca un solo certificado de S/MIME como predeterminado para cada alias.
Para obtener más información sobre los alias, consulta Administra alias y firmas con la API de Gmail.
Autoriza el acceso a la API
Para autorizar el acceso a la API de Gmail, usa uno de los siguientes métodos:
Usa una cuenta de servicio con delegación de autoridad en todo el dominio. Para obtener una explicación de estos términos, consulta Obtén información sobre la autenticación y la autorización. Para habilitar esta opción, consulta Crea credenciales de acceso.
Usa un flujo de OAuth 2.0 estándar que requiera el consentimiento del usuario para obtener un token de acceso de OAuth 2.0. Para obtener más información, consulta Más información sobre la autenticación y la autorización.
Para usar esta opción, el administrador del dominio debe seleccionar la casilla de verificación Habilitar la encriptación S/MIME para enviar y recibir correos electrónicos en la Consola del administrador de Google. Para obtener más información, consulta Cómo activar S/MIME alojado en tu Consola del administrador.
Permisos de autorización
La API de Gmail se basa en los mismos permisos de OAuth que los métodos Gmail sendAs:
gmail.settings.basic: Se requiere para actualizar elSendAsprincipal de S/MIME.gmail.settings.sharing: Se requiere para actualizar el S/MIME personalizado from.
Cómo configurar claves S/MIME
El recurso settings.sendAs.smimeInfo proporciona varios métodos para administrar certificados de S/MIME. Cada certificado está asociado con un alias de enviar como para un usuario.
Para determinar los alias de envío de un usuario, usa el método settings.sendAs.list en el recurso settings.sendAs.
Cómo subir una clave S/MIME
Usa el método settings.sendAs.smimeInfo.insert en el recurso settings.sendAs.smimeInfo para subir una clave S/MIME nueva para un alias que pertenece a un usuario. Identifica el alias de destino con los siguientes parámetros de ruta:
userId: La dirección de correo electrónico del usuario. Usa el valor especialmepara indicar el usuario autenticado.sendAsEmail: Es el alias para el que subirás la clave. Esta dirección de correo electrónico aparece en el encabezadoFrom:de los correos electrónicos enviados con este alias.
Proporciona el certificado S/MIME y la clave privada en el campo pkcs12 en formato PKCS #12. No configures ningún otro campo en la solicitud. El campo pkcs12 contiene la clave S/MIME del usuario y la cadena de certificados de firma. La API realiza validaciones estándar en este campo antes de aceptarlo y verifica lo siguiente:
- El asunto coincide con la dirección de correo electrónico especificada.
- Los vencimientos son válidos.
- La autoridad certificadora (CA) emisora se encuentra en la lista de entidades de confianza de Google.
- Los certificados cumplen con las restricciones técnicas de Gmail.
Si la clave está encriptada, proporciona la contraseña en el campo encryptedKeyPassword. Una llamada correcta al método settings.sendAs.smimeInfo.insert devuelve el recurso settings.sendAs.smimeInfo id que se usará para hacer referencia a la clave en el futuro.
Enumera las claves de S/MIME de un usuario
Usa el método settings.sendAs.smimeInfo.list en el recurso settings.sendAs.smimeInfo para mostrar la lista de claves de S/MIME del usuario y el alias especificados. Identifica el alias de destino con los siguientes parámetros de ruta:
userId: La dirección de correo electrónico del usuario. Usa el valor especialmepara indicar el usuario autenticado.sendAsEmail: Es el alias para el que se enumerarán las claves. Esta dirección de correo electrónico aparece en el encabezadoFrom:de los correos electrónicos enviados con este alias.
Recupera las claves de S/MIME para un alias
Usa el método settings.sendAs.smimeInfo.get en el recurso settings.sendAs.smimeInfo para devolver las claves S/MIME específicas de un alias de envío específico para un usuario. Identifica el alias de destino con los siguientes parámetros de ruta:
userId: La dirección de correo electrónico del usuario. Usa el valor especialmepara indicar el usuario autenticado.sendAsEmail: Es el alias para el que recuperas las claves. Esta dirección de correo electrónico aparece en el encabezadoFrom:de los correos electrónicos enviados con este alias.
Cómo borrar una clave S/MIME
Usa el método settings.sendAs.smimeInfo.delete en el recurso settings.sendAs.smimeInfo para borrar la clave S/MIME especificada de un alias. Identifica el alias de destino con los siguientes parámetros de ruta:
userId: La dirección de correo electrónico del usuario. Usa el valor especialmepara indicar el usuario autenticado.sendAsEmail: Es el alias desde el que borrarás la clave. Esta dirección de correo electrónico aparece en el encabezadoFrom:de los correos electrónicos enviados con este alias.id: Es el ID inmutable delsmimeInfo.
Una clave borrada ya no es visible ni se puede usar. No puedes desencriptar los correos electrónicos de S/MIME recibidos que se encriptaron con la clave pública correspondiente. Antes de borrar una clave, revócala con su autoridad emisora (CA).
Cómo establecer la clave S/MIME predeterminada para un alias
Usa el método settings.sendAs.smimeInfo.setDefault en el recurso settings.sendAs.smimeInfo para marcar la clave de S/MIME especificada como la predeterminada para el alias especificado. Identifica el alias de destino con los siguientes parámetros de ruta:
userId: La dirección de correo electrónico del usuario. Usa el valor especialmepara indicar el usuario autenticado.sendAsEmail: Es el alias para el que se establecerá la clave predeterminada. Esta dirección de correo electrónico aparece en el encabezadoFrom:de los correos electrónicos enviados con este alias.id: Es el ID inmutable delsmimeInfo.
Solo una clave de S/MIME es la predeterminada para el alias de enviar como de un usuario. Si llamas al método settings.sendAs.smimeInfo.setDefault, se anula el valor predeterminado anterior.
Cuando un usuario recibe mensajes de S/MIME firmados con una clave determinada, Gmail asocia la clave con la fecha de validez not_before más lejana en el futuro como la predeterminada cuando encripta el correo que se envía al usuario asociado. Para asegurarte de que los usuarios de Gmail con los que el usuario ya se comunicó usen la nueva clave predeterminada, asegúrate de que la nueva clave predeterminada tenga una fecha de not_before posterior a la de la clave predeterminada anterior o revoca la clave predeterminada anterior.
Muestras de código
En los siguientes ejemplos de código, se muestra cómo usar la API de Gmail para administrar certificados S/MIME para una organización con varios usuarios:
Crea un recurso smimeInfo para un certificado de S/MIME
En esta muestra de código, se muestra cómo leer un certificado de un archivo, codificarlo en una cadena Base64URL y asignarlo al campo pkcs12 del recurso settings.sendAs.smimeInfo:
Java
Python
Cómo subir un certificado S/MIME
Para subir un certificado, llama al método settings.sendAs.smimeInfo.insert y proporciona el recurso settings.sendAs.smimeInfo en el cuerpo de la solicitud:
Java
Python
Administra los certificados de varios usuarios
En estas muestras de código, se muestra cómo administrar certificados para varios usuarios de una organización en una sola llamada por lotes:
Cómo insertar certificados desde un archivo CSV
A continuación, se muestra un ejemplo de un archivo CSV que enumera los IDs de usuario y la ruta de acceso al certificado de cada usuario:
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
Java
Puedes usar los ejemplos CreateSmimeInfo y InsertSmimeInfo para subir los certificados de los usuarios especificados en un archivo CSV:
Python
Puedes usar los ejemplos create_smime_info y insert_smime_info para subir los certificados de los usuarios especificados en un archivo CSV:
Administración de certificados
En esta muestra, se combinan varios métodos del recurso settings.sendAs.smimeInfo para mostrar cómo administrar los certificados de tu organización. Enumera los certificados del usuario. Si el certificado predeterminado venció o no se configuró, se subirá el certificado que se encuentre en el archivo especificado. Luego, establece como predeterminado el certificado cuya fecha de vencimiento sea la más lejana.
Luego, esta función procesa un archivo CSV, de manera similar al ejemplo anterior de Insertar certificados desde un archivo CSV.
Java
Python
Temas relacionados
- Administra alias y firmas con la API de Gmail
- Elige los permisos de la API de Gmail
- Cómo activar las S/MIME alojadas para la encriptación de mensajes