仕様書

OAuth 1.0 資源所有者認可

[5] OAuth 1.0 クライアントは鯖にトークンcredentialsを要求するに先立ち、 鯖に対してアクセス要求を認可authorizeするよう利用者に求めなければなりません >>3。 この手順を資源所有者認可resource owner authorizationといいます。

[6] クライアントは、何らかの方法で鯖が広告した資源所有者認可のエンドポイントの URL を次の通り編集しつつ要求URL としなければなりません。 クライアントはその要求URLをHTTPリダイレクトその他の方法で資源所有者の利用者エージェントにアクセスさせます。 この時使う要求メソッドは GET でなければなりません。 >>3

[7] その URL の query に oauth_token 引数を追加します。

URL query (application/x-www-form-urlencoded)
oauth_token
一時credentials要求で鯖からクライアントに提供された一時credentialsの識別子 (oauth_token 引数の値) とします。 ただし、鯖は資源所有者に他の方法で一時credentialsの識別子を示させる方法を用意しているなら、 この引数を省略可能にできます。 >>3

[8] 鯖は、その他の引数も規定しても構いません >>3。

[91] OAuth 1.0 の拡張である xoauth_response_format 引数を使うと、通常のリダイレクトのかわりに XML や JSON などで結果を POST させることを求めることができます。 JSONP のための xoauth_json_callback 引数も規定されています。

xoauth_response_format 参照。実装例は見当たりません。

[88] Twitter は force_login、screen_name を規定しています >>87, >>89。いずれも省略可能です。

[81] Google は hd, hl, btmpl を規定していました。いずれも省略可能でした。 >>80

[108] Fitbit は locale、display、 requestCredentials を規定しています >>107。

[110] WP-API は wp_scope を規定しています >>109。

[116] Dropbox は locale、disable_signup を規定しています >>115。

[128] Evernote は preferRegistration 引数を規定しています >>127。

[130] UserVoice は guid, sso, scheme を規定しています >>129。

  • [87] GET oauth/authorize | Twitter Developers ( 版) https://dev.twitter.com/oauth/reference/get/oauth/authorize
  • [89] GET oauth/authenticate | Twitter Developers ( 版) https://dev.twitter.com/oauth/reference/get/oauth/authenticate
  • [80] OAuth 1.0 API Reference - Google Accounts Authentication and Authorization — Google Developers ( 版) https://developers.google.com/accounts/docs/OAuth_ref#GetAuth
  • [107] OAuth Authentication in the Fitbit API - API - Confluence ( 版) https://wiki.fitbit.com/display/API/OAuth+Authentication+in+the+Fitbit+API
  • [109] OAuth1/spec.md at master · WP-API/OAuth1 ( 版) https://github.com/WP-API/OAuth1/blob/master/docs/spec.md
  • [115] Dropbox - Core API - endpoint reference ( 版) https://www.dropbox.com/developers/core/docs
  • [127] 認証 - Evernote Developers ( 版) https://dev.evernote.com/intl/jp/doc/articles/authentication.php
  • [129] UserVoice OAuth Reference - UserVoice Developer (UserVoice 著, 版) https://developer.uservoice.com/docs/api/oauth/#_api_v1_oauth_authorize_

[9] 資源所有者認可で保安輸送路を使うか否かは鯖に任されていて、 OAuth としては規定されていません >>3。

[10] 鯖はまず資源所有者の identity を検証verifyしなければなりません。 その後認可要求をどう処理するかは鯖に委ねられています。 >>3

[16] 一般的には、鯖はまず資源所有者がそのWebアプリケーションにおけるアカウントでログイン状態にあるか (Cookie認証等で) 確認し、必要ならログイン処理を行います。 次に一時credentialsから調べた OAuth クライアントについての登録情報や、 (あれば) そのWebアプリケーションにおける可能な操作の範囲 (いわゆる scope) など判断に必要な情報を表示し、資源所有者に対して認可するか否かの選択を求めます。 (ログインしていない場合、ログインと認可を同時に確認する実装もあります。)[18] 既に一部の scope について認可していて、更に追加の scope の認可を求められている場合に差分だけ表示して確認を求める実装もあります。 また新たに要求された scope をすべて認可済みの時に、 確認を省略して直ちに HTTPリダイレクトする実装もあります >>21。 ただしその場合はセキュリティー的に問題ないか、鯖も資源所有者側の実装者も十分検討する必要があります。 特にクライアントcredentialsが流出している場合には、 資源所有者が気づかないうちにトークンcredentialsを与えてしまうことになるので危険です >>21。無確認でリダイレクトするのは特定の限定された scope のみとするなど、配慮が必要です >>21。

