Einbettung ohne Cookies

Wenn Looker mithilfe von signierter Einbettung in einen iFrame eingebettet wird, verwenden einige Browser standardmäßig eine Cookie-Richtlinie, die Drittanbieter-Cookies blockiert. Drittanbieter-Cookies werden abgelehnt, wenn der eingebettete iFrame von einer Domain geladen wird, die sich von der Domain unterscheidet, die die einbettende Anwendung lädt. Sie können diese Einschränkung in der Regel umgehen, indem Sie eine Vanity-Domain anfordern und verwenden. In einigen Szenarien können Vanity-Domains jedoch nicht verwendet werden. Für diese Szenarien kann die cookielose Einbettung von Looker verwendet werden.

Wie funktioniert die Einbettung ohne Cookies?

Wenn Drittanbieter-Cookies nicht blockiert werden, wird ein Sitzungscookie erstellt, wenn sich ein Nutzer zum ersten Mal bei Looker anmeldet. Dieses Cookie wird mit jeder Nutzeranfrage gesendet und vom Looker-Server verwendet, um die Identität des Nutzers festzustellen, der die Anfrage initiiert hat. Wenn Cookies blockiert sind, wird das Cookie nicht mit einer Anfrage gesendet. Der Looker-Server kann den Nutzer, der mit der Anfrage verknüpft ist, dann nicht identifizieren.

Um dieses Problem zu lösen, werden bei der cookielosen Einbettung von Looker jeder Anfrage Tokens zugeordnet, mit denen die Nutzersitzung auf dem Looker-Server wiederhergestellt werden kann. Es liegt in der Verantwortung der einbettenden Anwendung, diese Tokens abzurufen und der Looker-Instanz zur Verfügung zu stellen, die im eingebetteten iFrame ausgeführt wird. Der Prozess zum Abrufen und Bereitstellen dieser Tokens wird im weiteren Verlauf dieses Dokuments beschrieben.

Damit eine der beiden APIs verwendet werden kann, muss sich die einbettende Anwendung mit Administratorberechtigungen bei der Looker API authentifizieren können. Die Einbettungsdomain muss außerdem entweder in der Zulassungsliste für Einbettungsdomains aufgeführt sein oder, wenn Sie Looker 23.8 oder höher verwenden, kann die Einbettungsdomain beim Abrufen der cookielosen Sitzung angegeben werden.

Looker-Einbettungs-iFrame erstellen

Das folgende Sequenzdiagramm veranschaulicht die Erstellung eines eingebetteten iFrames. Mehrere iFrames können gleichzeitig oder nacheinander generiert werden. Bei korrekter Implementierung wird der iFrame automatisch der Sitzung hinzugefügt, die vom ersten iFrame erstellt wurde. Das Looker Embed SDK vereinfacht diesen Prozess, indem es automatisch der vorhandenen Sitzung beitritt. Richtlinien zur Vermeidung von Konflikten bei gleichzeitigen Anmeldungen beim Laden mehrerer iFrames finden Sie unter Best Practices für das Einbetten mehrerer iFrames mit cookieloser Einbettung.

