Looker API-Authentifizierung mit OAuth

Looker verwendet OAuth, damit sich OAuth-Clientanwendungen bei der Looker API authentifizieren können, ohne Client-IDs und Clientschlüssel für den Browser offenzulegen, in dem die OAuth-Clientanwendung ausgeführt wird.

Webanwendungen, die OAuth verwenden, müssen die folgenden Anforderungen erfüllen:

  • Die Authentifizierung mit OAuth ist nur mit der Looker API 4.0 verfügbar.
  • OAuth-Clientanwendungen müssen zuerst mit der API bei Looker registriert werden, bevor sich Nutzer der Anwendung bei Looker authentifizieren können.
  • Clientanwendungen müssen für alle Anfragen an die Looker API HTTPS verwenden. Clientanwendungen, die die SubtleCrypto APIs verwenden möchten, müssen über HTTPS gehostet werden.

CORS-Unterstützung für die Looker API

Die Looker API kann im Browser und über verschiedene Ursprünge hinweg mit dem Cross-Origin Resource Sharing-Protokoll (CORS) aufgerufen werden. Für die CORS-Unterstützung von Looker gelten die folgenden Anforderungen:

  • Nur Ursprünge, die in der Zulassungsliste für eingebettete Domains aufgeführt sind, können die API mit CORS aufrufen.

  • Nur Zugriffstokens, die von OAuth oder durch Aufrufen des API-Endpunkt /login abgerufen wurden, können verwendet werden, um mit CORS Aufrufe an die Looker API zu senden.

    Der API-Endpunkt /login kann nicht mit CORS-Anfragen aufgerufen werden. Clientanwendungen, die die Looker API mit CORS-Anfragen aufrufen möchten, müssen entweder den in Nutzeranmeldung mit OAuth beschriebenen OAuth-Anmeldeprozess verwenden oder ein Token von ihrem Anwendungsserver oder von nicht-CORS-API-Aufrufen abrufen.

Übersicht über die OAuth-Authentifizierung

Hier eine Übersicht über den OAuth-Authentifizierungsprozess:

  1. Registrieren Sie die OAuth-Clientanwendung bei der Looker API.
  2. Fügen Sie den Ursprung Ihrer OAuth-Clientanwendung der Zulassungsliste für eingebettete Domains für den API-Aufruf zum Codeaustausch und alle nachfolgenden CORS-API-Aufrufe hinzu.
  3. Leiten Sie die Browser-URL an den Endpunkt /auth auf dem Looker-UI-Hostnamen (nicht dem Looker-API-Hostnamen) weiter, wenn die OAuth-Clientanwendung versucht, einen Nutzer zu authentifizieren. Beispiel: https://instance_name.looker.com.
  4. Wenn der Nutzer erfolgreich authentifiziert und in Looker angemeldet wurde, gibt Looker sofort eine OAuth-Weiterleitung an die OAuth-Clientanwendung zurück. Wenn der Nutzer noch nicht auf dem Gerät und im Browser in Looker angemeldet ist, wird der Looker-Anmeldebildschirm angezeigt und der Nutzer wird aufgefordert, sich mit seinem regulären Authentifizierungsprotokoll in seinem Looker-Nutzerkonto anzumelden.
  5. Mit dem im OAuth-Redirect zurückgegebenen Autorisierungscode sollte Ihre OAuth-Clientanwendung als Nächstes einen Aufruf an den Endpunkt /token auf dem Looker-API-Hostnamen senden, z. B. https://instance_name.looker.com:19999. Der API-Hostname kann mit dem Looker-UI-Hostnamen identisch sein oder davon abweichen. Der Endpunkt /token ist nur auf dem Looker-API-Host und der Endpunkt /auth nur auf dem Looker-UI-Host vorhanden.
  6. Wenn der an den Endpunkt /token übergebene Autorisierungscode gültig ist, gibt Looker ein API-access_token zurück, das für CORS-API-Anfragen von der Domain der OAuth-Clientanwendung aktiviert ist.

OAuth-Clientanwendung registrieren

Jede OAuth-Clientanwendung, die versucht, sich mit OAuth bei der Looker API zu authentifizieren, muss zuerst bei der Looker-Instanz registriert werden, bevor Looker den Zugriff autorisiert. So registrieren Sie eine OAuth-Clientanwendung:

  1. Öffnen Sie den API Explorer in Ihrer Looker-Instanz.
  2. Wählen Sie im Drop-down-Menü „Version“ die Version 4.0 – stabil der API aus.

  3. Suchen Sie unter der Methode Auth den API-Endpunkt register_oauth_client_app(). Sie können auch im Feld Suchen nach „OAuth-App“ suchen. Mit register_oauth_client_app() können Sie Ihre OAuth-Clientanwendung bei Looker registrieren. Klicken Sie auf die Schaltfläche Ausführen und geben Sie die Parameter im API Explorer ein. Klicken Sie noch einmal auf Ausführen, um die OAuth-Clientanwendung zu registrieren, oder verwenden Sie den API-Endpunkt register_oauth_client_app() programmatisch. Die erforderlichen Parameter für register_oauth_client_app() sind:

    • client_guid: Eine global eindeutige ID für die Anwendung
    • redirect_uri: Der URI, an den die Anwendung eine OAuth-Weiterleitung mit einem Autorisierungscode erhält
    • display_name: Der Name der Anwendung, der den Nutzern der Anwendung angezeigt wird
    • description: Eine Beschreibung der Anwendung, die Nutzern auf einer Offenlegungs- und Bestätigungsseite angezeigt wird, wenn sie sich zum ersten Mal über die Anwendung anmelden

    Die Werte in den client_guid und redirect_uri Parametern müssen genau mit den Werten übereinstimmen, die die OAuth-Clientanwendung bereitstellt. Andernfalls wird die Authentifizierung verweigert.