[53] 鯖は CSRF 対策が必要です。

[12] 鯖は、資源所有者が認可すると判断したら、 一時credentials要求の oauth_callback 引数、 あるいはその他の手段で指定されたコールバックURLがあれば、 資源所有者をそこにリダイレクトします。 >>3

[13] コールバックURL の query には次の引数を追加しなければなりません >>3。 既に query があるなら、末尾に追加しなければなりません >>3。

URL query
[14] oauth_token
クライアントから受信した一時credentialsの識別子 >>3。
[15] oauth_verifier
検証符号verification code >>3。

[111] WP-API は wp_scope 引数も追加します >>109。

[117] Dropbox は uid 引数も追加します >>115。

[20] コールバックURL は不適切な値が指定されるかもしれません。 oauth_callback を参照してください。

[17] 鯖は、クライアントがコールバックURL が提供しなかった場合には、 検証符号を表示し、資源所有者に対して手動でクライアントに入力するよう指示するべきです >>3。

[118] 資源所有者認可で資源所有者が認可しないことを選択した場合の動作は、 OAuth 仕様としては規定されていません。鯖によりコールバックURL にそのままリダイレクトしたり、別途設定した取り消し時の URL にリダイレクトしたりします。クライアント側にリダイレクトしなければならないとの規定もありません。

[119] Dropbox は、コールバックURLに not_approved 引数を追加してリダイレクトします >>115。

OAuth 2.0 認可エンドポイント

[2] OAuth 2.0 認可鯖の認可エンドポイントauthorization endpointは、 資源所有者から認可承諾を得るために使うものです。 認可符号承諾型と暗示的承諾型で使います。 >>1

認可エンドポイントへの要求

[22] クライアントが認可エンドポイントの位置を知る方法は OAuth 仕様の範囲外ですが、通常はサービスのドキュメントにより示されます >>1。

[24] 認可エンドポイントでは TLS を使わなければなりません >>1, >>48。 クライアントは RFC 6125 により認可鯖のTLS証明書を検証し鯖の identity を認証しなければなりません >>48 (HTTPS鯖認証)。

[57] spoofing により認可鯖が攻撃者に入れ替わっている危険性がありますから、 鯖の確認は重要です >>56。
  • [56] RFC 6819 - OAuth 2.0 Threat Model and Security Considerations ( 版) http://tools.ietf.org/html/rfc6819#section-4.2.1

[23] 認可エンドポイントの URL には application/x-www-form-urlencoded 形式の query を含めても構いません。素片識別子を含んではなりません。 query が含まれる場合には、引数を追加する場合には元の query を残して追加しなければなりません。 >>1

[37] 認可符号またはアクセストークンを取得するために資源所有者をリダイレクトする URL の構築時には、引数を URL query に application/x-www-form-urlencoded 形式で指定します >>36, >>44。次の引数があります。

URL query (application/x-www-form-urlencoded)
[68] response_type
認可符号の取得なら code、 アクセストークンの取得なら token でなければなりません >>36, >>44。OpenID Connect 暗示フローなら id_token token または id_token としなければなりません >>73。
[69] client_id
クライアント識別子を指定しなければなりません >>36, >>44。
[70] redirect_uri
リダイレクトURLを指定できます >>36, >>44。
[71] scope
適用範囲を指定できます >>36, >>44。
[72] state
局所状態を表す値を指定するべきです >>36, >>44。
code_challenge
PKCE
code_challenge_method
PKCE

[67] OpenID Connect は、次の引数を規定しています。いくつかは必須です。

  • nonce
  • claims
  • display
  • prompt
  • max_age
  • ui_locales
  • id_token_hint
  • login_hint
  • openid2_realm >>90
  • registration
  • request
  • request_uri
  • response_mode
  • acr_values

[75] Google は OpenID 2.0 からの移行のための独自の openid.realm と独自の hd、access_type、 include_granted_scopes を追加しています >>76。 approval_prompt >>77 という引数もあるようです。

[83] Azure は resource と domain_hint を追加しています >>82。

[93] Spotify は show_dialog を追加しています >>92。

[95] Slack は team を追加しています >>94。

[97] reddit は duration を追加しています >>96。

[99] Salesforce は code_challenge, immediate を追加しています >>98。

