Autenticazione dell'API Looker tramite OAuth

Looker utilizza OAuth per consentire alle applicazioni client OAuth di autenticarsi nell'API Looker senza esporre gli ID client e i client secret al browser che esegue l'applicazione client OAuth.

Le applicazioni web che utilizzano OAuth devono soddisfare i seguenti requisiti:

• L'autenticazione tramite OAuth è disponibile solo con l'API Looker 4.0.
• Le applicazioni client OAuth devono prima essere registrate con Looker utilizzando l'API prima che gli utenti dell'applicazione possano autenticarsi in Looker.
• Le applicazioni client devono utilizzare HTTPS per tutte le richieste all'API Looker. Le applicazioni client che vogliono utilizzare le API SubtleCrypto fornite dal browser devono essere ospitate su HTTPS.

Supporto CORS dell'API Looker

L'API Looker supporta le chiamate nel browser e tra origini utilizzando il protocollo Cross-Origin Resource Sharing (CORS). Il supporto di CORS di Looker prevede i seguenti requisiti:

• Solo le origini elencate nella lista consentita dei domini incorporati possono chiamare l'API utilizzando CORS.

  Importante: la policy di accesso alla rete privata (PNA) del browser Google Chrome potrebbe bloccare le richieste di contenuti incorporati, in quanto può trattare la richiesta incorporata come una connessione a una rete non attendibile. Per risolvere il problema, puoi fornire una soluzione alternativa locale temporanea per i test di Chrome disattivando il flag del browser Local Network Access Check.

• Solo i token di accesso ottenuti da OAuth o dalla chiamata all'endpoint API /login possono essere utilizzati per effettuare chiamate all'API Looker utilizzando CORS.

  Nota: l'endpoint API /login non può essere chiamato utilizzando richieste CORS. Le applicazioni client che devono chiamare l'API Looker utilizzando richieste CORS devono utilizzare la procedura di accesso OAuth descritta in Esecuzione dell'accesso utente utilizzando OAuth o recuperare un token dal server dell'applicazione o da chiamate API non CORS.

Panoramica dell'autenticazione OAuth

Di seguito è riportata una panoramica della procedura di autenticazione OAuth:

1. Registra l'applicazione client OAuth con la tua istanza di Looker.

2. Aggiungi l'origine della tua applicazione client OAuth alla lista consentita dei domini incorporati per la chiamata API di scambio di codice e per tutte le chiamate API CORS successive.

   Importante: non includere una barra finale (/) nell'URL del dominio.