Nutzeranmeldung mit OAuth

  1. Leiten Sie den Nutzer zum Endpunkt /auth auf dem UI-Host weiter. Beispiel:

    async function oauth_login() {
  const code_verifier = secure_random(32)
  const code_challenge = await sha256_hash(code_verifier)
  const params = {
    response_type: 'code',
    client_id: '123456',
    redirect_uri: 'https://mywebapp.com:3000/authenticated',
    scope: 'cors_api',
    state: '1235813',
    code_challenge_method: 'S256',
    code_challenge: code_challenge,
  }
  const url = `${base_url}?${new URLSearchParams(params).toString()}` // Replace base_url with your full Looker instance's UI host URL, plus the `/auth` endpoint.
  log(url)

  // Stash the code verifier we created in sessionStorage, which
  // will survive page loads caused by login redirects
  // The code verifier value is needed after the login redirect
  // to redeem the auth_code received for an access_token
  //
  sessionStorage.setItem('code_verifier', code_verifier)

  document.location = url
}

function array_to_hex(array) {
  return Array.from(array).map(b => b.toString(16).padStart(2,'0')).join('')
}

function secure_random(byte_count) {
  const array = new Uint8Array(byte_count);
  crypto.getRandomValues(array);
  return array_to_hex(array)
}

async function sha256_hash(message) {
  const msgUint8 = new TextEncoder().encode(message)
  const hashBuffer = await crypto.subtle.digest('SHA-256', msgUint8)
  return base64.urlEncode(hashBuffer))  // Refers to the implementation of base64.encode stored at https://gist.github.com/jhurliman/1250118
}

    Looker versucht, den Nutzer mit dem Authentifizierungssystem zu authentifizieren, für das die Looker-Instanz konfiguriert ist.

    • Wenn der Nutzer bereits im aktuellen Browser in Looker angemeldet ist (d. h., es ist ein aktiver Anmeldecookie vorhanden), wird er nicht aufgefordert, seine Anmeldedaten einzugeben.
    • Wenn sich dieser Nutzer zum ersten Mal mit dieser OAuth-Clientanwendung anmeldet, zeigt Looker eine Offenlegungs- und Bestätigungsseite an, die der Nutzer bestätigen und akzeptieren muss. Der Text aus dem Parameter description, der bei der Registrierung der Anwendung verwendet wurde, wird angezeigt. Die Beschreibung sollte angeben, was die Anwendung mit dem Looker-Konto des Nutzers tun möchte. Wenn der Nutzer auf Akzeptieren klickt, wird die Seite zur redirect_uri der Anwendung weitergeleitet.
    • Wenn der Nutzer bereits im aktuellen Browser in Looker angemeldet ist und die Offenlegungsseite bereits bestätigt hat, erfolgt die OAuth-Anmeldung sofort und ohne visuelle Unterbrechung.

  2. Die Looker API gibt eine OAuth-Weiterleitung an die OAuth-Clientanwendung zurück. Speichern Sie den im URI-Parameter aufgeführten Autorisierungscode. Hier ein Beispiel für einen OAuth-Weiterleitungs-URI:

    https://mywebapp.com:3000/authenticated?&code=asdfasdfassdf&state=...

    Der Autorisierungscode wird nach &code= im URI angezeigt. In diesem Beispiel ist der Autorisierungscode asdfasdfassdf.

  3. Senden Sie eine Webanfrage an den Endpunkt /token in der Looker API und übergeben Sie den Autorisierungscode und Ihre Anwendungsinformationen. Beispiel:

    async function redeem_auth_code(response_str) {
  const params = new URLSearchParams(response_str)
  const auth_code = params.get('code')

  if (!auth_code) {
    log('ERROR: No authorization code in response')
    return
  }
  log(`auth code received: ${auth_code}`)
  log(`state: ${params.get('state')}`)

  const code_verifier = sessionStorage.getItem('code_verifier')
  if (!code_verifier) {
    log('ERROR: Missing code_verifier in session storage')
    return
  }
  sessionStorage.removeItem('code_verifier')
  const response = await
  fetch('https://mycompany.looker.com:19999/api/token', {  // This is the URL of your Looker instance's API web service
    method: 'POST',
    mode: 'cors',    // This line is required so that the browser will attempt a CORS request.
    body: stringify({
      grant_type: 'authorization_code',
      client_id: '123456',
      redirect_uri: 'https://mywebapp.com:3000/authenticated',
      code: auth_code,
      code_verifier: code_verifier,
    }),
    headers: {
      'x-looker-appid': 'Web App Auth & CORS API Demo', // This header is optional.
      'Content-Type': 'application/json;charset=UTF-8'  // This header is required.
    },
  }).catch((error) => {
    log(`Error: ${error.message}`)
  })

  const info = await response.json()
  log(`/api/token response: ${stringify(info)}`)

  // Store the access_token and other info,
  // which in this example is done in sessionStorage

  const expires_at = new Date(Date.now() + (info.expires_in * 1000))
  info.expires_at = expires_at
  log(`Access token expires at ${expires_at.toLocaleTimeString()} local time.`)
  sessionStorage.setItem('access_info', stringify(info))
  access_info = info
}

    Eine erfolgreiche Antwort stellt der OAuth-Clientanwendung ein API-access_token zur Verfügung. Die Antwort enthält auch ein refresh_token, mit dem Sie später ein neues access_token ohne Nutzerinteraktion abrufen können. Ein refresh_token ist einen Monat lang gültig. Speichern Sie das refresh_token sicher.

    Alle Tokens in diesem System können jederzeit vom Looker-Administrator widerrufen werden.