認証認可手順（旧方式） << mixi Developer Center (ミクシィデベロッパーセンター)

認証認可手順（旧方式）

各種APIをクライアントプログラムから利用するためには、OAuth 2.0 Protocolにより規定された認可を行うことが求められます。この手順により、クライアントプログラムがどのようなAPIアクセスを行い、そしてどのような情報が参照または更新されるのか（これをスコープと呼びます）がユーザに提示されます。ユーザの認証、および提示されたスコープについてユーザが同意した場合にのみ、クライアントプログラムはAPIにアクセスするための情報（トークンなど）を得ることができます。

[The OAuth 2.0 Protocol draft-ietf-oauth-v2-10]
http://openid-foundation-japan.github.com/draft-ietf-oauth-v2.ja.html

ここでは、APIを利用するために必要となる認証認可手順について説明いたします。

事前に必要なもの

認証認可手順を始めるためには、以下の情報をすでに入手している必要があります。

Consumer key (サービス登録後に発行されたもの)
Consumer secret (サービス登録後に発行されたもの)

これらを入手するためには、サービス管理のページをご覧ください。

認可とAuthorization Codeの入手

最初にクライアントプログラムは、Webブラウザにて以下のURLにアクセスします。

PC、スマートフォン向け： https://mixi.jp/connect_authorize.pl
携帯電話端末向け： http://m.mixi.jp/connect_authorize.pl

その際に指定しなければならないクエリーパラメータは以下となります。

パラメータ名	指定する値
client_id	Consumer key
response_type	“code”
scope	認可したいスコープ
display	認証認可画面を表示するデバイス
state	ユーザの認可後に行われるリダイレクト時にこの値が含まれます。アプリケーションがセッションを持つ場合、このパラメータを使用してセッションが維持されている事を確認してください。

scopeパラメータ値は、認可したいスコープを空白区切りで列挙した文字列を指定します。指定可能なスコープは、各APIの説明ページを参照ください。

displayパラメータは、クライアントプログラムのデバイスによって指定する値を使い分けます。指定可能なパラメータ値は、以下となります。

指定可能な値	意味
“pc”	PCデスクトップ向け画面が表示されます。
“touch” “smartphone”	スマートフォン向け画面が表示されます。
“ios”	iOSの場合に指定します。Appleの審査を通過するために、このパラメータを使用してください。

利用デバイスが携帯電話端末だった場合は、displayパラメータの指定は無視され、携帯電話端末向け画面が表示されます。その際、Docomo携帯端末の場合は、クエリパラメータとして「guid=ON」を付与してください。

stateパラメータを利用したセッション維持の確認がされない場合、アプリケーションにCSRF脆弱性が存在する事になります。これを防ぐために、セッションIDのハッシュ値等をstateパラメータに含めて下さい。そして、ユーザ認可後のリダイレクト時に、セッションとstateパラメータの組み合わせが正しいことを確認してください。詳しくは下記URLをご参照ください。
http://openid-foundation-japan.github.io/rfc6749.ja.html#CSRF

全てのパラメータ値は、URLエンコード済みの文字列を指定します。全体のURLは以下のようになるでしょう。

GET https://mixi.jp/connect_authorize.pl?client_id=908ed4da74f885a2ab&response_type=code&scope=r_profile%20r_voice&state=5c1b3eea390b53f54ad0975e9a4bbba2

各パラメータ値が正しければ、Webブラウザ上には認証または認可画面が表示されます。認証画面は、ユーザがすでに”http://mixi.jp/”または”https://mixi.jp/”にて最近ログインを行っていた場合は表示されません。また、携帯電話端末の場合について、ユーザがかんたんログインを設定していない場合は、その旨の案内ページが表示されます。認可画面には、先ほどscopeパラメータで指定したスコープの一覧が表示され、ユーザはクライアントプログラムが表示された処理をすることに同意するか選択します。

ユーザが同意した場合は、サービス登録時に入力したRedirect URLにリダイレクトされます。その際、クエリパラメータとしてcodeパラメータが付与されます。このcodeパラメータ値が、mixi Platformにて発行されたAuthorization Codeとなります。また、stateパラメータを指定していた場合は、クエリパラメータとしてその値も含まれます。リダイレクト時のURLは、例えば以下のようになります。

http://example.com/callback?code=347ab1db9398d60b5ef3515e672d1e&state=5c1b3eea390b53f54ad0975e9a4bbba2

発行されたAuthorization Codeの有効期限は3分となります。

リフレッシュトークン、アクセストークンの入手

クライアントプログラムは、発行されたAuthorization Codeを利用して、リフレッシュトークンおよびアクセストークンを入手します。そのために、クライアントプログラムは”https://secure.mixi-platform.com/2/token”にPOSTにてアクセスします。その際、以下のパラメータをリクエストボディにapplication/x-www-form-urlencoded形式で指定します。

パラメータ名	指定する値
grant_type	“authorization_code”
client_id	Consumer key
client_secret	Consumer secret
code	Authorization Code

全体のURLおよびリクエストボディは以下のようになるでしょう。

POST https://secure.mixi-platform.com/2/token

grant_type=authorization_code&client_id=908ed4da74f885a2ab&client_secret=9720b4826e90ad9f053a57500d3a8c697c01d1&code=347ab1db9398d60b5ef3515e672d1e

各パラメータが正しければ、レスポンスとして以下のような結果が返却されます。結果の形式は、application/jsonとなります。

