Interfejs Gmail S/MIME API zapewnia programowy dostęp do zarządzania certyfikatami e-mail S/MIME użytkowników w Google Workspace domenie.
Aby certyfikaty działały, administrator musi włączyć S/MIME w domenie.
Standard S/MIME zawiera specyfikację szyfrowania kluczem publicznym i podpisywania danych MIME. Skonfigurowanie 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 wychodzących e-maili.
- Gmail używa klucza prywatnego użytkownika do odszyfrowywania poczty przychodzącej.
- Gmail używa certyfikatu i klucza publicznego odbiorcy do szyfrowania poczty wychodzącej.
- Gmail używa certyfikatu i klucza publicznego nadawcy do weryfikowania poczty przychodzącej.
Generujesz poszczególne certyfikaty S/MIME i przesyłasz je za pomocą interfejsu API. Każdy certyfikat S/MIME jest przeznaczony dla konkretnego aliasu konta e-mail użytkownika. Aliasy obejmują podstawowy adres e-mail oraz niestandardowe adresy „Wyślij jako”. Jeden certyfikat S/MIME jest oznaczony jako domyślny dla każdego aliasu.
Autoryzowanie dostępu do interfejsu API
Dostęp do interfejsu API można autoryzować na 2 sposoby:
- Możesz użyć konta usługi z przekazywaniem dostępu w całej domenie. Wyjaśnienie tych terminów znajdziesz w artykule Terminy dotyczące uwierzytelniania i autoryzacji. Informacje o włączaniu tej opcji znajdziesz w artykule Tworzenie konta usługi z przekazywaniem uprawnień do całej domeny.
- Aby uzyskać token dostępu OAuth2, możesz użyć standardowego procesu OAuth2, który wymaga zgody użytkownika. Więcej informacji znajdziesz w omówieniu uwierzytelniania i autoryzacji. Aby korzystać z tej opcji, administrator domeny musi zaznaczyć pole wyboru „Dostęp użytkowników do interfejsu S/MIME API” w panelu sterowania domeną.
Zakresy list ACL
Ten interfejs API korzysta z tych samych zakresów ACL co metody Gmail sendAs:
- gmail.settings.basic
- Ten zakres jest wymagany do aktualizowania podstawowego adresu „Wyślij jako” S/MIME.
- gmail.settings.sharing
- Ten zakres jest wymagany do aktualizowania niestandardowego z S/MIME.
Korzystanie z interfejsu API
Zasób users.settings.sendAs.smimeInfo zawiera metody, których możesz używać do zarządzania certyfikatami S/MIME. Każdy certyfikat jest powiązany z jednym aliasem „Wyślij jako” 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 celu możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć wartości specjalnej
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego przesyłasz klucz. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku poczty wysyłanej przy użyciu tego aliasu.
Certyfikat S/MIME i klucz prywatny powinny być w tym formacie w polu pkcs12
. Żądanie nie powinno zawierać ż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 testy poprawności tego pola przed jego zaakceptowaniem, sprawdzając:
- Temat pasuje do podanego adresu e-mail.
- Zakończenie okresu wypożyczenia jest prawidłowe.
- Urząd certyfikacji, który wydał certyfikat, znajduje się na naszej liście zaufanych urzędów.
- Certyfikaty są zgodne z ograniczeniami technicznymi Gmaila.
Jeśli klucz jest zaszyfrowany, hasło powinno znajdować się w polu encryptedKeyPassword
. Wywołania insert() zakończone powodzeniem zwracają identyfikator smimeInfo, którego można używać w przyszłości do odwoływania się do klucza.
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 danego aliasu. Alias celu możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć wartości specjalnej
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego chcesz wyświetlić listę kluczy. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku poczty wysyłanej przy użyciu tego aliasu.
Pobieranie kluczy S/MIME dla aliasu
Użyj metody smimeInfo.get(), aby zwrócić konkretne klucze S/MIME dla określonego aliasu „Wyślij jako” użytkownika. Alias celu możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć wartości specjalnej
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego pobierasz klucze. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku poczty wysyłanej przy użyciu tego aliasu.
Usuwanie klucza S/MIME
Użyj metody smimeInfo.delete(), aby usunąć określony klucz S/MIME z aliasu. Alias celu możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć wartości specjalnej
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego pobierasz klucze. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku poczty wysyłanej przy użyciu tego aliasu.
- id
- Stały 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 celu możesz określić za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Możesz użyć wartości specjalnej
me
, aby wskazać aktualnie uwierzytelnionego użytkownika. - sendAsEmail
- Alias, dla którego pobierasz klucze. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku poczty wysyłanej przy użyciu tego aliasu.
- id
- Stały identyfikator SmimeInfo.
Przykładowy kod
Poniższe przykłady kodu pokazują, jak za pomocą interfejsu API zarządzać 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 do postaci ciągu base64url i przypisać 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
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 jednym wywołaniu pakietowym.
Wstawianie certyfikatów z pliku CSV
Załóżmy, że masz plik CSV z identyfikatorami użytkowników i ścieżkami do certyfikatów każdego z nich:
$ 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ć wywołań createSmimeInfo
i insertSmimeInfo
z wcześniejszego przykładu, aby przesłać certyfikaty zgodnie z informacjami w pliku CSV:
Python
Możesz użyć wywołań create_smime_info
i insert_smime_info
z wcześniejszego przykładu, aby przesłać certyfikaty zgodnie z informacjami w pliku CSV:
Zarządzanie certyfikatami
Ten przykład łączy kilka wywołań z smimeInfo
interfejsu API, aby pokazać, jak możesz zarządzać certyfikatami w swojej organizacji. Wyświetla listę certyfikatów użytkownika i sprawdza, czy domyślny certyfikat wygasł lub nie został ustawiony. Jeśli tak, przesyła certyfikat znaleziony w określonym pliku. Następnie ustawia certyfikat, którego data wygaśnięcia jest najbardziej odległa, jako domyślny.
Następnie jest on wywoływany z funkcji, która przetwarza plik CSV, jak w poprzednim przykładzie.