認証の基本

このセクションでは、認証の基本に焦点を当てます。具体的には、複数の異なる方法でアプリケーションの Web フローを実装する Ruby サーバー (Sinatra を使用) を作成します。

このプロジェクトの完全なソースコードは、platform-samples リポジトリからダウンロードできます。

アプリを登録する

まず、アプリケーションを登録する必要があります。登録した各 OAuth アプリケーションには、一意のクライアント ID とクライアントシークレットが割り当てられます。クライアントシークレットは共有しないでく� さい。それには文字列をリポジトリにチェックインすることが含まれます。

[承認コールバック URL] を除き、必要に応じてすべての情� �を入力できます。これは間違いなく、アプリケーションの設定にあたって最も重要な情� �です。認証の成功後に GitHub Enterprise Server からユーザーに返されるのは、そのコールバック URL です。

通常の Sinatra サーバーを実行しているため、ローカルインスタンスの� �所は http://127.0.0.1:4567 に設定されています。コールバック URL を「http://127.0.0.1:4567/callback」として入力しましょう。

ユーザ認証の承認

非推奨の注意: GitHub では、クエリパラメーターを使った API の認証が廃止されます。 API の認証は、HTTP 基本認証を使って行う必要があります。スケジュールされたブラウンアウトなど、詳しい情� �については、ブログの投稿を参照してく� さい。

クエリパラメーターを使った API の認証は、利用はできるものの、セキュリティ上の懸念からサポートされなくなりました。代わりに、client_id、または client_secret のアクセストークンをヘッダーに移動することをインテグレーターにお勧めします。 GitHubは、クエリパラメータによる認証の削除を、事前に通知します。

さて、簡単なサーバーの入力を始めましょう。 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 Enterprise Server に移動し、次のようなダイアログが表示されます。 GitHub の OAuth プロンプト

自分自身を信� �しているならば、 [アプリの承認] をクリックします。おっと、 Sinatra が 404 エラーを吐き出しました。いったい何が起こったのでしょうか。

さて、コールバック URL を callback に指定したときのことを覚えていますか。そのときルートを設定しなかったので、GitHub Enterprise Server はアプリケーションを承認した後、ユーザーをどこに降ろせばよいかがわからなかったのです。では、この問題を解決しましょう。

コールバックの設定

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 Enterprise Server から一時的な code 値が提供されます。このコードを POST し、access_token と引き換えに GitHub Enterprise Server に戻す必要があります。 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'
end

このアプリケーションでは、認証されたユーザーのプライベートメールアドレスをフェッチするのに必要な user:email スコープが付与されたかどうかを確認するために、scopes.include? を使用しています。アプリケーションが他のスコープを要求していれば、それらについても確認します。

また、スコープ間には階層的な関係があるため、必要なスコープのうち最も下位レベルのものが付与されたか確認する必要があります。たとえば、アプリケーションが user スコープを要求していた� �合に、user:email スコープのみが付与されていることがあり得ます。その� �合、アプリケーションが要求したスコープは付与されていないかもしれませんが、付与されたスコープでも十分でしょう。

要求を行う前に� けスコープを確認するのでは不十分です。というのは、確認時と実際の要求時の間に、ユーザーがスコープを変更する可能性があるからです。それが発生した� �合、成功すると思っていた API 呼び出しが、404 または 401 ステータスになって失敗したり、情� �の別のサブセットが返されたりする可能性があります。

このような状況に適切に対応できるように、有効なトークンを使用して行われた要求に対するすべての API 応答には、X-OAuth-Scopes ヘッダーも含まれています。このヘッダーには、要求を行うために使用されたトークンのスコープのリストが含まれています。それに� えて、OAuth Applications API には、トークンの有効性を確認するためのエンドポイントが用意されています。この情� �を使用してトークンのスコープ内での変更を検出し、利用可能なアプリケーション機能における変更をユーザーに通知します。

認証リクエストの実施

最後に、このアクセストークンで、ログイン済みユーザーとして認証の要求を行うことができます。

# fetch user information
auth_result = JSON.parse(RestClient.get('http(s)://HOSTNAME/api/v3/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('http(s)://HOSTNAME/api/v3/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>

「永続的な」認証の実装

Web ページにアクセスするたびに、ユーザーにアプリケーションへのログインを求めるとしたら、それは非常に悪いモデルです。たとえば、http://127.0.0.1:4567/basic に直接移動してみてく� さい。エラーになるでしょう。

ここをクリック プロセスを全部なくし、ユーザーが GitHub Enterprise Server にログインしている限り、それを "記憶" して、このアプリケーションにアクセスできるとしたらどうでしょうか。実のところ、これからやろうとしていること はまさにそういうことなのです。

上記に上げたサーバはかなり単純なものです。インテリジェントな認証を利用する目的で、トークンを保存するためにセッションを使用するように切り替えます。これにより、認証はユーザーに意識されないものになります。

また、セッション内のスコープを永続的にしているため、そのスコープを確認した後にユーザーが更新した� �合や、トークンを取り消した� �合に対処する必要があります。これを行うには、rescue ブロックを使用し、最初の API 呼び出しが成功したことを確認して、トークンがま� 有効であることを確かめます。その後、X-OAuth-Scopes 応答ヘッダーを確認して、ユーザーが user:email スコープを取り消していないことを確かめます。

advanced_server.rb というファイルを作成し、そこに、これらの行を貼り付けます。

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

# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL 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('http(s)://HOSTNAME/api/v3/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('http(s)://HOSTNAME/api/v3/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

コードの大部分は見慣れたもののはずです。たとえば、ここでも GitHub Enterprise Server API を呼び出すために RestClient.get を使用し、また ERB テンプレート (ここでは advanced.erb) に結果をレンダリングするために結果を渡しています。

また、ここでは authenticated? メソッドを使用して、ユーザーが既に認証されていることを確認しています。そうでない� �合は、authenticate! メソッドが呼び出され、OAuth フローを実行して、付与されたトークンとスコープでセッションを更新します。

次に、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 Enterprise Server のコールバック URL を / に変更する� けで、このラウンドトリップ経路を完全に簡略化できます。しかし、server.rb と advanced.rb の両方が同じコールバック URL に依存しているため、機能させるには少し不安定なことを行う必要があります。

また、このアプリケーションを GitHub Enterprise Server データにアクセスするように認証したことがない� �合、以前のポップアップと同じ確認ダイアログが表示され、警告されるでしょう。