feat: add restcatalog authentication api (#479)

Author: lishuxu

src/iceberg/catalog/rest/CMakeLists.txt

@@ -15,7 +15,12 @@
 # specific language governing permissions and limitations
 # under the License.
 
+add_subdirectory(auth)
+
 set(ICEBERG_REST_SOURCES
+    auth/auth_manager.cc
+    auth/auth_managers.cc
+    auth/auth_session.cc
     catalog_properties.cc
     endpoint.cc
     error_handlers.cc

src/iceberg/catalog/rest/auth/CMakeLists.txt

@@ -0,0 +1,18 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+iceberg_install_all_headers(iceberg/catalog/rest/auth)

src/iceberg/catalog/rest/auth/auth_manager.cc

@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "iceberg/catalog/rest/auth/auth_manager.h"
+
+#include "iceberg/catalog/rest/auth/auth_session.h"
+
+namespace iceberg::rest::auth {
+
+Result<std::shared_ptr<AuthSession>> AuthManager::InitSession(
+    HttpClient& init_client,
+    const std::unordered_map<std::string, std::string>& properties) {
+  // By default, use the catalog session for initialization
+  return CatalogSession(init_client, properties);
+}
+
+Result<std::shared_ptr<AuthSession>> AuthManager::ContextualSession(
+    [[maybe_unused]] const std::unordered_map<std::string, std::string>& context,
+    std::shared_ptr<AuthSession> parent) {
+  // By default, return the parent session as-is
+  return parent;
+}
+
+Result<std::shared_ptr<AuthSession>> AuthManager::TableSession(
+    [[maybe_unused]] const TableIdentifier& table,
+    [[maybe_unused]] const std::unordered_map<std::string, std::string>& properties,
+    std::shared_ptr<AuthSession> parent) {
+  // By default, return the parent session as-is
+  return parent;
+}
+
+}  // namespace iceberg::rest::auth

src/iceberg/catalog/rest/auth/auth_manager.h

@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+#include <memory>
+#include <string>
+#include <unordered_map>
+
+#include "iceberg/catalog/rest/iceberg_rest_export.h"
+#include "iceberg/catalog/rest/type_fwd.h"
+#include "iceberg/result.h"
+#include "iceberg/type_fwd.h"
+
+/// \file iceberg/catalog/rest/auth/auth_manager.h
+/// \brief Authentication manager interface for REST catalog.
+
+namespace iceberg::rest::auth {
+
+/// \brief Produces authentication sessions for catalog and table requests.
+class ICEBERG_REST_EXPORT AuthManager {
+ public:
+  virtual ~AuthManager() = default;
+
+  /// \brief Create a short-lived session used to contact the configuration endpoint.
+  ///
+  /// This session is used only during catalog initialization to fetch server
+  /// configuration and perform initial authentication. It is typically discarded after
+  /// initialization.
+  ///
+  /// \param init_client HTTP client used for initialization requests.
+  /// \param properties Client configuration supplied by the catalog.
+  /// \return Session for initialization or an error if credentials cannot be acquired.
+  virtual Result<std::shared_ptr<AuthSession>> InitSession(
+      HttpClient& init_client,
+      const std::unordered_map<std::string, std::string>& properties);
+
+  /// \brief Create the long-lived catalog session that acts as the parent session.
+  ///
+  /// This session is used for all catalog-level operations (list namespaces, list tables,
+  /// etc.) and serves as the parent session for contextual and table-specific sessions.
+  /// It is owned by the catalog and reused throughout the catalog's lifetime.
+  ///
+  /// \param shared_client HTTP client owned by the catalog and reused for auth calls.
+  /// \param properties Catalog properties (client config + server defaults).
+  /// \return Session for catalog operations or an error if authentication cannot be set
+  /// up.
+  virtual Result<std::shared_ptr<AuthSession>> CatalogSession(
+      HttpClient& shared_client,
+      const std::unordered_map<std::string, std::string>& properties) = 0;
+
+  /// \brief Create or reuse a session for a specific context.
+  ///
+  /// This method is used by SessionCatalog to create sessions for different contexts
+  /// (e.g., different users or tenants).
+  ///
+  /// \param context Context properties (e.g., user credentials, tenant info).
+  /// \param parent Catalog session to inherit from or return as-is.
+  /// \return A context-specific session, or the parent session if no context-specific
+  /// session is needed, or an error if session creation fails.
+  virtual Result<std::shared_ptr<AuthSession>> ContextualSession(
+      const std::unordered_map<std::string, std::string>& context,
+      std::shared_ptr<AuthSession> parent);
+
+  /// \brief Create or reuse a session scoped to a single table/view.
+  ///
+  /// This method is called when loading a table that may have table-specific auth
+  /// properties returned by the server.
+  ///
+  /// \param table Target table identifier.
+  /// \param properties Table-specific auth properties returned by the server.
+  /// \param parent Catalog or contextual session to inherit from or return as-is.
+  /// \return A table-specific session, or the parent session if no table-specific
+  /// session is needed, or an error if session creation fails.
+  virtual Result<std::shared_ptr<AuthSession>> TableSession(
+      const TableIdentifier& table,
+      const std::unordered_map<std::string, std::string>& properties,
+      std::shared_ptr<AuthSession> parent);
+
+  /// \brief Release resources held by the manager.
+  ///
+  /// \return Status of the close operation.
+  virtual Status Close() { return {}; }
+};
+
+}  // namespace iceberg::rest::auth

src/iceberg/catalog/rest/auth/auth_managers.cc

@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "iceberg/catalog/rest/auth/auth_managers.h"
+
+#include <algorithm>
+#include <cctype>
+
+#include "iceberg/catalog/rest/auth/auth_properties.h"
+#include "iceberg/util/string_util.h"
+
+namespace iceberg::rest::auth {
+
+namespace {
+
+/// \brief Registry type for AuthManager factories with heterogeneous lookup support.
+using AuthManagerRegistry =
+    std::unordered_map<std::string, AuthManagerFactory, StringHash, StringEqual>;
+
+// Infer the authentication type from properties.
+std::string InferAuthType(
+    const std::unordered_map<std::string, std::string>& properties) {
+  auto it = properties.find(AuthProperties::kAuthType);
+  if (it != properties.end() && !it->second.empty()) {
+    return StringUtils::ToLower(it->second);
+  }
+
+  // Infer from OAuth2 properties (credential or token)
+  bool has_credential = properties.contains(AuthProperties::kOAuth2Credential);
+  bool has_token = properties.contains(AuthProperties::kOAuth2Token);
+  if (has_credential || has_token) {
+    return AuthProperties::kAuthTypeOAuth2;
+  }
+
+  return AuthProperties::kAuthTypeNone;
+}
+
+// Get the global registry of auth manager factories.
+AuthManagerRegistry& GetRegistry() {
+  static AuthManagerRegistry registry;
+  return registry;
+}
+
+}  // namespace
+
+void AuthManagers::Register(std::string_view auth_type, AuthManagerFactory factory) {
+  GetRegistry()[StringUtils::ToLower(auth_type)] = std::move(factory);
+}
+
+Result<std::unique_ptr<AuthManager>> AuthManagers::Load(
+    std::string_view name,
+    const std::unordered_map<std::string, std::string>& properties) {
+  std::string auth_type = InferAuthType(properties);
+
+  auto& registry = GetRegistry();
+  auto it = registry.find(auth_type);
+  if (it == registry.end()) {
+    // TODO(Li Shuxu): Fallback to default auth manager implementations
+    return NotImplemented("Authentication type '{}' is not supported", auth_type);
+  }
+
+  return it->second(name, properties);
+}
+
+}  // namespace iceberg::rest::auth

src/iceberg/catalog/rest/auth/auth_managers.h

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+
+#include "iceberg/catalog/rest/auth/auth_manager.h"
+#include "iceberg/catalog/rest/iceberg_rest_export.h"
+#include "iceberg/result.h"
+
+/// \file iceberg/catalog/rest/auth/auth_managers.h
+/// \brief Factory for creating authentication managers.
+
+namespace iceberg::rest::auth {
+
+/// \brief Function that creates an AuthManager from its name.
+///
+/// \param name Name of the auth manager.
+/// \param properties Properties required by the auth manager.
+/// \return Newly created manager instance or an error if creation fails.
+using AuthManagerFactory = std::function<Result<std::unique_ptr<AuthManager>>(
+    std::string_view name,
+    const std::unordered_map<std::string, std::string>& properties)>;
+
+/// \brief Registry-backed factory for AuthManager implementations.
+class ICEBERG_REST_EXPORT AuthManagers {
+ public:
+  /// \brief Load a manager by consulting the "rest.auth.type" configuration.
+  ///
+  /// \param name Name of the auth manager.
+  /// \param properties Catalog properties used to determine auth type.
+  /// \return Manager instance or an error if no factory matches.
+  static Result<std::unique_ptr<AuthManager>> Load(
+      std::string_view name,
+      const std::unordered_map<std::string, std::string>& properties);
+
+  /// \brief Register or override the factory for a given auth type.
+  ///
+  /// This method is not thread-safe. All registrations should be done during
+  /// application startup before any concurrent access to Load().
+  ///
+  /// \param auth_type Case-insensitive type identifier (e.g., "basic").
+  /// \param factory Factory function that produces the manager.
+  static void Register(std::string_view auth_type, AuthManagerFactory factory);
+};
+
+}  // namespace iceberg::rest::auth