[103] SurveyMonkey は api_key を追加しています >>102。

[106] Viadeo は lang, cancel_url を追加しています >>105。

[113] Yahoo! は language を追加しています >>112。

[121] Dropbox は force_reapprove と disable_signup を追加しています >>120。

  • [76] OpenID Connect (OAuth 2.0 for Login) - Google Accounts Authentication and Authorization — Google Developers ( 版) https://developers.google.com/accounts/docs/OpenIDConnect
  • [77] Using OAuth 2.0 for Web Server Applications - Google Accounts Authentication and Authorization — Google Developers ( 版) https://developers.google.com/accounts/docs/OAuth2WebServer
  • [82] OAuth 2.0 in Azure AD ( 版) https://msdn.microsoft.com/en-us/library/azure/dn645545.aspx
  • [90] draft: OpenID 2.0 to OpenID Connect Migration 1.0 - draft 08 ( 版) http://openid.net/specs/openid-connect-migration-1_0.html
  • [92] Web API Authorization Guide - Spotify Developer ( 版) https://developer.spotify.com/web-api/authorization-guide/
  • [94] OAuth | Slack (Slack 著, 版) https://api.slack.com/docs/oauth
  • [96] OAuth2 · reddit/reddit Wiki ( 版) https://github.com/reddit/reddit/wiki/OAuth2#user-content-authorization
  • [98] Understanding the Web Server OAuth Authentication Flow ( 版) https://www.salesforce.com/us/developer/docs/api_rest/Content/intro_understanding_web_server_oauth_flow.htm
  • [102] SurveyMonkey - Guide OAuth ( 版) https://developer.surveymonkey.com/mashery/guide_oauth
  • [105] OAuth 2.0 Authentication | Viadeo API ( 版) http://dev.viadeo.com/documentation/authentication/oauth-authentication/
  • [112] Yahoo OAuth 2.0 Guide - Yahoo Developer Network ( 版) https://developer.yahoo.com/oauth2/guide/
  • [120] Dropbox - Core API - endpoint reference ( 版) https://www.dropbox.com/developers/core/docs
  • [131] 楽天ウェブサービス(RAKUTEN WEBSERVICE) ( 版) http://webservice.rakuten.co.jp/document/oauth

[74] OpenID Connect は URL query を直接使うのではなく、 JWT 要求オブジェクトによって間接的に指定する方法も規定しています。

[31] クライアントは、要求の response_type 引数で code (認可符号承諾型) か token (暗示的承諾型) か拡張の承諾型を表す値のいずれかを指定しなければなりません >>1。

[29] 要求の引数は、複数指定してはなりません >>1。

[25] 認可鯖は、認可エンドポイントにおいて GET 要求メソッドに対応しなければなりません。 POST 要求メソッドに対応しても構いません。 >>1

[132] 楽天は GET と POST に対応しています >>131。

認可エンドポイントでの処理

[4] 認可鯖は、まず資源所有者を認証 (identity を検証verify) しなければなりません >>1, >>36。 認可鯖が資源所有者を認証する方法は、 OAuth 仕様の範囲外で、利用者名と合言葉によるログインであれ、 セッションクッキーであれ、任意の方法を使うことができます >>1。

>>122

[52] 認可エンドポイントでは CSRF 対策を行わなければなりません >>48。

[32] 認可鯖は、 response_type 引数が指定されていない時や理解できない時は、 誤りを返さなければなりません >>1。

[35] 認可鯖はすべての必須の引数が指定されており、妥当であることを確認します。 >>36, >>44

[26] 要求の引数で値のないものは、指定されなかったものとして扱わなければなりません >>1。

[27] 値がないというのは、 application/x-www-form-urlencoded で = が含まれない組のことでしょうか? 空文字列と区別されるということでしょうか?

[28] 認可鯖は、認識できない引数を無視しなければなりません >>1。

[38] 認可鯖は、資源所有者に尋ねるなり、その他何らかの手段を使うなりして、 資源所有者から認可するかの決定を得ます >>36, >>44。

リダイレクトエンドポイントへのリダイレクト

[34] 認可鯖は、資源所有者がアクセス要求を承諾したら、 資源所有者をクライアント (のリダイレクトエンドポイント) へとリダイレクトにより戻します >>1, >>36, >>44。

[39] 認可符号を求められている場合で資源所有者の認可が得られた場合には、 リダイレクトURLの query には application/x-www-form-urlencoded 形式で次の引数を追加します >>36。

