OAuth pour l'API Looker

Looker utilise OAuth pour permettre aux applications clientes OAuth de s'authentifier auprès de l'API Looker sans exposer les ID client et les codes secrets du client au navigateur qui exécute l'application cliente OAuth.

Les applications Web utilisant OAuth doivent répondre aux exigences suivantes:

  • L'authentification via OAuth n'est disponible qu'avec l'API Looker 4.0.
  • Les applications clientes OAuth doivent d'abord être enregistrées dans Looker à l'aide de l'API register_oauth_client_app pour que les utilisateurs puissent s'authentifier dans Looker.
  • Les applications clientes doivent utiliser le protocole HTTPS pour toutes les requêtes adressées à l'API Looker. Les applications clientes qui souhaitent utiliser les API SubtleCrypto fournies par le navigateur doivent être hébergées sur HTTPS.

Compatibilité CORS de l'API Looker

L'API Looker permet d'être appelée dans le navigateur et entre les origines à l'aide du protocole Cross-Origin Resource Sharing (CORS). La compatibilité CORS de Looker est soumise aux exigences suivantes:

  • Seules les origines répertoriées dans la liste d'autorisation de domaines intégrés peuvent appeler l'API à l'aide de CORS.

  • Seuls les jetons d'accès obtenus via OAuth ou en appelant le point de terminaison de l'API /login peuvent être utilisés pour appeler l'API Looker via CORS.

    Le point de terminaison de l'API /login ne peut pas être appelé à l'aide de requêtes CORS. Les applications clientes souhaitant appeler l'API Looker à l'aide de requêtes CORS doivent soit utiliser le processus de connexion OAuth décrit dans Effectuer une connexion utilisateur avec OAuth, soit récupérer un jeton à partir de votre serveur d'applications ou à partir d'appels d'API autres que CORS.

Présentation de l'authentification OAuth

Voici un aperçu du processus d'authentification OAuth:

  1. Enregistrez l'application cliente OAuth auprès de l'API Looker.
  2. Ajoutez l'origine de votre application cliente OAuth à la liste d'autorisation de domaines intégrés pour l'appel d'API Exchange et tous les appels d'API CORS ultérieurs.
  3. Redirigez l'URL du navigateur vers le point de terminaison /auth du nom d'hôte de l'interface utilisateur Looker (et non du nom d'hôte de l'API Looker) lorsque l'application cliente OAuth tente d'authentifier un utilisateur. Par exemple, https://instance_name.looker.com.
  4. Si l'utilisateur est authentifié et connecté à Looker, Looker renvoie immédiatement une redirection OAuth vers l'application cliente OAuth. Si l'utilisateur n'est pas déjà connecté à Looker sur l'appareil et le navigateur actuels, l'écran de connexion Looker s'affiche et l'utilisateur est invité à se connecter à son compte utilisateur Looker à l'aide de son protocole d'authentification standard.
  5. À l'aide du code d'autorisation renvoyé dans la redirection OAuth, votre application cliente OAuth doit ensuite appeler le point de terminaison /token du nom d'hôte de l'API Looker, par exemple https://instance_name.looker.com:19999. Le nom d'hôte de l'API peut être identique ou non au nom d'hôte de l'interface utilisateur de Looker. Le point de terminaison /token n'existe que sur l'hôte de l'API Looker, tandis que le point de terminaison /auth n'existe que sur l'hôte de l'interface utilisateur Looker.
  6. Si le code d'autorisation transmis au point de terminaison /token est valide, Looker renvoie une API access_token activée pour les requêtes d'API CORS provenant du domaine de l'application cliente OAuth.

Enregistrer une application cliente OAuth

Chaque application cliente OAuth qui tente de s'authentifier auprès de l'API Looker à l'aide d'OAuth doit d'abord être enregistrée auprès de l'instance Looker avant que Looker n'autorise l'accès. Pour enregistrer une application cliente OAuth:

  1. Ouvrez l'explorateur d'API sur votre instance Looker.
  2. Dans le menu déroulant "Version", sélectionnez la version 4.0 - stable de l'API.

  3. Sous la méthode Auth, recherchez le point de terminaison de l'API register_oauth_client_app(). Vous pouvez également rechercher "oauth application" dans le champ Search. Vous pouvez utiliser register_oauth_client_app() pour enregistrer votre application cliente OAuth auprès de Looker. Cliquez sur le bouton Exécuter, puis saisissez les paramètres dans l'explorateur d'API, puis cliquez à nouveau sur Exécuter pour enregistrer l'application cliente OAuth ou utilisez le point de terminaison de l'API register_oauth_client_app() par programmation. Les paramètres register_oauth_client_app() obligatoires sont les suivants:

    • client_guid: identifiant unique pour l'application
    • redirect_uri: URI où l'application reçoit une redirection OAuth incluant un code d'autorisation.
    • display_name: nom de l'application présenté aux utilisateurs
    • description: description de l'application qui s'affiche sur une page de divulgation et de confirmation lorsque l'utilisateur se connecte pour la première fois à partir de l'application.

    Les valeurs des paramètres client_guid et redirect_uri doivent correspondre aux valeurs fournies exactement par l'application cliente OAuth, sans quoi l'authentification sera refusée.

Connexion d'un utilisateur avec OAuth

  1. Dirigez l'utilisateur vers le point de terminaison /auth de l'hôte de l'interface utilisateur. Exemple :

    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
}

    L'exemple de code ci-dessus repose sur les API SubtleCrypto fournies par le navigateur, mais celui-ci n'autorise l'utilisation de ces fonctions qu'à partir des pages Web sécurisées (HTTPS).

    Looker va tenter d'authentifier l'utilisateur à l'aide du système d'authentification pour lequel l'instance Looker est configurée.

    • Si l'utilisateur est déjà connecté à Looker dans le navigateur actuel (ce qui signifie qu'il a activé l'état du cookie de connexion), il ne sera pas invité à saisir ses identifiants de connexion.
    • Si c'est la première fois que cet utilisateur se connecte à l'aide de cette application cliente OAuth, Looker affiche une page de confirmation et de confirmation que l'utilisateur doit accepter et accepter. Le texte du paramètre description utilisé lors de l'enregistrement de l'application s'affiche. La description doit indiquer l'intention de l'application avec le compte Looker de l'utilisateur. Lorsque l'utilisateur clique sur Accepter, la page le redirige vers l'application redirect_uri.
    • Si l'utilisateur est déjà connecté à Looker dans le navigateur actuel et a déjà confirmé la page de divulgation, la connexion OAuth est instantanée, sans interruption visuelle.

  2. L'API Looker renvoie une redirection OAuth vers l'application cliente OAuth. Enregistrez le code d'autorisation indiqué dans le paramètre URI. Voici un exemple d'URI de redirection OAuth:

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

    Le code d'autorisation est indiqué après &code= dans l'URI. Dans l'exemple ci-dessus, le code d'autorisation est asdfasdfassdf.

  3. Envoyez une requête Web au point de terminaison /token dans l'API Looker en transmettant le code d'autorisation et les informations sur votre application. Exemple :

    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
}

    Une réponse réussie fournira à l'application cliente OAuth une API access_token. La réponse contiendra également un refresh_token, que vous pourrez utiliser ultérieurement pour obtenir un nouveau access_token sans interaction de l'utilisateur. Un refresh_token a une durée de vie d'un mois. Stockez refresh_token de manière sécurisée.

    Tous les jetons de ce système peuvent être révoqués à tout moment par l'administrateur Looker.