Interfejs S/MIME API w Gmailu zapewnia programowy dostęp do zarządzania certyfikatami e-mail S/MIME dla użytkowników w Google Workspace domenie.
Aby certyfikaty działały, administrator musi włączyć S/MIME w domenie.
Standard S/MIME zawiera wymagania dotyczące szyfrowania i podpisywania danych MIME za pomocą klucza publicznego. Konfigurowanie certyfikatów S/MIME na koncie użytkownika powoduje, że Gmail używa tego certyfikatu w następujący sposób:
- Gmail używa certyfikatu i klucza prywatnego użytkownika do podpisywania poczty wychodzącej.
- Gmail używa klucza prywatnego użytkownika do odszyfrowywania poczty przychodzącej.
- Gmail szyfruje pocztę wychodzącą przy użyciu certyfikatu odbiorcy i klucza publicznego.
- Gmail weryfikuje pocztę przychodzącą przy użyciu certyfikatu i klucza publicznego nadawcy.
Możesz wygenerować poszczególne certyfikaty S/MIME i przesłać je przy użyciu interfejsu API. Każdy certyfikat S/MIME dotyczy określonego aliasu konta e-mail użytkownika. Aliasy obejmują podstawowy adres e-mail oraz niestandardowe adresy „Wyślij jako”. Dla każdego aliasu jako domyślny jest oznaczany pojedynczy certyfikat S/MIME.
Autoryzacja dostępu do interfejsu API
Istnieją 2 sposoby autoryzacji dostępu do interfejsu API:
- Możesz używać konta usługi z przekazywaniem uprawnień w całej domenie. Więcej informacji o tych terminach znajdziesz w artykule Omówienie uwierzytelniania i autoryzacji. Informacje o włączaniu tej opcji znajdziesz w artykule Tworzenie konta usługi z przekazywaniem uprawnień w całej domenie.
- Aby uzyskać token dostępu Oauth2, możesz użyć standardowego procesu OAuth2, który wymaga zgody użytkownika. Więcej informacji znajdziesz w artykule Omówienie uwierzytelniania i autoryzacji Aby użyć tej opcji, administrator domeny musi zaznaczyć pole wyboru „Dostęp użytkowników interfejsu S/MIME API jest włączony” w panelu sterowania domeną.
Zakresy ACL
Ten interfejs API korzysta z tych samych zakresów ACL co metody Gmail sendAs:
- gmail.settings.basic
- Ten zakres jest wymagany do aktualizacji podstawowego S/MIME w SendAs.
- gmail.settings.sharing
- Ten zakres jest wymagany do aktualizacji ustawień niestandardowych z S/MIME.
Korzystanie z interfejsu API
Zasób users.settings.sendAs.smimeInfo udostępnia metody używane do zarządzania certyfikatami S/MIME. Każdy certyfikat jest powiązany z jednym aliasem wysyłania jako dla użytkownika.
Przesyłanie klucza S/MIME
Użyj metody smimeInfo.insert(), aby przesłać nowy klucz S/MIME dla aliasu należącego do użytkownika. Alias docelowy możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć specjalnej wartości
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego przesyłasz klucz. To adres e-mail, który pojawi się w nagłówku „Od:” w przypadku wiadomości wysyłanych z tego aliasu.
Certyfikat S/MIME i klucz prywatny powinny znajdować się w polu pkcs12
w tym formacie; w żądaniu nie należy ustawiać żadnych innych pól. Pole PKCS12 powinno zawierać zarówno klucz S/MIME użytkownika, jak i łańcuch certyfikatów podpisywania. Interfejs API przeprowadza standardowe weryfikacje tego pola, zanim je zaakceptuje, sprawdzając, czy:
- Temat odpowiada podanemu adresowi e-mail.
- Ważne daty ważności są ważne.
- Wystawiony urząd certyfikacji (CA) znajduje się na naszej liście zaufanych.
- Certyfikaty są zgodne z ograniczeniami technicznymi Gmaila.
Jeśli klucz jest zaszyfrowany, hasło powinno znajdować się w polu encryptedKeyPassword
. Udane wywołania insert() zwrócą identyfikator smimeInfo, którego można użyć do odwoływania się do klucza w przyszłości.
Wyświetlanie listy kluczy S/MIME użytkownika
Użyj metody smimeInfo.list(), aby zwrócić listę kluczy S/MIME dla danego użytkownika i aliasu. Alias docelowy możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć specjalnej wartości
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego ma zostać wyświetlona lista kluczy. To adres e-mail, który pojawi się w nagłówku „Od:” w przypadku wiadomości wysyłanych z tego aliasu.
Pobieranie kluczy S/MIME dla aliasu
Użyj metody smimeInfo.get(), aby zwrócić określone klucze S/MIME dla określonego aliasu wysyłania jako użytkownika. Alias docelowy możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć specjalnej wartości
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego pobierasz klucze. To adres e-mail, który pojawi się w nagłówku „Od:” w przypadku wiadomości wysyłanych z tego aliasu.
Usuwanie klucza S/MIME
Użyj metody smimeInfo.delete(), aby usunąć z aliasu określony klucz S/MIME. Alias docelowy możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć specjalnej wartości
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego pobierasz klucze. Ten adres e-mail pojawi się w nagłówku „Od:” w przypadku e-maili wysyłanych z tego aliasu.
- id
- Niezmienny identyfikator SmimeInfo.
Ustawianie domyślnego klucza S/MIME dla aliasu
Użyj metody smimeInfo.setDefault(), aby oznaczyć określony klucz S/MIME jako domyślny dla określonego aliasu. Alias docelowy możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć specjalnej wartości
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego pobierasz klucze. Ten adres e-mail pojawi się w nagłówku „Od:” w przypadku e-maili wysyłanych z tego aliasu.
- id
- Niezmienny identyfikator SmimeInfo.
Przykładowy kod
Poniżej znajdziesz przykładowy kod pokazujący, jak używać interfejsu API do zarządzania certyfikatami S/MIME w organizacji z wieloma użytkownikami.
Tworzenie zasobu SmimeInfo dla certyfikatu S/MIME
Poniższy przykładowy kod pokazuje, jak odczytać certyfikat z pliku, zakodować go na ciąg base64url i przypisać go do pola pkcs12
zasobu smimeInfo
:
Java
Python
Przesyłanie certyfikatu S/MIME
Aby przesłać certyfikat, wywołaj metodę smimeInfo.insert
i podaj zasób smimeInfo
w treści żądania:
Java
Python
Przykłady zarządzania certyfikatami wielu użytkowników
Czasami możesz chcieć zarządzać certyfikatami wielu użytkowników w organizacji jednocześnie. Poniższe przykłady pokazują, jak zarządzać certyfikatami wielu użytkowników w ramach jednego wywołania zbiorczego.
Wstawianie certyfikatów z pliku CSV
Załóżmy, że masz plik CSV zawierający identyfikatory użytkowników i ścieżkę do ich certyfikatów:
$ 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
Możesz użyć wcześniejszych wywołań createSmimeInfo
i insertSmimeInfo
do przesłania certyfikatów zgodnie z opisem w pliku CSV:
Python
Możesz użyć wcześniejszych wywołań create_smime_info
i insert_smime_info
do przesłania certyfikatów zgodnie z opisem w pliku CSV:
Zarządzanie certyfikatami
W tym przykładzie połączono kilka wywołań interfejsu API smimeInfo
, aby pokazać, jak możesz zarządzać certyfikatami w swojej organizacji. Zawiera ona listę certyfikatów użytkownika. Jeśli certyfikat domyślny wygasł lub nie został ustawiony, przesyła certyfikat znaleziony w określonym pliku. Następnie ustawia jako domyślny certyfikat, którego data ważności przypada najdalej w przyszłości.
Jest ono wywoływane z funkcji, która przetwarza plik CSV tak jak w poprzednim przykładzie.