ようこそゲストさん | ログイン | ヘルプ

HatenaAPIAuth

はてな認証API > ヘルプ > はてな認証APIの使い方

はてな認証APIを使った認証システムをウェブアプリケーションに組み込む方法

ここでははてな認証APIをサードパーティ製のウェブアプリケーションに組み込む方法を具体的に解説します。認証のシーケンスに関しては認証APIを利用した認証の流れをご覧ください。

■ 1. APIキーを取得する

認証APIを利用するアプリケーションには API キーが必要です。まずはAPI キーの新規取得ページからキーを取得します。

なお、APIキーは特定のアプリケーションに固有のものであり、複数のアプリケーションで使い回すことはできません。新規にアプリケーションを作りたい場合はその都度 APIキーを取得してください。

新規にAPIキーを取得すると、該当のキーがキー一覧に追加されます。

■ 2. APIキーの設定を行う

APIキーを取得したら次に、取得したキーの一覧から設定画面に進み、キーの設定を行います。画面の指示に従って、そのキーを使ったアプリケーションの情報を入力してください。

  • タイトル
  • 説明
  • コールバックURL (ステップ4で解説します)

を設定した後、キーを有効にして設定を保存してください。これで前準備は完了です。

■ 3. ログイン用のリンクを作成する

アプリケーションにはてなアカウントの認証機能を搭載していきます。まず、あなたのアプリケーションから、はてな認証APIのログイン画面へリンクを行います。リンクの形式は以下のようになります。

http://auth.hatena.ne.jp/auth?api_key={api_key}&api_sig={api_sig}

api_key には先ほど取得した API キーを指定します。一方の api_sig は、このリクエストが開発者本人から送られた正しいものであることを確認するためのシグネチャです。このシグネチャは、同時に指定する他の URL パラメータの値、キー一覧にある秘密鍵の値を使って生成します。

シグネチャの生成ロジックは以下のように実装してください。

  • api_sig 以外に指定するパラメータを、パラメータ名でアルファベット順にソートする
  • ソートされたパラメータを、"パラメータ名" "そのパラメータの値" の順ですべて文字列連結する
  • 秘密鍵とこの連結されたパラメータ文字列「秘密鍵 + 連結したパラメータ文字列」の順で更に文字列連結する
  • できあがった文字列を MD5 hex に変換する

例えば

  • 秘密鍵が e7b59cdcceaa3904
  • api_key が a47d51a93bafc7d1160efd712c6931bd

だった場合、e7b59cdcceaa3904api_keya47d51a93bafc7d1160efd712c6931bd と連結(秘密鍵 + 'api_key' + [api_key の値])した文字列の MD5 を取ります。その値が api_sig の値になります。

正しい api_key と api_sig の組み合わせでリンクを行うと、リンク先で認証が正しく動作します。組み合わせあるいは api_sig の値が正しくない場合は、そのURLへのリクエストは不正なリクエストとして扱われ、リンク先ページはエラー画面となります。

なお、ログイン用URLに api_key や api_sig 以外のパラメータを含めた場合、それらパラメータは次のステップで説明するコールバックURLまで引き継いで渡されます。例えば foo=bar&bar=baz というパラメータをログイン用リンクに追加すると、コールバックURLに cert の他に foo=bar と bar=baz がURLパラメータとして渡ります。

追加パラメータを付与する場合は、シグネチャ生成の際、それらパラメータも含めて値を計算してください。このときパラメータの値は URL エスケープする以前の値を使用してください。

■ 4. 認証ハンドラを作成する

ステップ3で用意したリンクを辿ると、そこでは訪問したユーザーに"該当のアプリケーションにはてなのアカウント情報を読み取る許可を与えてよいかどうか"を訪ねるページが表示されます。このページははてなでホストしています。つまりユーザーは、アプリケーションに用意されたログイン用のリンクをたどってはてなのサイトへアクセスし、そこで認証許可を確認するという流れになります。

ここでユーザーが許可を与えることに承諾すると、そのユーザーはコールバックURL(キーの設定画面であなたが入力したURL)へとリダイレクトされます。このリダイレクト先のURLには、cert というクエリパラメータが付与されています。