Ein Sequenzdiagramm, das die Erstellung eines eingebetteten iFrames veranschaulicht.

  1. Der Nutzer führt in der Einbettungsanwendung eine Aktion aus, die zur Erstellung eines Looker-iFrames führt.
  2. Der Client der Einbettungsanwendung ruft eine Looker-Sitzung ab. Das Looker Embed SDK kann verwendet werden, um diese Sitzung zu initiieren. Es muss jedoch eine Endpunkt-URL oder eine Callback-Funktion angegeben werden. Wenn eine Callback-Funktion verwendet wird, ruft sie den Server der einbettenden Anwendung auf, um die Looker-Einbettungssitzung abzurufen. Andernfalls ruft das Embed SDK die angegebene Endpunkt-URL auf.
  3. Der Server der Einbettungsanwendung verwendet die Looker API, um eine Einbettungssitzung zu erhalten. Dieser API-Aufruf ähnelt dem Signaturprozess für die signierte Einbettung von Looker, da er die Definition des eingebetteten Nutzers als Eingabe akzeptiert. Wenn für den aufrufenden Nutzer bereits eine Looker-Einbettungssitzung vorhanden ist, sollte das zugehörige Sitzungsreferenztoken im Aufruf enthalten sein. Dies wird im Abschnitt Sitzung abrufen dieses Dokuments ausführlicher erläutert.
  4. Die Verarbeitung des Endpunkts zum Abrufen der Einbettungssitzung ähnelt der des signierten /login/embed/(signed url)-Endpunkts, da die Definition des Looker-Einbettungsnutzers im Text der Anfrage und nicht in der URL erwartet wird. Der Prozess des Endpunkts zum Abrufen der Einbettungssitzung validiert den Einbettungsnutzer und erstellt oder aktualisiert ihn dann. Es kann auch ein vorhandenes Sitzungsreferenztoken akzeptieren. Das ist wichtig, da so mehrere eingebettete Looker-iFrames dieselbe Sitzung nutzen können. Der eingebettete Nutzer wird nicht aktualisiert, wenn ein Sitzungsreferenztoken angegeben wird und die Sitzung nicht abgelaufen ist. Dies unterstützt den Anwendungsfall, in dem ein iFrame mit einer signierten Einbettungs-URL und andere iFrames ohne signierte Einbettungs-URL erstellt werden. In diesem Fall übernehmen die iFrames ohne signierte Einbettungs-URLs das Cookie aus der ersten Sitzung.
  5. Der Looker API-Aufruf gibt vier Tokens zurück, jeweils mit einer Gültigkeitsdauer (TTL):
    • Autorisierungstoken (TTL = 30 Sekunden)
    • Navigationstoken (TTL = 10 Minuten)
    • API-Token (TTL = 10 Minuten)
    • Sitzungsreferenztoken (TTL = verbleibende Lebensdauer der Sitzung)
  6. Der einbettende Anwendungsserver muss die von den Looker-Daten zurückgegebenen Daten im Auge behalten und sie sowohl dem aufrufenden Benutzer als auch dem Benutzer-Agenten des Browsers des aufrufenden Benutzers zuordnen. Vorschläge dazu finden Sie im Abschnitt Tokens generieren dieses Dokuments. Dieser Aufruf gibt das Autorisierungstoken, ein Navigationstoken und ein API-Token zusammen mit allen zugehörigen TTLs zurück. Das Sitzungsreferenztoken sollte geschützt und nicht im aufrufenden Browser angezeigt werden.

  7. Nachdem die Tokens an den Browser zurückgegeben wurden, muss eine Looker-URL für die eingebettete Anmeldung erstellt werden. Das Looker Embed SDK erstellt die Einbettungs-Log-in-URL automatisch. Wenn Sie die windows.postMessage API verwenden möchten, um die Log-in-URL für die Einbettung zu erstellen, finden Sie im Abschnitt Looker windows.postMessage API verwenden dieses Dokuments Beispiele.

    Die Log-in-URL enthält nicht die Details des signierten eingebetteten Nutzers. Sie enthält die Ziel-URI, einschließlich des Navigations-Tokens, und das Autorisierungs-Token als Suchparameter. Das Autorisierungstoken muss innerhalb von 30 Sekunden verwendet werden und kann nur einmal verwendet werden. Wenn zusätzliche iFrames erforderlich sind, muss eine neue Einbettungssitzung gestartet werden. Wenn jedoch das Sitzungsreferenztoken angegeben wird, wird das Autorisierungstoken mit derselben Sitzung verknüpft.

  8. Der Looker-Anmeldeendpunkt für die Einbettung bestimmt, ob die Anmeldung für die cookielose Einbettung erfolgt. Dies wird durch das Vorhandensein des Autorisierungstokens angezeigt. Wenn das Autorisierungstoken gültig ist, wird Folgendes geprüft:

    • Die zugehörige Sitzung ist noch gültig.
    • Der zugehörige eingebettete Nutzer ist weiterhin gültig.
    • Der Browser-User-Agent, der mit der Anfrage verknüpft ist, stimmt mit dem Browser-Agenten überein, der mit der Sitzung verknüpft ist.

  9. Wenn die Prüfungen aus dem vorherigen Schritt erfolgreich sind, wird die Anfrage mithilfe des Ziel-URI in der URL weitergeleitet. Dies ist derselbe Prozess wie für die Anmeldung mit signierter Einbettung in Looker.

  10. Diese Anfrage ist die Weiterleitung zum Starten des Looker-Dashboards. Diese Anfrage enthält das Navigationstoken als Parameter.

  11. Bevor der Endpunkt ausgeführt wird, sucht der Looker-Server in der Anfrage nach dem Navigationstoken. Wenn der Server das Token findet, prüft er Folgendes:

    • Die zugehörige Sitzung ist noch gültig.
    • Der Browser-User-Agent, der mit der Anfrage verknüpft ist, stimmt mit dem Browser-Agenten überein, der mit der Sitzung verknüpft ist.

    Wenn sie gültig ist, wird die Sitzung für die Anfrage wiederhergestellt und die Dashboard-Anfrage wird ausgeführt.

  12. Der HTML-Code zum Laden des Dashboards wird an den iFrame zurückgegeben.

  13. Die Looker-Benutzeroberfläche, die im iFrame ausgeführt wird, erkennt, dass es sich beim Dashboard-HTML um eine cookielose Einbettungsantwort handelt. An diesem Punkt sendet die Looker-Benutzeroberfläche eine Nachricht an die Einbettungsanwendung, um die in Schritt 6 abgerufenen Tokens anzufordern. Die Benutzeroberfläche wartet dann, bis sie die Tokens empfängt. Wenn die Tokens nicht ankommen, wird eine Meldung angezeigt.

  14. Die einbettende Anwendung sendet die Tokens an den eingebetteten Looker-iFrame.

  15. Wenn die Tokens empfangen werden, startet die im iFrame ausgeführte Looker-Benutzeroberfläche den Prozess zum Rendern des Anfrageobjekts. Während dieses Vorgangs führt die Benutzeroberfläche API-Aufrufe an den Looker-Server aus. Das in Schritt 15 empfangene API-Token wird automatisch als Header in alle API-Anfragen eingefügt.

  16. Bevor ein Endpunkt ausgeführt wird, sucht der Looker-Server in der Anfrage nach dem API-Token. Wenn der Server das Token findet, prüft er Folgendes:

    • Die zugehörige Sitzung ist noch gültig.
    • Der Browser-User-Agent, der mit der Anfrage verknüpft ist, stimmt mit dem Browser-Agenten überein, der mit der Sitzung verknüpft ist.

    Wenn die Sitzung gültig ist, wird sie für die Anfrage wiederhergestellt und die API-Anfrage wird ausgeführt.

  17. Die Dashboard-Daten werden zurückgegeben.

  18. Das Dashboard wird gerendert.

  19. Der Nutzer hat die Kontrolle über das Dashboard.

