Dokumentation

AI Connect/Core concepts/Authentifizierung und Scope

Authentifizierung und Scope

Frag die KI über Vinkius

Halten Sie die Anmeldedaten der Anwendung auf dem Server, leiten Sie externalId aus einer vertrauenswürdigen Identität ab und schreiben Sie Anmeldedaten des Connectors, ohne die Werte zurückzulesen.

Das SDK authentifiziert Ihr Backend mit einer App ID und einem Application Key. Es authentifiziert nicht Ihre Endbenutzer. Ihre Anwendung muss den Aufrufer verifizieren, die angeforderte Operation autorisieren und die externalId ableiten, die in jeder benutzerbezogenen Anfrage verwendet wird.

Halten Sie den Application Key hinter einer Servergrenze

typescript
import { Vinkius } from '@vinkius/connect';

export const vinkius = new Vinkius({
  appId: process.env.VINKIUS_APP_ID!,
  apiKey: process.env.VINKIUS_APP_KEY!,
});

Anfragen senden die Application Key konzeptionell als Bearer-Autorisierung und die App ID in einem Anwendungs-Header. Initialisieren Sie diesen Client nicht in Browser-Code und geben Sie keinen der beiden Werte an einen Client zurück.

Das SDK stellt keine gehostete OAuth- oder Konnektor-Einrichtungs-UI-API bereit. Wenn ein Konnektor Anmeldedaten erfordert, erfasst Ihre Anwendung diese in ihrem eigenen authentifizierten Serverfluss und sendet sie mit credentials.set().

Leiten Sie externalId aus dem authentifizierten Zustand ab

typescript
interface Session {
  userId: string;
}

async function listActions(session: Session) {
  return vinkius.user(session.userId).capabilities();
}

Verwenden Sie eine eigene stabile und vorzugsweise opake Benutzerkennung. Das SDK verwirft Werte, die:

  • leer sind oder länger als 255 Zeichen sind;
  • Leerzeichen, / oder Backslashes enthalten;
  • mit vk_app_user_ beginnen, was eine interne Kennung und nicht Ihre ID bezeichnet.

user(externalId) gibt ein Handle zurück und sendet keine Anfrage. ensure(metadata) ist optional:

typescript
await vinkius.user(session.userId).ensure({ plan: 'team' });

Die API behandelt diesen Aufruf als idempotentes Upsert. Halten Sie die Metadaten frei von Geheimnissen; sie sind kein Speicher für Anmeldedaten.

Lehnen Sie einen vom Client gewählten Benutzerkontext ab

Dieser Endpunkt ist verwundbar, weil der Anfragekörper den Benutzer wählt:

typescript
// Do not use this pattern without an authorization check.
const { externalId } = await request.json();
const capabilities = await vinkius.user(externalId).capabilities();

Binden Sie den Benutzerkontext, bevor Sie das Handle erstellen:

typescript
async function handleCapabilities(request: Request) {
  const session = await requireSession(request); // application code
  const capabilities = await vinkius.user(session.userId).capabilities();

  return Response.json(
    capabilities.map(({ name, description, inputSchema }) => ({
      name,
      description,
      inputSchema,
    })),
  );
}

Die Autorisierungsgrenze ist Ihre Sitzungsabfrage. Eine App ID und ein Schlüssel autorisieren die Anwendung, nicht einen bestimmten Browser-Benutzer.

Lesen Sie das Anmeldedaten-Schema, bevor Sie Werte erfassen

credentials.schema() liest Konnektor-Metadaten aus dem Katalog. Eine bestehende Benutzerverbindung ist nicht erforderlich:

typescript
const github = vinkius.user(session.userId).connector('github');
const schema = await github.credentials.schema();

Verwenden Sie das Schema, um zu entscheiden, welche Felder Ihr Serverformular akzeptieren soll. Gehen Sie nicht davon aus, dass alle Konnektoren Tokens oder dieselben Schlüsselnamen verwenden.

Schreiben Sie Anmeldedaten erst nach dem Erstellen der Verbindung

typescript
await github.connect();
const state = await github.credentials.set({
  GITHUB_TOKEN: submittedToken,
});

console.log(state.configured.GITHUB_TOKEN);

credentials.status() und credentials.set() erfordern eine Verbindung; andernfalls lösen sie ConnectorNotConnectedError aus. Ihre Antworten enthalten das Schema und eine Zuordnung der konfigurierten Schlüssel, nicht die gespeicherten Werte der Anmeldedaten:

typescript
const state = await github.credentials.status();
// state.configured: Record<string, boolean>

Behandeln Sie übermittelte Werte in Ihrem eigenen Code als Geheimnisse. Die Observability-Schwärzung des Transports deckt eine feste Liste bekannter Feldnamen ab, kann aber nicht jeden benutzerdefinierten Namen erkennen, den Sie anderswo protokollieren könnten.

Trennen Sie die Anwendungs-Umgebungen

Verwenden Sie unterschiedliche App IDs und Schlüssel für Entwicklung, Staging und produktiven Datenverkehr. Dadurch werden Benutzer, Verbindungsstatus und die Rotation der Anmeldedaten an der Authentifizierungsgrenze der Anwendung getrennt.

Nächste Schritte