Interfejs Gmail S/MIME API zapewnia dostęp programowy do zarządzania certyfikatami e-mail S/MIME dla użytkowników w domenie Google Workspace .
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 przychodzących e-maili.
- Gmail używa certyfikatu i klucza publicznego odbiorcy do szyfrowania wychodzących e-maili.
- Gmail weryfikuje przychodzące e-maile, korzystając z certyfikatu nadawcy i klucza publicznego.
Musisz wygenerować poszczególne certyfikaty S/MIME i przesłać je za pomocą interfejsu API. Każdy certyfikat S/MIME jest przeznaczony do 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 przeniesioną w całej domenie władzą. Wyjaśnienie tych terminów znajdziesz w artykule o wymaganiach dotyczących uwierzytelniania i autoryzacji. Informacje o włączaniu tej opcji znajdziesz w artykule Tworzenie konta usługi z przekazaniem uprawnień w całej domenie.
- Możesz użyć standardowego procesu OAuth 2, który wymaga zgody użytkownika na uzyskanie tokena dostępu OAuth 2. Więcej informacji znajdziesz w artykule Omówienie uwierzytelniania i autoryzacji. Aby korzystać z tej opcji, administrator domeny musi zaznaczyć pole wyboru „Włączony dostęp użytkownika do interfejsu S/MIME API”.
Zakresy list ACL
Ten interfejs API korzysta z tych samych zakresów adresów IP co metody Gmail sendAs:
- gmail.settings.basic
- Ten zakres jest wymagany do aktualizowania podstawowego SendAs S/MIME.
- gmail.settings.sharing
- Ten zakres jest wymagany do aktualizowania niestandardowych ustawień z S/MIME.
Korzystanie z interfejsu API
Zasób users.settings.sendAs.smimeInfo udostępnia metody zarządzania certyfikatami S/MIME. Każdy certyfikat jest powiązany z jednym aliasem wysyłania za pomocą adresu e-mail użytkownika.
Przesyłanie klucza S/MIME
Aby przesłać nowy klucz S/MIME dla aliasu należącego do użytkownika, użyj metody smimeInfo.insert(). Alias docelowy możesz zidentyfikować za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Aby wskazać aktualnie uwierzytelnionego użytkownika, możesz użyć wartości specjalnej
me
. - sendAsEmail
- Alias, dla którego przesyłasz klucz. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku wiadomości wysłanej za pomocą tego aliasu.
W polu pkcs12
powinny znajdować się certyfikat S/MIME i klucz prywatny w tym formacie. Żadne inne pola nie powinny być ustawione w żądaniu. Pole PKCS12 powinno zawierać klucz S/MIME użytkownika oraz łańcuch certyfikatów podpisujących. Przed zaakceptowaniem tego pola interfejs API przeprowadza standardowe testy poprawności, weryfikując:
- Temat jest zgodny z podanym adresem e-mail.
- Terminy ważności są prawidłowe.
- Urząd certyfikacji (CA) wystawiający 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
Pomyślnie wykonane wywołania insert() zwracają identyfikator smimeInfo, który można wykorzystać do odwołania 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 danego użytkownika dla danego aliasu. Alias docelowy możesz zidentyfikować za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Aby wskazać aktualnie uwierzytelnionego użytkownika, możesz użyć wartości specjalnej
me
. - sendAsEmail
- Alias, dla którego mają być wyświetlane klucze. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku wiadomości wysłanej za pomocą 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 dla użytkownika. Alias docelowy możesz zidentyfikować za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Aby wskazać aktualnie uwierzytelnionego użytkownika, możesz użyć wartości specjalnej
me
. - sendAsEmail
- Alias, którego dotyczy odzyskiwanie kluczy. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku wiadomości wysłanej za pomocą tego aliasu.
Usuwanie klucza S/MIME
Aby usunąć określony klucz S/MIME z aliasu, użyj metody smimeInfo.delete(). Alias docelowy możesz zidentyfikować za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Aby wskazać aktualnie uwierzytelnionego użytkownika, możesz użyć wartości specjalnej
me
. - sendAsEmail
- Alias, którego dotyczy odzyskiwanie kluczy. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku wiadomości wysłanej za pomocą tego aliasu.
- id
- Niezmienne identyfikatory informacji 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 zidentyfikować za pomocą tych parametrów:
- userId
- Adres e-mail użytkownika. Aby wskazać aktualnie uwierzytelnionego użytkownika, możesz użyć wartości specjalnej
me
. - sendAsEmail
- Alias, którego dotyczy odzyskiwanie kluczy. Jest to adres e-mail, który pojawia się w nagłówku „Od:” w przypadku wiadomości wysłanej za pomocą tego aliasu.
- id
- Niezmienne identyfikatory informacji 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 odczytywanie certyfikatu z pliku, kodowanie go w postaci ciągu base64url i przypisywanie do pola pkcs12
zasobu smimeInfo
:
Java
Python
Przesyłanie certyfikatu S/MIME
Aby przesłać certyfikat, wywołaj funkcję 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 zbiorczym.
Wstawianie certyfikatów z pliku CSV
Załóżmy, że masz plik CSV z identyfikatorami użytkowników i ścieżką do certyfikatu 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
Aby przesłać certyfikaty zgodnie z danymi w pliku CSV, możesz użyć wywołań createSmimeInfo
i insertSmimeInfo
:
Python
Aby przesłać certyfikaty zgodnie z danymi w pliku CSV, możesz użyć wywołań create_smime_info
i insert_smime_info
:
Zarządzanie certyfikatami
Ten przykład łączy kilka wywołań interfejsu API smimeInfo
, aby pokazać, jak zarządzać certyfikatami w organizacji. Wyświetla 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 certyfikat, którego ważność wygasa najpóźniej, jako domyślny.
Jest on wywoływany z funkcji, która przetwarza plik CSV, jak w poprzednim przykładzie.