3. Reindirizza l'URL del browser all'endpoint /auth sul nome host della UI di Looker (non sul nome host dell'API Looker) quando l'applicazione client OAuth tenta di autenticare un utente. Ad esempio, https://instance_name.looker.com.

4. Se l'utente viene autenticato e accede correttamente a Looker, Looker restituisce immediatamente un reindirizzamento OAuth all'applicazione client OAuth. Se l'utente non ha ancora eseguito l'accesso a Looker sul dispositivo e sul browser, viene visualizzata la schermata di accesso di Looker e all'utente viene chiesto di accedere al proprio account utente di Looker utilizzando il protocollo di autenticazione standard.

5. Utilizzando il codice di autorizzazione restituito nel reindirizzamento OAuth, l'applicazione client OAuth deve quindi effettuare una chiamata all'endpoint /token sul nome host dell'API Looker, ad esempio https://instance_name.looker.com:19999. Il nome host dell'API potrebbe essere uguale o diverso dal nome host della UI di Looker. L'endpoint /token esiste solo sull'host dell'API Looker, mentre l'endpoint /auth esiste solo sull'host della UI di Looker.

6. Se il codice di autorizzazione passato all'endpoint /token è valido, Looker restituisce un'API access_token abilitata per le richieste API CORS dal dominio dell'applicazione client OAuth.

Registrazione di un'applicazione client OAuth

Ogni applicazione client OAuth che tenta di autenticarsi nell'API Looker utilizzando OAuth deve prima essere registrata con l'istanza Looker prima che Looker autorizzi l'accesso.

Gli amministratori di Looker possono registrare e gestire le applicazioni client OAuth personalizzate direttamente nel pannello Admin (Amministrazione) di Looker nella pagina Manage OAuth Clients (Gestisci client OAuth) (Admin > Authentication > Manage OAuth clients). Questa interfaccia consente agli amministratori di eseguire le seguenti attività:

• Configura uno o più URI di reindirizzamento autorizzati per l'applicazione in modo da supportare più ambienti e porte.
• Limitare l'accesso all'autorizzazione ai membri di un gruppo di utenti Looker specifico (Limita a ID gruppo).
• Visualizzare, modificare, attivare, disattivare o eliminare le applicazioni personalizzate registrate.

Per istruzioni passo passo su come registrare i client personalizzati nel pannello di amministrazione, consulta la pagina della documentazione Impostazioni di amministrazione - Gestisci i client OAuth.

Nota: i valori dell'ID client e dell'URI di reindirizzamento registrati in Looker devono corrispondere esattamente ai valori forniti dall'applicazione client OAuth, altrimenti l'autenticazione verrà negata.

Registrazione programmatica tramite l'API

In alternativa, gli amministratori possono registrare un'applicazione client OAuth in modo programmatico chiamando direttamente l'endpoint Register OAuth App o eseguendolo in Explorer API di Looker. I parametri includono:

• client_guid: un ID stringa univoco per l'applicazione (non può iniziare con com.looker.).
• redirect_uris: un array di URI di callback autorizzati in cui l'applicazione riceverà il reindirizzamento OAuth e il codice di autorizzazione.
• display_name: il nome dell'applicazione visualizzato dagli utenti.
• description: una descrizione dell'applicazione client OAuth.
• group_id (facoltativo): l'ID numerico di un gruppo di Looker a cui limitare l'accesso.

Esecuzione dell'accesso utente tramite OAuth

1. Indirizza l'utente all'endpoint /auth sull'host dell'interfaccia utente. Ad esempio:

   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
   }
   

   Suggerimento: il codice campione precedente si basa sulle API SubtleCrypto fornite dal browser, ma il browser consentirà l'utilizzo di queste funzioni solo da pagine web sicure (HTTPS).

   Looker tenterà di autenticare l'utente utilizzando il sistema di autenticazione per cui è configurata l'istanza di Looker.

   • Se l'utente ha già eseguito l'accesso a Looker nel browser corrente (ovvero esiste uno stato del cookie di accesso attivo), non gli verrà chiesto di inserire le credenziali di accesso.
   • Se è la prima volta che l'utente accede utilizzando questa applicazione client OAuth, Looker mostrerà una pagina di informativa e conferma che l'utente dovrà riconoscere e accettare. Verrà visualizzato il testo del parametro description utilizzato al momento della registrazione dell'applicazione. La descrizione deve indicare cosa intende fare l'applicazione con l'account Looker dell'utente. Quando l'utente fa clic su Accetta, la pagina reindirizza all'applicazione redirect_uri.
   • Se l'utente ha già eseguito l'accesso a Looker nel browser corrente e ha già accettato la pagina di informativa, l'accesso OAuth è istantaneo e non presenta interruzioni visive.

2. L'API Looker restituirà un reindirizzamento OAuth all'applicazione client OAuth. Salva il codice di autorizzazione elencato nel parametro URI. Di seguito è riportato un esempio di URI di reindirizzamento OAuth:

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

   Il codice di autorizzazione viene visualizzato dopo &code= nell'URI. In questo esempio, il codice di autorizzazione è asdfasdfassdf.

3. Invia una richiesta web all'endpoint /token nell'API Looker, passando il codice di autorizzazione e le informazioni sulla tua applicazione. Ad esempio:

   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
   }
   

   Una risposta corretta fornirà all'applicazione client OAuth una access_token API. La risposta conterrà anche un refresh_token, che potrai utilizzare in un secondo momento per ottenere un nuovo access_token senza l'interazione dell'utente. Un refresh_token ha una durata di un mese. Conserva refresh_token in modo sicuro.

   Tutti i token di questo sistema possono essere revocati dall'amministratore di Looker in qualsiasi momento.