A API S/MIME do Gmail oferece acesso programático para gerenciar certificados de e-mail S/MIME para usuários em um Google Workspace domínio.
Um administrador precisa ativar o S/MIME no domínio para que os certificados funcionem.
O padrão S/MIME fornece uma especificação para criptografia de chave pública e assinatura de dados MIME. A configuração de certificados S/MIME em uma conta de usuário faz com que o Gmail use esse certificado das seguintes maneiras:
- O Gmail usa o certificado e a chave privada do usuário para assinar os e-mails enviados.
- O Gmail usa a chave privada do usuário para descriptografar os e-mails recebidos.
- O Gmail usa o certificado e a chave pública do destinatário para criptografar os e-mails enviados.
- O Gmail usa o certificado do remetente e a chave pública para verificar os e-mails recebidos.
Você gera certificados S/MIME individuais e faz upload deles usando a API. Cada certificado S/MIME é para um alias específico de uma conta de e-mail de usuário. Os aliases incluem o endereço de e-mail principal e os endereços "Enviar como" personalizados. Um único certificado S/MIME é marcado como padrão para cada alias.
Como autorizar o acesso à API
Há duas formas de autorizar o acesso à API:
- Você pode usar uma conta de serviço com a delegação de autoridade em todo o domínio. Para uma explicação desses termos, consulte os Termos de visão geral da autenticação e autorização. Para informações sobre como ativar essa opção, consulte Criar uma conta de serviço com delegação de autoridade em todo o domínio.
- É possível usar um fluxo OAuth2 padrão que requer o consentimento do usuário final para receber um token de acesso do Oauth2. Para mais informações, consulte a Visão geral da autenticação e autorização. Para usar essa opção, o administrador do domínio precisa ativar a caixa de seleção "Acesso do usuário final da API S/MIME ativado" no painel de controle do domínio.
Escopos da ACL
Essa API depende dos mesmos escopos de ACL que os métodos sendAs do Gmail:
- gmail.settings.basic
- Este escopo é necessário para atualizar o S/MIME principal do remetente.
- gmail.settings.sharing
- Este escopo é necessário para atualizar o S/MIME do S/MIME personalizado.
Como usar a API
O recurso users.settings.sendAs.smimeInfo fornece os métodos usados para gerenciar certificados S/MIME. Cada certificado está associado a um alias enviar-como para um usuário.
Fazer upload de uma chave S/MIME
Use o método smimeInfo.insert() para fazer upload de uma nova chave S/MIME para um alias pertencente a um usuário. Para identificar o alias de destino, use os seguintes parâmetros:
- userId
- O endereço de e-mail do usuário. É possível usar o valor especial
me
para indicar o usuário autenticado no momento. - sendAsEmail
- O alias para onde você está fazendo o upload da chave. Esse é o endereço de e-mail que aparece no cabeçalho "De:" nos e-mails enviados usando esse alias.
O certificado S/MIME e a chave privada precisam estar presentes no campo pkcs12
nesse formato. Nenhum outro campo precisa ser definido na solicitação. O campo PKCS12 precisa conter a chave S/MIME do usuário
e a cadeia de certificados de assinatura. A API executa validações padrão nesse
campo antes de aceitá-lo, verificando o seguinte:
- O assunto corresponde ao endereço de e-mail especificado.
- As expirações são válidas.
- A autoridade certificadora (CA) emissora está na nossa lista de confiança.
- Os certificados correspondem às restrições técnicas do Gmail.
Se a chave estiver criptografada, a senha precisará estar no campo encryptedKeyPassword
. Chamadas insert() bem-sucedidas retornarão o ID do smimeInfo, que pode ser usado para se referir à chave no futuro.
Listar as chaves S/MIME de um usuário
Use o método smimeInfo.list() para retornar a lista de chaves S/MIME de determinado usuário para o alias especificado. Para identificar o alias de destino, use os seguintes parâmetros:
- userId
- O endereço de e-mail do usuário. É possível usar o valor especial
me
para indicar o usuário autenticado no momento. - sendAsEmail
- O alias para listar as chaves. Esse é o endereço de e-mail que aparece no cabeçalho "De:" nos e-mails enviados usando esse alias.
Recuperar as chaves S/MIME de um alias
Use o método smimeInfo.get() para retornar as chaves S/MIME específicas de um alias enviar-como específico para um usuário. Para identificar o alias de destino, use os seguintes parâmetros:
- userId
- O endereço de e-mail do usuário. É possível usar o valor especial
me
para indicar o usuário autenticado no momento. - sendAsEmail
- O alias para o qual você está recuperando as chaves. Esse é o endereço de e-mail que aparece no cabeçalho "De:" nos e-mails enviados usando esse alias.
Excluir uma chave S/MIME
Use o método smimeInfo.delete() para excluir a chave S/MIME especificada de um alias. Para identificar o alias de destino, use os seguintes parâmetros:
- userId
- O endereço de e-mail do usuário. É possível usar o valor especial
me
para indicar o usuário autenticado no momento. - sendAsEmail
- O alias para o qual você está recuperando as chaves. Esse é o endereço de e-mail que aparece no cabeçalho "De:" nos e-mails enviados usando esse alias.
- id
- O ID imutável do SmimeInfo.
Definir a chave S/MIME padrão de um alias
Use o método smimeInfo.setDefault() para marcar a chave S/MIME especificada como padrão para o alias especificado. Para identificar o alias de destino, use os seguintes parâmetros:
- userId
- O endereço de e-mail do usuário. É possível usar o valor especial
me
para indicar o usuário autenticado no momento. - sendAsEmail
- O alias para o qual você está recuperando as chaves. Esse é o endereço de e-mail que aparece no cabeçalho "De:" nos e-mails enviados usando esse alias.
- id
- O ID imutável do SmimeInfo.
Exemplo de código
Os exemplos de código a seguir demonstram o uso da API para gerenciar certificados S/MIME para uma organização com vários usuários.
Como criar um recurso SmimeInfo para um certificado S/MIME
O exemplo de código a seguir demonstra a leitura de um certificado do arquivo, a codificação
para uma string base64url e a atribuição dela ao campo pkcs12
do recurso
smimeInfo
:
Java
Python
Fazer upload de um certificado S/MIME
Para fazer upload de um certificado, chame smimeInfo.insert
e forneça o recurso smimeInfo
no corpo da solicitação:
Java
Python
Exemplos de gerenciamento de certificados de vários usuários
É possível gerenciar certificados de vários usuários na organização de uma só vez. Os exemplos a seguir mostram como gerenciar certificados de vários usuários em uma chamada em lote.
Inserir certificados de um arquivo CSV
Suponha que você tenha um arquivo CSV que liste os IDs do usuário e o caminho para o certificado de cada usuário:
$ 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
É possível usar as chamadas createSmimeInfo
e insertSmimeInfo
anteriores para fazer upload dos certificados, conforme especificado no arquivo CSV:
Python
É possível usar as chamadas create_smime_info
e insert_smime_info
anteriores para fazer upload dos certificados, conforme especificado no arquivo CSV:
Gerenciamento de certificados
Este exemplo combina várias chamadas da API smimeInfo
para mostrar como é possível gerenciar certificados para sua organização. Ele lista os certificados do
usuário e, se o certificado padrão estiver expirado ou não estiver definido, ele fará upload do certificado encontrado no
arquivo especificado. Em seguida, ele define o certificado cuja expiração está mais distante no futuro como o padrão.
Em seguida, ele é chamado em uma função que processa um arquivo CSV como no exemplo anterior.