700万人のための認証API

livedoor Auth

ウェブアプリケーションへの組み込み方法

ステップ1.アプリケーションの登録

livedoor Authを利用するためにはアプリケーションの登録をする必要があります。登録にはlivedoor IDが必要となります。

登録に必要な情報はアプリケーションのタイトルと説明、アプリケーションが提供されるURLとコールバックURLを入力します。コールバックURLは認証結果を受け取り、認証処理を行うためのURLです。

登録するとアプリケーションキーというアプリケーションを識別するための文字列と、livedoorとアプリケーション間で共有する秘密鍵が発行されます。

ステップ2.ログイン用URLの作成

livedoorのログイン画面へのURLを生成します。以下のような形式になります。

http://auth.livedoor.com/login/?app_key=<app_key>&perms=<perms>&t=<time>&v=1.0&userdata=<userdata>&sig=<sig>
app_key必須登録時に発行されたアプリケーションキー
perms必須要求するアクセス権、現状userhashとidの2種類がある
t必須URLが生成された時間をエポック秒で表したもの
v必須プロトコルバージョン、現在は1.0で固定
userdata任意コールバックURLに引き継ぎたい値を255バイトまで自由に設定できる
sig必須このURLの正当性を確認するためのシグネチャ

アクセス権

livedoor Authでは現在のところ、ユーザー情報に対して以下の二種類のアクセス権を要求する事が出来ます。

userhash
各アプリケーション毎にユーザーを一意に識別する文字列(ユーザーハッシュ)を知る事が出来、シングルサインオンが可能です。
id
userhashの権限に加え、livedoor IDを知る事が可能です。
要求したアクセス権をアプリケーションに与えるかどうかはユーザーによって判断されます。

シグネチャの生成

livedoor Authでは、全てのリクエストにおいて以下の方式でシグネチャを生成し、検証します。

  1. sigを除くすべてのパラメータをアルファベット順にソートする
  2. 1.でソートしたパラメータを <パラメータ名><パラメータの値>の順で全て連結する。
  3. 発行された秘密鍵を利用しHMAC SHA1 (hex)に変換する
  4. 生成された文字列をsigという名前で付加する。

Perlで書くと以下のようになります。

my %query = (
    app_key => "0357ae6de41ca6bd062803291210c297",
    v => '1.0',
    t => time,
    perms => 'userhash',
 );
 my $secret = "27dc0b335005729b";
 
 my $hmac = Digest::HMAC_SHA1->new($secret);
 for my $key(sort { $a cmp $b } keys %query) {
     $hmac->add($key);
     $hmac->add($query{$key});
 }
 $hmac->hexdigest; # この値が sig

URLの有効期限

tに指定された時刻から10分でURLは使えなくなります。

ステップ3.コールバックURLの実装

ユーザーはステップ2.で生成されたログイン用URLにアクセスし、アクセス権の許可がまだの場合は要求されてるアクセス権を与えるかの確認を行います。一度アクセス権を許可すると二回目以降は確認の画面は出ません。

ユーザーがアクセス権を許可すると、ステップ1.で設定したコールバックURLにパラメータが付与されてリダイレクトされます。

http://www.example.com/callback?app_key=<app_key>&userhash=<userhash>&token=<token>&t=<time>&v=1.0&userdata=<userdata>&sig=<sig>
app_key登録時に発行されたアプリケーションキー
userhashユーザーを一意に識別する文字列、アプリケーション毎にユニーク
tokenログイン成功毎に発行されるトークン、ステップ4.で使用する
tログイン処理が成功した時間をエポック秒で表したもの
vプロトコルバージョン、現在は1.0で固定
userdataステップ2.でuserdataが指定されていた場合はその値が渡ってくる
sigシグネチャ

ステップ2.と同様の方法でシグネチャを生成しsigの値と比較します。
シグネチャが一致すればuserhashで示されるユーザーがログインしているという事になります。
tの値を現在時刻と比較し、一定の時間(10分程度)以上経過している場合はタイムアウトとみなしてください。
perms=userhashの場合は以上で終了です。

ステップ4.livedoor ID等の取得

perms=idの場合は更にlivedoor IDの取得が行えます。livedoor IDの取得は認証用RPCをコールする事で行います。

http://auth.livedoor.com/rpc/auth

に対して以下のパラメータをPOSTメソッドで送信します。

app_key必須登録時に発行されたアプリケーションキー
format任意出力フォーマットxml、jsonに2種類が使用出来ます。省略した場合はjsonになる
token必須ステップ3で受け取ったtoken
t必須リクエスト時間をエポック秒で表したもの
v必須プロトコルバージョン、現在は1.0で固定
sig必須ステップ1.と同様の方法で生成したシグネチャ

レスポンスは以下の構造になりますerror=0の場合は成功です。

レスポンス(XML)

 <response>
  <error>0</error>
  <message>SUCCESS</message>
  <user>
    <livedoor_id>LivedoorId</livedoor_id>
  </user>
 </response>

レスポンス(JSON)

 {
    "error" : 0,
    "message" : "SUCCESS",
    "user" : {
       "livedoor_id" : "LivedoorID"
    }
 }

RPCリクエストの有効期限と実行可能回数

RPCリクエストは ステップ3.でtokenが生成されてから10分以内に一度だけ行う事が出来ます。

Perlでの実装

WebService::Livedoor::Authを使用する事で上記の処理を簡単に行う事が出来ます。

ログインURLの生成

    use WebService::Livedoor::Auth;
    
    my $auth = WebService::Livedoor::Auth->new({
        app_key => '...',
        secret => '...',
    });
    my $uri = $auth->uri_to_login({userdata => '...'});

コールバックURL

    use CGI;
    use WebService::Livedoor::Auth;
    
    my $q = CGI->new;
    my $auth = WebService::Livedoor::Auth->new({
        app_key => '...',
        secret => '...',
    });
    my $user = $auth->validate_response($q);
    if($user) {
        # LOGIN OK.
        my $livedoor_id = $auth->get_livedoor_id($user);
    }
    else {
        # LOGIN ERROR.
    }