Аутентификация: TLS и токены

Что же именно выключает insecure.NewCredentials() из пятого урока? Исходники insecure.go отвечают дословно: пакет insecure «provides an implementation of the credentials.TransportCredentials interface which disables transport security», а его NewCredentials «returns a credentials which disables transport security». Внутри сидит тип insecureTC, про который сказано: «The handshake methods simply return the passed in net.Conn and set the security level to NoSecurity» — рукопожатие не происходит вовсе, транспорт получает сырой сокет, уровень безопасности NoSecurity. Даже AuthType у такого соединения называется «insecure», и ProtocolInfo отдаёт SecurityProtocol «insecure». Именно поэтому пятый урок повторял: это режим для localhost, интеграционных тестов и изолированных CI-сетей, где на пути пакетов сидят только ваши собственные процессы. В любом другом окружении grpc tls — не опция, а требование: трафик gRPC — это HTTP/2-кадры с вашими protobuf-сообщениями и заголовками, включая Bearer-токены из десятого урока, и без шифрования их читает каждый, кто находится между клиентом и сервером. Защита в gRPC слоёная, и полезно сразу разложить её на три уровня. Первый — канал: TransportCredentials, TLS и mTLS, о них почти весь урок; они шифруют провод и аутентифицируют концы соединения. Второй — вызов: PerRPCCredentials и клиентские перехватчики из одиннадцатого урока прикладывают токен к каждому вызову — они отвечают на вопрос «кто именно пришёл». Третий — бизнес: хендлеры с правилами доступа вашего сервиса. Уровни дополняют друг друга, а не заменяют. И одно правило доке дорого как память: «Note that using this credentials with per-RPC credentials which require transport security is incompatible and will cause RPCs to fail» — insecure-канал несовместим с per-RPC-креденшелами, требующими защиты; как именно он сломается, увидим в предикте ниже.

Чтобы говорить о TLS на gRPC без суеверий, начнём с контракта. Дословно из credentials.go: «TransportCredentials defines the common interface for all the live gRPC wire protocols and supported transport security protocols (e.g., TLS, SSL)». Интерфейс требует пять методов. ClientHandshake(context.Context, string, net.Conn) — «ClientHandshake does the authentication handshake specified by the corresponding authentication protocol on rawConn for clients»: на исходящем соединении он разыгрывает рукопожатие и возвращает обёрнутый net.Conn, AuthInfo и ошибку. ServerHandshake(net.Conn) — «ServerHandshake does the authentication handshake for servers» — то же самое на приёме. Info() возвращает ProtocolInfo — статическую карточку протокола с полями SecurityProtocol («tls» или «insecure») и SecurityVersion. Clone() обязателен, потому что grpc-go клонирует креденшелы для разных адресов, не давая им расползаться мутациями. Пятый метод OverrideServerName помечен как deprecated — «this method is unused by gRPC», для переопределения имени есть grpc.WithAuthority. Результат рукопожатия — AuthInfo: «AuthInfo defines the common interface for the auth information the users are interested in» — один метод AuthType() string, который у TLS-соединения возвращает «tls», а у insecure — «insecure». На этом держится весь урок: кто реализует TransportCredentials, тот и решает, каким будет провод. Уровень защиты кодируется перечислением SecurityLevel из того же файла: NoSecurity — «indicates a connection is insecure»; IntegrityOnly — только целостность; PrivacyAndIntegrity — «provides both privacy and integrity protection», и это как раз TLS. Пара CommonAuthInfo{SecurityLevel} живёт внутри AuthInfo, а функция CheckSecurityLevel умеет проверять, «хватает ли» уровня, — ею пользуется, например, oauth-креденшел, который отказывается отправлять токен по слабому каналу. Для точности: TransportCredentials — интерфейс, и кроме TLS существуют ALTS и local (unix-сокеты); но подавляющее большинство прод-конфигураций — это credentials/tls.go, к которому переходим.

