JugemKey 認証APIの提供終了のお知らせ

いつもJUGEMをご利用いただきまして、誠にありがとうございます。
2014年5月27日(火)をもちまして、JugemKey 認証APIの提供を終了いたしました。
これまでご愛顧いただき、誠にありがとうございました。
今後ともJUGEMをどうぞよろしくお願いいたします。


JugemKey認証API

認証 API を利用した認証の流れ

  1. サービス利用開始
    • 1.1. ユーザはブラウザでサービス X へアクセスし、JugemKey へのログインリンクを取得します。
  2. JugemKey へのログインリンクをクリック
    • 2.1. ログインリンクには、サービス X 固有の api_key、サービス X が必要とするパーミッション、コールバック URL 、ならびにこれらのパラメータから生成された署名コード api_sig1 が含まれます。ログインリンクをクリックすることで、これらのパラメータが JugemKey へと渡されます。JugemKey は渡されたパラメータと api_sig1 を確認し、正しければログイン画面 HTML をブラウザへ返します。
  3. JugemKey へのログイン
    • 3.1. JugemKey のユーザ ID とパスワードを入力して、JugemKey へログインします。ログインが成功すると、2.1 で指定されたコールバックURL に frob を付加した URL を Location ヘッダにいれてブラウザに渡します。
    • 3.2. ブラウザが コールバック URL + frob へ自動的にリダイレクトされることにより、frob がサービス X へと渡ります。
    • 3.2.1. サービス X は api_key、frob、リクエスト時の時刻、ならびにこれらのパラメータから生成された署名コード api_sig2 を JugemKey へと渡します。パラメータと署名コードが正しければ、JugemKey はサービス X へ token と JugemKey ユーザ ID を渡します。frob は token と交換された時点で破棄されます。 サービス X は token とユーザ ID が取得できれば、認証は完了したとみなし、認証完了画面をブラウザに返します。また、必要であればセッション cookie を発行します。

開発者向け サービスへの組み込み方法

1. API キーの取得と設定

新規 API キー取得ページ にて、「サービス名称」「サービス説明」「サービス URL」「コールバック URL」を入力し、API キーを生成します。(これらの項目は後で変更することが可能です。)

「サービス名称」「サービス説明」「サービス URL」 は、あなたのサービスを ユーザに説明するためのものです。

「コールバック URL」は、ユーザが JugemKey での認証後にリダイレクトされる、あなたのサービスのベース URL を指定します。ログインリンク作成時にコールバック URL を指定しますが、ここで指定されたベース URL を含んだ URL である必要があります。

2. ログイン用のリンク作成

あなたのサービス画面に JugemKey 認証 API のログイン画面へのリンクをはります。

https://secure.jugemkey.jp/?mode=auth_issue_frob&api_key={api_key}&perms={permission}&callback_url={callback_url}&api_sig={api_sig}

mode=auth_issue_frob は固定パラメータですので、必ず指定してください。

api_key には 「1. API キーの取得と設定」で取得した API キーを指定します。

perms にはあなたのサービスが必要とするパーミッションを指定します。指定できるパーミッションは以下の通りです。(ただし、現在は auth 以外に対応したサービスが存在しませんので、どのパーミッションを指定しても、auth 権限のみ有効となります。)

auth
認証とユーザ情報(ユーザ名)の取得権限。
read
GMOペパボぺぱぼ サービスのユーザ固有データ(購読フィードの情報など)の読み取り権限。read には auth 権限が含まれる。
write
GMOペパボぺぱぼ サービスのユーザ固有データの書き込み権限。(新規購読フィードの追加など。)write には auth, read 権限が含まれる。
delete
GMOペパボぺぱぼ サービスのユーザ固有データの削除権限。(購読フィードの削除など。)delete には auth, read, wite 権限が含まれる。

callback_url には認証後にユーザがリダイレクトされる URL を指定します。URL にはクエリストリングを含むことも可能です。必ず URL エンコードして下さい。

