Autenticación de la API de Looker con OAuth

Looker usa OAuth para permitir que las aplicaciones cliente de OAuth se autentiquen en la API de Looker sin exponer los IDs de cliente ni los secretos de cliente al navegador que ejecuta la aplicación cliente de OAuth.

Las aplicaciones web que usan OAuth deben cumplir con los siguientes requisitos:

• La autenticación con OAuth solo está disponible con la API de Looker 4.0.
• Las aplicaciones cliente de OAuth primero deben registrarse en Looker con la API antes de que los usuarios de la aplicación puedan autenticarse en Looker.
• Las aplicaciones cliente deben usar HTTPS para todas las solicitudes a la API de Looker. Las aplicaciones cliente que quieran usar las APIs de SubtleCrypto que proporciona el navegador deben alojarse en HTTPS.

Compatibilidad con CORS de la API de Looker

La API de Looker admite llamadas en el navegador y entre orígenes con el protocolo de uso compartido de recursos de origen cruzado (CORS). La compatibilidad con CORS de Looker tiene los siguientes requisitos:

• Solo los orígenes que aparecen en la lista de dominios incorporados permitidos pueden llamar a la API con CORS.

  Importante: La política de acceso a redes privadas (PNA) del navegador Google Chrome puede bloquear las solicitudes de contenido incorporado, ya que puede tratar la solicitud incorporada como una conexión a una red no confiable. Para resolver este problema, puedes proporcionar una solución alternativa local temporal para las pruebas de Chrome inhabilitando el parámetro de configuración del navegador de verificación de acceso a la red local.

• Solo se pueden usar los tokens de acceso obtenidos de OAuth o de la llamada al extremo de API de /login para realizar llamadas a la API de Looker con CORS.

  Nota: No se puede llamar al /login extremo de API con solicitudes de CORS. Las aplicaciones cliente que necesitan llamar a la API de Looker con solicitudes de CORS deben usar el proceso de acceso de OAuth que se describe en Cómo realizar el acceso de usuarios con OAuth o recuperar un token de tu servidor de aplicaciones o de llamadas a la API que no sean de CORS.

Descripción general de la autenticación de OAuth

A continuación, se muestra una descripción general del proceso de autenticación de OAuth:

1. Registra la aplicación cliente de OAuth con tu instancia de Looker.

2. Agrega el origen de tu aplicación cliente de OAuth a tu lista de dominios incorporados permitidos para la llamada a la API de intercambio de código y cualquier llamada posterior a la API de CORS.

   Importante: No incluyas una barra diagonal final (/) en la URL del dominio.

3. Redirecciona la URL del navegador al extremo /auth en el nombre de host de la IU de Looker (no en el nombre de host de la API de Looker) cuando la aplicación cliente de OAuth intente autenticar a un usuario. Por ejemplo, https://instance_name.looker.com

4. Si el usuario se autentica y accede a Looker correctamente, Looker devuelve un redireccionamiento de OAuth a la aplicación cliente de OAuth de inmediato. Si el usuario aún no accedió a Looker en el dispositivo y el navegador, se mostrará la pantalla de acceso de Looker y se le solicitará que acceda a su cuenta de usuario de Looker con su protocolo de autenticación habitual.

5. Con el código de autorización que se muestra en el redireccionamiento de OAuth, tu aplicación cliente de OAuth debería realizar una llamada al extremo /token en el nombre de host de la API de Looker, por ejemplo, https://instance_name.looker.com:19999. El nombre de host de la API puede ser igual o diferente al nombre de host de la IU de Looker. El extremo /token solo existe en el host de la API de Looker, y el extremo /auth solo existe en el host de la IU de Looker.

6. Si el código de autorización que se pasa al extremo /token es válido, Looker devuelve un access_token de la API que está habilitado para las solicitudes a la API de CORS desde el dominio de la aplicación cliente de OAuth.

Registra una aplicación cliente de OAuth

Cada aplicación cliente de OAuth que intente autenticarse en la API de Looker con OAuth debe registrarse primero en la instancia de Looker antes de que Looker autorice el acceso.