Серверная сторона включается одной опцией. Дословно из server.go: «Creds returns a ServerOption that sets credentials for server connections» — grpc.NewServer(grpc.Creds(creds)), и с этого момента каждое входящее соединение обязано пройти рукопожатие, прежде чем по нему поедет хоть один gRPC-кадр. Где взять creds? В credentials/tls.go лежат конструкторы. NewServerTLSFromFile(certFile, keyFile) — «NewServerTLSFromFile constructs TLS credentials from the input certificate file and key file for server»: внутри он зовёт стандартный tls.LoadX509KeyPair, читая PEM-файлы сертификата и приватного ключа с диска. NewServerTLSFromCert(cert *tls.Certificate) принимает уже загруженную пару — удобно, когда сертификат приезжает из секрет-хранилища, а не с файловой системы. Оба в конечном счёте приходят к NewTLS, о котором ниже. Заметьте асимметрию с клиентом: серверу нужен свой сертификат — доказать «я тот самый сервер», — но не нужен пул корней: пока это обычный TLS, сервер пускает любых клиентов, проверка клиента — уже mTLS из середины урока. Регистрация сервиса, стримы, перехватчики из одиннадцатого урока — всё остаётся без изменений: TLS живёт ниже gRPC, на границе с TCP, и хендлеры про него не знают. Единственное, что они заметят, — в контексте появится peer с AuthInfo типа tls; подарок для блока про peer.FromContext.

Клиенту без mTLS нужен не сертификат, а доверие: корневой CA, которым подписан серверный сертификат. Дословно из credentials/tls.go: «NewClientTLSFromFile constructs TLS credentials from the provided root certificate authority certificate file(s) to validate server connections» — на вход PEM-файл с корнями, внутри строится x509.CertPool и кладётся в RootCAs. Второй параметр serverNameOverride снабжён честной оговоркой: «serverNameOverride is for testing only. If set to a non empty string, it will override the virtual host name of authority (e.g. :authority header field) in requests» — задавать имя сервера в проде не нужно: оно берётся из адреса подключения (localhost из localhost:50051) и проверяется стандартной VerifyHostname против SAN/CN сертификата; для легитимного переопределения :authority существует grpc.WithAuthority. Есть и версия из памяти: «NewClientTLSFromCert constructs TLS credentials from the provided root certificate authority certificate(s) to validate server connections» — принимает готовый x509.CertPool, если корни приезжают не с диска. И главный конструктор, через который проходят все остальные: «NewTLS uses c to construct a TransportCredentials based on TLS» — он принимает полный tls.Config и внутри приводит её к минимальным требованиям gRPC (что именно — в блоке про ALPN). Дока NewClientTLSFromFile сразу проговаривает и границу применимости: «If certificates to establish the identity of the client need to be included in the credentials (eg: for mTLS), use NewTLS instead, where a complete tls.Config can be specified» — как только клиенту нужен свой сертификат, короткие конструкторы кончаются, собираем tls.Config руками. Ошибка рукопожатия выглядит как «transport: authentication handshake failed: ...» и клиент видит её как codes.Unavailable: соединения нет, до статус-кодов хендлеров дело не доходит — при отладке различайте эти источники отказов.

TLS-рукопожатие согласовывает не только шифры, но и прикладной протокол — за это отвечает расширение ALPN (Application-Layer Protocol Negotiation): клиент предлагает список, сервер выбирает один. В вебе классическая пара кандидатов — «http/1.1» против «h2» (HTTP/2); gRPC живёт только на HTTP/2, поэтому h2 для него не пожелание, а требование. grpc-go решает это за вас: NewTLS применяет дефолты через applyDefaults, где config.NextProtos = credinternal.AppendH2ToNextProtos(config.NextProtos) — хелпер из internal/credentials с комментарием «AppendH2ToNextProtos appends h2 to next protos» дописывает h2 в список, если его там нет. Туда же — минимальная версия TLS: если вы не задали MinVersion, ставится TLS 1.2, «which is required by https://datatracker.ietf.org/doc/html/rfc7540#section-9.2» — таково требование RFC HTTP/2. Комментарий в ClientHandshake объясняет остальное: «h2: When the server supports ALPN. Only HTTP/2 can be negotiated since it is the only protocol advertised by the client during the handshake» и дальше про пустую строку: «(empty string): If the server doesn't support ALPN. ALPN is a requirement for using HTTP/2 over TLS. We can terminate the connection immediately». Историческая справка для тех, кто поймал внезапную поломку после обновления: ошибка «credentials: cannot check peer: missing selected ALPN property» выдаётся, когда вторая сторона не выбрала протокол; начиная с grpc-go 1.67 такая проверка включена по умолчанию (переменная окружения GRPC_ENFORCE_ALPN_ENABLED), и в тексте ошибки лежит подсказка именно про обновление с версий раньше 1.67. Практический вывод: между клиентом и gRPC-сервером не должен стоять терминирующий прокси, который согласует http/1.1 — либо прокси пропускает h2 насквозь, либо сам завершает TLS и к gRPC-серверу приходит уже с HTTP/2. Проверить, что согласовано, можно в AuthInfo: TLSInfo.State.NegotiatedProtocol вернёт ровно «h2».

