Gmail S/MIME API обеспечивает программный доступ для управления сертификатами электронной почты S/MIME для пользователей в Google Workspace домен.
Администратор должен включить S/MIME для домена , чтобы сертификаты работали.
Стандарт S/MIME предоставляет спецификацию шифрования с открытым ключом и подписи данных MIME. Настройка сертификатов S/MIME в учетной записи пользователя приводит к тому, что Gmail будет использовать этот сертификат следующими способами:
- Gmail использует сертификат и закрытый ключ пользователя для подписи исходящей почты.
- Gmail использует закрытый ключ пользователя для расшифровки входящей почты.
- Gmail использует сертификат получателя и открытый ключ для шифрования исходящей почты.
- Gmail использует сертификат отправителя и открытый ключ для проверки входящей почты.
Вы создаете отдельные сертификаты S/MIME и загружаете их с помощью API. Каждый сертификат S/MIME предназначен для определенного псевдонима учетной записи электронной почты пользователя. Псевдонимы включают в себя основной адрес электронной почты, а также собственные адреса «Отправить как». Один сертификат S/MIME помечается как сертификат по умолчанию для каждого псевдонима.
Авторизация доступа к API
Существует две формы авторизации доступа к API:
- Вы можете использовать сервисный аккаунт с делегированием полномочий на уровне домена . Объяснение этих терминов см. в разделе Обзор терминов аутентификации и авторизации . Информацию о включении этой опции см. в разделе Создание учетной записи службы с делегированием полномочий на уровне домена.
- Вы можете использовать стандартный поток OAuth2, требующий согласия конечного пользователя для получения токена доступа Oauth2. Для получения дополнительной информации обратитесь к обзору аутентификации и авторизации. Чтобы использовать эту опцию, администратор домена должен установить флажок «Доступ для конечных пользователей S/MIME API включен» на панели управления доменом.
Области ACL
Этот API использует те же области ACL, что и методы Gmail sendAs :
- gmail.settings.basic
- Эта область необходима для обновления основного S/MIME SendAs.
- gmail.settings.sharing
- Эта область необходима для обновления пользовательской версии S/MIME.
Использование API
Ресурсusers.settings.sendAs.smimeInfo предоставляет методы, которые вы используете для управления сертификатами S/MIME. Каждый сертификат связан с одним псевдонимом отправки как для пользователя.
Загрузите ключ S/MIME
Используйте метод smimeInfo.insert() , чтобы загрузить новый ключ S/MIME для псевдонима, принадлежащего пользователю. Вы определяете целевой псевдоним, используя следующие параметры:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
чтобы указать текущего аутентифицированного пользователя. - ОтправитьКакEmail
- Псевдоним, для которого вы загружаете ключ. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
Сертификат S/MIME и закрытый ключ должны присутствовать в поле pkcs12
в этом формате; никакие другие поля в запросе задаваться не должны. Ожидается, что поле PKCS12 будет содержать как пользовательский ключ S/MIME, так и цепочку сертификатов подписи. API выполняет стандартную проверку этого поля перед его принятием, проверяя следующее:
- Тема соответствует указанному адресу электронной почты.
- Сроки годности действительны.
- Выдающий центр сертификации (CA) находится в нашем списке доверенных.
- Сертификаты соответствуют техническим ограничениям Gmail.
Если ключ зашифрован, пароль должен быть в поле encryptedKeyPassword
. Успешные вызовы метода Insert() вернут идентификатор smimeInfo, который можно будет использовать для ссылки на ключ в будущем.
Получение списка ключей S/MIME пользователя
Используйте метод smimeInfo.list(), чтобы вернуть список ключей S/MIME для данного пользователя для данного псевдонима. Вы определяете целевой псевдоним, используя следующие параметры:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
чтобы указать текущего аутентифицированного пользователя. - ОтправитьКакEmail
- Псевдоним, для которого нужно перечислить ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
Получите ключи S/MIME для псевдонима.
Используйте метод smimeInfo.get(), чтобы вернуть определенные ключи S/MIME для определенного псевдонима отправки для пользователя. Вы определяете целевой псевдоним, используя следующие параметры:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
чтобы указать текущего аутентифицированного пользователя. - ОтправитьКакEmail
- Псевдоним, для которого вы получаете ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
Удаление ключа S/MIME
Используйте метод smimeInfo.delete(), чтобы удалить указанный ключ S/MIME из псевдонима. Вы определяете целевой псевдоним, используя следующие параметры:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
чтобы указать текущего аутентифицированного пользователя. - ОтправитьКакEmail
- Псевдоним, для которого вы получаете ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
- идентификатор
- Неизменяемый идентификатор для SmimeInfo.
Установите ключ S/MIME по умолчанию для псевдонима
Используйте метод smimeInfo.setDefault(), чтобы пометить указанный ключ S/MIME как ключ по умолчанию для указанного псевдонима. Вы определяете целевой псевдоним, используя следующие параметры:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
чтобы указать текущего аутентифицированного пользователя. - ОтправитьКакEmail
- Псевдоним, для которого вы получаете ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
- идентификатор
- Неизменяемый идентификатор для SmimeInfo.
Пример кода
В следующих примерах кода показано использование API для управления сертификатами S/MIME для организации с несколькими пользователями.
Создание ресурса SmimeInfo для сертификата S/MIME
В следующем примере кода показано чтение сертификата из файла, его кодирование в строку base64url и присвоение ее полю pkcs12
ресурса smimeInfo
:
Ява
Питон
Загрузка сертификата S/MIME
Чтобы загрузить сертификат, вызовите smimeInfo.insert
и укажите ресурс smimeInfo
в теле запроса:
Ява
Питон
Примеры управления сертификатами многих пользователей
Возможно, вам захочется управлять сертификатами для многих пользователей в организации одновременно. В следующих примерах показано, как управлять сертификатами для нескольких пользователей с помощью одного пакетного вызова.
Вставка сертификатов из файла CSV
Предположим, у вас есть файл CSV, в котором перечислены идентификаторы пользователей и путь к сертификату каждого пользователя:
$ 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
Ява
Вы можете использовать ранее использованные вызовы createSmimeInfo
и insertSmimeInfo
для загрузки сертификатов, как указано в CSV-файле:
Питон
Вы можете использовать вызовы create_smime_info
и insert_smime_info
ранее, чтобы загрузить сертификаты, как указано в CSV-файле:
Управление сертификатами
Этот пример объединяет несколько вызовов API smimeInfo
, чтобы показать, как вы можете управлять сертификатами для своей организации. В нем перечислены сертификаты для пользователя, и если срок действия сертификата по умолчанию истек или он не установлен, он загружает сертификат, найденный в указанном файле. Затем он устанавливает сертификат, срок действия которого истекает дальше всего в будущем, в качестве сертификата по умолчанию.
Затем он вызывается из функции, которая обрабатывает CSV-файл, как в предыдущем примере.