Клиентские сертификаты и их продление

Клиент, зарегистрированный с tls_client_auth, подтверждает себя сертификатом X.509, а его access-токены привязаны к этому сертификату (Токены с привязкой к отправителю). Сертификаты истекают, поэтому каждому такому клиенту нужен способ получить следующий. На этой странице описаны варианты, что делает Versola в каждом, чего не делает и за чем следить. Речь о сертификате API-клиента, например банка с интеграцией по FAPI 2.0. Сертификат, который edge предъявляет auth для нативных приложений, — другой случай: клиентские сертификаты edge.

Пошаговая инструкция — в Автоматическое продление клиентского сертификата (EST).

Что проверяет Versola

Для клиента tls_client_auth auth проверяет, что сертификат строится к известному ему доверенному якорю и что поле, названное в регистрации (mtlsAuth: subjectType и subjectValue), совпадает. Якоря — это файл trusted-certificates в блоке mutual-tls у auth или, если mutual TLS терминирует прокси, то, чему доверяет прокси. Для пути через прокси тенант задает заголовок и его кодировку: mtlsCertificateHeader и mtlsCertificateEncoding (urlEncodedPem или base64Der), в Security, Tokens & keys, Mutual TLS. В записи клиента сам сертификат не хранится, только то, что вы зарегистрировали, поэтому сертификат можно менять.

С токенами иначе. Токен несет cnf.x5t#S256, SHA-256-отпечаток сертификата, на который он выпущен. У нового сертификата другой отпечаток, поэтому токены, выпущенные на старый сертификат, с новым не работают. После продления клиент запрашивает новые токены. См. Токены с привязкой к отправителю.

Как продлевать сертификат

Тот же subject, тот же УЦ

Если у нового сертификата тот же subject (или SAN), что назван в регистрации, и он строится к тому же УЦ, в Versola ничего не меняется. Клиент начинает предъявлять новый сертификат и запрашивает новые токены. Запись клиента не трогайте. Выпустите сертификат в своем PKI и дайте старому истечь.

Автоматическая выдача и продление через EST

RFC 7030 (Enrollment over Secure Transport) описывает, как клиент запрашивает сертификат по HTTPS. auth обслуживает его по пути /.well-known/est/, а central решает, что выпускать, и поручает УЦ подписать, поэтому учетных данных УЦ у auth нет. Клиент регистрируется с estEnrollment, для чего нужен authMethod: tls_client_auth, и пока не выдал себе сертификат, сертификата у него нет.

Клиенту нужны два базовых URL: выдача на origin issuer’а, продление на origin mutual-TLS. Шаги — в Автоматическое продление клиентского сертификата (EST). Правила:

• Subject из регистрации. В сертификате стоит subject, по которому клиент зарегистрирован (mtlsAuth или CN=<client>,OU=<tenant>,O=Versola), а не тот, что назван в запросе. При продлениях он не меняется, поэтому регистрацию трогать не нужно.
• Новый ключ каждый раз. Ключи: EC P-256 или RSA не короче 2048 бит; продление с прежним ключом отклоняется.
• Одноразовый токен. Его создает оператор в central. Он живет 24 часа по умолчанию (не больше 168), показывается один раз, работает один раз и хранится только как хеш. Новый токен заменяет неиспользованные прежние токены клиента.
• Короткие сертификаты. Срок жизни — client-certificates.validity (по умолчанию 14 дней). Сертификат продлевается только в последней трети срока (client-identity.renew-window); раньше будет 403 с указанием, когда окно откроется.
• Цепочка. Продления образуют цепочку от выдачи. По достижении client-identity.max-age (по умолчанию год) продление прекращается с 403, пока оператор не вызовет POST /configuration/clients/est/extend или не включен client-identity.auto-extend. Граница мягкая: сертификат, выпущенный незадолго до нее, живет весь свой срок. Дата есть в каждом ответе в заголовке Versola-Chain-Ends-At.
• Поколения и отзыв. Отзывается право продлевать, а не сам сертификат. Каждый сертификат относится к поколению; повторная выдача с новым токеном или POST /configuration/clients/est/revoke лишают права продлевать все прежние (401). Сертификат, который заменило продление и который снова приходит продлеваться после 3-минутной отсрочки, закрывает цепочку (403): ключ у двоих. Оператор выдает клиенту сертификат заново.
• Ограничение частоты. simpleenroll допускает 30 попыток в минуту на client id и реплику (429, Retry-After).

