使用 OAuth 应用对 REST API 进行身份验证

了解使用 OAuth 应用进行身份验证的不同方法以及一些示例。

本文内容

在本节中，我们将重点介绍身份验证的基础知识。具体来说，我们将创建一个使用 Sinatra 的 Ruby 服务器，该服务器以多种不同的方式实现了应用程序的 Web 流程。

您可以从 platform-samples 仓库 下载此项目的完整源代码。

注册您的应用

首先，您需要 注册您的应用程序。每个注册的 OAuth 应用都分配了一个唯一的客户端 ID 和客户端密钥。客户端密钥用于获取已登录用户的访问令牌。您必须在本地应用程序中包含客户端密钥，但 Web 应用程序不应泄露此值。

您可以随意填写其他所有信息，但授权回调 URL除外。这是安全设置应用程序最重要的部分。它是 GitHub 在用户成功身份验证后返回用户的回调 URL。该 URL 的所有权可以确保用户登录您的应用程序，而不是将令牌泄露给攻击者。

由于我们正在运行一个普通的 Sinatra 服务器，本地实例的位置设置为 http://127.0.0.1:4567。让我们将回调 URL 填写为 http://127.0.0.1:4567/callback。

接受用户授权

弃用通知：GitHub 将停止使用查询参数对 API 进行身份验证。对 API 的身份验证应使用 HTTP 基本身份验证。使用查询参数对 API 进行身份验证将在 2021 年 5 月 5 日后不再有效。有关更多信息，包括计划的停机时间，请参阅 博客文章。

现在，让我们开始填写我们的简单服务器。创建一个名为 server.rb 的文件，并将以下内容粘贴到其中

require 'sinatra'
require 'rest-client'
require 'json'

CLIENT_ID = ENV['GH_BASIC_CLIENT_ID']
CLIENT_SECRET = ENV['GH_BASIC_SECRET_ID']

get '/' do
  erb :index, :locals => {:client_id => CLIENT_ID}
end

您的客户端 ID 和客户端密钥来自 您的应用程序配置页面。我们建议将这些值存储为 环境变量，以便于替换和使用——这正是我们在这里所做的。

接下来，在 views/index.erb 中，粘贴以下内容

<html>
  <head>
  </head>
  <body>
    <p>
      Well, hello there!
    </p>
    <p>
      We're going to now talk to the GitHub API. Ready?
      <a href="https://github.com/login/oauth/authorize?scope=user:email&client_id=<%= client_id %>">Click here</a> to begin!
    </p>
    <p>
      If that link doesn't work, remember to provide your own <a href="/apps/building-oauth-apps/authorizing-oauth-apps/">Client ID</a>!
    </p>
  </body>
</html>

（如果您不熟悉 Sinatra 的工作原理，我们建议您 阅读 Sinatra 指南。）

另外，请注意，该 URL 使用 scope 查询参数来定义应用程序请求的 范围。对于我们的应用程序，我们请求 user:email 范围以读取私有电子邮件地址。

将您的浏览器导航到 http://127.0.0.1:4567。单击链接后，您应该会被带到 GitHub，并显示一个“授权应用程序”对话框。

如果您信任自己，请单击授权应用程序。哎呀！Sinatra 吐出一个 404 错误。怎么回事？！

嗯，还记得我们指定回调 URL 为 callback 吗？我们没有为它提供路由，因此 GitHub 不知道在用户授权应用程序后将用户放到哪里。现在让我们解决这个问题！

提供回调

在 server.rb 中，添加一个路由来指定回调应该做什么

get '/callback' do
  # get temporary GitHub code...
  session_code = request.env['rack.request.query_hash']['code']

  # ... and POST it back to GitHub
  result = RestClient.post('https://github.com/login/oauth/access_token',
                          {:client_id => CLIENT_ID,
                           :client_secret => CLIENT_SECRET,
                           :code => session_code},
                           :accept => :json)

  # extract the token and granted scopes
  access_token = JSON.parse(result)['access_token']
end