{"refresh_token":"39c5662a2e8b87d41c1eebe79f68af","expires_in":900,"access_token":"c2be2257f3dae3df4efcb010ae6eea","scope":"r_profile r_voice"}

それぞれの値の意味は、以下となります。

パラメータ名	意味
refresh_token	アクセストークンを更新する際に利用するリフレッシュトークン文字列
expires_in	アクセストークンが失効するまでの時間(秒)
access_token	アクセストークン文字列
scope	ユーザーが認可したスコープを半角スペース区切りで連結した文字列

発行されたアクセストークンの有効期限は15分間となります。

リフレッシュトークンおよびアクセストークンの有効期間は、事前の予告なく変更する場合があります。そのため、これらの有効期間をクライアントプログラムにハードコーディングする、あるいはこれらの有効期間に基づく設計を行うことは避けるようお願いいたします。

もし、リクエストボディに指定したパラメータが不正であれば、リフレッシュトークンおよびアクセストークンは取得できません。その際、application/json形式のエラーメッセージが返されます。エラー内容は下記の通りです。

エラー内容	意味
{"error":"invalid_grant"}	code値が不正である
{"error":"invalid_client"}	client_idまたはclient_secret値が不正である
{"error":"unsupported_grant_type"}	grant_type値が不正である

APIへのアクセス

入手したアクセストークンを使用して、各種APIにアクセスすることができます。利用可能なAPIは、認可手順の際に指定したスコープに限定されます。

各APIを利用するためのURIはそれぞれ異なりますが、アクセストークンの指定は共通です。各種APIを呼び出す際に、 Authorizationリクエストヘッダにアクセストークンを指定します。例えば、以下のようになるでしょう。”OAuth”という文字列に続けて1 空白入れた後にアクセストークンを記述します。

GET /resource HTTP/1.1
Host: api.mixi-platform.com
Authorization: OAuth c2be2257f3dae3df4efcb010ae6eea

もしAuthorizationリクエストヘッダが使用できない状況の場合は、oauth_tokenパラメータにアクセストークンを指定することも可能です。例えば、People APIを利用する場合には、以下のようになるでしょう。


https://api.mixi-platform.com/2/people/@me/@self?oauth_token=c2be2257f3dae3df4efcb010ae6eea

通常はAuthorizationリクエストヘッダにてアクセストークンを指定するようにしてください。

APIアクセス時のエラーについて

APIへのアクセスの際に使用したアクセストークンが以下のような理由により無効だった場合、APIの呼び出しは失敗し、エラー内容がレスポンスとして返却されます。

アクセストークンの有効期限切れ
必要なスコープが認可されていない

この場合、HTTPレスポンスヘッダにエラー内容を示す”WWW-Authenticate”ヘッダが含まれます。

HTTP/1.1 401 Authorization Required
...
WWW-Authenticate: OAuth error='expired_token',realm='api.mixi-platform.com'

errorの値としては、以下の種類があります。

invalid_request	不正なリクエスト内容
invalid_token	不正なアクセストークン
expired_token	アクセストークンの有効期限切れ
insufficient_scope	アクセスに必要なスコープが認可されていない

アクセストークンの有効期限切れ (expired_token) の場合は「アクセストークンの再発行」を参考に再発行リクエストを発行してください。不正なアクセストークン (invalid_token) の場合は「認可とAuthorization Codeの入手」からやり直してください。

アクセストークンの再発行

発行されたアクセストークンの有効期限は短く、その有効期限を越えたアクセストークンを使用しても各APIへのアクセスは失敗します。クライアントプログラムは、リフレッシュトークンを使って、アクセストークンの再発行を行うことが可能です。リフレッシュトークンは、アクセストークンの発行時に含まれるrefresh_token値となります。

アクセストークンの再発行を行うために、クライアントプログラムは”https://secure.mixi-platform.com/2/token”にPOSTにてアクセスします（先ほどのアクセストークン発行時と同じです）。その際、以下のパラメータをリクエストボディにapplication/x-www-form-urlencoded形式で指定します。

パラメータ名	指定する値
grant_type	“refresh_token”
client_id	Consumer key
client_secret	Consumer Secret
refresh_token	リフレッシュトークン文字列

全体のURLおよびリクエストボディは以下のようになるでしょう。

POST https://secure.mixi-platform.com/2/token

grant_type=refresh_token&client_id=908ed4da74f885a2ab&client_secret=9720b4826e90ad9f053a57500d3a8c697c01d1&refresh_token=39c5662a2e8b87d41c1eebe79f68af

各パラメータの値が正しければ、以下のような結果を得るでしょう。

{"refresh_token":"39c5662a2e8b87d41c1eebe79f68af","expires_in":900,"access_token":"b1bdf0cd88d4b400dfe785da132a9a"}

access_token値として、新しく発行されたアクセストークンを得ることができます。この新しいアクセストークンを使用して、各種APIの利用を継続することが可能です。

リフレッシュトークンの期限切れ

リフレッシュトークンは、ユーザの認可状況あるいはAPIの利用状況によって、有効期限が切れることがあります。リフレッシュトークンの有効期限が切れていた場合にアクセストークンの再発行を試みた場合は、以下のようなレスポンスが返却されます。

HTTP/1.1 401 Authorization Required
Content-Type: application/json
...

{"error":"invalid_grant"}

期限の切れたリフレッシュトークンは一切使えませんので、改めて「認可とAuthorization Codeの入手」からやり直し、新しいトークンを取得するようにしてください。

このページの上部へ

mixi Developer Center (ミクシィ デベロッパーセンター)

mixi Connect