TLS доказывает клиенту, что сервер — тот самый. mTLS (mutual TLS) разворачивает доказательство в обе стороны: клиент тоже предъявляет сертификат, и сервер решает, пускать ли его вообще. Именно этот сценарий ищут по запросу «mtls go» — взаимный TLS на Go, и в репозитории grpc-go он собран целиком в examples/features/encryption/mTLS. Форма каноническая — сверим её построчно. Клиент добавляет в tls.Config два поля: Certificates — []tls.Certificate, загруженный tls.LoadX509KeyPair из client_cert.pem и client_key.pem, и RootCAs — пул корней для проверки СЕРВЕРА. Сервер добавляет тоже два: Certificates — свой серверный сертификат — и ClientCAs, пул корней, которым должны быть подписаны КЛИЕНТСКИЕ сертификаты, плюс ClientAuth: tls.RequireAndVerifyClientCert. Обратите внимание на параллель: RootCAs и ClientCAs — два независимых пула доверия; в аккуратной инфраструктуре их вообще выпускают разные CA — в examples/data это разные файлы, ca_cert.pem и client_ca_cert.pem. Поле ClientAuth — перечисление с пятью ступенями строгости: NoClientCert (по умолчанию — mTLS выключен), RequestClientCert (запросить, но не требовать), RequireAnyClientCert (требовать, но не проверять против ClientCAs), VerifyClientCertIfGiven и RequireAndVerifyClientCert (требовать и проверять — канонический mTLS). Если клиент пришёл без сертификата или с сертификатом не от ClientCAs, ServerHandshake падает на самом TLS-слое: никакого вызова, никакого хендлера, никакого Unauthenticated — клиент увидит ошибку соединения. И ещё раз про конструкторы: дока NewClientTLSFromFile сказала «use NewTLS instead, where a complete tls.Config can be specified» — короткий конструктор для mTLS непригоден, клиентская часть всегда через NewTLS.

Соединение установлено, сертификат клиента проверен — но где хендлер или перехватчик прочитает, кто именно подключился? Для этого в пакете peer есть дословно «Peer contains the information of the peer for an RPC, such as the address and authentication information»: структура { Addr net.Addr; LocalAddr net.Addr; AuthInfo credentials.AuthInfo }, где AuthInfo — «the authentication information of the transport. It is nil if there is no transport security being used». Сервер grpc-go вкладывает peer в контекст каждого вызова: serveStreams вызывает peer.NewContext(ctx, st.Peer()), так что peer.FromContext(ctx) — «returns the peer information in ctx if it exists» — работает и в unary-перехватчике, и в хендлере, и в стримовом через stream.Context(). AuthInfo на TLS-соединении — это credentials.TLSInfo: «TLSInfo contains the auth information for a TLS authenticated connection», AuthType() возвращает «tls». Внутри TLSInfo.State лежит стандартный tls.ConnectionState из crypto/tls, и нас интересуют два его поля. PeerCertificates — цепочка, которую клиент предъявил (лист — первый элемент). VerifiedChains — цепочки, проверенные против ClientCAs: раз рукопожатие прошло с RequireAndVerifyClientCert, здесь уже лежат верифицированные цепочки, и лист первой — тот самый клиентский сертификат, у которого есть Subject.CommonName. Дальше вопрос политики: сравнить CN с allow-листом и при промахе отказать PermissionDenied. Это тот же приём, что deny-список по info.FullMethod из одиннадцатого урока, только идентичность берётся не из заголовков, а из TLS. Два предостережения. Первое: CN — не уникальный идентификатор: второй сертификат с тем же CN пройдёт тот же allow-лист; для строгих решений сверяйте отпечаток сертификата или SPIFFE ID, который gRPC вынимает в TLSInfo.SPIFFEID. Второе: на insecure-канале assertion к TLSInfo не удастся — у AuthInfo там AuthType «insecure», и перехватчик обязан отработать этот случай статусом, а не паникой: предикт ниже покажет, как это выглядит.

