You can enforce **authenticated-users mode** for your Firebase project. When
enforced, all Gemini API requests via Firebase AI Logic must come from
*authenticated users* of your app. Specifically, the end user of your app must
be authenticated using [Firebase Authentication](https://firebase.google.com/docs/auth.md.txt) before they send a
request to Firebase AI Logic from your app. If the end user is
unauthenticated, the request is blocked.
When a request is blocked, the response will be a `401: unauthenticated` error.
> [!IMPORTANT]
> **Important:** The authenticated-users mode for Firebase AI Logic requires that authentication credentials are from [Firebase Authentication](https://firebase.google.com/docs/auth.md.txt). If your app uses a different authentication solution, enforcing this mode will **block** requests from your users.
## Important considerations
Be aware of the following important considerations for authenticated-users mode.
> [!NOTE]
> **Note:** Enforcing authenticated-users mode is one way to help secure Gemini API usage, but it's still **critical that you also
> [enforce Firebase App Check](https://firebase.google.com/docs/ai-logic/app-check.md.txt)**.
### When authenticated-users mode is enforced
When authenticated-users mode is enforced, be aware of the following:
- This setting is a **project-wide** setting for Firebase AI Logic.
- It applies to all apps registered in the project.
- It only applies to the project where it's enforced.
- This setting **blocks** all requests via Firebase AI Logic that do *not*
send Firebase Authentication credentials.
- The user must be authenticated via Firebase Authentication *before* sending the request to Firebase AI Logic.
- This setting applies to *all* requests via Firebase AI Logic to both the Gemini Developer API and the Agent Platform Gemini API (formerly Vertex AI).
- This setting applies to *all* requests that use [server prompt templates](https://firebase.google.com/docs/ai-logic/server-prompt-templates/get-started.md.txt).
- This setting *cannot* be applied on a per-user, per-API, or per-template basis.
- This setting does **not block** Gemini API requests in your project that
are *not* via Firebase AI Logic.
- If you're using [hybrid / on-device](https://firebase.google.com/docs/ai-logic/hybrid.md.txt):
- This setting **blocks** requests to the cloud-hosted model if the user is unauthenticated.
- This setting does **not block** requests to the on-device model no matter the authentication state of the user.
- If you're using the [Gemini Live API](https://firebase.google.com/docs/ai-logic/live-api.md.txt):
- This setting **blocks** usage of the Gemini Live API for *web apps* when using Firebase AI Logic --- even for authenticated users. This includes web apps using the Firebase JS SDK or Flutter *web* apps.
- If you're using the
[Firebase AI Logic REST API](https://firebase.google.com/docs/reference/ai-logic/rest.md.txt):
- This setting **blocks** *inference* requests that do *not* send Firebase Authentication credentials. This includes requests for server prompt templates like `templateGenerateContent` or `templateStreamGenerateContent`.
- This setting does **not block** *control-plane* requests (like those for managing templates and configurations) because they are guarded by IAM.
- This setting does **not block** requests to `countTokens` (the Count Tokens
API).
### Before enforcing authenticated-users mode
Be aware of the following *before* you enforce authenticated-users mode:
- If you have existing versions of your app that do *not* use
Firebase Authentication:
- This setting will **block** requests via Firebase AI Logic from those existing app versions.
- Make sure that all active clients have been updated to use Firebase Authentication *before* enforcing authenticated-users mode.
- **Older Flutter plugin versions** require
[special instantiation](https://firebase.google.com/docs/ai-logic/auth-mode.md.txt#instantiation-flutter) to send Firebase Authentication
credentials with requests.
- If your app uses the Flutter plugin `firebase_ai` v3.11.0 or lower (BoM v4.12.0 or lower) and does *not* pass in Authentication during instantiation, this setting will **block** requests via Firebase AI Logic --- even for authenticated users.
- Make sure that all active clients for Flutter have been updated to a newer version of the plugin *before* enforcing authenticated-users mode.
**Special instantiation required for Flutter if using older plugin versions**
|---|
| *Click your Gemini API provider to view provider-specific content and code on this page.* |
This special instantiation is only required if your app uses the Flutter plugin
`firebase_ai` v3.11.0 or lower (BoM v4.12.0 or lower). If your app uses a newer
version of the plugin, this special instantiation isn't needed.
> [!NOTE]
> **Note:** Firebase recommends using the [latest versions of SDKs, plugins, and tools](https://firebase.google.com/support/releases.md.txt#latest-versions) so that you have access to the latest features, bug fixes, etc.
If you enforce authenticated-users mode, then in Flutter apps that use older
plugin versions, you need to explicitly pass in Authentication during instantiation,
like so:
```dart
// ...
final ai = await FirebaseAI.googleAI(
auth: FirebaseAuth.instance, // for Flutter, pass in Authentication explicitly
);
// ...
```
## Set up Firebase Authentication
> [!IMPORTANT]
> **Important:** The authenticated-users mode for Firebase AI Logic requires that authentication credentials are from [Firebase Authentication](https://firebase.google.com/docs/auth.md.txt). If your app uses a different authentication solution, enforcing this mode will **block** requests from your users.
The [Firebase Authentication](https://firebase.google.com/docs/auth.md.txt) documentation provides descriptions and
implementation instructions for supported authentication providers, including
using passwords, phone numbers, popular federated identity providers (like
Google, Facebook, and GitHub), and more.
After you implement Firebase Authentication in your app, your app will automatically
send the Firebase Authentication credentials for the authenticated user in every
request to Firebase AI Logic.
Note the following about some of the authentication providers:
- **Custom auth** : You need to fetch a signed auth token to send along with
the request to Firebase AI Logic. For details, see
[Custom Authentication](https://firebase.google.com/docs/auth/where-to-start.md.txt#custom-auth).
- **Anonymous** or **Email/Password** auth methods: These users are considered
*authenticated* users, so their requests to Firebase AI Logic are *not*
blocked.
Note that even though the anonymous and email/password authentication
methods require users to visit your app to create Firebase Authentication
credentials, **they are not robust forms of authentication (especially for
protecting a paid resource)** because they do not by default require
identity verification from the user. If your app uses the default
implementation of these authentication methods, less protection is possible
even if you enforce the authenticated-users mode. **Make sure that you've
also [enforced Firebase App Check](https://firebase.google.com/docs/ai-logic/app-check.md.txt).**
## Manage the authenticated-users mode setting
You manage the setting for authenticated-users mode in the Firebase console.
> [!NOTE]
> **Note:** Enforcing authenticated-users mode is one way to help secure Gemini API usage, but it's still **critical that you also
> [enforce Firebase App Check](https://firebase.google.com/docs/ai-logic/app-check.md.txt)**.
### Required IAM permissions and roles
Managing the authenticated-users mode setting requires the
`firebasevertexai.configs.update` permission, which is included by default in
these IAM roles: Owner, Editor, Firebase Admin, and Firebase AI Logic Admin.
### Enforce authenticated-users mode
Here's how to enforce authenticated-users mode for your Firebase project:
1. If you haven't already, review the
[important considerations](https://firebase.google.com/docs/ai-logic/auth-mode.md.txt#important-considerations) for
authenticated-users mode earlier in this guide.
2. If you haven't already, [set up Firebase Authentication](https://firebase.google.com/docs/ai-logic/auth-mode.md.txt#set-up-auth) in your app
(as described earlier in this guide).
3. Enforce authenticated-users mode:
1. In the Firebase console, go to **AI Services** \> **AI Logic** \>
[**Settings** tab](https://console.firebase.google.com/project/_/ailogic/templates?useAutoProject=true).
2. Under **Authenticated-users mode** , slide the toggle for
**Enforce authenticated-users mode** to **Enforced**.
3. Review the confirmation dialog, and then click **Confirm**.
### Stop enforcement of authenticated-users mode
If you stop enforcement of authenticated-users mode, be aware of the following:
- Requests via Firebase AI Logic that do *not* send Firebase Authentication credentials will be allowed.
- This is a **project-wide** setting for Firebase AI Logic.
Here's how to stop enforcement of authenticated-users mode for your Firebase
project:
1. In the Firebase console, go to **AI Services** \> **AI Logic** \>
[**Settings** tab](https://console.firebase.google.com/project/_/ailogic/templates?useAutoProject=true).
2. Under **Authenticated-users mode** , turn off
**Enforce authenticated-users mode**.
3. Review the confirmation dialog, and then click **Confirm**.