Webregister

Mit KI erkunden

• In ChatGPT öffnen (öffnet in neuem Tab)
• In Claude öffnen (öffnet in neuem Tab)
• Kopie für LLM
• Als Markdown anzeigen (öffnet in neuem Tab)

Verfügbare Pläne

premium

elite

ultimativer

Webregister ähneln Browser-Tabs, sind jedoch innerhalb von Zoho Books zugänglich. Sie können jede Webseite oder Anwendung, die eine Einbettungs-URL bereitstellt, direkt in Zoho Books öffnen, sodass Ihr Team auf externe Tools zugreifen kann, ohne die Tabs zu wechseln. Sie können außerdem die JWT-Authentifizierung für ein Webregister aktivieren, damit Ihre externe App überprüfen kann, dass Anfragen von Zoho Books für die richtige Organisation und den richtigen Nutzer stammen.

Webregister können je nach Ihren geschäftlichen Anforderungen auf viele Arten verwendet werden.

Ein Webregister erstellen

So erstellen Sie ein neues Webregister:

• Gehen Sie zu Einstellungen.
• Wählen Sie Webregister unter Anpassung.
• Klicken Sie auf + Neues Webregister in der oberen rechten Ecke.
• Geben Sie im Feld Registername einen Namen für das Webregister ein.
• Geben Sie im Feld URL die URL der externen Anwendung ein.
  • Um dynamische Werte wie den Organisationsnamen oder die Kunden-ID in die URL einzufügen, klicken Sie auf Platzhalter einfügen und wählen Sie die benötigten Werte aus.
• Wählen Sie Diese URL gehört zu einer Zoho-App oder -Website, wenn die URL auf ein Zoho-Produkt oder eine Zoho-Website verweist.
• Um zu überprüfen, dass Anfragen an Ihre externe App von Zoho Books für die richtige Organisation und den richtigen Nutzer stammen, aktivieren Sie die JWT-Authentifizierung.
  • Geben Sie einen Geheimschlüssel mit 32 bis 500 Zeichen ein. Zoho Books verwendet diesen Schlüssel, um jedes Token zu signieren, das es an Ihre App sendet. Bewahren Sie ihn ausschließlich auf Ihrem Server auf und fügen Sie ihn nicht in den Frontend-Code ein.
  • Wählen Sie eine Gültigkeitsdauer des Tokens: 10 Minuten, 30 Minuten, 1 Stunde oder 3 Stunden.
• Wählen Sie unter Sichtbarkeit aus, wer dieses Webregister sehen kann:
  • Nur ich: Nur Sie können das Webregister sehen.
  • Nur ausgewählte Nutzer & Rollen: Wählen Sie bestimmte Nutzer und Rollen aus dem angezeigten Dropdown aus.
  • Jeder: Alle Nutzer in Ihrer Organisation können das Webregister sehen.
• Klicken Sie auf Speichern.

Nach dem Speichern wird das Webregister in der linken Seitenleiste unter Webregister angezeigt. Klicken Sie darauf, um Ihre externe App innerhalb von Zoho Books zu öffnen.

Ein Webregister bearbeiten

Sie können ein Webregister bearbeiten, um dessen Namen, URL, JWT-Authentifizierungseinstellungen oder Sichtbarkeit zu aktualisieren. So bearbeiten Sie ein Webregister:

• Gehen Sie zu Einstellungen.
• Wählen Sie Webregister unter Anpassung.
• Klicken Sie auf das Webregister, das Sie bearbeiten möchten, oder fahren Sie mit der Maus darüber, klicken Sie auf das Dropdown-Symbol und wählen Sie Bearbeiten.

• Nehmen Sie die erforderlichen Änderungen vor und klicken Sie auf Speichern.

Ein JWT-Token validieren

Mit der Funktion JWT-Token validieren können Sie ein Token überprüfen, das Ihre App von Zoho Books erhalten hat. Verwenden Sie sie, um die Token-Details zu bestätigen oder Probleme zu diagnostizieren, bevor Sie Änderungen an Ihrem Server vornehmen.

