Looker API-Authentifizierung mit OAuth

Looker verwendet OAuth, damit sich OAuth-Clientanwendungen bei der Looker API authentifizieren können, ohne dass Client-IDs und Clientschlüssel für den Browser offengelegt werden, 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 über die 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 vom Browser bereitgestellten 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 ursprungsübergreifend über das CORS-Protokoll (Cross-Origin Resource Sharing) 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 über CORS aufrufen.

  Wichtig: Die Richtlinie für den Zugriff auf private Netzwerke (Private Network Access, PNA) des Google Chrome-Browsers blockiert möglicherweise Anfragen für eingebettete Inhalte, da die eingebettete Anfrage als Verbindung zu einem nicht vertrauenswürdigen Netzwerk behandelt werden kann. Sie können dieses Problem beheben, indem Sie eine vorübergehende lokale Problemumgehung für Chrome-Tests bereitstellen. Deaktivieren Sie dazu das Browser-Flag „Local Network Access Check“.

• Nur Zugriffstokens, die über OAuth oder durch Aufrufen des API-Endpunkt /login abgerufen wurden, können für Aufrufe der Looker API über CORS verwendet werden.

  Hinweis: Der API-Endpunkt /login kann nicht über CORS-Anfragen aufgerufen werden. Clientanwendungen, die die Looker API über CORS-Anfragen aufrufen müssen, müssen entweder den unter Nutzeranmeldung mit OAuth durchführen beschriebenen OAuth-Anmeldevorgang verwenden oder ein Token von Ihrem Anwendungsserver oder von Nicht-CORS-API-Aufrufen abrufen.

OAuth-Authentifizierung – Übersicht

Hier finden Sie eine Übersicht über den OAuth-Authentifizierungsprozess:

1. Registrieren Sie die OAuth-Clientanwendung bei Ihrer Looker-Instanz.

2. Fügen Sie den Ursprung Ihrer OAuth-Clientanwendung zur Zulassungsliste für eingebettete Domains für den API-Aufruf zum Codeaustausch und alle nachfolgenden CORS-API-Aufrufe hinzu.

   Wichtig: Die Domain-URL darf keinen abschließenden Schrägstrich (/) enthalten.

3. Leiten Sie die Browser-URL an den Endpunkt /auth auf dem Hostnamen der Looker-Benutzeroberfläche (nicht auf dem Hostnamen der Looker API) weiter, wenn die OAuth-Clientanwendung versucht, einen Benutzer 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 Benutzer auf dem Gerät und im Browser noch nicht bei Looker angemeldet ist, wird der Looker-Anmeldebildschirm angezeigt und der Benutzer wird aufgefordert, sich mit seinem regulären Authentifizierungsprotokoll bei seinem Looker-Benutzerkonto anzumelden.

5. Mit dem Autorisierungscode, der in der OAuth-Weiterleitung zurückgegeben wird, 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 Hostnamen der Looker-Benutzeroberfläche identisch sein oder davon abweichen. Der Endpunkt /token ist nur auf dem Looker API-Host vorhanden und der Endpunkt /auth nur auf dem Looker-UI-Host.

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 über OAuth bei der Looker API zu authentifizieren, muss zuerst bei der Looker-Instanz registriert werden, bevor Looker den Zugriff autorisiert.

Looker-Administratoren können benutzerdefinierte OAuth-Clientanwendungen direkt im Looker-Admin-Bereich auf der Seite OAuth-Clients verwalten (Admin > Authentifizierung > OAuth-Clients verwalten) registrieren und verwalten. Über diese Oberfläche können Administratoren die folgenden Aufgaben ausführen:

• Konfigurieren Sie einen oder mehrere autorisierte Weiterleitungs-URIs für die Anwendung, um mehrere Umgebungen und Ports zu unterstützen.
• Den Autorisierungszugriff auf Mitglieder einer bestimmten Looker-Nutzergruppe beschränken (Auf Gruppen-ID beschränken).
• Registrierte benutzerdefinierte Anwendungen ansehen, bearbeiten, aktivieren, deaktivieren oder löschen.

Eine detaillierte Anleitung zum Registrieren benutzerdefinierter Clients im Admin-Bereich finden Sie auf der Dokumentationsseite Administratoreinstellungen – OAuth-Clients verwalten.

Hinweis: Die in Looker registrierten Werte für die Client-ID und den Weiterleitungs-URI müssen genau mit den Werten übereinstimmen, die Ihre OAuth-Clientanwendung bereitstellt. Andernfalls wird die Authentifizierung abgelehnt.

Programmatische Registrierung über die API

Alternativ können Administratoren eine OAuth-Clientanwendung programmatisch registrieren, indem sie den Endpunkt „OAuth-Anwendung registrieren“ direkt aufrufen oder im Looker API Explorer ausführen. Zu den Parametern gehören:

• client_guid: Eine eindeutige String-ID für die Anwendung (darf nicht mit com.looker. beginnen).
• redirect_uris: Ein Array autorisierter Callback-URIs, an die die Anwendung die OAuth-Weiterleitung und den Autorisierungscode erhält.
• display_name: Der Name der Anwendung, der Nutzern angezeigt wird.
• description: Eine Beschreibung der OAuth-Clientanwendung.
• group_id (optional): Die numerische ID einer Looker-Gruppe, auf die der Zugriff beschränkt werden soll.

Nutzeranmeldung mit OAuth ausführen

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
   }
   

   Tipp: Der vorherige Beispielcode basiert auf SubtleCrypto-APIs, die vom Browser bereitgestellt werden. Der Browser lässt die Verwendung dieser Funktionen jedoch nur auf sicheren (HTTPS-)Webseiten zu.

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

   • Wenn der Benutzer bereits im aktuellen Browser bei Looker angemeldet ist (d. h. es gibt einen aktiven Anmelde-Cookie-Status), wird der Benutzer nicht aufgefordert, seine Anmeldedaten einzugeben.
   • Wenn sich dieser Benutzer zum ersten Mal mit dieser OAuth-Clientanwendung anmeldet, zeigt Looker eine Offenlegungs- und Bestätigungsseite an, die der Benutzer bestätigen und akzeptieren muss. Der Text aus dem Parameter description, der bei der Registrierung der Anwendung verwendet wurde, wird angezeigt. In der Beschreibung sollte angegeben werden, was die Anwendung mit dem Looker-Konto des Benutzers tun soll. Wenn der Nutzer auf Akzeptieren klickt, wird er zur Anwendung redirect_uri weitergeleitet.
   • Wenn der Benutzer im aktuellen Browser bereits bei 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 ist 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 lautet 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
   }
   

   Bei einer erfolgreichen Antwort erhält die OAuth-Clientanwendung ein API-access_token. Die Antwort enthält auch ein refresh_token, mit dem Sie später ohne Nutzerinteraktion ein neues access_token erhalten können. Ein refresh_token hat eine Lebensdauer von einem Monat. Bewahren Sie die refresh_token sicher auf.

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