http://yourapp.test.com/auth?cert=52bc7c3bb92b6c22

つまり、コールバックURLにはあなたのアプリケーションにおいて認証処理を実行するURLを指定しておき、そのURLをトリガにして走る処理でURLパラメータからcertの値を取得するようにし、その cert パラメータを使って以降の処理を実装していくことになります。

■ 5. 認証APIを呼び出す

cert の値が取得できたら、認証APIのURL(http://auth.hatena.ne.jp/api/auth.json)に HTTP GET リクエストを投げます。このとき GET リクエストに以下の三つの値をURLパラメータとして指定します。

  • api_key
  • cert
  • api_sig

api_key はステップ2に同じ値です。certはコールバックURLのURLパラメータから取得したもの、api_sigはステップ2と同じ手順で作成します。

つまり、秘密鍵 + 'api_key' + [api_keyの値] + 'cert' + [certの値] ですので、先の例でいくとe7b59cdcceaa3904api_keya47d51a93bafc7d1160efd712c6931bdcert52bc7c3bb92b6c22 となる文字列の MD5 を取ったものが api_sigの値になります。

http://auth.hatena.ne.jp/api/auth.json?api_key=...&cert=...&api_sig=...

この URL へ HTTP GET リクエストを送ると、ユーザー情報が JSON で返却されてきます。例えば以下のようになります。

{
  "has_error": false,
  "user": {
    "name": "hatena",
    "image_url": "http://www.hatena.ne.jp/users/ha/hatena/profile.gif",
    "thumbnail_url": "http://www.hatena.ne.jp/users/ha/hatena/profile_s.gif"
  }
}

現時点では

  • name : はてなのアカウント名(はてなID)
  • image_url : プロフィール画像のURL
  • thumbnail_url : プロフィール画像のサムネイルのURL

の三つの情報が返却されます。

この JSON をパースしてアプリケーションにユーザー情報を取り込んでください。取得したユーザー情報とアプリケーションのセッションとの紐づけは、各アプリケーションでセッション管理用 Cookie を発行してそこへ紐づけるなどして実装してください。

なお、certパラメータは一回使い切りの値になります。同じcertの値で再度ユーザー情報を取得することはできません。

■ 認証APIのレスポンス例

  • エラー時も含めた認証API のレスポンス例を以下に示します。
  • 認証API の URL の auth.json の箇所を auth.xml へ変更することで、結果を XML として取得することが可能です。

JSON

正常時
{
  "has_error": false,
  "user": {
    "name": "hatena",
    "image_url": "http://www.hatena.ne.jp/users/ha/hatena/profile.gif",
    "thumbnail_url": "http://www.hatena.ne.jp/users/ha/hatena/profile_s.gif"
  }
}
エラー時
{
  "has_error": true,
  "error": {
    message: "Invalid API key"
  }
}

XML

正常時
<?xml version="1.0" encoding="utf-8" ?>
<response>
  <has_error>false</has_error>
  <user>
    <name>hatena</name>
    <image_url>http://www.hatena.ne.jp/users/ha/hatena/profile.gif</image_url>
    <thumbnail_url>http://www.hatena.ne.jp/users/ha/hatena/profile_s.gif</thumbnail_url>
  </user>
</response>
エラー時
<?xml version="1.0" encoding="utf-8" ?>
<response>
  <has_error>true</has_error>
  <error>
    <message>Invalid API key</message>
  </error>
</response>

■ 各言語用のライブラリ/モジュール

アプリケーションの開発言語に Perl を利用している場合は、はてな認証APIを抽象化したモジュールである Hatena::API を利用することで、認証APIを処理するコードを簡単に記述することができます。Hatena::API::Auth は CPAN からインストール可能です。詳しい使い方は Hatena::API::Auth のドキュメント (search.cpan.org) を参照してください。

Ruby を利用している場合は、Ruby 用の Hatena::API::Auth ライブラリが利用可能です。Hatna::API::Auth のドキュメント (rubyforge.org) を参照してください。

最終更新日: 05/19/2011

Copyright (C) 2001-2012 hatena. All Rights Reserved.