BlobEntwickler

Mit Blob anmelden

Lass Leute sich mit Blob anmelden

Blob ist ein OpenID-Connect-Anbieter. Bau einen Button in deine Website ein, und Schülerinnen und Schüler melden sich mit dem Konto an, das sie schon für Notizen und Lektionen nutzen. Du siehst und speicherst nie ein Passwort.

Vorschau

Der Button, den blob.button() erzeugt. Ein eigener Button geht genauso.

So funktioniert's

  1. 1

    Deine Seite öffnet Blob

    signIn() öffnet Blob in einem kleinen Pop-up-Fenster. Sind Pop-ups blockiert, gibt es stattdessen eine normale Weiterleitung.

  2. 2

    Anmelden und zustimmen

    Blob zeigt, wer sich anmeldet und was deine Seite sehen darf. Vertrauenswürdige Apps überspringen diesen Schritt.

  3. 3

    Zurück mit einem Einmal-Code

    Blob schickt das Pop-up an deine Redirect-URI. Die Callback-Seite gibt den Code an deine Seite weiter und schließt sich.

  4. 4

    Deine Seite kennt die Person

    Das SDK tauscht den Code mit PKCE gegen Tokens, prüft das ID-Token und gibt dir die Person.

Schnellstart

Für Websites ohne eigenen Servercode. Drei Schritte.

  1. 1

    App registrieren

    Ein Blob-Admin trägt deine Seite unter Admin › Apps und APIs ein und gibt dir eine Client-ID. Nenn dabei deine Redirect-URI, zum Beispiel https://deine-seite.de/blob-callback.html.

  2. 2

    Callback-Seite ablegen

    Leg blob-callback.html genau unter dieser Redirect-URI ab. Die winzige Seite gibt das Ergebnis an das Fenster zurück, das Blob geöffnet hat.

    blob-callback.html herunterladen
  3. 3

    SDK einbinden

    Lade das Modul von Blob, erstell BlobAuth mit deiner Client-ID und Redirect-URI und ruf signIn() auf, wenn jemand auf deinen Button klickt.

    index.html
    <button id="login">Mit Blob anmelden</button>
    
    <script type="module">
      import { BlobAuth } from "https://blob.bojes.org/sdk/blob-auth.js";
      const blob = new BlobAuth({ clientId: "YOUR_CLIENT_ID", redirectUri: "https://deine-seite.de/blob-callback.html" });
      document.querySelector("#login").onclick = async () => { const user = await blob.signIn(); };
    </script>

    Ersetz YOUR_CLIENT_ID und die Redirect-URI durch die Werte deiner App aus dem Admin-Bereich.

Eine vollständige Seite

Mit Abmelden, Updates aus anderen Tabs und einem Token für deine eigene API.

index.html
<button id="login">Mit Blob anmelden</button>
<button id="logout" hidden>Abmelden</button>

<script type="module">
  import { BlobAuth } from "https://blob.bojes.org/sdk/blob-auth.js";

  const blob = new BlobAuth({
    clientId: "YOUR_CLIENT_ID",
    redirectUri: "https://deine-seite.de/blob-callback.html",
  });

  // Anmeldung abschließen, die ohne Pop-up zurückkam
  await blob.handleRedirect();

  // Wird sofort aufgerufen und bei jedem An- oder Abmelden (in jedem Tab)
  blob.onChange((user) => {
    document.querySelector("#login").hidden = !!user;
    document.querySelector("#logout").hidden = !user;
  });

  document.querySelector("#login").onclick = async () => {
    const user = await blob.signIn(); // öffnet Blob in einem Pop-up
    console.log(user.name, user.email);
  };
  document.querySelector("#logout").onclick = () => blob.signOut();

  // Für deine eigene API: als Authorization: Bearer … mitschicken
  const token = await blob.getAccessToken();

  // Oder der fertige Button:
  // document.body.append(blob.button());
</script>

SDK-Referenz

blob-auth.js ist ein kleines ES-Modul ohne Abhängigkeiten. Tokens liegen im localStorage und werden automatisch erneuert.

new BlobAuth({ clientId, redirectUri, issuer?, scope? })
Erstellt den Client. issuer ist standardmäßig die Adresse, von der das SDK geladen wurde, scope „openid profile email offline_access“.
signIn()
Öffnet Blob und liefert die Person. Schlägt mit einem BlobAuthError fehl, z. B. Code „access_denied“ oder „popup_closed“.
handleRedirect()
Schließt eine Anmeldung ab, die ohne Pop-up zurückkam. Einmal beim Laden der Seite aufrufen.
user
Die angemeldete Person ({ sub, name, given_name, email, picture, locale }) oder null.
onChange(callback)
Ruft sofort zurück und jedes Mal, wenn sich jemand an- oder abmeldet, in jedem Tab. Gibt eine Funktion zum Abmelden des Listeners zurück.
getAccessToken()
Ein gültiges Access-Token für deine eigene API, bei Bedarf erneuert, oder null, wenn niemand angemeldet ist.
signOut()
Meldet von deiner Seite ab und widerruft das Refresh-Token. Blob selbst bleibt angemeldet.
button()
Ein fertiger Button „Mit Blob anmelden“, der signIn() aufruft.
data.list() · get(key) · put(key, value) · delete(key)
Die eigenen Daten der App im Blob-Konto der Person (braucht den Scope „data“). Jede App sieht nur ihre eigenen Schlüssel.