api_sig はこのリクエストが正しいものであるかを確認するためのシグネチャです。このシグネチャは以下のロジックで生成します。

  • api_key, callback_url, perms の順で、値のみをすべて文字列連結する。(callback_url は URL エンコードする前の値。)
  • 連結された文字列をもとに、秘密鍵をキーとした HMAC_SHA1 で署名コードを生成。

例えば、

  • 秘密鍵が 1d4c74a7cc19aeb1
  • API キーが 40025ab515df245d2483d758ca9d0680
  • パーミッション が read
  • コールバック URL が http://jugemkey.jp/

の場合、文字列を連結すると 40025ab515df245d2483d758ca9d0680http://jugemkey.jp/read となり、HMAC_SHA1 の値は 4661d533d19ff44a6d5586df95aba86b1bfcfa06 となります。この値が api_sig の値になります。

api_sig が正しくない場合には JugemKey へのログイン時にエラーが表示されます。

3. frob の取得

ユーザが「2. ログイン用のリンク作成」で作成したリンクにアクセスすると、JugemKey の認証画面が表示され、JugemKey のID とパスワードを入力して認証します。既に JugemKey にログインしている場合には、cookie により認証されます。

認証後、あなたのサービスに対して、指定されたパーミッションを与えることを許可するかどうかの確認画面が表示されます。

ユーザが許可すると、ログインリンクに含まれる コールバック URL に、frob を付加した以下の様な URL を Location ヘッダとして返します。

http://yourService.jp/?frob=e5976e098a9f0daf

ブラウザがこの URL へリダイレクトされることによって、あなたのサービスへ frob が渡されます。frob は 認証のための token との引き換えチケットで、1度 token と交換されると、破棄されて利用できなくなります。

4. ユーザ情報と token の取得

frob が取得できたら、ユーザ情報と token を取得するために、http://api.jugemkey.jp/api/auth/token に 以下の様なリクエストを投げます。(秘密鍵が 1d4c74a7cc19aeb1 の場合の例です。)

GET /api/auth/token HTTP/1.x
X-JUGEMKEY-API-CREATED: 2006-05-20T01:09:39Z
X-JUGEMKEY-API-KEY: ccbcdd4f6350a590e9a4fe3f0642ee82
X-JUGEMKEY-API-FROB: e5976e098a9f0daf
X-JUGEMKEY-API-SIG: d9347152773f47d6ff08d0aa4b249240133c514b

X-JUGEMKEY-API-CREATED にはリクエスト時の時刻を W3C Date and Time Formatsで指定します。

X-JUGEMKEY-API-KEY には APIキーを指定します。

X-JUGEMKEY-API-FROB には frob を指定します。

X-JUGEMKEY-API-SIG は、 APIキーの値, 時刻, frob の順で値のみを文字列連結して、秘密鍵をキーとした HMAC_SHA1 で生成した署名コードです。

API キー, 時刻, frob, 署名コードがすべて正しい場合には、以下の様な Atom Entry が返ります。 X-JUGEMKEY-API-CREATED の時刻がリクエスト時点の時刻から5分以上ずれている場合には、エラーとなります。

HTTP/1.x 200 OK

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#" xmlns:auth="http://pepabo.com/atom/auth#">
  <title xmlns="http://purl.org/atom/ns#">JugemKey のユーザ名</title>
  <auth:token xmlns="http://purl.org/atom/ns#">XXXXXXXXXXXXXXXXXXXXX</auth:token>
</entry>

エラーの場合は以下の様な XML が返ります。

HTTP/1.x 401 Unauthorized

<?xml version="1.0" encoding="utf-8"?>
<error>Invalid X-JUGEMKEY-API-TOKEN</error>

あなたのサービスでは、この token を利用してユーザ情報取得や、他の GMOペパボぺぱぼ サービス API 利用時の 認証を行うことになります。

5. token を利用したユーザ情報の取得

token を利用すると、ユーザ情報の取得(現在はユーザ ID のみ)や、他の GMOペパボ サービス API での認証が可能になります。token からユーザ情報を取得するには、http://api.jugemkey.jp/api/auth/user に 以下の様なリクエストを投げます。(秘密鍵が 1d4c74a7cc19aeb1 の場合の例です。)

