Yetkilendirme ve bütünlük

Herkese açık bir uygulama geliştirirken sisteminizde depolanan verileri korumak son derece önemlidir. LLM'ler söz konusu olduğunda, modelin yalnızca gerekli verilere eriştiğinden, araç çağrılarının LLM'yi çağıran kullanıcıya uygun şekilde kapsamlandırıldığından ve akışın yalnızca doğrulanmış istemci uygulamaları tarafından çağrıldığından emin olmak için daha fazla özen gösterilmesi gerekir.

Firebase Genkit, yetkilendirme politikalarını ve bağlamları yönetmek için mekanizmalar sağlar. Firebase'de çalışan akışlar, kimlik doğrulama politikası geri çağırma işlevi (veya yardımcısı) kullanabilir. Alternatif olarak Firebase, kendi kontrollerini yapabileceği kimlik doğrulama bağlamını akışa da sağlar. İşlev dışı akışlar için kimlik doğrulama, orta katman aracılığıyla yönetilebilir ve ayarlanabilir.

Bir akış içinde yetkilendirme

Akışlar, yetkilendirmeyi iki şekilde kontrol edebilir: İstek bağlama (ör.Firebase için Cloud Functions'de onCallGenkit veya express) yetkilendirmeyi zorunlu kılabilir ya da bu çerçeveler, yetkilendirme politikalarını akışa iletebilir. Bu durumda akış, akış içinde yönetilen yetkilendirme bilgilerine erişebilir.

import { genkit, z, UserFacingError } from 'genkit';

const ai = genkit({ ... });

export const selfSummaryFlow = ai.defineFlow( {
  name: 'selfSummaryFlow',
  inputSchema: z.object({ uid: z.string() }),
  outputSchema: z.string(),
}, async (input, { context }) => {
  if (!context.auth) {
    throw new UserFacingErrorError('UNAUTHENTICATED', 'Unauthenticated');
  }
  if (input.uid !== context.auth.uid) {
    throw new UserFacingError('PERMISSION_DENIED', 'You may only summarize your own profile data.');
  }
  // Flow logic here...
});

Bu durumda context.auth değerinin doldurulması istek bağlamaya bağlıdır. Örneğin, onCallGenkit, context.auth (Firebase Authentication), context.app (Firebase Uygulama Kontrolü) ve context.instanceIdToken (Firebase Cloud Messaging) öğelerini otomatik olarak doldurur. Bir akışı manuel olarak çağırırken kendi kimlik doğrulama bağlamınızı manuel olarak ekleyebilirsiniz.

// Error: Authorization required.
await selfSummaryFlow({ uid: 'abc-def' });

// Error: You may only summarize your own profile data.
await selfSummaryFlow.run(
  { uid: 'abc-def' },
  {
    context: { auth: { uid: 'hij-klm' } },
  }
);

// Success
await selfSummaryFlow(
  { uid: 'abc-def' },
  {
    context: { auth: { uid: 'abc-def' } },
  }
);

Genkit Geliştirme kullanıcı arayüzüyle çalışırken "Auth JSON" sekmesine JSON girerek Auth nesnesini iletebilirsiniz: {"uid": "abc-def"}.

Ayrıca akış tarafından çağrılan işlevler dahil olmak üzere akış içinde dilediğiniz zaman ai.currentContext()'yi çağırarak akış için kimlik doğrulama bağlamını alabilirsiniz:

import { genkit, z } from 'genkit';

const ai = genkit({ ... });;

async function readDatabase(uid: string) {
  const auth = ai.currentContext()?.auth;
  // Note: the shape of context.auth depends on the provider. onCallGenkit puts
  // claims information in auth.token
  if (auth?.token?.admin) {
    // Do something special if the user is an admin
  } else {
    // Otherwise, use the `uid` variable to retrieve the relevant document
  }
}

export const selfSummaryFlow = ai.defineFlow(
  {
    name: 'selfSummaryFlow',
    inputSchema: z.object({ uid: z.string() }),
    outputSchema: z.string(),
    authPolicy: ...
  },
  async (input) => {
    await readDatabase(input.uid);
  }
);

Genkit geliştirici araçlarıyla akışları test ederken bu kimlik doğrulama nesnesini kullanıcı arayüzünde veya komut satırında --context işaretiyle belirtebilirsiniz:

genkit flow:run selfSummaryFlow '{"uid": "abc-def"}' --context '{"auth": {"email_verified": true}}'

Cloud Functions for Firebase'i kullanarak yetki verme

Firebase için Cloud Functions SDK'ları, Firebase Auth / Google Cloud Identity Platform ile entegrasyon ve yerleşik Firebase App Check desteği de dahil olmak üzere Genkit'i destekler.

Kullanıcı kimlik doğrulaması

Firebase Functions kitaplığı tarafından sağlanan onCallGenkit() sarmalayıcısı, Firebase için Cloud Functions istemci SDK'ları için yerleşik destek içerir. Bu SDK'ları kullandığınızda, uygulama istemciniz de Firebase Auth SDK'sını kullandığı sürece Firebase Auth başlığı otomatik olarak eklenir. onCallGenkit() ile tanımlanan akışlarınızı korumak için Firebase Auth'i kullanabilirsiniz:

import { genkit } from 'genkit';
import { onCallGenkit } from 'firebase-functions/https';

const ai = genkit({ ... });;

const selfSummaryFlow = ai.defineFlow({
  name: 'selfSummaryFlow',
  inputSchema: z.string(),
  outputSchema: z.string(),
}, async (input) => {
  // Flow logic here...
});

export const selfSummary = onCallGenkit({
  authPolicy: (auth) => auth?.token?.['email_verified'] && auth?.token?.['admin'],
}, selfSummaryFlow);

onCallGenkit kullanıldığında context.auth, kullanıcı kimliği için bir uid ve DecodedIdToken olan bir token içeren bir nesne olarak döndürülür. Daha önce belirtildiği gibi, bu nesneyi dilediğiniz zaman ai.currentContext() kullanarak alabilirsiniz. Geliştirme sırasında bu akışı çalıştırırken kullanıcı nesnesini aynı şekilde iletirsiniz:

genkit flow:run selfSummaryFlow '{"uid": "abc-def"}' --context '{"auth": {"admin": true}}'

Bir Cloud işlevini daha geniş internete açtığınızda verilerinizi ve müşterilerinizin verilerini korumak için bir tür yetkilendirme mekanizması kullanmanız son derece önemlidir. Bununla birlikte, kod tabanlı yetkilendirme kontrolleri içermeyen bir Cloud Functions işlevi dağıtmanız gerekebilir (örneğin, işleviniz herkes tarafından çağrılabilir değil, Cloud IAM tarafından korunuyor olabilir). Cloud Functions for Firebase, IAM erişimini kontrol eden invoker mülkünü kullanarak bunu yapmanıza olanak tanır. 'private' özel değeri, işlevi varsayılan IAM ayarı olarak bırakır. Bu, işlevi yalnızca Cloud Run Çağırıcı rolüne sahip olan kullanıcıların çalıştırabileceği anlamına gelir. Bunun yerine, tam olarak bu işlevi çağırma izni verilmesi gereken bir kullanıcının veya hizmet hesabının e-posta adresini sağlayabilirsiniz.

import { onCallGenkit } from 'firebase-functions/https'

const selfSummaryFlow = ai.defineFlow({
  name: 'selfSummaryFlow',
  inputSchema: z.string(),
  outputSchema: z.string(),
}, async (input) => {
  // Flow logic here...
});

export const selfSummary = onCallGenkit({
  invoker: 'private',
}, selfSummaryFlow);

Müşteri bütünlüğü

Kimlik doğrulama, uygulamanızı korumak için tek başına çok önemli bir adımdır. Ancak işlevlerinizin yalnızca istemci uygulamalarınızın çağırdığından emin olmak da önemlidir. Genkit için Firebase eklentisi, Firebase Uygulama Kontrolü için birinci sınıf destek içerir. Bunu yapmak için onCallGenkit()'nize aşağıdaki yapılandırma seçeneklerini ekleyerek yapabilirsiniz:

import { onCallGenkit } from 'firebase-functions/https';

const selfSummaryFlow = ai.defineFlow({
  name: 'selfSummaryFlow',
  inputSchema: z.string(),
  outputSchema: z.string(),
}, async (input) => {
  // Flow logic here...
});

export const selfSummary = onCallGenkit({
  // These two fields for app check. The consumeAppCheckToken option is for
  // replay protection, and requires additional client configuration. See the
  // App Check docs.
  enforceAppCheck: true,
  consumeAppCheckToken: true,

  authPolicy: ...,
}, selfSummaryFlow);

Firebase dışı HTTP yetkilendirmesi

Firebase için Cloud Functions dışındaki bir sunucu bağlamına akış dağıtırken, yerleşik akışların yanı sıra kendi yetkilendirme kontrollerinizi ayarlamanızı sağlayacak bir yönteme sahip olmanız gerekir.

auth gibi bağlam değerlerini doldurmak ve açıklayıcı bir politika veya politika geri çağırma sağlamak için ContextProvider kullanın. Genkit SDK'sı, apiKey gibi ContextProvider'ler sağlar ve eklentiler de bunları gösterebilir. Örneğin, @genkit-ai/firebase/context eklentisi, Firebase Auth kimlik bilgilerini doğrulamak ve bağlama doldurmak için bir bağlam sağlayıcısı gösterir.

Çeşitli uygulamalarda görünebilecek aşağıdaki gibi bir kodla:

// Express app with a simple API key
import { genkit, z } from 'genkit';

const ai = genkit({ ... });;

export const selfSummaryFlow = ai.defineFlow(
  {
    name: 'selfSummaryFlow',
    inputSchema: z.object({ uid: z.string() }),
    outputSchema: z.string(),
  },
  async (input) => {
    // Flow logic here...
  }
);

Basit bir "akış sunucusu" hızlı uygulamasını şu şekilde yazarak güvence altına alabilirsiniz:

import { apiKey } from "genkit";
import { startFlowServer, withContext } from "@genkit-ai/express";

startFlowServer({
  flows: [
    withContext(selfSummaryFlow, apiKey(process.env.REQUIRED_API_KEY))
  ],
});

Dilerseniz aynı araçları kullanarak özel bir hızlı uygulama da oluşturabilirsiniz:

import { apiKey } from "genkit";
import * as express from "express";
import { expressHandler } from "@genkit-ai/express;

const app = express();
// Capture but don't validate the API key (or its absence)
app.post('/summary', expressHandler(selfSummaryFlow, { contextProvider: apiKey()}))

app.listen(process.env.PORT, () => {
  console.log(`Listening on port ${process.env.PORT}`);
})

ContextProvider, web çerçevesini soyutlar. Bu nedenle bu araçlar Next.js gibi diğer çerçevelerde de çalışır. Next.js üzerinde oluşturulmuş bir Firebase uygulaması örneğini aşağıda bulabilirsiniz.

import { appRoute } from "@genkit-ai/express";
import { firebaseContext } from "@genkit-ai/firebase";

export const POST = appRoute(selfSummaryFlow, { contextProvider: firebaseContext })

Express'i kullanma hakkında daha fazla bilgi için Cloud Run talimatlarına bakın.