So validieren Sie ein JWT-Token:

• Gehen Sie zu Einstellungen.
• Wählen Sie Webregister unter Anpassung.
• Klicken Sie auf das Webregister, das Sie bearbeiten möchten, oder fahren Sie mit der Maus darüber, klicken Sie auf das Dropdown-Symbol und wählen Sie Bearbeiten.
• Klicken Sie auf JWT-Token validieren in der oberen rechten Ecke der Seite Webregister bearbeiten.
• Fügen Sie Ihr JWT-Token in das Feld JWT-Token ein.
• Klicken Sie auf Überprüfen. Zoho Books überprüft das Token anhand des für dieses Webregister gespeicherten Geheimschlüssels und zeigt eines der folgenden Ergebnisse an:

Ein Webregister als inaktiv markieren

Wenn Sie ein Webregister nicht mehr benötigen, können Sie es als inaktiv markieren, anstatt es zu löschen. Inaktive Webregister werden in der linken Seitenleiste ausgeblendet und können nicht geöffnet werden, können aber bei Bedarf später wieder als aktiv markiert werden.

So markieren Sie ein Webregister als inaktiv:

• Gehen Sie zu Einstellungen.
• Wählen Sie Webregister unter Anpassung.
• Fahren Sie mit der Maus über das Webregister, das Sie als inaktiv markieren möchten, klicken Sie auf das Dropdown-Symbol und wählen Sie Als inaktiv markieren.

Ein Webregister als aktiv markieren

So markieren Sie ein inaktives Webregister als aktiv:

• Gehen Sie zu Einstellungen.
• Wählen Sie Webregister unter Anpassung.
• Fahren Sie mit der Maus über das inaktive Webregister, das Sie als aktiv markieren möchten, klicken Sie auf das Dropdown-Symbol und wählen Sie Als aktiv markieren.

Ein Webregister löschen

Wenn Sie ein Webregister nicht mehr benötigen, können Sie es löschen. Das Löschen eines Webregisters entfernt es dauerhaft aus Zoho Books und kann nicht rückgängig gemacht werden.

So löschen Sie ein Webregister:

• Gehen Sie zu Einstellungen.
• Wählen Sie Webregister unter Anpassung.
• Fahren Sie mit der Maus über das Webregister, das Sie löschen möchten, klicken Sie auf das Dropdown-Symbol und wählen Sie Löschen.

• Klicken Sie im Bestätigungs-Pop-up auf OK.

JWT-Authentifizierung

Webregister können unter Einstellungen für Ihre Organisationsnutzer, unter den Kundenportal-Einstellungen für Ihre Kunden und als Komponenten innerhalb von Erweiterungen erstellt werden, die im Zoho Books Developer Portal entwickelt wurden. Sie können die JWT-Authentifizierung für jedes dieser Webregister aktivieren, damit Ihre externe App überprüfen kann, dass Anfragen von Zoho Books für die richtige Organisation und den richtigen Nutzer stammen. Der Token-Mechanismus ist in allen drei Fällen derselbe.

Wie das Token übermittelt wird

Das JWT-Token wird nicht an die Webregister-URL angehängt. Zoho Books übermittelt es per postMessage vom übergeordneten Zoho Books-Fenster an Ihre App, nachdem diese im iframe geladen wurde.

Wenn ein Nutzer das Webregister öffnet, führt Zoho Books Folgendes aus:

• Lädt die URL Ihrer App im iframe.
• Sendet das JWT-Token mit dem Nachrichtentyp ZOHO_WEBTAB_AUTH_TOKENS an Ihre App.

Ihre App empfängt die Nachricht und leitet das Token zur Validierung an Ihren Server weiter. Ihr Server validiert das Token, bevor Daten angezeigt werden.

Die Nachricht, die Ihre App empfängt:

{
  "type": "ZOHO_WEBTAB_AUTH_TOKENS",
  "jwt_token": "eyJhbGciOiJIUzI1NiJ9..."
}

Wenn eine Sitzung endet, sendet Zoho Books jwt_token: null im selben Nachrichtentyp.