Теперь токены — и обещание десятого урока: там мы заметили декларативный канал — интерфейс credentials.PerRPCCredentials — и пообещали разобрать его отдельно. Время пришло. Дословно из credentials.go: «PerRPCCredentials defines the common interface for the credentials which need to attach security information to every RPC (e.g., oauth2)». Два метода. GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) — «gets the current request metadata, refreshing tokens if required. This should be called by the transport layer on each request, and the data should be populated in headers or other context»: зовёт ТРАНСПОРТ на каждый вызов, а не ваш код; uri — audience, строка вида https://host/package.Service, привычная OAuth2-серверам. RequireTransportSecurity() bool — «indicates whether the credentials requires transport security» — флаг «поверх открытого провода меня не отправлять». Регистрация — опцией канала, дословно из dialoptions.go: «WithPerRPCCredentials returns a DialOption which sets credentials and places auth state on each outbound RPC». Что происходит на проводе: при открытии вызова транспорт собирает заголовки, зовёт GetRequestMetadata у всех PerRPCCredentials канала и пер-вызовных опций, понижает ключи к нижнему регистру (HTTP/2, десятый урок) и вливает пары в заголовки — тот же authorization: Bearer ..., что и AppendToOutgoingContext из одиннадцатого. Разница архитектурная: клиентский перехватчик — императивное «сделай сам» с доступом к req и invoker, PerRPCCredentials — декларативное «эти пары должны ехать с каждым вызовом»; живёт на канале и не знает про методы. Они не конкурируют: перехватчик решает ПО методу, PerRPCCredentials поставляет СЕКРЕТ. Готовая реализация уже в пакете credentials/oauth: «TokenSource supplies PerRPCCredentials from an oauth2.TokenSource» — его GetRequestMetadata кладёт authorization: token.Type() + " " + token.AccessToken, предварительно проверив credentials.CheckSecurityLevel(ai, credentials.PrivacyAndIntegrity), и RequireTransportSecurity у него true. А что, если соврать каналу? Исходники clientconn.go отвечают точно: если TransportCredentials.Info().SecurityProtocol — «insecure», и хотя бы один PerRPCCredentials требует защиты, NewClient возвращает ошибку «grpc: the credentials require transport level security (use grpc.WithTransportCredentials() to set)» — ещё до сети. Плюс gRFC A54 ограничивает набор кодов, которыми GetRequestMetadata может отвечать ошибкой, — но это уже к тринадцатому уроку про статус-коды.

Отдельная честная оговорка про формат: в курсе есть песочница с интерпретатором Go, но сеть и gRPC-стек в браузере недоступны — TLS-рукопожатие в ней не разыграть, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет. Всё разобранное проверяется локально за десять минут: сгенерируйте лабораторные сертификаты (openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.pem -subj /CN=lab-ca и две пары для сервера и клиента), поднимите сервер четвёртого урока с grpc.Creds, а клиент пятого переведите с insecure.NewCredentials() на NewClientTLSFromFile — и понаблюдайте три эффекта: insecure-клиент против TLS-сервера падает с ошибкой рукопожатия; TLS-клиент без правильного ca.pem не доверяет серверу; клиент с правильным ca.pem работает как раньше, только провод уже шифрованный. Затем добавьте mTLS и снимите у клиента поле Certificates — соединение будет рваться до всякого хендлера. Перехватчик из одиннадцатого урока легко становится CN-авторизатором: peer.FromContext уже в контексте, а VerifiedChains лежат в credentials.TLSInfo. Дальше по маршруту: тринадцатый урок — статус-коды во всей красе: codes.*, status.Errorf и details в ошибках; четырнадцатый — дедлайны и распространение отмены, где таймаут, поставленный на ClientHandshake из этого урока, наконец встретится с контекстом. Метаданные из десятого урока остались фундаментом: Bearer-схема и нижний регистр ключей живут под TLS без единой правки. Полный маршрут курса — на странице gRPC-Go.