La API de S/MIME de Gmail proporciona acceso programático para administrar los certificados de correo electrónico de S/MIME de los usuarios en un dominio de Google Workspace.
Para que los certificados funcionen, el administrador debe habilitar S/MIME para el dominio.
El estándar S/MIME proporciona una especificación para la encriptación de clave pública y la firma de datos MIME. Cuando se configuran certificados S/MIME en la cuenta de un usuario, Gmail usa ese certificado de las siguientes maneras:
- Gmail usa el certificado y la clave privada del usuario para firmar el correo saliente.
- Gmail usa la clave privada del usuario para desencriptar el correo entrante.
- Gmail usa el certificado y la clave pública del destinatario para encriptar el correo saliente.
- Gmail usa el certificado y la clave pública del remitente para verificar el correo entrante.
Generas certificados S/MIME individuales y los subes con la API. 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". Un solo certificado S/MIME se marca como predeterminado para cada alias.
Autoriza el acceso a la API
Existen dos formas de autorizar el acceso a la API:
- Puedes usar una cuenta de servicio con delegación de autoridad en todo el dominio. Para obtener una explicación de estos términos, consulta Términos de la descripción general de la autenticación y la autorización. Para obtener información sobre cómo habilitar esta opción, consulta Crea una cuenta de servicio con delegación de autoridad en todo el dominio.
- Puedes usar un flujo de OAuth2 estándar que requiera el consentimiento del usuario final para obtener un token de acceso de OAuth2. Para obtener más información, consulta la Descripción general de la autenticación y la autorización. Para usar esta opción, el administrador del dominio debe habilitar la casilla de verificación "Acceso de usuario final a la API de S/MIME habilitado" en el panel de control del dominio.
Alcances de LCA
Esta API se basa en los mismos permisos de ACL que los métodos de Gmail sendAs:
- gmail.settings.basic
- Este alcance es obligatorio para actualizar el S/MIME principal de SendAs.
- gmail.settings.sharing
- Este alcance es obligatorio para actualizar el de S/MIME personalizado.
Usa la API
El recurso users.settings.sendAs.smimeInfo proporciona los métodos que usas para administrar los certificados de S/MIME. Cada certificado está asociado con un alias de enviar como para un usuario.
Cómo subir una clave S/MIME
Usa el método smimeInfo.insert() para subir una nueva clave de S/MIME para un alias que pertenece a un usuario. Identifica el alias de destino con los siguientes parámetros:
- userid
- La dirección de correo electrónico del usuario. Puedes usar el valor especial
me
para indicar el usuario autenticado actualmente. - sendAsEmail
- Es el alias para el que subes la clave. Esta es la dirección de correo electrónico que aparece en el encabezado "De:" de los correos electrónicos enviados con este alias.
El certificado de S/MIME y la clave privada deben estar presentes en el campo pkcs12
en ese formato. No se debe configurar ningún otro campo en la solicitud. Se espera que el campo PKCS12 contenga tanto la clave S/MIME del usuario como 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 nuestra lista de entidades de confianza.
- Los certificados cumplen con las restricciones técnicas de Gmail.
Si la clave está encriptada, la contraseña debe estar en el campo encryptedKeyPassword
. Las llamadas a insert() que se realicen correctamente devolverán el ID de smimeInfo, que se puede usar para hacer referencia a la clave en el futuro.
Enumera las claves de S/MIME de un usuario
Usa el método smimeInfo.list() para devolver la lista de claves de S/MIME del usuario y el alias especificados. Identifica el alias de destino con los siguientes parámetros:
- userid
- La dirección de correo electrónico del usuario. Puedes usar el valor especial
me
para indicar el usuario autenticado actualmente. - sendAsEmail
- Alias para el que se enumerarán las claves. Esta es la dirección de correo electrónico que aparece en el encabezado "De:" de los correos electrónicos enviados con este alias.
Recupera las claves de S/MIME para un alias
Usa el método smimeInfo.get() para devolver las claves de 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:
- userid
- La dirección de correo electrónico del usuario. Puedes usar el valor especial
me
para indicar el usuario autenticado actualmente. - sendAsEmail
- Es el alias para el que recuperas las claves. Esta es la dirección de correo electrónico que aparece en el encabezado "De:" de los correos electrónicos enviados con este alias.
Cómo borrar una clave de S/MIME
Usa el método smimeInfo.delete() para borrar la clave S/MIME especificada de un alias. Identifica el alias de destino con los siguientes parámetros:
- userid
- La dirección de correo electrónico del usuario. Puedes usar el valor especial
me
para indicar el usuario autenticado actualmente. - sendAsEmail
- Es el alias para el que recuperas las claves. Esta es la dirección de correo electrónico que aparece en el encabezado "De:" de los correos electrónicos enviados con este alias.
- id
- Es el ID inmutable de SmimeInfo.
Cómo establecer la clave S/MIME predeterminada para un alias
Usa el método smimeInfo.setDefault() 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:
- userid
- La dirección de correo electrónico del usuario. Puedes usar el valor especial
me
para indicar el usuario autenticado actualmente. - sendAsEmail
- Es el alias para el que recuperas las claves. Esta es la dirección de correo electrónico que aparece en el encabezado "De:" de los correos electrónicos enviados con este alias.
- id
- Es el ID inmutable de SmimeInfo.
Código de muestra
En los siguientes ejemplos de código, se muestra cómo usar la API para administrar certificados S/MIME para una organización con varios usuarios.
Crea un recurso de SmimeInfo para un certificado de S/MIME
En la siguiente 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 smimeInfo
:
Java
Python
Cómo subir un certificado S/MIME
Para subir un certificado, llama a smimeInfo.insert
y proporciona el recurso smimeInfo
en el cuerpo de la solicitud:
Java
Python
Ejemplos para administrar los certificados de muchos usuarios
Es posible que desees administrar los certificados de muchos usuarios de la organización a la vez. En los siguientes ejemplos, se muestra cómo administrar certificados para varios usuarios en una sola llamada por lotes.
Cómo insertar certificados desde un archivo CSV
Supongamos que tienes 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 las llamadas createSmimeInfo
y insertSmimeInfo
de antes para subir los certificados como se especifica en el archivo CSV:
Python
Puedes usar las llamadas create_smime_info
y insert_smime_info
de antes para subir los certificados como se especifica en el archivo CSV:
Administración de certificados
En este ejemplo, se combinan varias llamadas de la API de smimeInfo
para mostrar cómo podrías administrar los certificados de tu organización. Enumera los certificados del usuario y, si el certificado predeterminado venció o no se configuró, sube el certificado que se encuentra en el archivo especificado. Luego, establece como predeterminado el certificado cuyo vencimiento sea más lejano en el futuro.
Luego, se llama desde una función que procesa un archivo CSV, como en el ejemplo anterior.