Firebase

Le package @mastra/auth-firebase fournit à Mastra l'authentification Firebase Authentication. Il vérifie les requêtes entrantes au moyen de jetons d'identification Firebase et s'intègre au serveur Mastra grâce à l'option auth.

Prérequis

Cet exemple utilise Firebase Authentication. Veillez à :

1. créer un projet Firebase dans la console Firebase ;
2. activer Authentication et configurer les méthodes de connexion souhaitées, par exemple Google ou e-mail et mot de passe ;
3. générer une clé de compte de service depuis Project Settings > Service Accounts ;
4. télécharger le fichier JSON du compte de service.

.env

FIREBASE_SERVICE_ACCOUNT=/path/to/your/service-account-key.json
FIRESTORE_DATABASE_ID=(default)
# Alternative environment variable names:
# FIREBASE_DATABASE_ID=(default)

remarque

Conservez le fichier JSON de votre compte de service en lieu sûr et ne le validez jamais dans votre système de gestion de versions.

Installation

Avant d'utiliser la classe MastraAuthFirebase, vous devez installer le package @mastra/auth-firebase.

npm

npm install @mastra/auth-firebase@latest

pnpm

pnpm add @mastra/auth-firebase@latest

Yarn

yarn add @mastra/auth-firebase@latest

Bun

bun add @mastra/auth-firebase@latest

Exemples d'utilisation

Utilisation de base avec des variables d'environnement

Si vous définissez les variables d'environnement requises (FIREBASE_SERVICE_ACCOUNT et FIRESTORE_DATABASE_ID), vous pouvez initialiser MastraAuthFirebase sans argument de constructeur. La classe lit automatiquement ces variables d'environnement comme configuration :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthFirebase } from '@mastra/auth-firebase'

// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthFirebase(),
  },
})

Configuration personnalisée

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthFirebase } from '@mastra/auth-firebase'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthFirebase({
      serviceAccount: '/path/to/service-account.json',
      databaseId: 'your-database-id',
    }),
  },
})

Configuration

La classe MastraAuthFirebase peut être configurée au moyen des options du constructeur ou de variables d'environnement.

Variables d'environnement

• FIREBASE_SERVICE_ACCOUNT : chemin du fichier JSON du compte de service Firebase
• FIRESTORE_DATABASE_ID ou FIREBASE_DATABASE_ID : identifiant de la base de données Firestore

remarque

Lorsque les options du constructeur ne sont pas fournies, la classe lit automatiquement ces variables d'environnement. Vous pouvez donc appeler new MastraAuthFirebase() sans argument si vos variables d'environnement sont correctement configurées.

Autorisation des utilisateurs

Par défaut, MastraAuthFirebase utilise Firestore pour gérer l'accès des utilisateurs. Il attend une collection user_access dont les documents sont indexés par les UID des utilisateurs. La présence d'un document dans cette collection détermine si l'utilisateur est autorisé.

firestore-structure.txt

user_access/
  {user_uid_1}/     // Document exists = user authorized
  {user_uid_2}/     // Document exists = user authorized

Pour personnaliser l'autorisation des utilisateurs, fournissez une fonction authorizeUser personnalisée :

src/mastra/auth.ts

import { MastraAuthFirebase } from '@mastra/auth-firebase'

const firebaseAuth = new MastraAuthFirebase({
  authorizeUser: async user => {
    // Custom authorization logic
    return user.email?.endsWith('@yourcompany.com') || false
  },
})

Consultez MastraAuthFirebase pour découvrir toutes les options de configuration disponibles.

Configuration côté client

Lorsque vous utilisez l'authentification Firebase, vous devez initialiser Firebase côté client, authentifier les utilisateurs et récupérer leurs jetons d'identification pour les transmettre dans vos requêtes Mastra.

Configurer Firebase côté client

Commencez par initialiser Firebase dans votre application cliente :

lib/firebase.ts

import { initializeApp } from 'firebase/app'
import { getAuth, GoogleAuthProvider } from 'firebase/auth'

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
}

const app = initializeApp(firebaseConfig)
export const auth = getAuth(app)
export const googleProvider = new GoogleAuthProvider()

Authentifier les utilisateurs et récupérer les jetons

Utilisez l'authentification Firebase pour connecter les utilisateurs et récupérer leurs jetons d'identification :

lib/auth.ts

import { signInWithPopup, signOut, User } from 'firebase/auth'
import { auth, googleProvider } from './firebase'

export const signInWithGoogle = async () => {
  try {
    const result = await signInWithPopup(auth, googleProvider)
    return result.user
  } catch (error) {
    console.error('Error signing in:', error)
    throw error
  }
}

export const getIdToken = async (user: User) => {
  try {
    const idToken = await user.getIdToken()
    return idToken
  } catch (error) {
    console.error('Error getting ID token:', error)
    throw error
  }
}

export const signOutUser = async () => {
  try {
    await signOut(auth)
  } catch (error) {
    console.error('Error signing out:', error)
    throw error
  }
}

remarque

Consultez la documentation Firebase pour découvrir d'autres méthodes d'authentification, notamment par e-mail et mot de passe ou par téléphone.

Configurer MastraClient

Lorsque auth est activé, toutes les requêtes effectuées avec MastraClient doivent inclure un jeton d'identification Firebase valide dans l'en-tête Authorization :

lib/mastra/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const createMastraClient = (idToken: string) => {
  return new MastraClient({
    baseUrl: 'https://<mastra-api-url>',
    headers: {
      Authorization: `Bearer ${idToken}`,
    },
  })
}

info

Le jeton d'identification doit être précédé de Bearer dans l'en-tête Authorization.

Consultez le SDK client Mastra pour davantage d’options de configuration.

Effectuer des requêtes authentifiées

Une fois MastraClient configuré avec le jeton d'identification Firebase, vous pouvez envoyer des requêtes authentifiées :

React

src/components/test-agent.tsx

'use client'

import { useAuthState } from 'react-firebase-hooks/auth'
import { MastraClient } from '@mastra/client-js'
import { auth } from '../lib/firebase'
import { getIdToken } from '../lib/auth'

export const TestAgent = () => {
  const [user] = useAuthState(auth)

  async function handleClick() {
    if (!user) return

    const token = await getIdToken(user)
    const client = createMastraClient(token)

    const weatherAgent = client.getAgent('weatherAgent')
    const response = await weatherAgent.generate("What's the weather like in New York")

    console.log({ response })
  }

  return (
    <button onClick={handleClick} disabled={!user}>
      Test Agent
    </button>
  )
}

Node.js

server.js

const express = require('express')
const admin = require('firebase-admin')
const { MastraClient } = require('@mastra/client-js')

// Initialize Firebase Admin
admin.initializeApp({
  credential: admin.credential.cert({
    // Your service account credentials
  }),
})

const app = express()
app.use(express.json())

app.post('/generate', async (req, res) => {
  try {
    const { idToken } = req.body

    // Verify the token
    await admin.auth().verifyIdToken(idToken)

    const mastra = new MastraClient({
      baseUrl: 'http://localhost:4111',
      headers: {
        Authorization: `Bearer ${idToken}`,
      },
    })

    const weatherAgent = mastra.getAgent('weatherAgent')
    const response = await weatherAgent.generate("What's the weather like in Nairobi")

    res.json({ response: response.text })
  } catch (error) {
    res.status(401).json({ error: 'Unauthorized' })
  }
})

cURL

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-firebase-id-token>" \
  -d '{
    "messages": "Weather in London"
  }'