Neue Tokens werden generiert

Das folgende Sequenzdiagramm veranschaulicht die Generierung neuer Tokens.

Ein Sequenzdiagramm, das die Generierung neuer Tokens veranschaulicht.

  1. Die Looker-Benutzeroberfläche, die im eingebetteten iFrame ausgeführt wird, überwacht die TTL der Einbettungstokens.
  2. Wenn die Tokens bald ablaufen, sendet die Looker-Benutzeroberfläche eine Nachricht mit einem Aktualisierungstoken an den Client der Einbettungsanwendung.
  3. Der Client der einbettenden Anwendung fordert dann neue Tokens von einem Endpunkt an, der auf dem Server der einbettenden Anwendung implementiert ist. Das Looker Embed SDK fordert automatisch neue Tokens an. Sie müssen jedoch die Endpunkt-URL oder eine Callback-Funktion angeben. Wenn die Callback-Funktion verwendet wird, ruft sie den Server der einbettenden Anwendung auf, um neue Tokens zu generieren. Andernfalls ruft das Embed SDK die angegebene Endpunkt-URL auf.
  4. Die einbettende Anwendung sucht nach dem session_reference_token, der mit der Einbettungssitzung verknüpft ist. Im Beispiel im Git-Repository für das Looker Embed SDK werden Sitzungscookies verwendet. Es kann aber auch ein verteilter serverseitiger Cache wie Redis verwendet werden.
  5. Der Anwendungsserver, auf dem die Einbettung erfolgt, sendet eine Anfrage an den Looker-Server, um Tokens zu generieren. Für diese Anfrage sind außerdem aktuelle API- und Navigations-Tokens sowie der User-Agent des Browsers erforderlich, der die Anfrage initiiert hat.
  6. Der Looker-Server validiert den User-Agent, das Sitzungsreferenz-Token, das Navigations-Token und das API-Token. Wenn die Anfrage gültig ist, werden neue Tokens generiert.
  7. Die Tokens werden an den aufrufenden Einbettungsanwendungsserver zurückgegeben.
  8. Der Server der Einbettungsanwendung entfernt das Sitzungsreferenztoken aus der Antwort und gibt die verbleibende Antwort an den Client der Einbettungsanwendung zurück.
  9. Der Client der Einbettungsanwendung sendet die neu generierten Tokens an die Looker-Benutzeroberfläche. Das Looker Embed SDK übernimmt dies automatisch. Anwendungsclients, die die windows.postMessage API verwenden, sind für das Senden der Tokens verantwortlich. Sobald die Looker-Benutzeroberfläche die Tokens empfängt, werden sie in nachfolgenden API-Aufrufen und Seitennavigationen verwendet.

