Mit Glossia anmelden

Diese Anleitung führt Sie durch das Hinzufügen von "Login mit Glossia" zu Ihrer Anwendung. Bis zum Ende können Ihre Benutzer sich mit ihrem Glossia-Konto anmelden und Ihre App verfügt über einen Zugriffstoken, um die Glossia-API im Namen der Benutzer aufzurufen.

Glossia verwendet OAuth 2.1 mit PKCE (Proof Key for Code Exchange). PKCE ist für alle Clients erforderlich, einschließlich serverseitiger Anwendungen.

1. Registrieren Sie Ihre OAuth-Anwendung

Sie haben zwei Optionen zur Registrierung Ihrer Anwendung:

Option A: Über das Dashboard (empfohlen)

1. Melden Sie sich bei Glossia an und navigieren Sie zu Ihrem Konto-Dashboard.
2. Öffnen Sie die API Sektion in der Seitenleiste und klicken Sie OAuth-Anwendungen.
3. Klicken Sie Neue Anwendung.
4. Geben Sie die Anwendung Name und Callback-URL (auch als Redirect URI bezeichnet).
5. Klicken Sie Anwendung erstellen.

Nach der Erstellung, beachten Sie das Client-ID und Client-Secret. Das Secret wird einmal angezeigt, speichern Sie es daher sicher.

Option B: Dynamische Client-Registrierung

Senden Sie eine POST Anfrage an /oauth/register:

curl -X POST https://glossia.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.com/auth/callback"],
    "grant_types": ["authorization_code"]
  }'

Die Antwort enthält client_id und client_secret.

2. Generiere eine PKCE-Code-Challenge

Bevor der Benutzer umgeleitet wird, generiere einen PKCE-Code-Verifier und eine Code-Challenge:

function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);
// Store codeVerifier in your session -- you will need it in step 4

3. Leiten Sie den Benutzer zu Glossia um.

Erstellen Sie die Autorisierungs-URL und leiten Sie den Browser des Benutzers um:

https://glossia.ai/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://myapp.com/auth/callback
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &scope=user:read+project:read
  &state=RANDOM_STATE_VALUE

Parameter:

Der Nutzer wird einen Einverständnisscreen sehen, der den Namen Ihrer Anwendung und die angeforderten Bereiche anzeigt. Nach Genehmigung leitet Glossia auf Ihre callback URL um und übermittelt einen Autorisierungscode.

4. Code gegen Tokens eintauschen

Wenn der Benutzer zurück zu Ihrer callback URL umgeleitet wird, enthält die URL einen code Parameter:

https://myapp.com/auth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

Zuerst überprüfen Sie, dass state es mit dem übereinstimmt, was Sie in Schritt 3 gesendet haben. Tauschen Sie dann den Code gegen Tokens ein:

curl -X POST https://glossia.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://myapp.com/auth/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Die Antwort:

{
  "access_token": "eyJhbGciOiJSUzI1...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJl..."
}

Speichere beide Tokens sicher. Der AccessToken wird für API-Anfragen verwendet. Der Refresh-Token wird verwendet, um einen neuen AccessToken zu erhalten, wenn der aktuelle abgelaufen ist.

5. Ruft die API im Namen des Benutzers auf

Verwende den AccessToken, um authentifizierte API-Anfragen zu stellen:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1..." \
  https://glossia.ai/api/projects

Die Scopes des Tokens begrenzen, welche Endpunkte du zugreifen kannst. Die Ressourcensebene-Autorisierung gilt weiterhin - beispielsweise ein Token, der project:read kann nur Projekte lesen, auf die der Benutzer Zugriff hat.

6. Aktualisiere den Token

Wenn der AccessToken abgelaufen ist, verwende den Refresh-Token, um einen neuen Token zu erhalten, ohne den Benutzer erneut durch den Einwilligungsfluss zu führen:

curl -X POST https://glossia.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=dGhpcyBpcyBhIHJl..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

7. Token widerrufen

Wenn sich ein Nutzer von Ihrer App trennt oder Sie den Zugriff nicht mehr benötigen, widerrufen Sie das Token:

curl -X POST https://glossia.ai/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJSUzI1..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Berechtigungen auswählen

Fordern Sie nur die für Ihre Anwendung benötigten Berechtigungen an. Hier sind einige gängige Kombinationen:

Siehe die Vollständige Bereiche-Referenz für alle verfügbaren Bereiche.

Entdeckungs-Endpunkte

Ihre Anwendung kann die OAuth-Endpunkte von Glossia automatisch entdecken, indem sie die Servermetadaten abruft:

curl https://glossia.ai/.well-known/oauth-authorization-server

Dies liefert ein JSON-Dokument mit dem authorization_endpointDas neuassembled Dokument hat die Validierung zuvor nicht bestanden: Die Wiederherstellung von Markdown-Textknoten ergab eine leere Übersetzung token_endpointDas neu zusammengesetzte Dokument hat die Validierung zuvor nicht bestanden: Die Wiederherstellung von Markdown-Textknoten erzeugte eine leere Übersetzung revocation_endpoint, und weitere Details. Die Nutzung von Discovery macht die Integration robust gegenüber Änderungen der Endpunkte.

Fehlerbehandlung

Autorisierungsfehler

Wenn der Benutzer der Zustimmung verweigert oder bei der Autorisierung etwas schiefgeht, leitet Glossia zur Callback-URL mit einem error Parameter:

https://myapp.com/auth/callback?error=access_denied&state=RANDOM_STATE_VALUE

Typische Fehlercodes:

Tokenfehler

Der Token-Endpunkt gibt HTTP 400 mit einem JSON-Fehlerinhalt zurück:

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired or was already used."
}

Ratenlimits

OAuth-Endpunkte sind pro IP limitiert. Wenn Sie das Limit erreichen, erhalten Sie HTTP 429. Sehen Sie den Referenz zur Rate Limiting für weitere Details.

Sicherheits-Checkliste

Bevor Sie in die Produktion gehen, überprüfen Sie, dass Ihre Implementierung diese Praktiken einhält:

• Verwenden Sie immer HTTPS für Callback-URLs in der Produktion
• Validieren Sie den state Parameter im Callback, um CSRF zu verhindern
• Speichern Sie Tokens verschlüsselt im Ruhezustand
• Veröffentlichen Sie niemals Tokens in clientseitigem JavaScript oder Browser-URLs
• Verwenden Sie das Minimum an benötigten Scopes
• Verarbeiten Sie Token-Abläufe sanft mittels Refresh-Tokens
• Entziehen Sie Tokens, wenn sich Benutzer abmelden oder ihr Konto löschen