Write BYO-CIAM token, expiresIn to the Auth Object initialized

common/api-review/auth.api.md

@@ -364,6 +364,9 @@ export interface EmulatorConfig {
 
 export { ErrorFn }
 
+// @public (undocumented)
+export function exchangeToken(auth: Auth, idpConfigId: string, customToken: string): Promise<string>;
+
 // Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.d.ts
 //
 // @public

docs-devsite/_toc.yaml

@@ -306,6 +306,8 @@ toc:
     path: /docs/reference/js/auth.samlauthprovider.md
   - title: TenantConfig
     path: /docs/reference/js/auth.tenantconfig.md
+  - title: TokenResponse
+    path: /docs/reference/js/auth.tokenresponse.md
   - title: TotpMultiFactorAssertion
     path: /docs/reference/js/auth.totpmultifactorassertion.md
   - title: TotpMultiFactorGenerator

docs-devsite/auth.auth.md

@@ -31,8 +31,9 @@ export interface Auth
 |  [languageCode](./auth.auth.md#authlanguagecode) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's language code. |
 |  [name](./auth.auth.md#authname) | string | The name of the app associated with the <code>Auth</code> service instance. |
 |  [settings](./auth.auth.md#authsettings) | [AuthSettings](./auth.authsettings.md#authsettings_interface) | The [Auth](./auth.auth.md#auth_interface) instance's settings. |
-|  [tenantConfig](./auth.auth.md#authtenantconfig) | [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) | The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) used to initialize a Regional Auth. This is only present if regional auth is initialized and  backend endpoint is used. |
+|  [tenantConfig](./auth.auth.md#authtenantconfig) | [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) | The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) used to initialize a Regional Auth. This is only present if regional auth is initialized and <code>DefaultConfig.REGIONAL_API_HOST</code> backend endpoint is used. |
 |  [tenantId](./auth.auth.md#authtenantid) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. |
+|  [tokenResponse](./auth.auth.md#authtokenresponse) | [TokenResponse](./auth.tokenresponse.md#tokenresponse_interface) \| null | The token response initialized via [exchangeToken()](./auth.md#exchangetoken_b6b1871) endpoint. |
 
 ## Methods
 
@@ -123,7 +124,7 @@ readonly settings: AuthSettings;
 
 ## Auth.tenantConfig
 
-The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) used to initialize a Regional Auth. This is only present if regional auth is initialized and  backend endpoint is used.
+The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) used to initialize a Regional Auth. This is only present if regional auth is initialized and `DefaultConfig.REGIONAL_API_HOST` backend endpoint is used.
 
 <b>Signature:</b>
 
@@ -156,6 +157,18 @@ const result = await signInWithEmailAndPassword(auth, email, password);
 
 ```
 
+## Auth.tokenResponse
+
+The token response initialized via [exchangeToken()](./auth.md#exchangetoken_b6b1871) endpoint.
+
+This field is only supported for [Auth](./auth.auth.md#auth_interface) instance that have defined [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+readonly tokenResponse: TokenResponse | null;
+```
+
 ## Auth.authStateReady()
 
 returns a promise that resolves immediately when the initial auth state is settled. When the promise resolves, the current user might be a valid user or `null` if the user signed out.

docs-devsite/auth.dependencies.md

@@ -29,7 +29,7 @@ export interface Dependencies
 |  [errorMap](./auth.dependencies.md#dependencieserrormap) | [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. |
 |  [persistence](./auth.dependencies.md#dependenciespersistence) | [Persistence](./auth.persistence.md#persistence_interface) \| [Persistence](./auth.persistence.md#persistence_interface)<!-- -->\[\] | Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first <code>Persistence</code> that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary <code>Persistence</code>, the account is moved to the primary <code>Persistence</code>.<!-- -->If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence)<!-- -->. |
 |  [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver)<!-- -->. This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup_770f816) or [signInWithRedirect()](./auth.md#signinwithredirect_770f816) are being used. |
-|  [tenantConfig](./auth.dependencies.md#dependenciestenantconfig) | [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) | The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) to use. This dependency is only required if you want to use regional auth which works with  endpoint. It should not be set otherwise. |
+|  [tenantConfig](./auth.dependencies.md#dependenciestenantconfig) | [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) | The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) to use. This dependency is only required if you want to use regional auth which works with <code>DefaultConfig.REGIONAL_API_HOST</code>\` endpoint. It should not be set otherwise. |
 
 ## Dependencies.errorMap
 
@@ -65,7 +65,7 @@ popupRedirectResolver?: PopupRedirectResolver;
 
 ## Dependencies.tenantConfig
 
-The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) to use. This dependency is only required if you want to use regional auth which works with  endpoint. It should not be set otherwise.
+The [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) to use. This dependency is only required if you want to use regional auth which works with `DefaultConfig.REGIONAL_API_HOST` endpoint. It should not be set otherwise.
 
 <b>Signature:</b>
 

docs-devsite/auth.md

@@ -28,6 +28,7 @@ Firebase Authentication
 |  [confirmPasswordReset(auth, oobCode, newPassword)](./auth.md#confirmpasswordreset_749dad8) | Completes the password reset process, given a confirmation code and new password. |
 |  [connectAuthEmulator(auth, url, options)](./auth.md#connectauthemulator_657c7e5) | Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. |
 |  [createUserWithEmailAndPassword(auth, email, password)](./auth.md#createuserwithemailandpassword_21ad33b) | Creates a new user account associated with the specified email address and password. |
+|  [exchangeToken(auth, idpConfigId, customToken)](./auth.md#exchangetoken_b6b1871) | Asynchronously exchanges an OIDC provider's Authorization code or Id Token for an OidcToken i.e. Outbound Access Token. |
 |  [fetchSignInMethodsForEmail(auth, email)](./auth.md#fetchsigninmethodsforemail_efb3887) | Gets the list of possible sign in methods for the given email address. This method returns an empty list when [Email Enumeration Protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection) is enabled, irrespective of the number of authentication methods available for the given email. |
 |  [getMultiFactorResolver(auth, error)](./auth.md#getmultifactorresolver_201ba61) | Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. |
 |  [getRedirectResult(auth, resolver)](./auth.md#getredirectresult_c35dc1f) | Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. |
@@ -138,6 +139,7 @@ Firebase Authentication
 |  [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | Interface for a supplied <code>AsyncStorage</code>. |
 |  [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | Interface representing reCAPTCHA parameters.<!-- -->See the [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/display#render_param) for the list of accepted parameters. All parameters are accepted except for <code>sitekey</code>: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering.<!-- -->For an invisible reCAPTCHA, set the <code>size</code> key to <code>invisible</code>. |
 |  [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) | The tenant config that can be used to initialize a Regional [Auth](./auth.auth.md#auth_interface) instance. |
+|  [TokenResponse](./auth.tokenresponse.md#tokenresponse_interface) | Interface for TokenRespone returned via [exchangeToken()](./auth.md#exchangetoken_b6b1871) endpoint. This is expected to be returned only if [Auth](./auth.auth.md#auth_interface) object initialized has defined [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface)<!-- -->. |
 |  [TotpMultiFactorAssertion](./auth.totpmultifactorassertion.md#totpmultifactorassertion_interface) | The class for asserting ownership of a TOTP second factor. Provided by [TotpMultiFactorGenerator.assertionForEnrollment()](./auth.totpmultifactorgenerator.md#totpmultifactorgeneratorassertionforenrollment) and [TotpMultiFactorGenerator.assertionForSignIn()](./auth.totpmultifactorgenerator.md#totpmultifactorgeneratorassertionforsignin)<!-- -->. |
 |  [TotpMultiFactorInfo](./auth.totpmultifactorinfo.md#totpmultifactorinfo_interface) | The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for TOTP second factors. The <code>factorId</code> of this second factor is [FactorId](./auth.md#factorid)<!-- -->.TOTP. |
 |  [User](./auth.user.md#user_interface) | A user account. |
@@ -405,6 +407,34 @@ export declare function createUserWithEmailAndPassword(auth: Auth, email: string
 
 Promise&lt;[UserCredential](./auth.usercredential.md#usercredential_interface)<!-- -->&gt;
 
+### exchangeToken(auth, idpConfigId, customToken) {:#exchangetoken_b6b1871}
+
+Asynchronously exchanges an OIDC provider's Authorization code or Id Token for an OidcToken i.e. Outbound Access Token.
+
+This method is implemented only for `DefaultConfig.REGIONAL_API_HOST` and requires [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface) to be configured in the [Auth](./auth.auth.md#auth_interface) instance used.
+
+Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service.
+
+<b>Signature:</b>
+
+```typescript
+export declare function exchangeToken(auth: Auth, idpConfigId: string, customToken: string): Promise<string>;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. |
+|  idpConfigId | string | The ExternalUserDirectoryId corresponding to the OIDC custom Token. |
+|  customToken | string | The OIDC provider's Authorization code or Id Token to exchange. |
+
+<b>Returns:</b>
+
+Promise&lt;string&gt;
+
+The firebase access token (JWT signed by Firebase Auth).
+
 ### fetchSignInMethodsForEmail(auth, email) {:#fetchsigninmethodsforemail_efb3887}
 
 Gets the list of possible sign in methods for the given email address. This method returns an empty list when [Email Enumeration Protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection) is enabled, irrespective of the number of authentication methods available for the given email.

docs-devsite/auth.tokenresponse.md

@@ -0,0 +1,42 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# TokenResponse interface
+Interface for TokenRespone returned via [exchangeToken()](./auth.md#exchangetoken_b6b1871) endpoint. This is expected to be returned only if [Auth](./auth.auth.md#auth_interface) object initialized has defined [TenantConfig](./auth.tenantconfig.md#tenantconfig_interface)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export interface TokenResponse 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [expiresIn](./auth.tokenresponse.md#tokenresponseexpiresin) | string |  |
+|  [token](./auth.tokenresponse.md#tokenresponsetoken) | string |  |
+
+## TokenResponse.expiresIn
+
+<b>Signature:</b>
+
+```typescript
+readonly expiresIn: string;
+```
+
+## TokenResponse.token
+
+<b>Signature:</b>
+
+```typescript
+readonly token: string;
+```

packages/auth/src/api/authentication/exchange_token.test.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * 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 { expect, use } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+
+import {
+  regionalTestAuth,
+  testAuth,
+  TestAuth
+} from '../../../test/helpers/mock_auth';
+import * as mockFetch from '../../../test/helpers/mock_fetch';
+import { mockRegionalEndpointWithParent } from '../../../test/helpers/api/helper';
+import { exchangeToken } from './exchange_token';
+import { HttpHeader, RegionalEndpoint } from '..';
+import { FirebaseError } from '@firebase/util';
+import { ServerError } from '../errors';
+
+use(chaiAsPromised);
+
+describe('api/authentication/exchange_token', () => {
+  let auth: TestAuth;
+  let regionalAuth: TestAuth;
+  const request = {
+    parent: 'test-parent',
+    token: 'custom-token'
+  };
+
+  beforeEach(async () => {
+    auth = await testAuth();
+    regionalAuth = await regionalTestAuth();
+    mockFetch.setUp();
+  });
+
+  afterEach(mockFetch.tearDown);
+
+  it('returns accesss token for Regional Auth', async () => {
+    const mock = mockRegionalEndpointWithParent(
+      RegionalEndpoint.EXCHANGE_TOKEN,
+      'test-parent',
+      { accessToken: 'outbound-token', expiresIn: '1000' }
+    );
+
+    const response = await exchangeToken(regionalAuth, request);
+    expect(response.accessToken).equal('outbound-token');
+    expect(response.expiresIn).equal('1000');
+    expect(mock.calls[0].request).to.eql({
+      parent: 'test-parent',
+      token: 'custom-token'
+    });
+    expect(mock.calls[0].method).to.eq('POST');
+    expect(mock.calls[0].headers!.get(HttpHeader.CONTENT_TYPE)).to.eq(
+      'application/json'
+    );
+  });
+
+  it('throws exception for default Auth', async () => {
+    await expect(exchangeToken(auth, request)).to.be.rejectedWith(
+      FirebaseError,
+      'Firebase: Operations not allowed for the auth object initialized. (auth/operation-not-allowed).'
+    );
+  });
+
+  it('should handle errors', async () => {
+    const mock = mockRegionalEndpointWithParent(
+      RegionalEndpoint.EXCHANGE_TOKEN,
+      'test-parent',
+      {
+        error: {
+          code: 400,
+          message: ServerError.INVALID_CUSTOM_TOKEN,
+          errors: [
+            {
+              message: ServerError.INVALID_CUSTOM_TOKEN
+            }
+          ]
+        }
+      },
+      400
+    );
+
+    await expect(exchangeToken(regionalAuth, request)).to.be.rejectedWith(
+      FirebaseError,
+      '(auth/invalid-custom-token).'
+    );
+    expect(mock.calls[0].request).to.eql(request);
+  });
+});

packages/auth/src/api/authentication/exchange_token.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * 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 {
+  RegionalEndpoint,
+  HttpMethod,
+  _performRegionalApiRequest
+} from '../index';
+import { Auth } from '../../model/public_types';
+
+export interface ExchangeTokenRequest {
+  parent: string;
+  token: string;
+}
+
+export interface ExchangeTokenRespose {
+  accessToken: string;
+  expiresInSec: string;
+}
+
+export async function exchangeToken(
+  auth: Auth,
+  request: ExchangeTokenRequest
+): Promise<ExchangeTokenRespose> {
+  return _performRegionalApiRequest<ExchangeTokenRequest, ExchangeTokenRespose>(
+    auth,
+    HttpMethod.POST,
+    RegionalEndpoint.EXCHANGE_TOKEN,
+    request,
+    {},
+    request.parent
+  );
+}