Looker-Einbettung ohne Cookies implementieren

Die cookielose Einbettung von Looker kann entweder mit dem Looker Embed SDK oder der windows.postMessage API implementiert werden. Sie können die Methode Looker Embed SDK verwenden. Es ist aber auch ein Beispiel für die Verwendung der windows.postMessage API verfügbar. Detaillierte Erläuterungen zu beiden Implementierungen finden Sie in der README-Datei zum Looker Embed SDK. Das Git-Repository für das Embed SDK enthält ebenfalls funktionierende Implementierungen.

Looker-Instanz konfigurieren

Die cookielose Einbettung hat ähnliche Merkmale wie die signierte Einbettung von Looker.

Vorbereitung

Damit die Einbettung ohne Cookies verwendet und die API-Endpunkte für die Einbettung ohne Cookies verfügbar gemacht werden können, muss ein Looker-Administrator die folgenden Anforderungen im Looker-Admin-Bereich prüfen und aktivieren:

  • SSO-Authentifizierung einbetten: Aktivieren Sie im Bereich Admin > Plattform > Einbetten die Option SSO-Authentifizierung einbetten. Die cookielose Einbettung basiert auf der zugrunde liegenden Funktion SSO-Authentifizierung einbetten als grundlegende Einstellung.
  • Dauerhafte Sitzungen: Aktivieren Sie im Bereich Admin > Authentifizierung > Sitzungen die Option Dauerhafte Sitzungen.
  • API-Nutzerberechtigungen: Die API-Anmeldedaten, die zum Abrufen des Tokens verwendet werden, müssen zu einem Looker-Nutzer mit der Rolle Admin oder einer benutzerdefinierten Rolle mit der Berechtigung manage_embed_settings gehören.

JSON Web Token-Secret konfigurieren

Im Gegensatz zur signierten Einbettung von Looker wird bei der cookielosen Einbettung die Einstellung Embed Secret nicht verwendet. Bei der cookielosen Einbettung wird ein JSON Web Token (JWT) in Form der Einstellung JWT-Secret einbetten verwendet. Diese Einstellung kann auf der Seite Einbetten im Abschnitt Plattform des Menüs Admin festgelegt oder zurückgesetzt werden.

Das Festlegen des JWT-Secrets ist nicht erforderlich, da das JWT beim ersten Versuch, eine cookielose Einbettungssitzung zu erstellen, erstellt wird. Vermeiden Sie es, dieses Token zurückzusetzen, da dadurch alle aktiven cookielosen Einbettungssitzungen ungültig werden.

Im Gegensatz zum Einbettungs-Secret wird das Einbettungs-JWT-Secret nie offengelegt, da es nur intern auf dem Looker-Server verwendet wird.

Anwendungsclient-Implementierung

In diesem Abschnitt finden Sie Beispiele für die Implementierung der cookielosen Einbettung im Anwendungsclient. Er enthält die folgenden Unterabschnitte:

Looker Embed SDK installieren oder aktualisieren

Die folgenden Looker SDK-Versionen sind für die cookielose Einbettung erforderlich:

@looker/embed-sdk >= 2.0.0
@looker/sdk >= 22.16.0

Looker Embed SDK verwenden

Dem Embed SDK wurde eine neue Initialisierungsmethode hinzugefügt, um die cookielose Sitzung zu starten. Diese Methode akzeptiert entweder zwei URL-Strings oder zwei Callback-Funktionen. Die URL-Strings sollten auf Endpunkte im einbettenden Anwendungsserver verweisen. Details zur Implementierung dieser Endpunkte auf dem Anwendungsserver finden Sie im Abschnitt Anwendungsserver-Implementierung dieses Dokuments.

getEmbedSDK().initCookieless(
  runtimeConfig.lookerHost,
  '/acquire-embed-session',
  '/generate-embed-tokens'
)

Das folgende Beispiel zeigt, wie Callbacks verwendet werden. Callbacks sollten nur verwendet werden, wenn es für die einbettende Clientanwendung erforderlich ist, den Status der Looker-Einbettungssitzung zu kennen. Sie können auch das Ereignis session:status verwenden, sodass keine Callbacks mit dem Embed SDK erforderlich sind.

const acquireEmbedSessionCallback =
  async (): Promise<LookerEmbedCookielessSessionData> => {
    const resp = await fetch('/acquire-embed-session')
    if (!resp.ok) {
      console.error('acquire-embed-session failed', { resp })
      throw new Error(
        `acquire-embed-session failed: ${resp.status} ${resp.statusText}`
      )
    }
    return (await resp.json()) as LookerEmbedCookielessSessionData
  }

