L'API Gmail S/MIME fornisce accesso programmatico per gestire i certificati email S/MIME per gli utenti di un Google Workspace dominio.
Un amministratore deve abilitare S/MIME per il dominio affinché i certificati funzionino.
Lo standard S/MIME fornisce una specifica per la crittografia della chiave pubblica e la firma dei dati MIME. Se configuri i certificati S/MIME nell'account di un utente, Gmail utilizzerà il certificato nei seguenti modi:
- 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.
Puoi generare singoli certificati S/MIME e caricarli utilizzando l'API. Ogni certificato S/MIME è destinato a un alias specifico per un account email dell'utente. Gli alias includono l'indirizzo email principale e gli indirizzi personalizzati "Invia come". Un singolo certificato S/MIME è contrassegnato come predefinito per ciascun alias.
Autorizzazione dell'accesso all'API
Esistono due modi per autorizzare l'accesso all'API:
- Puoi utilizzare un account di servizio con la delega dell'autorità a livello di dominio. Per una spiegazione di questi termini, consulta la sezione Termini della panoramica di autenticazione e autorizzazioni. Per informazioni sull'abilitazione di 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 di dominio deve abilitare la casella di controllo "Accesso utente finale API S/MIME abilitato" nel pannello di controllo Dominio.
Ambiti ACL
Questa API si basa sugli stessi ambiti ACL dei metodi SendAs di Gmail:
- gmail.settings.basic
- Questo ambito è obbligatorio per l'aggiornamento del codice S/MIME principale di SendAs.
- gmail.settings.sharing
- Questo ambito è obbligatorio per l'aggiornamento di S/MIME personalizzato da.
Utilizzo dell'API
La risorsa users.settings.sendAs.smimeInfo fornisce i metodi utilizzati per gestire i certificati S/MIME. Ogni certificato è associato a un alias di invio come per un utente.
Carica una chiave S/MIME
Utilizza il metodo smimeInfo.insert() per caricare una nuova chiave S/MIME per un alias appartenente a un utente. Puoi identificare l'alias di destinazione 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:" della 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 deve contenere sia la chiave S/MIME dell'utente sia la catena di certificati 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 emittente (CA) è presente nel nostro elenco di certificati attendibili.
- I certificati soddisfano i vincoli tecnici di Gmail.
Se la chiave è criptata, la password deve trovarsi nel campo encryptedKeyPassword
. Le chiamate insert() riuscite restituiranno l'ID smimeInfo che può essere utilizzato per fare riferimento alla chiave in futuro.
Elencare le chiavi S/MIME di un utente
Utilizza il metodo smimeInfo.list() per restituire l'elenco di chiavi S/MIME per l'utente specificato per l'alias. Puoi identificare l'alias di destinazione 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:" della posta inviata utilizzando questo alias.
Recuperare le chiavi S/MIME per un alias
Utilizza il metodo smimeInfo.get() per restituire le chiavi S/MIME specifiche per un alias di invio come specifico per un utente. Puoi identificare l'alias di destinazione 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:" della 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. Puoi identificare l'alias di destinazione 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:" della posta inviata utilizzando questo alias.
- id
- L'ID immutabile di 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. Puoi identificare l'alias di destinazione 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:" della posta inviata utilizzando questo alias.
- id
- L'ID immutabile di SmimeInfo.
Codice campione
I seguenti esempi di codice mostrano l'utilizzo dell'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 file, la codifica in una stringa base64url e l'assegnazione al campo pkcs12
della risorsa smimeInfo
:
Java
Python
Caricare 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 di certificati di molti utenti
Potresti voler gestire contemporaneamente i certificati per più utenti dell'organizzazione. Gli esempi seguenti mostrano come gestire i certificati per più utenti in un'unica chiamata batch.
Inserimento di certificati da un file CSV
Supponi di avere un file CSV in cui sono elencati 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
precedenti per caricare i certificati come specificato nel file CSV:
Python
Puoi utilizzare le chiamate create_smime_info
e insert_smime_info
precedenti per caricare i certificati come specificato nel file CSV:
Gestione dei certificati
Questo esempio combina diverse chiamate dall'API smimeInfo
per mostrare come puoi gestire i certificati per la tua organizzazione. Elenca i certificati per l'utente e, se il certificato predefinito è scaduto o non è impostato, carica quello trovato nel file specificato. poi imposta come predefinito il certificato la cui scadenza è la più lontana nel futuro.
Viene quindi richiamata da una funzione che elabora un file CSV come nell'esempio precedente.