JWT-Payload-Claims

Nachdem Ihr Server die Signatur des Tokens überprüft hat, können Sie die folgenden Claims aus der Payload auslesen:

Token-Einstellungen:

Optionen für die Token-Gültigkeitsdauer:

Was die JWT-Validierung schützt

Die Validierung des JWT-Tokens bestätigt, dass:

• Die Webregister-Anfrage von Zoho Books generiert wurde.
• Das Token mit dem für dieses Webregister konfigurierten Geheimschlüssel signiert wurde.
• Das Token während der Übertragung nicht verändert wurde.
• Das Token nicht abgelaufen ist.
• Die Anfrage zum erwarteten Webregister, zur erwarteten Organisation und zum erwarteten Nutzer gehört.

Vertrauen Sie Platzhalterwerten oder JWT-Claim-Werten erst, nachdem die Signaturprüfung und die Ablaufprüfung erfolgreich waren.

Auf Ihrem Server validieren

Führen Sie diese Prüfungen in dieser Reihenfolge für jedes JWT-Token durch, das Ihr Frontend per postMessage empfängt:

• Lehnen Sie das Token ab, wenn es fehlt oder leer ist.
• Überprüfen Sie die Signatur mit dem Geheimschlüssel Ihres Webregisters und dem Algorithmus HS256.
• Lehnen Sie das Token ab, wenn exp in der Vergangenheit liegt.
• Lehnen Sie das Token ab, wenn token_type nicht access ist.
• Lehnen Sie das Token optional ab, wenn tab_id nicht mit Ihrer Webregister-ID übereinstimmt.
• Verwenden Sie organization_id und user_id erst dann, um Daten zu laden.

Zeigen Sie keine sensiblen Inhalte an, bevor diese Prüfungen erfolgreich waren.

Token-Aktualisierung

JWT-Tokens laufen nach der von Ihnen festgelegten Gültigkeitsdauer ab. Ihre App ruft nicht direkt Zoho-APIs auf, um ein neues Token zu erhalten. Stattdessen sendet sie eine postMessage an das übergeordnete Zoho Books-Fenster, und Zoho Books gibt ein neues Token zurück.

Die Aktualisierungsanfrage, die Ihre App sendet:

{
  "type": "ZOHO_WEBTAB_REQUEST_TOKEN_REFRESH"
}

Regeln:

• Nur die Zoho Books-App ruft die Aktualisierungs-API auf. Rufen Sie keine Zoho-Aktualisierungs-Endpunkte von Ihrem Server aus auf.
• Wenn die Aktualisierung fehlschlägt, bitten Sie den Nutzer, das Webregister neu zu laden.
• Protokollieren Sie keine vollständigen JWT-Tokens oder Ihren Geheimschlüssel.

URL-Platzhalter und Vertrauen

Sie können unterstützte Platzhalter in die Webregister-URL einfügen, indem Sie bei der Konfiguration des Webregisters auf Platzhalter einfügen klicken. Beispiel:

https://yourapp.example.com/entry?customer_id=${CONTACT.CONTACT_ID}

Zoho Books löst die Platzhalter auf, bevor Ihre App geladen wird. Behandeln Sie Platzhalterwerte als nicht vertrauenswürdig, bis das JWT auf Ihrem Server validiert wurde. Ein Angreifer könnte eine URL mit beliebigen Platzhalterwerten erstellen. Lesen Sie organization_id und user_id nur aus der verifizierten JWT-Payload aus.

Sicherheit des Geheimschlüssels

Der Geheimschlüssel wird ausschließlich zwischen Zoho Books und Ihrem Server geteilt.

Speichern Sie den Geheimschlüssel niemals in:

• Frontend-JavaScript
• Mobilen Apps
• Öffentlichen Repositorys
• Protokollen
• Im Browser sichtbaren Antworten
• Clientseitigen Konfigurationsdateien

Server-SDK-Beispiele