GET /api/auth/user HTTP/1.x
X-JUGEMKEY-API-CREATED: 2006-05-20T01:09:39Z
X-JUGEMKEY-API-KEY: ccbcdd4f6350a590e9a4fe3f0642ee82
X-JUGEMKEY-API-TOKEN: cf9d4ee646b6e89d
X-JUGEMKEY-API-SIG: d74f07aaa00f6ca5b27b1dba90c8adb280b04155

X-JUGEMKEY-API-CREATED にはリクエスト時の時刻を W3C Date and Time Formatsで指定します。

X-JUGEMKEY-API-KEY には APIキーを指定します。

X-JUGEMKEY-API-TOKEN には token を指定します。

X-JUGEMKEY-API-SIG は、 APIキーの値, 時刻, token の順で値のみを文字列連結して、秘密鍵をキーとした HMAC_SHA1 で生成した署名コードです。

API キー, 時刻, token, シグネチャがすべて正しい場合には、以下の様な Atom Entry が返ります。 X-JUGEMKEY-API-CREATED の時刻がリクエスト時点の時刻から5分以上ずれている場合には、エラーとなります。

HTTP/1.x 200 OK

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#" xmlns:auth="http://pepabo.com/atom/auth#">
  <title xmlns="http://purl.org/atom/ns#">JugemKey のユーザ名</title>
</entry>

エラーの場合は以下の様な XML が返ります。

HTTP/1.x 401 Unauthorized

<?xml version="1.0" encoding="utf-8"?>
<error>Invalid X-JUGEM-API-TOKEN</error>

FAQ

開発者向け FAQ

Q. JugemKey 認証 API はどんな人が利用するのですか?
主に JugemKey ユーザ向けにウェブサービスを開発したい方が利用します。 JugemKey は およそ 20 万人のユーザが利用しています。
Q. JugemKey 認証 API を利用すると何ができますか?
ユーザの管理や認証を JugemKey に任せることで、ご自身でユーザ管理をする必要なく、認証が必要なウェブサービスを開発/提供することが可能になります。JugemKey 認証 API を利用したサービスとしては、以下のものがあります。
Q. 利用するには JugemKey へのユーザ登録が必要ですか?
はい、必要です。
Q. 利用方法は?
「認証 API 仕様/開発者向けサービスへの組み込み方法」をご参照ください。
Q. 今後の機能拡張の予定は?
以下の様な機能拡張を予定しています。
  • ユーザが自身のアイコンを登録できるようにし、API経由でアイコンを取得できるように。
  • PAIPO フィード API を公開し、認証 API 経由で認証や、フィードの登録/取得などができるように。
  • 外部サービス開発者が JugemKey ユーザへ課金できる仕組みの提供。
  • ユーザ情報のJSON形式での出力。
  • ログイン画面カスタマイズ機能。
Q. 商用利用は可能ですか?
商用のサービスで利用される場合は、お問い合わせフォーム にてお問い合わせください。
各プログラミング言語用ライブラリはありますか?
以下の言語用ライブラリを提供しています。
PHP4
JugemKey Authentication API Class
PHP5
JugemKey Authentication API Class
Perl
WebService::JugemKey::Auth

外部サービス利用者向け FAQ

Q. JugemKey 認証 API を利用した外部サービスから直接 JugemKey のパスワードを求められることはありますか?
JugemKey 認証 API は、外部サービスに直接パスワードを渡すことなく認証できる仕組みづくりのために提供されています。したがいまして、secure.jugemkey.jp ドメイン以外の外部サービスから直接パスワードの入力を求められた場合、あなたのパスワードを騙し取ろうとしている可能性がありますので、ご注意ください。
Q. JugemKey 認証 API を利用した外部サービスには、自分に関するどんな情報が渡されますか?
あなたの JugemKey ユーザID のみが 外部サービスに渡されます。パスワードやメールアドレスなど、ユーザID以外の情報が渡されることは一切ありません。
Q. JugemKey 認証 API を利用した外部サービスにはどんなものがありますか?
JugemKey 認証 API を利用したサービスとしては、以下のものがあります。