const generateEmbedTokensCallback =
  async ({ api_token, navigation_token }): Promise<LookerEmbedCookielessSessionData> => {
    const resp = await fetch('/generate-embed-tokens', {
      method: 'PUT',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ api_token, navigation_token }),
    })
    if (!resp.ok) {
      console.error('generate-embed-tokens failed', { resp })
      throw new Error(
        `generate-embed-tokens failed: ${resp.status} ${resp.statusText}`
      )
    }
    return (await resp.json()) as LookerEmbedCookielessSessionData
  }

getEmbedSDK().initCookieless(
  runtimeConfig.lookerHost,
  acquireEmbedSessionCallback,
  generateEmbedTokensCallback
)

Looker windows.postMessage API verwenden

Ein detailliertes Beispiel für die Verwendung der windows.postMessage API finden Sie in den Dateien message_example.ts und message_utils.ts im Git-Repository des Embed SDK. Hier sind die wichtigsten Punkte des Beispiels aufgeführt.

Das folgende Beispiel zeigt, wie die URL für den iFrame erstellt wird. Die Callback-Funktion ist mit der im vorherigen acquireEmbedSessionCallback-Beispiel identisch.

  private async getCookielessLoginUrl(): Promise<string> {
    const { authentication_token, navigation_token } =
      await this.embedEnvironment.acquireSession()
    const url = this.embedUrl.startsWith('/embed')
      ? this.embedUrl
      : `/embed${this.embedUrl}`
    const embedUrl = new URL(url, this.frameOrigin)
    if (!embedUrl.searchParams.has('embed_domain')) {
      embedUrl.searchParams.set('embed_domain', window.location.origin)
    }
    embedUrl.searchParams.set('embed_navigation_token', navigation_token)
    const targetUri = encodeURIComponent(
      `${embedUrl.pathname}${embedUrl.search}${embedUrl.hash}`
    )
    return `${embedUrl.origin}/login/embed/${targetUri}?embed_authentication_token=${authentication_token}`
  }

Im folgenden Beispiel wird gezeigt, wie Sie auf Tokenanfragen warten, neue Tokens generieren und an Looker senden. Die Callback-Funktion ist mit der im vorherigen generateEmbedTokensCallback-Beispiel identisch.

      this.on(
        'session:tokens:request',
        this.sessionTokensRequestHandler.bind(this)
      )

  private connected = false

  private async sessionTokensRequestHandler(_data: any) {
    const contentWindow = this.getContentWindow()
    if (contentWindow) {
      if (!this.connected) {
        // When not connected the newly acquired tokens can be used.
        const sessionTokens = this.embedEnvironment.applicationTokens
        if (sessionTokens) {
          this.connected = true
          this.send('session:tokens', this.embedEnvironment.applicationTokens)
        }
      } else {
        // If connected, the embedded Looker application has decided that
        // it needs new tokens. Generate new tokens.
        const sessionTokens = await this.embedEnvironment.generateTokens()
        this.send('session:tokens', sessionTokens)
      }
    }
  }

  send(messageType: string, data: any = {}) {
    const contentWindow = this.getContentWindow()
    if (contentWindow) {
      const message: any = {
        type: messageType,
        ...data,
      }
      contentWindow.postMessage(JSON.stringify(message), this.frameOrigin)
    }
    return this
  }

Anwendungsserver-Implementierung

In diesem Abschnitt finden Sie Beispiele für die Implementierung der cookielosen Einbettung auf dem Anwendungsserver. Er enthält die folgenden Unterabschnitte:

Einfache Implementierung

Die einbettende Anwendung muss zwei serverseitige Endpunkte implementieren, die Looker-Endpunkte aufrufen. So wird sichergestellt, dass das Sitzungsreferenztoken sicher bleibt. Dies sind die Endpunkte:

  1. Sitzung abrufen: Wenn bereits ein Sitzungsreferenztoken vorhanden und noch aktiv ist, werden Anfragen für eine Sitzung der vorhandenen Sitzung hinzugefügt. „Sitzung abrufen“ wird aufgerufen, wenn ein iFrame erstellt wird.
  2. Tokens generieren: Looker löst regelmäßig Aufrufe an diesen Endpunkt aus.

Sitzung erfassen

