Zooomr API: 認証 API

認証の必須条件

Zooomr認証APIを使うアプリケーションはあらかじめZooomr APIキー?を入手しておかなければなりません。 APIキーは以下の設定を持っています。

• アプリケーション名
• アプリケーションの説明
• アプリケーションについてのURL (推奨,非必須)

APIキーがZooomrに認められたとき、'共有キー'と呼ばれる特別なトークンが割り当てられます。 この秘密のトークンは署名プロセスに使われます。詳細は 署名呼び出しを参照してください。

アプリケーションがAPIキーと共有キーを手に入れると、Webベース か 非Webベース の二つの認証メソッドを使えるようになります。 各アプリケーションキーは一度に一つの認証メソッドにのみ関連づけられます。

Webベース認証

Web-based 認証を使うには、開発者はコールバックURL?を登録しないといけません。 このURLが何に使われるかはWebベースアプリケーションの認証で説明します。

非Webベース認証

非Webベース認証は特に手順は必要ありません。

Webベースアプリケーションの認証

Webベースアプリケーションがユーザーの認証を必要とする時、以下のURLにリダイレクトします。

http://www.zooomr.com/services/auth/?api_key=[api_key]&perms=[perms]&api_sig=[api_sig]

以下は上記のURLの内訳の説明です。

• api_key アプリケーションのAPI Key
• perms アプリケーションがユーザーに代わって操作を行うために必要な権限の要求レベル。詳しくは認証権限の説明を参照してください。
• api_sig シグネチャー。詳しくは署名呼び出しの説明を参照してください。

まず、ユーザーがZooomrにログインしていない時は、ログインするように求められます。

次にZooomrはユーザーにこのアプリケーションに認証を与えるかを訊ねます。 アプリケーション名と説明と共に、アプリケーションの要求する権限の説明が表示されます。 そして、その要求をユーザーが許可をするか、しないかを選択するプロンプトが表示されます。

ユーザーがそのアクセスレベルでアカウントにアクセスする許可を与えた時、自動的にAPIキーに登録されたコールバックURLへリダイレクトが行われます。 コールバックURLには以下の引数が追加されます。

?frob=[frob]

アプリケーションは直ちにAPIメソッドの zooomr.auth.getToken を呼び出し、APIキーと受け取ったフロブの値を渡さなければなりません。 また、この呼び出しは共有キーで署名されていなければなりません。(署名呼び出しの説明を参照してください) リクエストが正しいものであれば、このメソッドは以後の許可された権限でのZooomr APIの呼び出しに利用する認証トークンを返します。

Webベース認証トークンの更新

認証トークンを更新するには、Webペースのアプリケーションは先に定義した認証URLに単にリダイレクトするだけで行えます。 ユーザーがZooomrにログインしていて、以前にアプリケーションに要求された権限で認証を与えていた場合(または一部の権限を与えていた場合)で、且つトークンの期限が切れていない場合、権限を許可するページを素通りして、フロブと共にアプリケーションのコールバックURLにリダイレクトされます。 アプリケーションは新しいトークンを取得するため、zooomr.auth.getToken を呼び出さなければなりません。

実装に関する重要なガイドライン

• アプリケーションが、認証情報をクッキー中に保存する場合、一つのセッションにのみ保存しておく必要があります。
• ユーザーへの'ログアウト'のリンクを用意しておかなければなりません。

非Webベースアプリケーションの認証

デスクトップやブラウザで使うもの以外のアプリケーションがユーザーの認証を必要とするとき、 まず zooomr.auth.getFrob を呼び出します。また、そのメソッドは署名を必要とします。(署名呼び出しの説明を参照してください) メソッドの呼び出しに対する応答は、ユーザに認証を続けさせるためのURLを構築するのに必要な'フロブ' を含んでいます。

http://www.zooomr.com/services/auth/?api_key=[api_key]&perms=[perms]&frob=[frob]&api_sig=[api_sig]

パラメータはウェブペースアプリケーションの認証で説明したものと同一です。

ユーザーが権限を許可した時、コールバックURLにリダイレクトする代わりに、Zooomrは完了画面を表示し、アプリケーションの操作に戻るように促します。

