Authentifizierungs-Tokens

Authentifizierungs-Tokens sind unverzichtbar, wenn Ihre Custom Widgets API-Anfragen an sichere Endpunkte oder Dienste stellen muessen, die eine Benutzerauthentifizierung erfordern. Der Widget Builder bietet Zugriff auf Staffbase Authentifizierungs-Tokens, die Sie in Ihren API-Anfragen verwenden koennen.

Verfuegbare Authentifizierungs-Tokens

Der Widget Builder stellt zwei Arten von Staffbase Authentifizierungs-Tokens bereit, die Sie in Ihren API-Anfragen verwenden koennen:

Staffbase ID Token

Das ID Token ist ein JSON Web Token (JWT), das Informationen ueber den authentifizierten Benutzer enthaelt. Es liefert Identitaetsinformationen, mit denen ueberprueft werden kann, wer der Benutzer ist.

Dies ist ein Beispiel-Payload des Staffbase ID Tokens:

{
  "at_hash": "SfaFUUXInY8qOcHj-iMrtg",
  "aud": ["a5ba7f74-bedf-4d09-a4b0-ab84faf3ca7b"],
  "auth_time": 1758618864,
  "display_name": "Max Mustermann",
  "exp": 1758723348,
  "iat": 1758719748,
  "iss": "https://id-us1.staffbase.com/",
  "jti": "9df571d8-b9ab-4c90-9e7b-12f439139d88",
  "public_email": "max.mustermann@jasp.eu",
  "rat": 1758618861,
  "sid": "058855b2-ef8d-4eb4-9ccd-bb3f022e4a9c",
  "sub": "640b43f6fd99249009a41ba4"
}

So greifen Sie auf das ID Token zu

In Ihren Handlebars Templates koennen Sie mit dem staffbaseIdToken Helper auf das ID Token zugreifen:

<!-- Returns the jwt token -->
{{staffbaseIdToken}}

<!-- Returns a object -->
{{decode_jwt (staffbaseIdToken)}}

<!-- Returns a value from the payload -->
{{extract_jwt (staffbaseIdToken) "sub"}}

Wann Sie das ID Token verwenden sollten

Verwenden Sie das ID Token, wenn:

• Sie sich bei Diensten authentifizieren muessen, die Staffbase-Benutzer validieren
• Sie auf Benutzer-Identitaetsinformationen zugreifen muessen
• Sie API-Aufrufe an Dienste durchfuehren, die Staffbase ID Tokens zur Authentifizierung akzeptieren
• Sie die Identitaet des Benutzers serverseitig verifizieren muessen

Beispiel: Verwendung des ID Tokens in einer API-Anfrage

<script>
async function fetchUserData() {
  const response = await fetch("https://api.example.com/user-data", {
    headers: { Authorization: "Bearer {{staffbaseIdToken}}" },
  });
  const data = await response.json();
  console.log("Response: ", data);
}
</script>

Staffbase Access Token

Das Access Token wird verwendet, um Zugriff auf bestimmte Ressourcen oder Dienste zu gewaehren. Im Gegensatz zum ID Token, das primaer der Identifikation dient, wird das Access Token fuer Autorisierungszwecke eingesetzt.

So greifen Sie auf das Access Token zu

In Ihren Handlebars Templates koennen Sie mit dem staffbaseAccessToken Helper auf das Access Token zugreifen:

{{staffbaseAccessToken}}

Dieser Helper gibt das Token als Zeichenkette zurueck, die typischerweise so aussieht:

ory_ae4b742ea3...

Wann Sie das Access Token verwenden sollten

Verwenden Sie das Access Token, wenn:

• Sie Anfragen an Staffbase APIs oder Dienste stellen muessen
• Sie sich bei Drittanbieter-Diensten authentifizieren muessen, die mit Staffbase integriert wurden
• Sie bestimmte Aktionen autorisieren muessen, anstatt nur den Benutzer zu identifizieren
• Sie API-Aufrufe durchfuehren, die Berechtigungen fuer den Zugriff auf bestimmte Ressourcen erfordern

Beispiel: Verwendung des Access Tokens in einer API-Anfrage

