OAuth para a API Looker

O Looker usa o OAuth para permitir que os aplicativos cliente OAuth façam a autenticação na Looker API sem expor IDs e senhas de clientes ao navegador que executa o aplicativo cliente OAuth.

Os aplicativos da Web que usam o OAuth precisam atender aos seguintes requisitos:

A autenticação com OAuth está disponível apenas com a Looker API 4.0.
Os aplicativos clientes OAuth precisam primeiro ser registrados no Looker usando a API register_oauth_client_app para que os usuários do aplicativo possam se autenticar no Looker.
Os aplicativos cliente precisam usar HTTPS em todas as solicitações para a API Looker. Os aplicativos clientes que quiserem usar as APIs SubtleCrypto fornecidas pelo navegador precisam ser hospedados em HTTPS.

Compatibilidade com CORS da API Looker

A API Looker é compatível com chamadas no navegador e entre origens usando o protocolo CORS (Cross-Origin Resource Sharing). O suporte ao CORS do Looker tem os seguintes requisitos:

Somente origens listadas na lista de permissões de domínios incorporados podem chamar a API usando CORS.
Somente os tokens de acesso recebidos do OAuth ou de chamadas do endpoint de API /login podem ser usados para fazer chamadas à API Looker usando o CORS.

O endpoint de API /login não pode ser chamado usando solicitações CORS. Os aplicativos clientes que quiserem chamar a Looker API usando solicitações CORS devem usar o processo de login OAuth descrito em Como executar o login do usuário usando OAuth, ou recuperar um token a partir do seu servidor de aplicativo ou de chamadas que não sejam da API CORS.

Visão geral da autenticação OAuth

Uma visão geral do processo de autenticação OAuth é a seguinte:

Registre o aplicativo cliente OAuth com a API Looker.
Adicione a origem do seu aplicativo cliente do OAuth à lista de permissões de domínios incorporados para a chamada da API de troca de código e todas as chamadas subsequentes da API do CORS.
Redirecione o URL do navegador para o endpoint /auth no nome do host da IU do Looker (não o nome do host da API Looker) quando o aplicativo cliente OAuth tentar autenticar um usuário. Por exemplo, https://instance_name.looker.com.
Se o usuário estiver autenticado e conectado ao Looker, a Looker retornará imediatamente um redirecionamento OAuth ao aplicativo cliente OAuth. Se o usuário ainda não tiver feito login no Looker no dispositivo e no navegador atuais, a tela de login do Looker será exibida e o usuário precisará fazer login na conta de usuário do Looker usando o protocolo de autenticação regular.
Usando o código de autorização retornado no redirecionamento OAuth, seu aplicativo cliente OAuth precisa fazer uma chamada para o endpoint /token no nome do host da API Looker, por exemplo, https://instance_name.looker.com:19999. O nome do host da API pode ser igual ou diferente do nome do host da IU do Looker. O endpoint /token existe apenas no host da API Looker, e o endpoint /auth existe apenas no host da IU do Looker.
Se o código de autorização transmitido para o endpoint /token for válido, o Looker retornará uma API access_token ativada para solicitações de API CORS do domínio do aplicativo cliente OAuth.

Como registrar um aplicativo cliente OAuth

Todos os aplicativos clientes OAuth que tentam se autenticar na Looker API usando o OAuth precisam ser registrados com a instância do Looker antes de autorizar o acesso. Para registrar um aplicativo cliente OAuth:

Abra o API Explorer na instância do Looker.
No menu suspenso de versão, escolha a versão 4.0 - estável da API.
No método Auth, localize o endpoint de API register_oauth_client_app(). Também é possível pesquisar "oauth app" no campo Search. Use register_oauth_client_app() para registrar seu aplicativo cliente OAuth com o Looker. Clique no botão Executar, insira os parâmetros no API Explorer e clique em Executar novamente para registrar o aplicativo cliente OAuth ou use o endpoint register_oauth_client_app() da API de maneira programática. Os parâmetros register_oauth_client_app() necessários são:
- client_guid: um ID globalmente exclusivo para o aplicativo.
- redirect_uri: o URI em que o aplicativo receberá um redirecionamento do OAuth que inclui um código de autorização.
- display_name: o nome do aplicativo que é exibido aos usuários dele.
- description: uma descrição do aplicativo exibida aos usuários em uma página de divulgação e confirmação quando o usuário faz login no aplicativo pela primeira vez
Os valores nos parâmetros client_guid e redirect_uri precisam corresponder aos valores que o aplicativo cliente OAuth fornecerá exatamente. Caso contrário, a autenticação será negada.

Como executar o login do usuário usando OAuth

Navegue até o endpoint /auth no host da UI. Exemplo:

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
}

O exemplo de código acima depende das SubtleCrypto APIs fornecidas pelo navegador, mas o navegador só permite o uso dessas funções em páginas seguras (HTTPS).

O Looker tentará autenticar o usuário usando o sistema de autenticação em que a instância dele está configurada.

Se o usuário já tiver feito login no Looker no navegador atual (ou seja, se houver um estado de cookie de login ativo), ele não receberá uma solicitação para inserir as credenciais de login.
Se esta for a primeira vez que o usuário faz login usando esse aplicativo cliente OAuth, o Looker mostrará uma página de confirmação e confirmação para o usuário. O texto do parâmetro description usado quando o aplicativo foi registrado será exibido. A descrição deve indicar o que o aplicativo pretende fazer com a conta do Looker do usuário. Quando o usuário clicar em aceitar, a página será redirecionada para o aplicativo redirect_uri.
Se o usuário já tiver feito login no Looker no navegador atual e já tiver reconhecido a página de divulgação, o login do OAuth será instantâneo, sem interrupções visuais.

A API Looker retornará um redirecionamento OAuth para o aplicativo cliente OAuth. Salve o código de autorização listado no parâmetro do URI. Veja a seguir um exemplo de URI de redirecionamento OAuth:
```
https://mywebapp.com:3000/authenticated?&code=asdfasdfassdf&state=...
```
O código de autorização é mostrado depois de &code= no URI. No exemplo acima, o código de autorização é asdfasdfassdf.

Faça uma solicitação da Web para o endpoint /token na API Looker transmitindo o código de autorização e as informações do aplicativo. Exemplo:

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
}

Uma resposta bem-sucedida fornecerá ao aplicativo cliente OAuth uma API access_token. A resposta também conterá um refresh_token, que pode ser usado depois para receber um novo access_token sem interação do usuário. Uma refresh_token tem duração de um mês. Armazene o refresh_token com segurança.

Todos os tokens neste sistema podem ser revogados pelo administrador do Looker a qualquer momento.