Verwenden Sie diese Beispiele, um ein JWT-Token auf Ihrem Server zu validieren. Speichern Sie Ihren Geheimschlüssel in einer Umgebungsvariable. Fügen Sie ihn niemals in den Frontend-Code ein.

Node.js

Abhängigkeit: jsonwebtoken

const jwt = require("jsonwebtoken");

function validateJwtToken(token, secret, expectedTabId) {
  const claims = jwt.verify(token, secret, { algorithms: ["HS256"] });
  if (claims.exp * 1000 < Date.now()) throw new Error("Token expired.");
  if (claims.token_type !== "access") throw new Error("Invalid token type.");
  if (expectedTabId && String(claims.tab_id) !== String(expectedTabId)) {
    throw new Error("Invalid tab.");
  }
  return {
    organization_id: claims.organization_id,
    user_id: claims.user_id,
    tab_id: claims.tab_id,
  };
}

Python

Abhängigkeit: PyJWT

import jwt
import time

def validate_jwt_token(token, secret, expected_tab_id=None):
    claims = jwt.decode(token, secret.encode("utf-8"), algorithms=["HS256"])
    if claims["exp"] < time.time():
        raise ValueError("Token expired.")
    if claims.get("token_type") != "access":
        raise ValueError("Invalid token type.")
    if expected_tab_id and str(claims.get("tab_id")) != str(expected_tab_id):
        raise ValueError("Invalid tab.")
    return {
        "organization_id": claims["organization_id"],
        "user_id": claims["user_id"],
        "tab_id": claims["tab_id"],
    }

Java

Abhängigkeit: io.jsonwebtoken:jjwt

Claims claims = Jwts.parser()
    .setSigningKey(webTabSecret.getBytes(StandardCharsets.UTF_8))
    .parseClaimsJws(token)
    .getBody();

if (claims.getExpiration().before(new Date())) {
    throw new IllegalArgumentException("Token expired.");
}
if (!"access".equals(claims.get("token_type", String.class))) {
    throw new IllegalArgumentException("Invalid token type.");
}
if (expectedTabId != null && !expectedTabId.equals(claims.get("tab_id", String.class))) {
    throw new IllegalArgumentException("Invalid tab.");
}
// Verwenden Sie claims.get("organization_id") und claims.get("user_id")

PHP

Abhängigkeit: firebase/php-jwt

$claims = (array) JWT::decode($token, new Key($webTabSecret, 'HS256'));
if (($claims['exp'] ?? 0) < time()) {
    throw new InvalidArgumentException('Token expired.');
}
if (($claims['token_type'] ?? '') !== 'access') {
    throw new InvalidArgumentException('Invalid token type.');
}
if ($expectedTabId !== null && $expectedTabId !== (string) $claims['tab_id']) {
    throw new InvalidArgumentException('Invalid tab.');
}
// Verwenden Sie $claims['organization_id'] und $claims['user_id']

Go

Abhängigkeit: github.com/golang-jwt/jwt/v5

parsed, err := jwt.ParseWithClaims(token, &webTabClaims{}, func(t *jwt.Token) (interface{}, error) {
    return []byte(webTabSecret), nil
})
claims := parsed.Claims.(*webTabClaims)
if claims.ExpiresAt != nil && !claims.ExpiresAt.After(time.Now()) {
    return nil, ErrExpiredToken
}
if claims.TokenType != "access" {
    return nil, ErrInvalidType
}
if expectedTabID != "" && expectedTabID != claims.TabID {
    return nil, ErrInvalidTabID
}
// Verwenden Sie claims.OrganizationID und claims.UserID

Client-SDK

Ihre App läuft in einem iframe innerhalb von Zoho Books oder dem Kundenportal. Verwenden Sie das Client-SDK, um JWT-Tokens per postMessage zu empfangen und eine Aktualisierung anzufordern, wenn sie ablaufen.

API

Das SDK validiert event.origin anhand von parentOrigin, hält ein einzelnes JWT im Arbeitsspeicher und plant onSessionExpired anhand des exp-Claims des Tokens. Es ruft weder Ihren Server noch Zoho-APIs auf. Ihre App muss das JWT auf dem Server validieren.