<script>
async function fetchProtectedResource() {
    const response = await fetch('https://app.staffbase.com/api/users', {
        headers: { 'Authorization': 'Basic {{staffbaseAccessToken}}' }
    });
    const data = await response.json();
    document.getElementById('resource-data').textContent = JSON.stringify(data);
}
</script>

Tokens fuer Drittanbieter-Verbindungen

Sie koennen das Access Token aus den Verbindungen zu Microsoft, Google Workspace, ServiceNow, Atlassian oder Box zu Ihrer Anfrage hinzufuegen. Bitte kontaktieren Sie unseren Support fuer Anweisungen.

Authentifizierung zu API-Anfragen im Widget Builder hinzufuegen

Beim Erstellen von API-Anfragen im Widget Builder koennen Sie die Authentifizierung einfach mit den Staffbase Tokens hinzufuegen:

1. Navigieren Sie im Widget Builder zum Tab "API"
2. Erstellen oder bearbeiten Sie eine API-Anfrage
3. Fuegen Sie im Abschnitt Headers einen Authorization-Header hinzu:
   • Fuer das ID Token: Authorization: Bearer {{staffbaseIdToken}}
   • Fuer das Access Token: Authorization: Bearer {{staffbaseAccessToken}}

Sicherheitshinweise

Beachten Sie beim Umgang mit Authentifizierungs-Tokens folgende Best Practices fuer die Sicherheit:

• Speichern Sie Tokens nicht ueber laengere Zeitraeume in localStorage oder sessionStorage
• Verwenden Sie HTTPS fuer alle API-Anfragen, um sicherzustellen, dass Tokens waehrend der Uebertragung verschluesselt sind

Fehlerbehebung

Wenn Sie Probleme mit Authentifizierungs-Tokens haben:

1. Token-Format ueberpruefen: Stellen Sie sicher, dass Sie das korrekte Format fuer den Authorization-Header verwenden
2. CORS-Einstellungen pruefen: Cross-Origin Resource Sharing-Einschraenkungen koennten Ihre Anfragen blockieren
3. Netzwerkanfragen untersuchen: Verwenden Sie die Browser-Entwicklertools, um die tatsaechliche Anfrage und Antwort einzusehen
4. API-Berechtigungen ueberpruefen: Stellen Sie sicher, dass der API-Endpunkt den von Ihnen verwendeten Token-Typ akzeptiert

Beispielimplementierung

Hier ist ein vollstaendiges Beispiel eines Widgets, das beide Token-Typen verwendet:

<div class="authenticated-widget">
  <h2>User Profile</h2>
  <div id="user-data">Loading...</div>

  <button onclick="fetchUserProfile()">Load Profile</button>
  <button onclick="fetchUserResources()">Load Resources</button>

  <script>
    // Using ID Token to get user information async function fetchUserProfile()
    function fetchUserProfile() {
        try {
            const response = await fetch('https://api.example.com/profile', {
                headers: { 'Authorization': 'Bearer {{staffbaseIdToken}}' }
            });
            if (!response.ok) throw new Error('Failed tofetch profile');
            const data = await response.json();
            document.getElementById('user-data').innerHTML = `<p>Name: ${data.name}</p><p>Email: ${data.email}</p>`;
        } catch (error) {
            document.getElementById('user-data').textContent = 'Error: ' + error.message;
        }
    }

    // Using Access Token to get protected resources async
    function fetchUserResources() {
        try {
            const response = await fetch('https://app.staffbase.com/api/users', {
                headers: { 'Authorization': 'Basic {{staffbaseAccessToken}}' }
            });
            if (!response.ok) throw new Error('Failed to fetch resources');
            const data = await response.json();
            document.getElementById('user-data').innerHTML = `<h3>Your Resources</h3><pre>${JSON.stringify(data, null, 2)}</pre>`;
        } catch (error) {
            document.getElementById('user-data').textContent = 'Error: ' + error.message;
        }
    }
  </script>
</div>

Durch das Verstaendnis der Unterschiede zwischen ID- und Access-Tokens und deren jeweiligem Einsatzzweck koennen Sie sichere und leistungsfaehige Custom Widgets erstellen, die sich mit verschiedenen Diensten integrieren und dabei eine ordnungsgemaesse Authentifizierung gewaehrleisten.