OAuth2: PKCE(Proof Key for Code Exchange)

api/envoy/extensions/filters/http/oauth2/v3/oauth.proto

@@ -27,7 +27,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#next-free-field: 6]
 message OAuth2Credentials {
-  // [#next-free-field: 7]
+  // [#next-free-field: 8]
   message CookieNames {
     // Cookie name to hold OAuth bearer token value. When the authentication server validates the
     // client and returns an authorization token back to the OAuth filter, no matter what format
@@ -56,6 +56,10 @@ message OAuth2Credentials {
     // Cookie name to hold the nonce value. Defaults to ``OauthNonce``.
     string oauth_nonce = 6
         [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
+
+    // Cookie name to hold the PKCE code verifier. Defaults to ``OauthCodeVerifier``.
+    string code_verifier = 7
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
   }
 
   // The client_id to be used in the authorize calls. This value will be URL encoded when sent to the OAuth server.

changelogs/current.yaml

@@ -8,6 +8,9 @@ minor_behavior_changes:
 - area: http2
   change: |
     Sets runtime guard ``envoy.reloadable_features.http2_use_oghttp2`` to true by default.
+- area: oauth2
+  change: |
+    Introduced PKCE(Proof Key for Code Exchange) support for OAuth2 authorization code flow.
 
 bug_fixes:
 # *Changes expected to improve the state of the world and are unlikely to have negative effects*

source/extensions/filters/http/oauth2/filter.cc

@@ -27,6 +27,7 @@
 #include "absl/strings/str_split.h"
 #include "jwt_verify_lib/jwt.h"
 #include "jwt_verify_lib/status.h"
+#include "openssl/rand.h"
 
 using namespace std::chrono_literals;
 
@@ -50,6 +51,8 @@ constexpr absl::string_view queryParamsError = "error";
 constexpr absl::string_view queryParamsCode = "code";
 constexpr absl::string_view queryParamsState = "state";
 constexpr absl::string_view queryParamsRedirectUri = "redirect_uri";
+constexpr absl::string_view queryParamsCodeChallenge = "code_challenge";
+constexpr absl::string_view queryParamsCodeChallengeMethod = "code_challenge_method";
 
 constexpr absl::string_view stateParamsUrl = "url";
 constexpr absl::string_view stateParamsCsrfToken = "csrf_token";
@@ -203,6 +206,30 @@ bool validateCsrfTokenHmac(const std::string& hmac_secret, const std::string& cs
   return generateHmacBase64(hmac_secret_vec, token) == hmac;
 }
 
+// Generates a PKCE code verifier with 32 octets of randomness.
+// This follows recommendations in RFC 7636:
+// https://datatracker.ietf.org/doc/html/rfc7636#section-7.1
+std::string generateCodeVerifier(Random::RandomGenerator& random) {
+  MemBlockBuilder<uint64_t> mem_block(4);
+  // create 4 random uint64_t values to fill the buffer because RFC 7636 recommends 32 octets of
+  // randomness.
+  for (size_t i = 0; i < 4; i++) {
+    mem_block.appendOne(random.random());
+  }
+
+  std::unique_ptr<uint64_t[]> data = mem_block.release();
+  return Base64Url::encode(reinterpret_cast<char*>(data.get()), 4 * sizeof(uint64_t));
+}
+
+// Generates a PKCE code challenge from a code verifier.
+std::string generateCodeChallenge(const std::string& code_verifier) {
+  auto& crypto_util = Envoy::Common::Crypto::UtilitySingleton::get();
+  std::vector<uint8_t> sha256_digest =
+      crypto_util.getSha256Digest(Buffer::OwnedImpl(code_verifier));
+  std::string sha256_string(sha256_digest.begin(), sha256_digest.end());
+  return Base64Url::encode(sha256_string.data(), sha256_string.size());
+}
+
 /**
  * Encodes the state parameter for the OAuth2 flow.
  * The state parameter is a base64Url encoded JSON object containing the original request URL and a
@@ -217,6 +244,128 @@ std::string encodeState(const std::string& original_request_url, const std::stri
   return Base64Url::encode(json.data(), json.size());
 }
 
+/**
+ * Encrypt a plaintext string using AES-256-CBC.
+ */
+std::string encrypt(const std::string& plaintext, const std::string& secret,
+                    Random::RandomGenerator& random) {
+  // Generate the key from the secret using SHA-256
+  std::vector<unsigned char> key(SHA256_DIGEST_LENGTH); // AES-256 requires 256-bit (32 bytes) key
+  SHA256(reinterpret_cast<const unsigned char*>(secret.c_str()), secret.size(), key.data());
+
+  // Generate a random IV
+  MemBlockBuilder<uint64_t> mem_block(4);
+  // create 2 random uint64_t values to fill the buffer because AES-256-CBC requires 16 bytes IV
+  for (size_t i = 0; i < 2; i++) {
+    mem_block.appendOne(random.random());
+  }
+
+  std::unique_ptr<uint64_t[]> data = mem_block.release();
+  const unsigned char* raw_data = reinterpret_cast<const unsigned char*>(data.get());
+
+  std::vector<unsigned char> iv(16); // AES uses 16-byte IV
+  iv.assign(raw_data, raw_data + 16);
+
+  EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new();
+  if (!ctx) {
+    throw EnvoyException("Failed to create context");
+  }
+
+  std::vector<unsigned char> ciphertext(plaintext.size() + EVP_MAX_BLOCK_LENGTH);
+  int len = 0, ciphertext_len = 0;
+
+  // Initialize encryption operation
+  if (EVP_EncryptInit_ex(ctx, EVP_aes_256_cbc(), nullptr, key.data(), iv.data()) != 1) {
+    EVP_CIPHER_CTX_free(ctx);
+    throw EnvoyException("Encryption initialization failed");
+  }
+
+  // Encrypt the plaintext
+  if (EVP_EncryptUpdate(ctx, ciphertext.data(), &len,
+                        reinterpret_cast<const unsigned char*>(plaintext.c_str()),
+                        plaintext.size()) != 1) {
+    EVP_CIPHER_CTX_free(ctx);
+    throw EnvoyException("Encryption update failed");
+  }
+  ciphertext_len += len;
+
+  // Finalize encryption
+  if (EVP_EncryptFinal_ex(ctx, ciphertext.data() + len, &len) != 1) {
+    EVP_CIPHER_CTX_free(ctx);
+    throw EnvoyException("Encryption finalization failed");
+  }
+  ciphertext_len += len;
+
+  EVP_CIPHER_CTX_free(ctx);
+
+  ciphertext.resize(ciphertext_len); // Resize to actual length
+
+  // Prepend the IV to the ciphertext
+  std::vector<unsigned char> combined(iv.size() + ciphertext.size());
+  std::copy(iv.begin(), iv.end(), combined.begin());
+  std::copy(ciphertext.begin(), ciphertext.end(), combined.begin() + iv.size());
+
+  // Base64Url encode the IV + ciphertext
+  return Base64Url::encode(reinterpret_cast<const char*>(combined.data()), combined.size());
+}
+
+/**
+ * Decrypt an AES-256-CBC encrypted string.
+ */
+std::string decrypt(const std::string& encrypted, const std::string& secret) {
+  // Decode the Base64Url-encoded input
+  std::string decoded = Base64Url::decode(encrypted);
+  std::vector<unsigned char> combined(decoded.begin(), decoded.end());
+
+  if (combined.size() <= 16) {
+    throw EnvoyException("Invalid encrypted data");
+  }
+
+  // Extract the IV (first 16 bytes)
+  std::vector<unsigned char> iv(combined.begin(), combined.begin() + 16);
+
+  // Extract the ciphertext (remaining bytes)
+  std::vector<unsigned char> ciphertext(combined.begin() + 16, combined.end());
+
+  // Generate the key from the secret using SHA-256
+  std::vector<unsigned char> key(SHA256_DIGEST_LENGTH); // 256-bit key
+  SHA256(reinterpret_cast<const unsigned char*>(secret.c_str()), secret.size(), key.data());
+
+  EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new();
+  if (!ctx) {
+    throw EnvoyException("Failed to create context");
+  }
+
+  std::vector<unsigned char> plaintext(ciphertext.size() + EVP_MAX_BLOCK_LENGTH);
+  int len = 0, plaintext_len = 0;
+
+  // Initialize decryption operation
+  if (EVP_DecryptInit_ex(ctx, EVP_aes_256_cbc(), nullptr, key.data(), iv.data()) != 1) {
+    EVP_CIPHER_CTX_free(ctx);
+    throw EnvoyException("Decryption initialization failed");
+  }
+
+  // Decrypt the ciphertext
+  if (EVP_DecryptUpdate(ctx, plaintext.data(), &len, ciphertext.data(), ciphertext.size()) != 1) {
+    EVP_CIPHER_CTX_free(ctx);
+    throw EnvoyException("Decryption update failed");
+  }
+  plaintext_len += len;
+
+  // Finalize decryption
+  if (EVP_DecryptFinal_ex(ctx, plaintext.data() + len, &len) != 1) {
+    EVP_CIPHER_CTX_free(ctx);
+    throw EnvoyException("Decryption finalization failed");
+  }
+  plaintext_len += len;
+
+  EVP_CIPHER_CTX_free(ctx);
+
+  plaintext.resize(plaintext_len); // Resize to actual plaintext length
+
+  return std::string(plaintext.begin(), plaintext.end());
+}
+
 } // namespace
 
 FilterConfig::FilterConfig(
@@ -464,8 +613,18 @@ Http::FilterHeadersStatus OAuth2Filter::decodeHeaders(Http::RequestHeaderMap& he
       Formatter::FormatterImpl::create(config_->redirectUri()), Formatter::FormatterPtr);
   const auto redirect_uri =
       formatter->formatWithContext({&headers}, decoder_callbacks_->streamInfo());
+
+  std::string encrypted_code_verifier =
+      Http::Utility::parseCookieValue(headers, config_->cookieNames().code_verifier_);
+  if (encrypted_code_verifier.empty()) {
+    ENVOY_LOG(error, "code verifier cookie is missing in the request");
+    sendUnauthorizedResponse();
+    return Http::FilterHeadersStatus::StopIteration;
+  }
+  std::string code_verifier = decrypt(encrypted_code_verifier, config_->hmacSecret());
+
   oauth_client_->asyncGetAccessToken(auth_code_, config_->clientId(), config_->clientSecret(),
-                                     redirect_uri, config_->authType());
+                                     redirect_uri, code_verifier, config_->authType());
 
   // pause while we await the next step from the OAuth server
   return Http::FilterHeadersStatus::StopAllIterationAndBuffer;
@@ -526,22 +685,13 @@ void OAuth2Filter::redirectToOAuthServer(Http::RequestHeaderMap& headers) {
   // The CSRF token cookie contains the CSRF token that is used to prevent CSRF attacks for the
   // OAuth flow. It was named "oauth_nonce" because the CSRF token contains a generated nonce.
   // "oauth_csrf_token" would be a more accurate name for the cookie.
-  std::string csrf_token;
-  bool csrf_token_cookie_exists = false;
-  const auto csrf_token_cookie =
-      Http::Utility::parseCookies(headers, [this](absl::string_view key) {
-        return key == config_->cookieNames().oauth_nonce_;
-      });
-  if (csrf_token_cookie.find(config_->cookieNames().oauth_nonce_) != csrf_token_cookie.end()) {
-    csrf_token = csrf_token_cookie.at(config_->cookieNames().oauth_nonce_);
-    csrf_token_cookie_exists = true;
-  } else {
-    // Generate a CSRF token to prevent CSRF attacks.
-    csrf_token = generateCsrfToken(config_->hmacSecret(), random_);
-  }
-
+  std::string csrf_token =
+      Http::Utility::parseCookieValue(headers, config_->cookieNames().oauth_nonce_);
+  bool csrf_token_cookie_exists = !csrf_token.empty();
   // Set the CSRF token cookie if it does not exist.
   if (!csrf_token_cookie_exists) {
+    // Generate a CSRF token to prevent CSRF attacks.
+    csrf_token = generateCsrfToken(config_->hmacSecret(), random_);
     // Expire the CSRF token cookie in 10 minutes.
     // This should be enough time for the user to complete the OAuth flow.
     std::string expire_in = std::to_string(10 * 60);
@@ -574,6 +724,28 @@ void OAuth2Filter::redirectToOAuthServer(Http::RequestHeaderMap& headers) {
       Http::Utility::PercentEncoding::urlEncodeQueryParameter(redirect_uri);
   query_params.overwrite(queryParamsRedirectUri, escaped_redirect_uri);
 
+  // Generate a PKCE code verifier and challenge for the OAuth flow.
+  const std::string code_verifier = generateCodeVerifier(random_);
+  // Encrypt the code verifier, using HMAC secret as the symmetric key.
+  const std::string encrypted_code_verifier =
+      encrypt(code_verifier, config_->hmacSecret(), random_);
+
+  // Expire the code verifier cookie in 10 minutes.
+  // This should be enough time for the user to complete the OAuth flow.
+  std::string expire_in = std::to_string(10 * 60);
+  std::string cookie_tail_http_only = fmt::format(CookieTailHttpOnlyFormatString, expire_in);
+  if (!config_->cookieDomain().empty()) {
+    cookie_tail_http_only = absl::StrCat(
+        fmt::format(CookieDomainFormatString, config_->cookieDomain()), cookie_tail_http_only);
+  }
+  response_headers->addReferenceKey(Http::Headers::get().SetCookie,
+                                    absl::StrCat(config_->cookieNames().code_verifier_, "=",
+                                                 encrypted_code_verifier, cookie_tail_http_only));
+
+  const std::string code_challenge = generateCodeChallenge(code_verifier);
+  query_params.overwrite(queryParamsCodeChallenge, code_challenge);
+  query_params.overwrite(queryParamsCodeChallengeMethod, "S256");
+
   // Copy the authorization endpoint URL to replace its query params.
   auto authorization_endpoint_url = config_->authorizationEndpointUrl();
   const std::string path_and_query_params = query_params.replaceQueryString(
@@ -621,6 +793,10 @@ Http::FilterHeadersStatus OAuth2Filter::signOutUser(const Http::RequestHeaderMap
       Http::Headers::get().SetCookie,
       absl::StrCat(fmt::format(CookieDeleteFormatString, config_->cookieNames().oauth_nonce_),
                    cookie_domain));
+  response_headers->addReferenceKey(
+      Http::Headers::get().SetCookie,
+      absl::StrCat(fmt::format(CookieDeleteFormatString, config_->cookieNames().code_verifier_),
+                   cookie_domain));
   response_headers->setLocation(new_path);
   decoder_callbacks_->encodeHeaders(std::move(response_headers), true, SIGN_OUT);
 

source/extensions/filters/http/oauth2/filter.h

@@ -90,31 +90,36 @@ struct CookieNames {
                   cookie_names)
       : CookieNames(cookie_names.bearer_token(), cookie_names.oauth_hmac(),
                     cookie_names.oauth_expires(), cookie_names.id_token(),
-                    cookie_names.refresh_token(), cookie_names.oauth_nonce()) {}
+                    cookie_names.refresh_token(), cookie_names.oauth_nonce(),
+                    cookie_names.code_verifier()) {}
 
   CookieNames(const std::string& bearer_token, const std::string& oauth_hmac,
               const std::string& oauth_expires, const std::string& id_token,
-              const std::string& refresh_token, const std::string& oauth_nonce)
+              const std::string& refresh_token, const std::string& oauth_nonce,
+              const std::string& code_verifier)
       : bearer_token_(bearer_token.empty() ? BearerToken : bearer_token),
         oauth_hmac_(oauth_hmac.empty() ? OauthHMAC : oauth_hmac),
         oauth_expires_(oauth_expires.empty() ? OauthExpires : oauth_expires),
         id_token_(id_token.empty() ? IdToken : id_token),
         refresh_token_(refresh_token.empty() ? RefreshToken : refresh_token),
-        oauth_nonce_(oauth_nonce.empty() ? OauthNonce : oauth_nonce) {}
+        oauth_nonce_(oauth_nonce.empty() ? OauthNonce : oauth_nonce),
+        code_verifier_(code_verifier.empty() ? CodeVerifier : code_verifier) {}
 
   const std::string bearer_token_;
   const std::string oauth_hmac_;
   const std::string oauth_expires_;
   const std::string id_token_;
   const std::string refresh_token_;
   const std::string oauth_nonce_;
+  const std::string code_verifier_;
 
   static constexpr absl::string_view OauthExpires = "OauthExpires";
   static constexpr absl::string_view BearerToken = "BearerToken";
   static constexpr absl::string_view OauthHMAC = "OauthHMAC";
   static constexpr absl::string_view OauthNonce = "OauthNonce";
   static constexpr absl::string_view IdToken = "IdToken";
   static constexpr absl::string_view RefreshToken = "RefreshToken";
+  static constexpr absl::string_view CodeVerifier = "CodeVerifier";
 };
 
 /**

source/extensions/filters/http/oauth2/oauth_client.cc

@@ -25,10 +25,11 @@ namespace Oauth2 {
 
 namespace {
 constexpr const char* UrlBodyTemplateWithCredentialsForAuthCode =
-    "grant_type=authorization_code&code={0}&client_id={1}&client_secret={2}&redirect_uri={3}";
+    "grant_type=authorization_code&code={0}&client_id={1}&client_secret={2}&redirect_uri={3}&code_"
+    "verifier={4}";
 
 constexpr const char* UrlBodyTemplateWithoutCredentialsForAuthCode =
-    "grant_type=authorization_code&code={0}&redirect_uri={1}";
+    "grant_type=authorization_code&code={0}&redirect_uri={1}&code_verifier={2}";
 
 constexpr const char* UrlBodyTemplateWithCredentialsForRefreshToken =
     "grant_type=refresh_token&refresh_token={0}&client_id={1}&client_secret={2}";
@@ -40,7 +41,8 @@ constexpr const char* UrlBodyTemplateWithoutCredentialsForRefreshToken =
 
 void OAuth2ClientImpl::asyncGetAccessToken(const std::string& auth_code,
                                            const std::string& client_id, const std::string& secret,
-                                           const std::string& cb_url, AuthType auth_type) {
+                                           const std::string& cb_url,
+                                           const std::string& code_verifier, AuthType auth_type) {
   ASSERT(state_ == OAuthState::Idle);
   state_ = OAuthState::PendingAccessToken;
 
@@ -52,15 +54,17 @@ void OAuth2ClientImpl::asyncGetAccessToken(const std::string& auth_code,
   case AuthType::UrlEncodedBody:
     body = fmt::format(UrlBodyTemplateWithCredentialsForAuthCode, auth_code,
                        Http::Utility::PercentEncoding::encode(client_id, ":/=&?"),
-                       Http::Utility::PercentEncoding::encode(secret, ":/=&?"), encoded_cb_url);
+                       Http::Utility::PercentEncoding::encode(secret, ":/=&?"), encoded_cb_url,
+                       code_verifier);
     break;
   case AuthType::BasicAuth:
     const auto basic_auth_token = absl::StrCat(client_id, ":", secret);
     const auto encoded_token = Base64::encode(basic_auth_token.data(), basic_auth_token.size());
     const auto basic_auth_header_value = absl::StrCat("Basic ", encoded_token);
     request->headers().appendCopy(Http::CustomHeaders::get().Authorization,
                                   basic_auth_header_value);
-    body = fmt::format(UrlBodyTemplateWithoutCredentialsForAuthCode, auth_code, encoded_cb_url);
+    body = fmt::format(UrlBodyTemplateWithoutCredentialsForAuthCode, auth_code, encoded_cb_url,
+                       code_verifier);
     break;
   }
 

source/extensions/filters/http/oauth2/oauth_client.h

@@ -30,6 +30,7 @@ class OAuth2Client : public Http::AsyncClient::Callbacks {
 public:
   virtual void asyncGetAccessToken(const std::string& auth_code, const std::string& client_id,
                                    const std::string& secret, const std::string& cb_url,
+                                   const std::string& code_verifier,
                                    AuthType auth_type = AuthType::UrlEncodedBody) PURE;
 
   virtual void asyncRefreshAccessToken(const std::string& refresh_token,
@@ -63,7 +64,7 @@ class OAuth2ClientImpl : public OAuth2Client, Logger::Loggable<Logger::Id::oauth
    */
   void asyncGetAccessToken(const std::string& auth_code, const std::string& client_id,
                            const std::string& secret, const std::string& cb_url,
-                           AuthType auth_type) override;
+                           const std::string& code_verifier, AuthType auth_type) override;
 
   void asyncRefreshAccessToken(const std::string& refresh_token, const std::string& client_id,
                                const std::string& secret, AuthType auth_type) override;