O Looker usa o OAuth para permitir que os aplicativos cliente OAuth se autentiquem na API Looker sem expor IDs e chaves secretas do cliente ao navegador que está executando o aplicativo cliente OAuth.
Os aplicativos da Web que usam o OAuth precisam atender aos seguintes requisitos:
- A autenticação por OAuth está disponível apenas com a API Looker 4.0.
- Os aplicativos cliente OAuth precisam ser registrados no Looker usando a API antes que os usuários do aplicativo possam se autenticar no Looker.
- Os aplicativos clientes precisam usar HTTPS em todas as solicitações feitas à API Looker. Os aplicativos clientes que querem usar as APIs
SubtleCrypto
fornecidas pelo navegador precisam ser hospedados em HTTPS.
Suporte ao CORS da API Looker
A API Looker permite chamadas no navegador e entre origens usando o protocolo Compartilhamento de recursos entre origens (CORS, na sigla em inglês). 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 o CORS.
Somente tokens de acesso recebidos do OAuth ou da chamada 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 com solicitações de CORS. Os aplicativos clientes que quiserem chamar a API Looker usando solicitações de CORS precisam usar o processo de login OAuth descrito em Fazer login de usuários com o OAuth ou recuperar um token do servidor do aplicativo ou de chamadas de API que não sejam do 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 OAuth à lista de permissões de domínio incorporado para a chamada da API Code Exchange e todas as chamadas subsequentes da API CORS.
- Redirecione o URL do navegador para o endpoint
/auth
no nome do host da interface do Looker (não para 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 for autenticado e conectado ao Looker, o Looker retornará um redirecionamento OAuth para o aplicativo cliente OAuth imediatamente. Se o usuário ainda não tiver feito login no Looker no dispositivo e no navegador, a tela de login do Looker vai aparecer e o usuário vai precisar fazer login na conta de usuário do Looker usando o protocolo de autenticação normal.
- Usando o código de autorização retornado no redirecionamento do OAuth, seu aplicativo cliente OAuth precisa chamar 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 interface do Looker. O endpoint/token
existe apenas no host da API Looker, e o endpoint/auth
existe apenas no host da interface do Looker. - Se o código de autorização transmitido ao endpoint
/token
for válido, o Looker retornará uma APIaccess_token
ativada para solicitações da API CORS do domínio do aplicativo cliente OAuth.
Como registrar um aplicativo cliente OAuth
Todo aplicativo cliente OAuth que tentar se autenticar na API Looker usando OAuth precisa ser registrado na instância do Looker para que o Looker autorize o acesso. Para registrar um aplicativo cliente OAuth:
- Abra o APIs Explorer na instância do Looker.
- Usando o menu suspenso de versão, escolha a versão 4.0 - stable da API.
No método Auth, encontre o endpoint de API
register_oauth_client_app()
. Você também pode pesquisar "oauth app" no campo Pesquisa. Você pode usarregister_oauth_client_app()
para registrar seu aplicativo cliente OAuth com o Looker. Clique no botão Executar, insira os parâmetros no APIs Explorer e clique em Executar novamente para registrar o aplicativo cliente OAuth ou use o endpoint de APIregister_oauth_client_app()
de maneira programática. Os parâmetrosregister_oauth_client_app()
obrigatórios são:client_guid
: um ID globalmente exclusivo para o aplicativo.redirect_uri
: o URI em que o aplicativo receberá um redirecionamento de OAuth que inclui um código de autorização.display_name
: o nome do aplicativo que é exibido para os usuários do aplicativo.description
: uma descrição do aplicativo que é exibida para os usuários em uma página de divulgação e confirmação quando eles fazem login pela primeira vez.
Os valores nos parâmetros
client_guid
eredirect_uri
precisam corresponder aos valores que o aplicativo cliente OAuth fornecerá exatamente. Caso contrário, a autenticação será negada.
Fazer login do usuário com o 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 Looker vai tentar autenticar o usuário usando o sistema de autenticação com que a instância do Looker 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 vai precisar inserir as credenciais de login.
- Se esta é a primeira vez que o usuário faz login usando esse aplicativo cliente OAuth, o Looker mostra uma página de divulgação e confirmação para o usuário confirmar e aceitar. 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 aplicativoredirect_uri
. - Se o usuário já tiver feito login no Looker no navegador atual e confirmado a página de divulgação, o login do OAuth será instantâneo, sem interrupção visual.
A API Looker vai retornar um redirecionamento OAuth para o aplicativo cliente OAuth. Salve o código de autorização listado no parâmetro URI. Veja a seguir um exemplo de URI de redirecionamento de OAuth:
https://mywebapp.com:3000/authenticated?&code=asdfasdfassdf&state=...
O código de autorização é mostrado após
&code=
no URI. Neste exemplo, 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 seu 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 vai conter umrefresh_token
, que pode ser usado mais tarde para receber um novoaccess_token
sem interação do usuário. Orefresh_token
tem a duração de um mês. Armazene orefresh_token
com segurança.Todos os tokens nesse sistema podem ser revogados pelo administrador do Looker a qualquer momento.