在应用程序成功身份验证后，GitHub 会提供一个临时的 code 值。您需要将此代码与您的客户端密钥一起 POST 回 GitHub，以换取 access_token。为了简化我们的 GET 和 POST HTTP 请求，我们使用的是 rest-client。请注意，您可能永远不会通过 REST 访问 API。对于更严肃的应用程序，您应该使用 您选择的语言编写的库。

检查授予的范围

用户可以通过直接更改 URL 来编辑您请求的范围。这可能会授予您的应用程序比您最初要求的更少的访问权限。在使用令牌进行任何请求之前，请检查用户为令牌授予的范围。有关请求范围和授予范围的更多信息，请参阅“OAuth 应用程序的范围”。

授予的范围作为交换令牌的响应的一部分返回。

get '/callback' do
  # ...
  # Get the access_token using the code sample above
  # ...

  # check if we were granted user:email scope
  scopes = JSON.parse(result)['scope'].split(',')
  has_user_email_scope = scopes.include? 'user:email' || scopes.include? 'user'
end

在我们的应用程序中，我们使用 scopes.include? 来检查我们是否被授予了获取已认证用户的私人电子邮件地址所需的 user:email 范围。如果应用程序请求了其他范围，我们也会检查这些范围。

此外，由于范围之间存在层次关系，您应该检查您是否被授予了所需范围的任何更高级别。例如，如果应用程序请求了 user 范围，则不会明确授予 user:email 范围。在这种情况下，它将收到带有 user 范围的令牌，这将适用于请求用户的电子邮件地址，即使它在令牌上没有明确包含 user:email。检查 user 和 user:email 确保您检查了这两种情况。

仅在进行请求之前检查范围是不够的，因为用户可能会在您的检查和实际请求之间更改范围。如果发生这种情况，您预期会成功的 API 调用可能会失败，并显示 404 或 401 状态，或者返回不同的信息子集。

为了帮助您优雅地处理这些情况，所有使用有效 OAuth 应用程序令牌进行的请求的 API 响应还包含一个 X-OAuth-Scopes 标头。此标头包含用于进行请求的令牌的范围列表。除此之外，REST API 还提供了一个端点来 检查令牌的有效性。使用此信息来检测令牌范围的变化，并告知您的用户应用程序功能的可用性变化。

进行身份验证请求

最后，使用此访问令牌，您将能够以登录用户的身份进行身份验证请求

# fetch user information
auth_result = JSON.parse(RestClient.get('https://api.github.com/user',
                                        {:params => {:access_token => access_token}}))

# if the user authorized it, fetch private emails
if has_user_email_scope
  auth_result['private_emails'] =
    JSON.parse(RestClient.get('https://api.github.com/user/emails',
                              {:params => {:access_token => access_token}}))
end

erb :basic, :locals => auth_result

我们可以对结果做任何我们想做的事情。在这种情况下，我们将直接将它们转储到 basic.erb 中

<p>Hello, <%= login %>!</p>
<p>
  <% if !email.nil? && !email.empty? %> It looks like your public email address is <%= email %>.
  <% else %> It looks like you don't have a public email. That's cool.
  <% end %>
</p>
<p>
  <% if defined? private_emails %>
  With your permission, we were also able to dig up your private email addresses:
  <%= private_emails.map{ |private_email_address| private_email_address["email"] }.join(', ') %>
  <% else %>
  Also, you're a bit secretive about your private email addresses.
  <% end %>
</p>

实现“持久”身份验证

如果每次用户需要访问网页时都要求他们登录应用程序，那将是一个非常糟糕的模型。例如，尝试直接导航到http://127.0.0.1:4567/basic。你会得到一个错误。

如果我们可以绕过整个“点击这里”的过程，并且只记住，只要用户登录了 GitHub，他们就应该能够访问此应用程序？准备好你的帽子，因为这正是我们要做的。

我们上面的这个小服务器相当简单。为了插入一些智能身份验证，我们将切换到使用会话来存储令牌。这将使身份验证对用户透明。

此外，由于我们在会话中持久化了范围，因此我们需要处理用户在检查范围后更新范围或撤销令牌的情况。为此，我们将使用一个rescue块并检查第一个 API 调用是否成功，这将验证令牌是否仍然有效。之后，我们将检查X-OAuth-Scopes响应头以验证用户是否已撤销user:email范围。

