implementing regionalized auth and exchangeToken

Author: srushtisv

FirebaseAuth/Sources/Swift/Auth/Auth.swift

@@ -170,6 +170,49 @@ extension Auth: AuthInterop {
   /// Gets the `FirebaseApp` object that this auth object is connected to.
   @objc public internal(set) weak var app: FirebaseApp?
 
+  /// New R-GCIP v2 + BYO-CIAM initializer.
+    ///
+    /// This initializer allows to create an `Auth` instance with a specific `tenantConfig` for
+    /// R-GCIP.
+    /// - Parameters:
+    ///   - app: The `FirebaseApp` for which to initialize the `Auth` instance.
+    ///   - tenantConfig: The configuration for the tenant, including location and tenant ID.
+    /// - Returns: An `Auth` instance configured for the specified tenant.
+    public static func auth(app: FirebaseApp, tenantConfig: TenantConfig) -> Auth {
+      // start from the legacy initializer so we get a fully-formed Auth object
+      let auth = auth(app: app)
+      kAuthGlobalWorkQueue.sync {
+        auth.requestConfiguration.location = tenantConfig.location
+        auth.requestConfiguration.tenantId = tenantConfig.tenantId
+      }
+      return auth
+    }
+
+    /// Holds configuration for a R-GCIP tenant.
+    public struct TenantConfig {
+      public let location: String /// The location of the tenant.
+      public let tenantId: String /// The ID of the tenant.
+
+      /// Initializes a `TenantConfig` instance.
+      /// - Parameters:
+      ///   - location: The location of the tenant, defaults to "prod-global".
+      ///   - tenantId: The ID of the tenant.
+      public init(location: String = "prod-global", tenantId: String) {
+        self.location = location
+        self.tenantId = tenantId
+      }
+    }
+
+    /// Holds a Firebase ID token and its expiration.
+    public struct AuthExchangeToken {
+      public let token: String
+      public let expirationDate: Date?
+      init(token: String, expirationDate: Date?) {
+        self.token = token
+        self.expirationDate = expirationDate
+      }
+    }
+  
   /// Synchronously gets the cached current user, or null if there is none.
   @objc public var currentUser: User? {
     kAuthGlobalWorkQueue.sync {
@@ -2425,3 +2468,40 @@ extension Auth: AuthInterop {
   /// Mutations should occur within a @synchronized(self) context.
   private var listenerHandles: NSMutableArray = []
 }
+
+@available(iOS 13, *)
+public extension Auth {
+  /// Exchanges a third-party OIDC token for a Firebase STS token.
+  ///
+  /// Requires the `Auth` instance to be configured with a `TenantConfig` for R-GCIP.
+  /// - Parameters:
+  ///   - idpConfigID: The ID of the OIDC provider configuration.
+  ///   - ciamOidcToken: The OIDC token to exchange.
+  ///   - completion: Called with the Firebase ID token or an error.
+  @objc func exchangeToken(_ idpConfigID: String,
+                           _ ciamOidcToken: String,
+                           completion: @escaping (String?, Error?) -> Void) {
+    // Check if R-GCIP (location and tenantId) is configured.
+    guard let location = requestConfiguration.location,
+          let tenantId = requestConfiguration.tenantId
+    else {
+      completion(nil, AuthErrorUtils.operationNotAllowedError(
+        message: "Set location & tenantId first"
+      ))
+      return
+    }
+    let request = ExchangeTokenRequest(
+      idpConfigID: idpConfigID,
+      idToken: ciamOidcToken,
+      config: requestConfiguration
+    )
+    Task {
+      do {
+        let resp = try await backend.call(with: request)
+        DispatchQueue.main.async { completion(resp.firebaseToken, nil) }
+      } catch {
+        DispatchQueue.main.async { completion(nil, error) }
+      }
+    }
+  }
+}

FirebaseAuth/Sources/Swift/Backend/AuthRequestConfiguration.swift

@@ -43,16 +43,25 @@ final class AuthRequestConfiguration {
 
   /// If set, the local emulator host and port to point to instead of the remote backend.
   var emulatorHostAndPort: String?
+  
+  /// R-GCIP region, set once during Auth init.
+  var location: String?
+
+  /// R-GCIP tenantId, set once during Auth init.
+  var tenantId: String?
 
   init(apiKey: String,
        appID: String,
        auth: Auth? = nil,
        heartbeatLogger: FIRHeartbeatLoggerProtocol? = nil,
-       appCheck: AppCheckInterop? = nil) {
+       appCheck: AppCheckInterop? = nil,
+       tenantConfig: Auth.TenantConfig? = nil) {
     self.apiKey = apiKey
     self.appID = appID
     self.auth = auth
     self.heartbeatLogger = heartbeatLogger
     self.appCheck = appCheck
+    location = tenantConfig?.location
+    tenantId = tenantConfig?.tenantId
   }
 }

FirebaseAuth/Sources/Swift/Backend/IdentityToolkitRequest.swift

@@ -16,43 +16,40 @@ import Foundation
 
 private let kHttpsProtocol = "https:"
 private let kHttpProtocol = "http:"
-
-private let kEmulatorHostAndPrefixFormat = "%@/%@"
-
-/// Host for server API calls. This should be changed via
-/// `IdentityToolkitRequest.setHost(_ host:)` for testing purposes only.
-private nonisolated(unsafe) var gAPIHost = "www.googleapis.com"
-
+// Legacy GCIP v1 hosts
 private let kFirebaseAuthAPIHost = "www.googleapis.com"
-private let kIdentityPlatformAPIHost = "identitytoolkit.googleapis.com"
-
 private let kFirebaseAuthStagingAPIHost = "staging-www.sandbox.googleapis.com"
-private let kIdentityPlatformStagingAPIHost =
-  "staging-identitytoolkit.sandbox.googleapis.com"
-
-/// Represents a request to an identity toolkit endpoint.
+// Regional R-GCIP v2 hosts
+private let kRegionalGCIPAPIHost = "identityplatform.googleapis.com"
+private let kRegionalGCIPStagingAPIHost = "staging-identityplatform.sandbox.googleapis.com"
+#if compiler(>=6)
+  private nonisolated(unsafe) var gAPIHost = "www.googleapis.com"
+#else
+  private var gAPIHost = "www.googleapis.com"
+#endif
+/// Represents a request to an Identity Toolkit endpoint, routing either to
+/// legacy GCIP v1 or regionalized R-GCIP v2 based on presence of tenantID.
 @available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)
 class IdentityToolkitRequest {
-  /// Gets the RPC's endpoint.
+  /// RPC endpoint name, e.g. "signInWithPassword" or full exchange path
   let endpoint: String
-
   /// Gets the client's API key used for the request.
   var apiKey: String
-
   /// The tenant ID of the request. nil if none is available.
   let tenantID: String?
-
   /// The toggle of using Identity Platform endpoints.
   let useIdentityPlatform: Bool
-
   /// The toggle of using staging endpoints.
   let useStaging: Bool
-
   /// The type of the client that the request sent from, which should be CLIENT_TYPE_IOS;
   var clientType: String
 
-  private let _requestConfiguration: AuthRequestConfiguration
+  /// Optional local emulator host and port
+  var emulatorHostAndPort: String? {
+    return _requestConfiguration.emulatorHostAndPort
+  }
 
+  private let _requestConfiguration: AuthRequestConfiguration
   init(endpoint: String, requestConfiguration: AuthRequestConfiguration,
        useIdentityPlatform: Bool = false, useStaging: Bool = false) {
     self.endpoint = endpoint
@@ -64,57 +61,76 @@ class IdentityToolkitRequest {
     tenantID = requestConfiguration.auth?.tenantID
   }
 
+  /// Override this if you need query parameters (default none)
   func queryParams() -> String {
     return ""
   }
 
-  /// Returns the request's full URL.
+  /// Provide the same configuration for AuthBackend
+  func requestConfiguration() -> AuthRequestConfiguration {
+    return _requestConfiguration
+  }
+
+  /// Build the full URL, branching on whether tenantID is set.
   func requestURL() -> URL {
-    let apiProtocol: String
-    let apiHostAndPathPrefix: String
+    guard let auth = _requestConfiguration.auth else {
+      fatalError("Internal Auth error: missing Auth on requestConfiguration")
+    }
+    let protocolScheme: String
+    let hostPrefix: String
     let urlString: String
-    let emulatorHostAndPort = _requestConfiguration.emulatorHostAndPort
-    if useIdentityPlatform {
-      if let emulatorHostAndPort = emulatorHostAndPort {
-        apiProtocol = kHttpProtocol
-        apiHostAndPathPrefix = "\(emulatorHostAndPort)/\(kIdentityPlatformAPIHost)"
+    // R-GCIP v2 if location is non-nil
+    let tenant = _requestConfiguration.tenantId
+    if let region = _requestConfiguration.location {
+      // Project identifier
+      guard let project = auth.app?.options.projectID else {
+        fatalError("Internal Auth error: missing projectID")
+      }
+      // Choose emulator, staging, or prod host
+      if let emu = emulatorHostAndPort {
+        protocolScheme = kHttpProtocol
+        hostPrefix = "\(emu)/\(kRegionalGCIPAPIHost)"
       } else if useStaging {
-        apiHostAndPathPrefix = kIdentityPlatformStagingAPIHost
-        apiProtocol = kHttpsProtocol
+        protocolScheme = kHttpsProtocol
+        hostPrefix = kRegionalGCIPStagingAPIHost
       } else {
-        apiHostAndPathPrefix = kIdentityPlatformAPIHost
-        apiProtocol = kHttpsProtocol
+        protocolScheme = kHttpsProtocol
+        hostPrefix = kRegionalGCIPAPIHost
       }
-      urlString = "\(apiProtocol)//\(apiHostAndPathPrefix)/v2/\(endpoint)?key=\(apiKey)"
-
+      // Regionalized v2 path
+      urlString =
+        "\(protocolScheme)//\(hostPrefix)/v2/projects/\(project)"
+          + "/locations/\(region)/tenants/\(tenant)/idpConfigs/\(endpoint)?key=\(apiKey)"
     } else {
-      if let emulatorHostAndPort = emulatorHostAndPort {
-        apiProtocol = kHttpProtocol
-        apiHostAndPathPrefix = "\(emulatorHostAndPort)/\(kFirebaseAuthAPIHost)"
+      // Legacy GCIP v1 branch
+      if let emu = emulatorHostAndPort {
+        protocolScheme = kHttpProtocol
+        hostPrefix = "\(emu)/\(kFirebaseAuthAPIHost)"
       } else if useStaging {
-        apiProtocol = kHttpsProtocol
-        apiHostAndPathPrefix = kFirebaseAuthStagingAPIHost
+        protocolScheme = kHttpsProtocol
+        hostPrefix = kFirebaseAuthStagingAPIHost
       } else {
-        apiProtocol = kHttpsProtocol
-        apiHostAndPathPrefix = kFirebaseAuthAPIHost
+        protocolScheme = kHttpsProtocol
+        hostPrefix = kFirebaseAuthAPIHost
       }
       urlString =
-        "\(apiProtocol)//\(apiHostAndPathPrefix)/identitytoolkit/v3/relyingparty/\(endpoint)?key=\(apiKey)"
+        "\(protocolScheme)//\(hostPrefix)" +
+        "/identitytoolkit/v3/relyingparty/\(endpoint)?key=\(apiKey)"
     }
     guard let returnURL = URL(string: "\(urlString)\(queryParams())") else {
       fatalError("Internal Auth error: Failed to generate URL for \(urlString)")
     }
     return returnURL
   }
 
-  /// Returns the request's configuration.
-  func requestConfiguration() -> AuthRequestConfiguration {
-    _requestConfiguration
-  }
+  // MARK: - Testing API
 
-  // MARK: Internal API for development
+  /// For testing: override the global host for legacy flows
+  static var host: String {
+    get { gAPIHost }
+    set { gAPIHost = newValue }
+  }
 
-  static var host: String { gAPIHost }
   static func setHost(_ host: String) {
     gAPIHost = host
   }

FirebaseAuth/Sources/Swift/Backend/RPC/ExchangeTokenRequest.swift

@@ -0,0 +1,82 @@
+// Copyright 2025 Google LLC
+//
+// Licensed 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.
+
+import Foundation
+
+/// A request to exchange a third-party OIDC token for a Firebase STS token.
+///
+/// This structure encapsulates the parameters required to make an API request
+/// to exchange an OIDC token for a Firebase ID token. It conforms to the
+/// `AuthRPCRequest` protocol, providing the necessary properties and
+/// methods for the authentication backend to perform the request.
+@available(iOS 13, *)
+struct ExchangeTokenRequest: AuthRPCRequest {
+  /// The type of the expected response.
+  typealias Response = ExchangeTokenResponse
+
+  /// The identifier of the OIDC provider configuration.
+  private let idpConfigID: String
+
+  /// The third-party OIDC token to exchange.
+  private let idToken: String
+
+  /// The configuration for the request, holding API key, tenant, etc.
+  private let config: AuthRequestConfiguration
+
+  /// Initializes a new `ExchangeTokenRequest` instance.
+  ///
+  /// - Parameters:
+  ///   - idpConfigID: The identifier of the OIDC provider configuration.
+  ///   - idToken: The third-party OIDC token to exchange.
+  ///   - config: The configuration for the request.
+  init(idpConfigID: String,
+       idToken: String,
+       config: AuthRequestConfiguration) {
+    self.idpConfigID = idpConfigID
+    self.idToken = idToken
+    self.config = config
+  }
+
+  /// The unencoded HTTP request body for the API.
+  var unencodedHTTPRequestBody: [String: AnyHashable]? {
+    return ["id_token": idToken]
+  }
+
+  /// Constructs the URL for the API request.
+  ///
+  /// - Returns: The URL for the token exchange endpoint.
+  /// - FatalError: if location, tenantID, projectID or apiKey are missing.
+  func requestURL() -> URL {
+    guard let region = config.location,
+          let tenant = config.tenantId,
+          let project = config.auth?.app?.options.projectID
+    else {
+      fatalError(
+        "exchangeOidcToken requires `auth.useIdentityPlatform`, `auth.location`, `auth.tenantID` & `projectID`"
+      )
+    }
+    let host = "\(region)-identityplatform.googleapis.com"
+    let path = "/v2/projects/\(project)/locations/\(region)" +
+      "/tenants/\(tenant)/idpConfigs/\(idpConfigID):exchangeOidcToken"
+    guard let url = URL(string: "https://\(host)\(path)?key=\(config.apiKey)") else {
+      fatalError("Failed to create URL for exchangeOidcToken")
+    }
+    return url
+  }
+
+  /// Returns the request configuration.
+  ///
+  /// - Returns: The `AuthRequestConfiguration`.
+  func requestConfiguration() -> AuthRequestConfiguration { config }
+}

FirebaseAuth/Sources/Swift/Backend/RPC/ExchangeTokenResponse.swift

@@ -0,0 +1,27 @@
+// Copyright 2025 Google LLC
+//
+// Licensed 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.
+
+import Foundation
+
+/// Response containing the new Firebase STS token.
+@available(iOS 13, *)
+struct ExchangeTokenResponse: AuthRPCResponse {
+  let firebaseToken: String
+  init(dictionary: [String: AnyHashable]) throws {
+    guard let token = dictionary["idToken"] as? String else {
+      throw AuthErrorUtils.unexpectedResponse(deserializedResponse: dictionary)
+    }
+    firebaseToken = token
+  }
+}