Полномочия УЦ у central (step-ca или cert-manager, клиентские сертификаты edge), у auth их нет. Но auth находится в зоне доверия терминатора mutual TLS: он сообщает central, какой сертификат предъявил клиент и какой токен прислал, а central не может проверить ни то, ни другое. Кто контролирует auth или его внутренний токен к central, тот может продлить сертификат любого EST-клиента, у которого есть действующий сертификат, и выдать себе сертификат по токену, который он наблюдает. Что central сужает: продлевается только сертификат, выпущенный через EST, текущего поколения, только в последней трети срока; цепочка заканчивается на max-age; subject всегда зарегистрированный.

Токены и сертификаты. Access-токен привязан к сертификату, на который выпущен (cnf.x5t#S256). У продленного сертификата другой отпечаток, поэтому токены, выпущенные на старый, с новым не работают. Клиент продолжает предъявлять старый сертификат со старыми токенами, пока они не истекут, или запрашивает новые токены с новым сертификатом.

Что не охвачено

• Смена subject. В сертификате стоит зарегистрированный subject, поэтому через EST его не изменить. Измените регистрацию или зарегистрируйте нового клиента и перейдите на него.
• Смена УЦ. Чтобы перевести клиента на другой УЦ, добавьте новый УЦ в доверенные якоря auth до того, как клиент переключится, и уберите старый после истечения последнего подписанного им сертификата. EST этого не делает.
• Самоподписанные клиенты. EST требует tls_client_auth. Клиент self_signed_tls_client_auth сопоставляется по ключу, зарегистрированному в его jwks, а не по УЦ. Ротация ручная: зарегистрируйте новый ключ в JWK Set до того, как клиент начнет им пользоваться, переключите клиента, уберите старый ключ, когда старый сертификат больше не используется.
• Истекший сертификат и потерянный ключ. Истекший сертификат не продлевается сам собой, а потерянный ключ не восстанавливается: оператор создает новый токен, и клиент проходит выдачу заново.

Эксплуатация

• Мониторинг срока. Versola не предупреждает клиента о скором истечении сертификата. Настройте оповещение по дате окончания сертификата клиента в своем мониторинге с запасом в несколько периодов продления. Для клиента на EST GET /configuration/clients показывает est.certificateExpiresAt и est.chainEndsAt; настройте оповещение на сертификат в последней трети срока, который не продлился, и на исходы est_requests_total (Наблюдаемость).
• Горячая перезагрузка у клиента. Продленный сертификат бесполезен, пока TLS-стек клиента его не использует. Пусть клиент перечитывает ключ и сертификат без перезапуска или перезапускается по очереди, и сразу после этого запрашивает новые токены.
• Доверенные якоря. Держите УЦ, подписывающий клиентские сертификаты, в trusted-certificates у auth и, если вы отдаете API на mutual-TLS listener edge, у edge тоже. На время смены УЦ держите оба.
• Отзыв — это истечение. Versola не обращается к CRL или OCSP. Сертификат действителен до notAfter, поэтому механизм отзыва — короткий срок жизни. Для клиента на EST отзывается право продлевать (POST /configuration/clients/est/revoke). Чтобы отрезать сертификат сразу, смените subject в mtlsAuth клиента или удалите клиента в central.

См. также

• Автоматическое продление клиентского сертификата (EST)
• Клиент
• Вызов API с токеном, привязанным к сертификату