ユーザーがアプリケーションに戻り、認証の継続を求めた時、アプリケーションは zooomr.auth.getToken を呼び出し、APIキーとフロブの値を渡す必要があります。 (この呼び出しは署名されていなければなりません。署名呼び出しを参照してください) この呼び出しが正しいものであった時、このメソッドの応答は、以後許可された権限でのZooomr APIの呼び出しに使用する認証トークンを返します。

非Webベース認証トークンの更新

トークンの更新が必要か、必要な権限を持っているかをチェックするには、アプリケーションは zooomr.auth.checkToken を利用します。 トークンが不正な場合、または必要な権限を持っていない場合、アプリケーションは新規に取得するのと同じ手順で新しいトークンをリクエストする必要があります。

実装に関する重要なガイドライン

• 認証トークンを含むユーザープロファイルデータはOSの提供するローカルのユーザー設定内に保存されるべきです。そのようにすることで、複数のプロファイル/ユーザーで認証情報を共用すること無く、切り替えることができます。

WindowsではHKEY_CURRENT_USER以下のレジストリに相当します。OSXや*NIXではホームディレクトリとなります

• ユーザーの認証情報や個人情報を消去する方法を用意しておかなければなりません。

認証権限

常識的に言って、アプリケーションは操作に対して必要以上の権限を求めるべきではありません。 権限フィールドは分かりづらい文字列で権限レベルを表しています。 それぞれのレベルはそのレベル以下の権限を含んでいます。 指定可能な権限は以下の通りです

• read -> プライベート情報の読み出し権限
• write -> オブジェクト(写真、その他)、メタデータの書き込み、編集、削除。 read 権限を含みます。
• delete -> オブジェクト(写真、その他)の削除。 write と{{{ read}} 権限を含みます。

例えば write 権限はユーザーに代わって、アプリケーションに read と write }} を行うことを許可します。 {{{ delete は delete 、 write 、 read 、全ての権限を許可します。

認証フロブ

それぞれの認証フロブはユーザーとアプリケーションの関係を示しています。 単独のフロブはそれを作ったアプリケーションキーと合わせたときのみ使うことができます。 認証フロブは作成されてから60分間まで、またはアプリケーションが zooomr.auth.getToken を呼び出した時まで有効です。

注意 一度に、ユーザー一人につき、一つのアプリケーション、一つの認証フロブのみが有効です。アプリケーションは有効期限が過ぎたり、不正な認証フロブには柔軟に対処し、必要な時に再発行するようにしなければなりません。

認証トークン

それぞれの認証トークンはユーザーとアプリケーションのAPIキーの関係を示しています。トークンは他のアプリケーションキーとは合わせて使うことができません。

アプリケーションはAPIメソッド zooomr.auth.checkToken を呼び出すことで、認証トークンの状態をチェックすることができます。 このメソッドはトークンの正当性、認証をしたユーザーについての情報、許可された権限について返します。

追加機能として、ユーザーがアプリケーションに対する認証の有効期間をどのように選択しているか、認証トークンを使って検出させることができます。有効期間は1時間か、期限無しかを設定することができます。

注意 一度に、ユーザー一人につき、一つの認証トークンのみが有効です。 アプリケーションは有効期限が過ぎたり、不正な認証トークンには柔軟に対処し、必要な時に再発行するようにしなければなりません。 また、認証トークンを使った全てのAPI呼び出しは、署名されていなければなりません。 (署名呼び出しを参照してください)

署名呼び出し

認証トークンを使った全てのAPI呼び出しは、必ず署名されていなければなりません。 加えて、 zooomr.auth.* メソッドの呼び出し、全てのZooomrの認証ページへのリダイレクト転送もまた署名されていなければなりません。

署名アルゴリズムは以下の通りです。:

• 引数のリストをパラメータキーの名前でアルファベット順にソートします。(例: foo=1, bar=2, baz=3 を並び替え、 bar=2, baz=3, foo=1 にします)
• 共有キーと引数のキーと値の組み合わせを繋ぎ合わせます。(例: SECRETbar2baz3foo1)
• この文字列のmd5()ハッシュ値を計算し、16進数の文字列にします。
• ハッシュ値を引数リストに api_sig という名前で追加します。(例: api_sig=d25100ff30af7ad87f5da8a509c4b6a5)