In diesem TypeScript-Beispiel wird die Sitzung verwendet, um das Sitzungsreferenztoken zu speichern oder wiederherzustellen. Der Endpunkt muss nicht in TypeScript implementiert werden.

  app.get(
    '/acquire-embed-session',
    async function (req: Request, res: Response) {
      try {
        const current_session_reference_token =
          req.session && req.session.session_reference_token
        const response = await acquireEmbedSession(
          req.headers['user-agent']!,
          user,
          current_session_reference_token
        )
        const {
          authentication_token,
          authentication_token_ttl,
          navigation_token,
          navigation_token_ttl,
          session_reference_token,
          session_reference_token_ttl,
          api_token,
          api_token_ttl,
        } = response
        req.session!.session_reference_token = session_reference_token
        res.json({
          api_token,
          api_token_ttl,
          authentication_token,
          authentication_token_ttl,
          navigation_token,
          navigation_token_ttl,
          session_reference_token_ttl,
        })
      } catch (err: any) {
        res.status(400).send({ message: err.message })
      }
    }
  )

async function acquireEmbedSession(
  userAgent: string,
  user: LookerEmbedUser,
  session_reference_token: string
) {
  await acquireLookerSession()
    try {
    const request = {
      ...user,
      session_reference_token: session_reference_token,
    }
    const sdk = new Looker40SDK(lookerSession)
    const response = await sdk.ok(
      sdk.acquire_embed_cookieless_session(request, {
        headers: {
          'User-Agent': userAgent,
        },
      })
    )
    return response
  } catch (error) {
    console.error('embed session acquire failed', { error })
    throw error
  }
}

Ab Looker 23.8 kann die Einbettungsdomain beim Abrufen der cookielosen Sitzung angegeben werden. Dies ist eine Alternative zum Hinzufügen der Einbettungsdomain über den Bereich Verwaltung > Einbetten in Looker. Looker speichert die Einbettungsdomain in der internen Looker-Datenbank, sodass sie nicht im Bereich Verwaltung > Einbetten angezeigt wird. Stattdessen wird die eingebettete Domain mit der cookielosen Sitzung verknüpft und existiert nur für die Dauer der Sitzung. Wenn Sie diese Funktion nutzen möchten, lesen Sie die Best Practices für die Sicherheit.

Tokens generieren

In diesem TypeScript-Beispiel wird die Sitzung verwendet, um das Sitzungsreferenztoken zu speichern oder wiederherzustellen. Der Endpunkt muss nicht in TypeScript implementiert werden.

Es ist wichtig, dass Sie wissen, wie Sie mit 400-Antworten umgehen, die auftreten, wenn Tokens ungültig sind. Eine 400-Antwort sollte zwar nicht zurückgegeben werden, aber wenn dies der Fall ist, empfiehlt es sich, die Looker-Einbettungssitzung zu beenden. Sie können die eingebettete Looker-Sitzung beenden, indem Sie entweder den eingebetteten iFrame löschen oder den Wert session_reference_token_ttl in der session:tokens-Nachricht auf null setzen. Wenn Sie den Wert session_reference_token_ttl auf null setzen, wird im Looker-Iframe ein Dialogfeld angezeigt, das darauf hinweist, dass die Sitzung abgelaufen ist.