URL query (application/x-www-form-urlencoded)
code
認可鯖が生成した認可符号を指定しなければなりません。
state
クライアントが認可の要求に state 引数を指定していれば、まったく同じ値を指定しなければなりません。

[84] Azure は更に admin_consent と session_state を追加しています >>82。

[45] アクセストークンを求められている場合で資源所有者の認可が得られた場合には、 リダイレクトURLの素片識別子には application/x-www-form-urlencoded 形式で次の引数を追加します >>33。

素片識別子 (application/x-www-form-urlencoded)
access_token
認可鯖が発行したアクセストークンを指定しなければなりません >>33。
token_type
発行したトークンの種類を指定しなければなりません >>33。
expires_in
アクセストークンの寿命を秒単位で指定するべきです >>33。
scope
クライアントが要求した適用範囲とアクセストークンの適用範囲が異なるなら、指定しなければなりません。同じ場合も指定できます。 >>33
state
クライアントが認可の要求に state 引数を指定していれば、まったく同じ値を指定しなければなりません >>33。
id_token
OpenID Connect の場合は指定しなければなりません。

[46] この場合更新トークンを発行してはなりません >>33。

[100] Salesforce は独自の id, instance_url, issued_at, signature を指定するようです。 >>101

[114] Yahoo! は独自の xoauth_yahoo_guid を指定するようです >>112。

  • [101] Force.com REST API Developer's Guide ( 版) https://www.salesforce.com/us/developer/docs/api_rest/

[43] 資源所有者がアクセス要求を拒んだ場合やリダイレクトURLの欠如や非妥当ではない点で要求に問題がある場合には、 認可符号を求められているならリダイレクトURLの query、 アクセストークンを求められているならリダイレクトURL の素片識別子に application/x-www-form-urlencoded 形式で次の引数を追加します >>41, >>33。

URL query/素片識別子 (application/x-www-form-urlencoded)
error
誤り符号を指定しなければなりません。
error_description
人間可読な誤りの説明を指定して構いません。
error_uri
人間可読な誤りの説明を含むWebページの URL を指定して構いません。
state
クライアントが認可の要求に state 引数を指定していれば、まったく同じ値を指定しなければなりません。

[30] 応答の引数は、複数指定してはなりません >>1。

[78] OpenID による拡張である要求の request_mode 引数は、 URL query と素片識別子、あるいは application/x-www-form-urlencoded のいずれの方法で応答の引数を返すべきかを指定するものです。

[79] Google の拡張はリダイレクトURLの指定により素片識別子でなく URL query を使うことを求めたり、リダイレクトのかわりに認可符号を含む HTML文書を表示させること、窓を閉じることを求めるHTML文書を表示させることを指定できるようにしています。

[40] リダイレクトエンドポイント、認可符号も参照。

[42] リダイレクトURLが指定されていない場合、非妥当な場合、一致しない場合や、 クライアント識別子が指定されない場合や非妥当な場合には、 資源所有者に誤りを知らせるべきであり、 自動的に非妥当なリダイレクトURLにリダイレクトしてはなりません。 >>1, >>41, >>33

[51] OAuth 1.0 の oauth_callback=oob に相当する仕組みは用意されていません。他の承諾型を使うなどするべきです。

資源所有者に対する認可の確認画面

[122] 認可鯖は認可するか尋ねるに当って HTTP クライアントが当該サービス上のどの資源所有者であるか認証する必要があります。この認証は Cookie認証その他当該サービスの従来の方式によるもので、 OAuth の仕様の範囲外です。

[123] HTTP クライアントがCookieを有していないなど認証されない状態でアクセスしてきている場合には、 ログイン画面へ誘導する、あるいは認可と同時にログインを求める、 認可と同時に credentials の入力を求めるといった方法でどの資源所有者か特定する必要が生じます。

[124] そのため、資源所有者認可ステップは複数回の認可鯖-HTTPクライアント (資源所有者) 間のやり取りで構成される場合があります。

[125] 認可鯖のサービス上のアカウントを既に保有していない HTTP クライアントからのアクセスだった場合には、 新規のアカウント登録を求める認可鯖もあります。そのような利用方法を認めていない場合や、 認めるかどうかを OAuth クライアントに指定させる場合もあります。

[126] 特にこの場合には次のステップに進むまで時間がかかることがあり、 OAuth 1.0 一時credentialsの有効期限を超過する虞もあります。