Scopes und Claims

Frag nur nach dem, was du brauchst. Jeder Scope steht auf der Zustimmungsseite, und der Admin legt fest, welche deine App anfragen darf.

openid
sub
Pflicht. Eine private, feste ID der Person in deiner App.
profile
name, given_name, picture, locale, updated_at
Name, Vorname, Profilbild und Sprache, so wie sie in Blob stehen.
email
email, email_verified
Die E-Mail-Adresse und ob sie bestätigt ist.
data
–
Die App darf eigene Daten der Person in Blob ablegen (z. B. Fortschritt), über blob.data oder /api/v1/data. Nur für Apps, denen der Admin das erlaubt.
offline_access
refresh_token
Ein Refresh-Token, damit man bis zu 30 Tage angemeldet bleibt.

Dieselben Claims liefert der Userinfo-Endpunkt mit einem Access-Token. sub ändert sich nie, nutz es also (nicht die E-Mail), um Leute wiederzuerkennen.

Endpunkte

Alles steht auch im Discovery-Dokument, damit sich OpenID-Connect-Bibliotheken mit einer einzigen URL einrichten können.

Discovery
https://blob.bojes.org/.well-known/openid-configuration
Issuer
https://blob.bojes.org
Autorisierung
https://blob.bojes.org/oauth/authorize
Token
https://blob.bojes.org/api/oauth/token
Benutzerinfo
https://blob.bojes.org/api/oauth/userinfo
Widerruf
https://blob.bojes.org/api/oauth/revoke
Öffentliche Schlüssel (JWKS)
https://blob.bojes.org/oauth/jwks
App-Daten (Scope data)
https://blob.bojes.org/api/v1/data

Apps mit Server

Hat deine App einen eigenen Server, kann sie als vertraulicher Client mit Client-Secret registriert werden. Schick die Leute zum Autorisierungs-Endpunkt und tausch den Code dann auf deinem Server. Authentifiziert wird per HTTP Basic (client_secret_basic) oder mit Formularfeldern (client_secret_post). PKCE ist auch hier empfohlen.

1. Leute zu Blob schicken

GET /oauth/authorize
https://blob.bojes.org/oauth/authorize?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fdeine-seite.de%2Fblob-callback.html
  &scope=openid%20profile%20email
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

2. Code gegen Tokens tauschen

POST /api/oauth/token
# Auf deinem Server: Einmal-Code gegen Tokens tauschen (innerhalb von 2 Minuten)
curl -X POST "https://blob.bojes.org/api/oauth/token" \
  -u "YOUR_CLIENT_ID:$BLOB_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://deine-seite.de/blob-callback.html" \
  -d code_verifier="$CODE_VERIFIER"

# Später: frisches Access-Token. Das Refresh-Token rotiert, heb das neue auf
curl -X POST "https://blob.bojes.org/api/oauth/token" \
  -u "YOUR_CLIENT_ID:$BLOB_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

Die Antwort

200 OK · application/json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiIsInR5cCI6ImF0K2p3dCJ9…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email offline_access",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiIsInR5cCI6IkpXVCJ9…",
  "refresh_token": "blob_rt_…"
}

Prüf das ID-Token, bevor du ihm vertraust: RS256-Signatur mit einem Schlüssel aus dem JWKS, iss ist der Issuer, aud ist deine Client-ID, exp liegt in der Zukunft und nonce ist die, die du geschickt hast.

Tokens und Laufzeiten

Autorisierungscode
2 Minuten
Nur einmal nutzbar. An die Redirect-URI und die PKCE-Challenge gebunden.
Access-Token
1 Stunde
JWT, signiert mit RS256 (typ at+jwt). Für Userinfo und deine eigene API.
ID-Token
1 Stunde
JWT mit den Claims der Person, aud = deine Client-ID.
Refresh-Token
30 Tage
Rotiert: Jede Nutzung liefert ein neues. Wird ein altes noch mal benutzt, ist die ganze Anmeldung gesperrt.

Sicherheit

  • PKCE mit S256 ist für Browser-Apps Pflicht und für alle anderen empfohlen.
  • Redirect-URIs müssen genau passen: keine Platzhalter, nur https (http nur für localhost), kein #Fragment.
  • Schick immer state und nonce mit und prüf sie bei der Rückkehr. Das SDK macht das für dich.
  • Blob hängt iss an die Weiterleitung an (RFC 9207). Prüf es, wenn deine Seite mit mehreren Anbietern spricht.
  • Ein Client-Secret gehört nie in Browser-Code. Browser-Apps bekommen keins.
  • Man kann deiner App den Zugriff jederzeit in Blob unter Einstellungen › Verbundene Apps entziehen. Dann funktionieren Refresh-Tokens nicht mehr, behandle invalid_grant also wie „abgemeldet“.
  • Die Zustimmungsseite lässt sich nicht in einem Frame anzeigen. Nimm das Pop-up oder eine Weiterleitung.