使用 OAuth 进行 Looker API 身份验证

Looker 使用 OAuth，让 OAuth 客户端应用能够向 Looker API 进行身份验证，而无需向运行 OAuth 客户端应用的浏览器公开客户端 ID 和客户端密钥。

使用 OAuth 的 Web 应用必须满足以下要求：

只有 Looker API 4.0 支持使用 OAuth 进行身份验证。
OAuth 客户端应用必须先使用 API 向 Looker 注册，然后应用的用户才能向 Looker 进行身份验证。
客户端应用必须对 Looker API 的所有请求使用 HTTPS。想要使用浏览器提供的 SubtleCrypto API 的客户端应用必须采用 HTTPS 托管。

Looker API CORS 支持

Looker API 支持使用跨域资源共享 (CORS) 协议在浏览器中和跨源进行调用。Looker CORS 支持有以下要求：

只有嵌入式网域许可名单中列出的来源才能使用 CORS 调用 API。
只有通过 OAuth 或调用 /login API 端点获得的访问令牌才能用于使用 CORS 调用 Looker API。

无法使用 CORS 请求调用 /login API 端点。想要使用 CORS 请求调用 Looker API 的客户端应用必须使用使用 OAuth 执行用户登录中所述的 OAuth 登录流程，或者从应用服务器或非 CORS API 调用中检索令牌。

OAuth 身份验证概览

OAuth 身份验证流程的概览如下：

向 Looker API 注册 OAuth 客户端应用。
将 OAuth 客户端应用的来源添加到您的嵌入式网域许可名单中，以用于代码交换 API 调用和任何后续 CORS API 调用。

**重要提示：** 请勿在网域网址中添加尾部斜杠 (/)。
当 OAuth 客户端应用尝试对用户进行身份验证时，将浏览器网址重定向到 Looker 界面主机名（而非 Looker API 主机名）上的 /auth 端点。例如，https://instance_name.looker.com。
如果用户已成功通过身份验证并登录 Looker，Looker 会立即向 OAuth 客户端应用返回 OAuth 重定向。如果用户尚未在设备和浏览器上登录 Looker，系统会显示 Looker 登录界面，并提示用户使用常规身份验证协议登录其 Looker 用户账号。
OAuth 客户端应用接下来应使用 OAuth 重定向中返回的授权代码，对 Looker API 主机名（例如 https://instance_name.looker.com:19999）上的 /token 端点进行调用。API 主机名可能与 Looker 界面主机名相同，也可能不同。/token 端点仅存在于 Looker API 主机上，而 /auth 端点仅存在于 Looker 界面主机上。
如果传递给 /token 端点的授权代码有效，Looker 会返回一个 API access_token，该令牌已针对来自 OAuth 客户端应用网域的 CORS API 请求启用。

注册 OAuth 客户端应用

每个尝试使用 OAuth 向 Looker API 进行身份验证的 OAuth 客户端应用都必须先向 Looker 实例注册，然后 Looker 才会授权访问。如需注册 OAuth 客户端应用，请执行以下操作：

在 Looker 实例上打开 API Explorer。
使用版本下拉菜单，选择 4.0 - stable 版本的 API。
在 Auth 方法下，找到 register_oauth_client_app() API 端点。您还可以在搜索字段中搜索“oauth app”。您可以使用 register_oauth_client_app() 向 Looker 注册 OAuth 客户端应用。点击运行按钮，然后在 API Explorer 中输入参数并再次点击运行，以注册 OAuth 客户端应用，或者以编程方式使用 register_oauth_client_app() API 端点。register_oauth_client_app() 的必需参数包括：
- client_guid：应用的全局唯一 ID
- redirect_uri：应用将接收包含授权代码的 OAuth 重定向的 URI
- display_name：向应用用户显示的应用名称
- description：当用户首次从应用登录时，在披露和确认页面上向用户显示的应用说明
client_guid 和 redirect_uri 参数中的值必须与 OAuth 客户端应用将提供的 确切值一致，否则身份验证将被拒绝。

使用 OAuth 执行用户登录

将用户导航到界面主机上的 /auth 端点。例如：

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
}

Looker 将尝试使用为 Looker 实例配置的身份验证系统对用户进行身份验证。

如果用户已在当前浏览器中登录 Looker（这意味着存在有效的登录 Cookie 状态），系统不会提示用户输入登录凭据。
如果这是用户首次使用此 OAuth 客户端应用登录，Looker 将向用户显示披露和确认页面，供用户确认和接受。系统将显示应用注册时使用的 description 参数中的文本。说明应指明应用打算如何使用用户的 Looker 账号。当用户点击接受时，页面将重定向到应用 redirect_uri。
如果用户已在当前浏览器中登录 Looker，并且已确认披露页面，则 OAuth 登录是即时的，不会出现视觉中断。

Looker API 将向 OAuth 客户端应用返回 OAuth 重定向。保存 URI 参数中列出的授权代码。以下是 OAuth 重定向 URI 示例：
```
https://mywebapp.com:3000/authenticated?&code=asdfasdfassdf&state=...
```
授权代码显示在 URI 中的 &code= 之后。在此示例中，授权代码为 asdfasdfassdf。

向 Looker API 中的 /token 端点发出 Web 请求，传递授权代码和应用信息。例如：

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
}

成功响应将为 OAuth 客户端应用提供 API access_token。响应还将包含 refresh_token，您稍后可以使用该令牌获取新的 access_token，而无需用户互动。refresh_token 的有效期为一个月。请安全地存储 refresh_token。

Looker 管理员可以随时撤消此系统中的所有令牌。