Wenn die Einbettungssitzung abläuft, wird keine 400-Antwort zurückgegeben. Wenn die Einbettungssitzung abgelaufen ist, wird eine 200-Antwort zurückgegeben, wobei der Wert session_reference_token_ttl auf null gesetzt ist.

  app.put(
    '/generate-embed-tokens',
    async function (req: Request, res: Response) {
      try {
        const session_reference_token = req.session!.session_reference_token
        const { api_token, navigation_token } = req.body as any
        const tokens = await generateEmbedTokens(
          req.headers['user-agent']!,
          session_reference_token,
          api_token,
          navigation_token
        )
        res.json(tokens)
      } catch (err: any) {
        res.status(400).send({ message: err.message })
      }
    }
  )
}
async function generateEmbedTokens(
  userAgent: string,
  session_reference_token: string,
  api_token: string,
  navigation_token: string
) {
  if (!session_reference_token) {
    console.error('embed session generate tokens failed')
    // missing session reference  treat as expired session
    return {
      session_reference_token_ttl: 0,
    }
  }
  await acquireLookerSession()
  try {
    const sdk = new Looker40SDK(lookerSession)
    const response = await sdk.ok(
      sdk.generate_tokens_for_cookieless_session(
        {
          api_token,
          navigation_token,
          session_reference_token: session_reference_token || '',
        },
        {
          headers: {
            'User-Agent': userAgent,
          },
        }
      )
    )
    return {
      api_token: response.api_token,
      api_token_ttl: response.api_token_ttl,
      navigation_token: response.navigation_token,
      navigation_token_ttl: response.navigation_token_ttl,
      session_reference_token_ttl: response.session_reference_token_ttl,
    }
  } catch (error: any) {
    if (error.message?.includes('Invalid input tokens provided')) {
      // The Looker UI does not know how to handle bad
      // tokens. This shouldn't happen but if it does expire the
      // session. If the token is bad there is not much that that
      // the Looker UI can do.
      return {
        session_reference_token_ttl: 0,
      }
    }
    console.error('embed session generate tokens failed', { error })
    throw error
  }

Hinweise zur Implementierung

Die einbettende Anwendung muss das Sitzungsreferenztoken im Auge behalten und sicher aufbewahren. Dieses Token sollte mit dem Nutzer der eingebetteten Anwendung verknüpft sein. Das Token der Einbettungsanwendung kann auf eine der folgenden Arten gespeichert werden:

  • In der Sitzung des Nutzers der eingebetteten Anwendung
  • In einem serverseitigen Cache, der in einer Clusterumgebung verfügbar ist
  • In einer Datenbanktabelle, die dem Nutzer zugeordnet ist

Wenn die Sitzung als Cookie gespeichert wird, sollte das Cookie verschlüsselt werden. Im Beispiel im Repository des Einbettungs-SDK wird ein Sitzungscookie verwendet, um das Sitzungsreferenztoken zu speichern.

Wenn die Looker-Einbettungssitzung abläuft, wird im eingebetteten iFrame ein Dialogfeld angezeigt. An diesem Punkt kann der Nutzer in der eingebetteten Instanz nichts mehr tun. In diesem Fall werden die session:status-Ereignisse generiert, sodass die einbettende Anwendung den aktuellen Status der eingebetteten Looker-Anwendung erkennen und entsprechende Maßnahmen ergreifen kann.

Eine Einbettungsanwendung kann erkennen, ob die Einbettungssitzung abgelaufen ist, indem sie prüft, ob der vom generate_tokens-Endpunkt zurückgegebene session_reference_token_ttl-Wert null ist. Wenn der Wert null ist, ist die Einbettungssitzung abgelaufen. Sie können eine Callback-Funktion verwenden, um Tokens zu generieren, wenn die cookielose Einbettung initialisiert wird. Die Callback-Funktion kann dann feststellen, ob die Einbettungssitzung abgelaufen ist, und den eingebetteten iFrame zerstören, anstatt das Standarddialogfeld für abgelaufene Einbettungssitzungen zu verwenden.

Best Practices für das Einbetten mehrerer iFrames mit cookieloser Einbettung

Wenn Sie mehrere Looker-iFrames auf einer einzelnen Seite in einer cookielosen Einbettung einbetten, benötigt jeder iFrame ein eigenes Einmal-authentication_token von acquire_embed_cookieless_session. Alle iFrames auf der Seite müssen jedoch ein einzelnes session_reference_token gemeinsam nutzen. Beachten Sie die folgenden Best Practices, wenn Sie mehrere iFrames mit cookieloser Einbettung einbetten:

  • Sitzung einmal abrufen und session_reference_token wiederverwenden: Rufen Sie die cookielose Sitzung zuerst einmal ab, speichern Sie die zurückgegebene session_reference_token im Cache Ihres Backend-Servers und übergeben Sie diese session_reference_token in nachfolgenden acquire_embed_cookieless_session-Aufrufen für zusätzliche iFrames. Looker hängt dann jeden neuen iFrame an die vorhandene Sitzung an und überspringt die Aktualisierung des eingebetteten Nutzers.

  • Parallele Erfassung der ersten Sitzung vermeiden: Wenn mehrere iFrames gleichzeitig bereitgestellt werden und Ihr Backend acquire_embed_cookieless_session parallel aufruft, ohne eine vorhandene session_reference_token zu übergeben, behandelt Looker jede Anfrage als neue Anmeldung, aktualisiert den eingebetteten Nutzer gleichzeitig und erstellt separate Sitzungen. Gleichzeitige Anmeldeanfragen für denselben eingebetteten Nutzer können zu Sperrkonflikten auf dem Looker-Server führen. Außerdem wird durch das Überschreiben des gespeicherten session_reference_token mit der letzten Antwort die Tokenaktualisierung (generate_tokens_for_cookieless_session) für die früheren iFrames mit einem 400 Invalid input tokens provided-Fehler unterbrochen.

  • Iframe vorab laden und In-Frame-Navigation verwenden: Um die eingebettete Nutzersitzung vor dem Laden von Inhalten einzurichten, laden Sie einen Iframe vorab mit /embed/preload (oder der Methode .preload() im Embed SDK v2). Wenn Sie das Embed SDK v2 verwenden, können Sie auch innerhalb eines vorhandenen iFrames navigieren, indem Sie Methoden wie connection.loadDashboard(DASHBOARD_ID) oder connection.loadUrl(EMBED_URL) verwenden, anstatt zusätzliche iFrames zu erstellen. Weitere Informationen finden Sie unter Einführung in das Embed SDK.

Beispiel für die cookielose Einbettung von Looker ausführen

Das Repository des Einbettungs-SDK enthält einen Node-Express-Server und einen in TypeScript geschriebenen Client, der eine Einbettungsanwendung implementiert. Die zuvor gezeigten Beispiele stammen aus dieser Implementierung. Im Folgenden wird davon ausgegangen, dass Ihre Looker-Instanz wie oben beschrieben für die cookielose Einbettung konfiguriert wurde.

So führen Sie den Server aus:

  1. Klonen Sie das Embed SDK-Repository: git clone git@github.com:looker-open-source/embed-sdk.git
  2. Verzeichnis ändern – cd embed-sdk
  3. Abhängigkeiten installieren – npm install
  4. Konfigurieren Sie den Server wie im Abschnitt Server konfigurieren dieses Dokuments beschrieben.
  5. Server ausführen – npm run server

Server konfigurieren

Erstellen Sie im Stammverzeichnis des geklonten Repositorys eine .env-Datei. Diese ist in .gitignore enthalten.

Das Format dafür ist:

LOOKER_WEB_URL=your-looker-instance-url.com
LOOKER_API_URL=https://your-looker-instance-url.com
LOOKER_DEMO_HOST=localhost
LOOKER_DEMO_PORT=8080
LOOKER_EMBED_SECRET=embed-secret-from-embed-admin-page
LOOKER_CLIENT_ID=client-id-from-user-admin-page
LOOKER_CLIENT_SECRET=client-secret-from-user-admin-page
LOOKER_DASHBOARD_ID=id-of-dashboard
LOOKER_LOOK_ID=id-of-look
LOOKER_EXPLORE_ID=id-of-explore
LOOKER_EXTENSION_ID=id-of-extension
LOOKER_VERIFY_SSL=true
LOOKER_REPORT_ID=id-of-report
LOOKER_QUERY_VISUALIZATION_ID=id-of-query-visualization

Wenn Sie die cookielose Einbettung von Looker verwenden, kann es beim Versuch, Links in einem neuen Browsertab oder -fenster zu öffnen (z. B. Dashboard-Drills, Explores oder Dokumentdownloads), zu einem HTTP 401 Unauthorized-Fehler kommen oder die Nutzer werden zur Looker-Anmeldeseite weitergeleitet. Dieses Problem tritt am häufigsten auf, wenn Drittanbieter-Cookies im Browser deaktiviert sind.

Ursache

Um Sicherheitslücken durch Session-Hijacking zu verhindern, wurde ein Sicherheitspatch für Looker (Versionen 25.18.61+, 25.20.44+ und 26.0.22+) eingeführt, der absichtlich verhindert, dass Sitzungscookies in der ersten cookielosen Einbettungsantwort zurückgegeben werden. Da der Browser dieses Sitzungscookie nicht mehr empfängt, geht beim Öffnen einer Looker-URL in einem neuen Tab oder Fenster der Authentifizierungskontext verloren, was dazu führt, dass die Anfrage fehlschlägt.

Lösung und Problemumgehungen

  • Looker aktualisieren: Aktualisieren Sie die Looker-Instanz auf Version 26.0.36 oder höher. In diesem Release wird ein Fix eingeführt, der URLs, die während einer cookielosen Einbettungssitzung in einem neuen Fenster geöffnet werden, auf sichere Weise ein Einmaltoken hinzufügt. Dadurch können Nutzer wieder sichere Links in neuen Tabs öffnen.
  • Links im selben iFrame öffnen: Wenn ein Upgrade nicht sofort möglich ist, konfigurieren Sie alle Links in den eingebetteten Dashboards so, dass sie im selben iFrame geöffnet werden. Legen Sie dazu die Linkziele auf _self fest (z. B. target="_self").
  • Über die gehostete Anwendung weiterleiten: Wenn das Öffnen in einem neuen Tab oder Fenster unbedingt erforderlich ist, leiten Sie den Link auf eine neue Seite in Ihrer gehosteten Anwendung weiter, die einen neuen cookielosen eingebetteten iFrame initialisiert, anstatt direkt auf die Looker-Instanz zu verlinken.
  • Signierte Einbettung mit einer benutzerdefinierten Domain verwenden: Alternativ können Sie die standardmäßige signierte Einbettung mit einer benutzerdefinierten Domain verwenden.