创建一个名为advanced_server.rb的文件，并将这些行粘贴到其中

require 'sinatra'
require 'rest_client'
require 'json'

# Don't use hard-coded values in your app
# Instead, set and test environment variables, like below
# if ENV['GITHUB_CLIENT_ID'] && ENV['GITHUB_CLIENT_SECRET']
#  CLIENT_ID        = ENV['GITHUB_CLIENT_ID']
#  CLIENT_SECRET    = ENV['GITHUB_CLIENT_SECRET']
# end

CLIENT_ID = ENV['GH_BASIC_CLIENT_ID']
CLIENT_SECRET = ENV['GH_BASIC_SECRET_ID']

use Rack::Session::Pool, :cookie_only => false

def authenticated?
  session[:access_token]
end

def authenticate!
  erb :index, :locals => {:client_id => CLIENT_ID}
end

get '/' do
  if !authenticated?
    authenticate!
  else
    access_token = session[:access_token]
    scopes = []

    begin
      auth_result = RestClient.get('https://api.github.com/user',
                                   {:params => {:access_token => access_token},
                                    :accept => :json})
    rescue => e
      # request didn't succeed because the token was revoked so we
      # invalidate the token stored in the session and render the
      # index page so that the user can start the OAuth flow again

      session[:access_token] = nil
      return authenticate!
    end

    # the request succeeded, so we check the list of current scopes
    if auth_result.headers.include? :x_oauth_scopes
      scopes = auth_result.headers[:x_oauth_scopes].split(', ')
    end

    auth_result = JSON.parse(auth_result)

    if scopes.include? 'user:email'
      auth_result['private_emails'] =
        JSON.parse(RestClient.get('https://api.github.com/user/emails',
                       {:params => {:access_token => access_token},
                        :accept => :json}))
    end

    erb :advanced, :locals => auth_result
  end
end

get '/callback' do
  session_code = request.env['rack.request.query_hash']['code']

  result = RestClient.post('https://github.com/login/oauth/access_token',
                          {:client_id => CLIENT_ID,
                           :client_secret => CLIENT_SECRET,
                           :code => session_code},
                           :accept => :json)

  session[:access_token] = JSON.parse(result)['access_token']

  redirect '/'
end

大部分代码应该看起来很熟悉。例如，我们仍然使用RestClient.get调用 GitHub API，并且我们仍然将结果传递给 ERB 模板进行渲染（这次，它被称为advanced.erb）。

此外，我们现在有了authenticated?方法，它检查用户是否已通过身份验证。如果没有，则调用authenticate!方法，该方法执行 OAuth 流程并使用授予的令牌和范围更新会话。

接下来，在views中创建一个名为advanced.erb的文件，并将此标记粘贴到其中

<html>
  <head>
  </head>
  <body>
    <p>Well, well, well, <%= login %>!</p>
    <p>
      <% if !email.empty? %> It looks like your public email address is <%= email %>.
      <% else %> It looks like you don't have a public email. That's cool.
      <% end %>
    </p>
    <p>
      <% if defined? private_emails %>
      With your permission, we were also able to dig up your private email addresses:
      <%= private_emails.map{ |private_email_address| private_email_address["email"] }.join(', ') %>
      <% else %>
      Also, you're a bit secretive about your private email addresses.
      <% end %>
    </p>
  </body>
</html>

从命令行调用ruby advanced_server.rb，这将在端口4567上启动你的服务器 - 与我们使用简单 Sinatra 应用程序时使用的端口相同。当你导航到http://127.0.0.1:4567时，应用程序调用authenticate!，它会将你重定向到/callback。/callback然后将我们送回/，并且由于我们已经通过身份验证，因此会渲染advanced.erb。

我们可以通过简单地将 GitHub 中的回调 URL 更改为/来完全简化此往返路由。但是，由于server.rb和advanced.rb都依赖于相同的回调 URL，因此我们必须做一些奇怪的事情才能使其正常工作。

此外，如果我们从未授权此应用程序访问我们的 GitHub 数据，我们也会看到之前弹出的相同确认对话框，并向我们发出警告。