[11] 要求されたアクセスを認可するかどうか OAuth 1.0 鯖が資源所有者に尋ねるときには、 一時credentialsとクライアントの identity との関連付けに基づき、アクセスを要求しているクライアントについての情報を表示するべきです。 表示に際しては、その情報が検証verifyされたものかどうか示すべきです。 >>3

[50] OAuth 2.0 認可鯖は、資源所有者の認証を明示的に行った上で、 クライアントや要求されている認可の適用範囲や寿命についての情報を資源所有者に提供するべきです。 現在のクライアントに照らしてその情報を確認し認可するかどうかを判断するのは資源所有者の責任です。 >>48

トークンエンドポイントのクライアント認証の項も参照。

[59] 認可鯖は資源所有者に対して認可の適用範囲を理解可能な形で説明し、 必要以上の権限をクライアントに与えてしまわないように注意する必要があります >>58。

[61] 認可鯖は、既に過去に認可を得ている場合には、 資源所有者に対する確認を省いて自動的にリダイレクトしてクライアントに戻すことができます >>60。

[49] OAuth 2.0 認可鯖は、繰り返される認可の要求について、 クライアント認証が行われる場合やその他の手段で本来のクライアントから求められていると確認できる場合を除き、 (明示的に資源所有者が操作せずに) 自動的に処理するべきではありません >>48, >>62。 また自動承認する適用範囲を限定することも好ましいかもしれません >>60。

[86] Twitter その他 >>85, >>104, >>107 はOAuthログインと認可で資源所有者認可エンドポイントを別にしており、 後者では自動リダイレクトはしないとしています。

[19] この確認画面はクリックジャッキング対策が必要です >>63。 またWebブラウザー以外で表示したり、アドレスバーを隠したりするのはフィッシングの疑いを拭い去れないため、避けるべきと考えられています。

[47] ネイティブアプリケーションは埋め込みブラウザー (アプリ内ブラウザー) ではなく外部のブラウザーを使うべきです >>48。

[55] 不正なクライアントは埋め込みブラウザーを使って、 資源所有者の認証で入力された利用者名と合言葉を盗む >>54 など、 不適切な動作をするかもしれません。 (認可に限らず) 埋め込みブラウザーによってフィッシングサイトを表示するなどの危険性があります。 利用者に啓蒙する、アプリマーケットで審査するといった対策は挙げられてはいますが >>54、 OAuth の仕様の内外を問わず、根本的に解決するのは難しい問題です。

[65] また不正なクライアントは埋め込みブラウザーを使って資源所有者に無断で機械的に認可 (認可鯖のフォームを勝手に POST など) する >>64 こともあるかもしれません。 CAPTCHA などにより資源所有者が実際に操作していることを確認したり、 認可後に電子メールなどで資源所有者に通知したりする対策が必要かもしれません >>64。

[66] Final: OpenID Connect Core 1.0 incorporating errata set 1 ( 版) http://openid.net/specs/openid-connect-core-1_0.html#Terminology

Authorization Request

OAuth 2.0 Authorization Request as defined by [RFC6749].

[133] Using OAuth 2.0 — Fitbit Web API Docs () https://dev.fitbit.com/docs/oauth2/

Any attempt to embed the OAuth 2.0 authentication page will result in your application being banned from the Fitbit API.

For security consideration, the OAuth 2.0 authorization page must be presented in a dedicated browser view. Fitbit users can only confirm they are authenticating with the genuine Fitbit.com site if they have the tools provided by the browser, such as the URL bar and Transport Layer Security (TLS) certificate information.

For native applications, this means the authorization page must open in the default browser. Native applications can use custom URL schemes as redirect URIs to redirect the user back from the browser to the application requesting permission.

iOS applications may use the SFSafariViewController class instead of app switching to Safari. Use of the WKWebView or UIWebView class is prohibited.

Android applications may use Chrome Custom Tabs instead of app switching to the default browser. Use of WebView is prohibited.

For web applications, do not use an iframe. Web applications may use a pop-up window, so long as the URL bar is visible.

[134] 認証と認可 | Cacoo Developer API | Nulab ( ()) https://developer.nulab-inc.com/ja/docs/cacoo/auth/#2-oauth

OAuth での認証からアカウント登録を行う場合、以下のパラメータを Authorize の URL に指定することで、アカウント登録フォームへの事前入力ができます。

Name Description

signup.mailAddress アカウントのメールアドレス

signup.nickname アカウントのニックネーム