Los administradores de Looker pueden registrar y administrar aplicaciones cliente de OAuth personalizadas directamente en el panel de administración de Looker Administrador, en la página Administrar clientes de OAuth (Administrador > Autenticación > Administrar clientes de OAuth). Esta interfaz permite que los administradores realicen las siguientes tareas:

• Configura uno o más URI de redireccionamiento autorizados para que la aplicación admita varios entornos y puertos.
• Restringir el acceso de autorización a los miembros de un grupo de usuarios de Looker específico (Restringir al ID de grupo)
• Ver, editar, habilitar, inhabilitar o borrar aplicaciones personalizadas registradas

Para obtener instrucciones paso a paso sobre cómo registrar clientes personalizados en el panel de Administrador, consulta la página de documentación Configuración de administrador: Administra clientes de OAuth.

Nota: Los valores de ID de cliente y URI de redireccionamiento que se registran en Looker deben coincidir exactamente con los valores que proporciona tu aplicación cliente de OAuth; de lo contrario, se denegará la autenticación.

Registro programático con la API

Como alternativa, los administradores pueden registrar una aplicación cliente de OAuth de manera programática llamando directamente al endpoint de registro de la app de OAuth o ejecutándolo en el Explorador de APIs de Looker. Entre los parámetros, se incluyen los siguientes:

• client_guid: Es un ID de cadena único para la aplicación (no puede comenzar con com.looker.).
• redirect_uris: Es un array de URIs de devolución de llamada autorizados en los que la aplicación recibirá el redireccionamiento de OAuth y el código de autorización.
• display_name: Es el nombre de la aplicación que se muestra a los usuarios.
• description: Es una descripción de la aplicación cliente de OAuth.
• group_id (opcional): Es el ID numérico de un grupo de Looker al que se restringirá el acceso.

Acceso de usuarios con OAuth

1. Navega al usuario al extremo /auth en el host de la IU. Por ejemplo:

   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
   }
   

   Sugerencia: El código de muestra anterior se basa en las APIs de SubtleCrypto que proporciona el navegador, pero este solo permitirá el uso de estas funciones desde páginas web seguras (HTTPS).

   Looker intentará autenticar al usuario con el sistema de autenticación para el que está configurada la instancia de Looker.

   • Si el usuario ya accedió a Looker en el navegador actual (lo que significa que hay un estado de cookie de acceso activo), no se le solicitará que ingrese sus credenciales de acceso.
   • Si es la primera vez que este usuario está conectado con esta aplicación cliente de OAuth, Looker mostrará una página de divulgación y confirmación para que el usuario la reconozca y la acepte. Se mostrará el texto del parámetro description que se usó cuando se registró la aplicación. La descripción debe indicar lo que la aplicación pretende hacer con la cuenta de Looker del usuario. Cuando el usuario haga clic en Aceptar, la página se redireccionará a la aplicación redirect_uri.
   • Si el usuario ya accedió a Looker en el navegador actual y ya confirmó la página de divulgación, el acceso de OAuth es instantáneo y no se produce ninguna interrupción visual.

2. La API de Looker devolverá un redireccionamiento de OAuth a la aplicación cliente de OAuth. Guarda el código de autorización que aparece en el parámetro del URI. A continuación, se muestra un ejemplo de un URI de redireccionamiento de OAuth:

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

   El código de autorización se muestra después de &code= en el URI. En este ejemplo, el código de autorización es asdfasdfassdf.

3. Realiza una solicitud web al extremo /token en la API de Looker y pasa el código de autorización y la información de tu aplicación. Por ejemplo:

   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 respuesta correcta proporcionará a la aplicación cliente de OAuth un access_token de la API. La respuesta también contendrá un refresh_token, que podrás usar más adelante para obtener un access_token nuevo sin interacción del usuario. Un refresh_token tiene una vida útil de un mes. Almacena el refresh_token de forma segura.

   El administrador de Looker puede revocar todos los tokens de este sistema en cualquier momento.