Schnellstart

<script type="module">
  import { createWebTabAuthClient } from './zoho-webtab-auth-sdk.js';

  const JWT_VERIFICATION_API_ENDPOINT = '/api/webtab/session'; // Endpunkt: Ihr Endpunkt zur Überprüfung des JWT-Tokens

  const auth = createWebTabAuthClient({
    parentOrigin: 'https://books.zoho.com', // Portal: der Ursprung Ihres Portal-Hosts
    onToken({ jwt_token }) {
      fetch(JWT_VERIFICATION_API_ENDPOINT, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ jwt_token }),
      });
    },
    onSessionExpired() {
      auth.requestRefresh();
    },
  });

  auth.init();
</script>

Wenn Ihre API 401 zurückgibt, rufen Sie auth.requestRefresh() auf. Rufen Sie keine Zoho-Aktualisierungs-Endpunkte von Ihrem Server aus auf.

SDK-Quellcode

const MESSAGE_AUTH_TOKENS = 'ZOHO_WEBTAB_AUTH_TOKENS';
const MESSAGE_REQUEST_REFRESH = 'ZOHO_WEBTAB_REQUEST_TOKEN_REFRESH';

function getTokenExpiryMs(token) {
  try {
    const segment = token.split('.')[1];
    if (!segment) return null;
    const payload = JSON.parse(atob(segment.replace(/-/g, '+').replace(/_/g, '/')));
    if (!payload.exp) return null;
    return payload.exp * 1000;
  } catch {
    return null;
  }
}

export function createWebTabAuthClient(config) {
  const { parentOrigin, onToken, onSessionExpired } = config || {};
  if (!parentOrigin) throw new Error('parentOrigin is required');

  let jwt_token = null;
  let initialized = false;
  let expiryTimerId = null;

  function clearExpiryTimer() {
    if (expiryTimerId) { clearTimeout(expiryTimerId); expiryTimerId = null; }
  }

  function scheduleExpiry(token) {
    clearExpiryTimer();
    const expiresAt = getTokenExpiryMs(token);
    if (!expiresAt) return;
    const delay = expiresAt - Date.now();
    if (delay <= 0) { onSessionExpired?.(); return; }
    expiryTimerId = setTimeout(() => { expiryTimerId = null; onSessionExpired?.(); }, delay);
  }

  function onMessage(event) {
    if (event.origin !== parentOrigin) return;
    const data = event.data;
    if (!data || data.type !== MESSAGE_AUTH_TOKENS) return;
    if (data.jwt_token === null || data.jwt_token === undefined) {
      clearExpiryTimer(); jwt_token = null; onSessionExpired?.(); return;
    }
    jwt_token = data.jwt_token;
    scheduleExpiry(jwt_token);
    onToken?.({ jwt_token });
  }

  function init() {
    if (initialized) return;
    initialized = true;
    window.addEventListener('message', onMessage);
  }

  function destroy() {
    if (!initialized) return;
    initialized = false;
    window.removeEventListener('message', onMessage);
    clearExpiryTimer();
    jwt_token = null;
  }

  function getAccessToken() { return jwt_token; }

  function requestRefresh() {
    window.parent.postMessage({ type: MESSAGE_REQUEST_REFRESH }, parentOrigin);
  }

  return { init, destroy, getAccessToken, requestRefresh };
}

export default createWebTabAuthClient;

if (typeof window !== 'undefined') {
  window.ZohoWebTabAuth = { createWebTabAuthClient };
}

Hat dieses Dokument Ihnen geholfen?

Ja

Nein

Hat dieses Dokument Ihnen geholfen?

Geben Sie Ihre Kommentare oder Rückmeldungen zu dieser Seite ein

Geben Sie Ihre E-Mail-Adresse ein

Aktualisieren

Geben Sie die Zeichen aus dem Bild oben ein

Durch Klicken auf 'Absenden' stimmen Sie unseren Datenschutzrichtlinie .

Absenden Abbrechen

Submit

Submit

Vielen Dank für Ihre Rückmeldung!