L'API Gmail S/MIME fornisce accesso programmatico per gestire i certificati email S/MIME per gli utenti di un Google Workspace dominio.
Affinché i certificati funzionino, un amministratore deve attivare S/MIME per il dominio.
Lo standard S/MIME fornisce una specifica per la crittografia e la firma con chiave pubblica dei dati MIME. La configurazione dei certificati S/MIME nell'account di un utente fa sì che Gmail li utilizzi nel seguente modo:
- Gmail utilizza il certificato e la chiave privata dell'utente per firmare la posta in uscita.
- Gmail utilizza la chiave privata dell'utente per decriptare la posta in arrivo.
- Gmail utilizza il certificato e la chiave pubblica del destinatario per criptare la posta in uscita.
- Gmail utilizza il certificato e la chiave pubblica del mittente per verificare la posta in arrivo.
Genera singoli certificati S/MIME e caricali utilizzando l'API. Ogni certificato S/MIME è destinato a un alias specifico per l'account email di un utente. Gli alias includono l'indirizzo email principale e gli indirizzi "Invia come" personalizzati. Un singolo certificato S/MIME è contrassegnato come predefinito per ogni alias.
Autorizzazione dell'accesso all'API
Esistono due forme di autorizzazione di accesso all'API:
- Puoi utilizzare un account di servizio con delega dell'autorità a livello di dominio. Per una spiegazione di questi termini, consulta Termini della panoramica di autenticazione e autorizzazione. Per informazioni su come attivare questa opzione, consulta Creare un account di servizio con delega dell'autorità a livello di dominio
- Puoi utilizzare un flusso OAuth2 standard che richiede il consenso dell'utente finale per ottenere un token di accesso OAuth2. Per ulteriori informazioni, consulta la Panoramica di autenticazione e autorizzazione. Per utilizzare questa opzione, l'amministratore del dominio deve attivare la casella di controllo "Accesso utente finale all'API S/MIME abilitato" nel pannello di controllo del dominio.
Ambiti ACL
Questa API si basa sugli stesse autorizzazioni di accesso controllato dei metodi sendAs di Gmail:
- gmail.settings.basic
- Questo ambito è necessario per aggiornare l'attributo SendAs S/MIME principale.
- gmail.settings.sharing
- Questo ambito è necessario per aggiornare da S/MIME personalizzato.
Utilizzo dell'API
La risorsa users.settings.sendAs.smimeInfo fornisce i metodi che utilizzi per gestire i certificati S/MIME. Ogni certificato è associato a un alias di invio per un utente.
Caricare una chiave S/MIME
Utilizza il metodo smimeInfo.insert() per caricare una nuova chiave S/MIME per un alias appartenente a un utente. L'alias target viene identificato utilizzando i seguenti parametri:
- userId
- L'indirizzo email dell'utente. Puoi utilizzare il valore speciale
me
per indicare l'utente attualmente autenticato. - sendAsEmail
- L'alias per cui stai caricando la chiave. Si tratta dell'indirizzo email visualizzato nell'intestazione "Da:" per la posta inviata utilizzando questo alias.
Il certificato S/MIME e la chiave privata devono essere presenti nel campo pkcs12
in questo formato; non devono essere impostati altri campi nella richiesta. Il campo PKCS12 dovrebbe contenere sia la chiave S/MIME dell'utente sia la catena del certificato di firma. L'API esegue convalide standard su questo
campo prima di accettarlo, verificando quanto segue:
- L'oggetto corrisponde all'indirizzo email specificato.
- Le scadenze sono valide.
- L'autorità di certificazione (CA) che ha emesso il certificato è presente nel nostro elenco attendibile.
- I certificati corrispondono ai vincoli tecnici di Gmail.
Se la chiave è criptata, la password deve trovarsi nel campo encryptedKeyPassword
. Le chiamate insert() andate a buon fine restituiranno l'ID di smimeInfo che può essere utilizzato per fare riferimento alla chiave in futuro.
Elenca le chiavi S/MIME di un utente
Utilizza il metodo smimeInfo.list() per restituire l'elenco delle chiavi S/MIME per l'utente e l'alias specificati. L'alias target viene identificato utilizzando i seguenti parametri:
- userId
- L'indirizzo email dell'utente. Puoi utilizzare il valore speciale
me
per indicare l'utente attualmente autenticato. - sendAsEmail
- L'alias per cui elencare le chiavi. Si tratta dell'indirizzo email visualizzato nell'intestazione "Da:" per la posta inviata utilizzando questo alias.
Recuperare le chiavi S/MIME per un alias
Utilizza il metodo smimeInfo.get() per ripristinare le chiavi S/MIME specifiche per un alias Invia come specifico per un utente. L'alias target viene identificato utilizzando i seguenti parametri:
- userId
- L'indirizzo email dell'utente. Puoi utilizzare il valore speciale
me
per indicare l'utente attualmente autenticato. - sendAsEmail
- L'alias per cui stai recuperando le chiavi. Si tratta dell'indirizzo email visualizzato nell'intestazione "Da:" per la posta inviata utilizzando questo alias.
Eliminare una chiave S/MIME
Utilizza il metodo smimeInfo.delete() per eliminare la chiave S/MIME specificata da un alias. L'alias target viene identificato utilizzando i seguenti parametri:
- userId
- L'indirizzo email dell'utente. Puoi utilizzare il valore speciale
me
per indicare l'utente attualmente autenticato. - sendAsEmail
- L'alias per cui stai recuperando le chiavi. Si tratta dell'indirizzo email visualizzato nell'intestazione "Da:" per la posta inviata utilizzando questo alias.
- id
- L'ID non modificabile per SmimeInfo.
Impostare la chiave S/MIME predefinita per un alias
Utilizza il metodo smimeInfo.setDefault() per contrassegnare la chiave S/MIME specificata come predefinita per l'alias specificato. L'alias target viene identificato utilizzando i seguenti parametri:
- userId
- L'indirizzo email dell'utente. Puoi utilizzare il valore speciale
me
per indicare l'utente attualmente autenticato. - sendAsEmail
- L'alias per cui stai recuperando le chiavi. Si tratta dell'indirizzo email visualizzato nell'intestazione "Da:" per la posta inviata utilizzando questo alias.
- id
- L'ID non modificabile per SmimeInfo.
Codice di esempio
I seguenti esempi di codice mostrano come utilizzare l'API per gestire i certificati S/MIME per un'organizzazione con più utenti.
Creazione di una risorsa SmimeInfo per un certificato S/MIME
Il seguente esempio di codice mostra la lettura di un certificato da un file, la codifica in una stringa base64url e l'assegnazione al campo pkcs12
della risorsa smimeInfo
:
Java
Python
Caricamento di un certificato S/MIME
Per caricare un certificato, chiama
smimeInfo.insert
,
e fornisci la risorsa smimeInfo
nel corpo della richiesta:
Java
Python
Esempi per la gestione dei certificati di molti utenti
Potresti voler gestire i certificati per molti utenti dell'organizzazione contemporaneamente. Gli esempi riportati di seguito mostrano come gestire i certificati per più utenti in una chiamata batch.
Inserire i certificati da un file CSV
Supponiamo di avere un file CSV che elenca gli ID utente e il percorso del certificato di ciascun utente:
$ 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
Puoi utilizzare le chiamate createSmimeInfo
e insertSmimeInfo
di cui sopra per caricare i certificati come specificato nel file CSV:
Python
Puoi utilizzare le chiamate create_smime_info
e insert_smime_info
di cui sopra per caricare i certificati come specificato nel file CSV:
Gestione dei certificati
Questo esempio combina diverse chiamate dell'API smimeInfo
per mostrare come gestire i certificati per la tua organizzazione. Elenca i certificati per l'utente e, se il certificato predefinito è scaduto o non è impostato, carica il certificato trovato nel file specificato. Imposta poi come predefinito il certificato la cui scadenza è più lontana nel futuro.
Viene poi chiamato da una funzione che elabora un file CSV come nell'esempio precedente.