=====
認証
=====

http://developer.foursquare.com/docs/oauth.html

.. The foursquare APIv2 can only be accessed via OAuth 2.0. This is
   really important to help us track usage of the API by your
   applications while keeping our users' data safe. It's a standard
   used by various large API providers, including the Facebook Graph
   API.

Foursquare APIv2 は `OAuth2.0 <http://oauth.net/2/>`_ を通してし
か使用できません。これはあなたのアプリケーションがユーザのデータを安全
に保っていることと、我々がAPIの利用状況を追跡することを手助けすることの
ために重要なことです。OAuth 2.0はFacebookのGraph APIなどの様々な巨大な
APIプロバイダーで使われている標準です。

.. If you had a rough experience trying to use OAuth 1.0, rest assured
   the new version is radically simpler and more awesome. There are
   various tutorials floating around, but one we found helpful was
   this blog post.

もし、OAuth 1.0を使った経験があるならば、新しいバージョンはもっと簡単で
もっと素晴らしいことが分かるでしょう。周囲にはさまざまなチュートリアル
がありますが、そのうちの一つ、 `このblog記事
<http://www.sociallipstick.com/?p=239>`_ が参考になるでしょう。

----------------------------
1. サインアップ
----------------------------

.. Start by registering your application and obtaining your API
   credentials. You may want to sign up under a separate account with
   an extra-secure password to own these credentials. Since each
   credential is tied to a particular URL, you may want to create a
   set of development credentials which point to your development
   server URL, and production credentials which point to your
   production server URL. For the purposes of OAuth2, your "key" from
   that registration process is your "id" here, and your secret from
   registering is your secret here.

始めるにあたり、まず、あなたの `アプリケーションを登録
<https://foursquare.com/oauth>`_ し、APIのクレデンシャルを取得します。
さらに安全なパスワードを使って、別のアカウントで登録することもできます。
それぞれのクレデンシャルは対応するURLと結びついているため、開発サーバの
URLを示す開発用クレデンシャル、製品サーバのURLを示す製品クレデンシャル
のセットを作ることも出来ます。OAuth2のために、登録処理によって得られた
あなたの"キー"はあなたの"id"であり、登録時のあなたのシークレットはあな
たのシークレットとなります。(訳註: 訳不正確)

-----------------------------
2. アクセストークンの取得
-----------------------------

新しいAPIを使用するには、大きく分けて三つの方法があります。

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Web アプリケーション
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(PHP, Perl, Ruby, Python, Java, Scala, など)

- 認証をしたいユーザを以下に **リダイレクト** 

::

  https://foursquare.com/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

- もしユーザが了承したら、以下のURLに再びリダイレクト 

::

  https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE  

- あなたのサーバは以下の **リクエストを生成** 

:: 

  https://foursquare.com/oauth2/access_token
    ?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &code=CODE

- レスポンスはJSONで返ってきます 

::
          
  { access_token: ACCESS_TOKEN }

- あなたのデータベースにこのアクセストークンを **保存** します


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
純粋な AJAX アプリケーション
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(Javascript)

- 認証をしたいユーザを以下に **リダイレクト** 

::
  
  https://foursquare.com/oauth2/authenticate
    ?client_id=CLIENT_ID
    &response_type=token
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

- もしユーザが了承したら、以下のURLに再びリダイレクト 

::

  http://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN    

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
携帯電話あるいはクライアント側のアプリケーション
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(Android Java, iOS Objective-C, など)

.. if you have a server that works with your application, we strongly
   prefer you use the server flow above, possibly in an embedded
   browser. Similar to the Facebook API, you can add display=touch to
   your authorize or authenticate URLs to get a mobile optimized
   interface.

もし、あなたのアプリケーションと一緒になって動くサーバがある場合、私た
ちは上記のサーバの場合を使うことを強く勧めます。これは埋め込みのブラウ
ザで動作するかもしれません。Facebook APIと同じように、モバイル用に最適
化されたインタフェースを得るために、あなたの認証や認証用URLに
`display=touch` を付け加えても構いません。

------------------------------------------------------
3. リクエストの作成
------------------------------------------------------

.. Once you have an access token. It's easy to use any of the
   endpoints, but just adding oauth_token=ACCESS_TOKEN to your GET or
   POST request. For example, from the command line, you can do

一度アクセストークンを得たら、どんな :doc:`エンドポイント <endpoint>`
も使うのは簡単です。oauth_token=ACCESS_TOKEN をGETかPOSTに付け加えるだ
けです。例えばコマンドラインから、以下のようにします。

::

  curl https://api.foursquare.com/checkin/history?oauth_token=ACCESS_TOKEN

いえい！たったこれだけです！

-----------------------------------
API v1 からの移行
-----------------------------------

.. If you have users who already registered with OAuth 1.0 for the old
  foursquare API, don't worry! All you have to do is use the user's
  secret as the oauth_token in APIv2 and you're good to go.

もしもあなたが古いfoursquare APIのために、OAuth 1.0で既に登録している場
合、心配しないでください！ユーザのシークレットをAPIv2のoauth_tokenとし
て使うだけです。


.. _auth-useless:

-----------------------------------
無意味なアクセス
-----------------------------------

.. Some endpoints (e.g. venue search) allow you to not act as any
  particular user. We will return unpersonalized data suitable for
  generic use, and the performance should be slightly better. In these
  cases, pass your client ID as client_id and your client secret as
  client_secret. Although the draft 11 of the OAuth2 spec provides a
  mechanism for consumers to act via token entitled Client
  Credentials, we do not currently support this.

(Venue 検索などの)いくつかのエンドポイントは特定のユーザに対してなにか
を行うわけではありません。この場合、私たちは使用個人情報に基づかない全
体のデータを返します。この時の性能は他のエンドポイントへのアクセスより
わずかに優れています。これらのエンドポイントの場合、あなたのクライアン
トIDを `client_id` として、あなたのクライアントシークレットを
`client_secret` として渡します。OAuth2仕様書のdraft 11によれば、
"Client Credentials"という名前のトークンを利用してコンシューマに対する
機構を提供する方法がありますが、私たちは現在この方式をサポートしていま
せん。

-----------------------------------
注意
-----------------------------------

.. OAuth2 can pass secrets in the clear without requiring manual
   signing of requests. The catch is that all requests must be via
   HTTPS, and you'll see errors when not using HTTPS.

OAuth2はリクエストの手動での署名を求めない場合、平文で送ることが出来ま
す。全てのリクエストはHTTPSを通して行われなければなりません。HTTPSを使
わない場合、エラーとなります。

.. Be sure to note that although API requests are against
   api.foursquare.com, OAuth token and authorization requests are
   against foursquare.com.

APIのリクエストは `api.foursquare.com` に対して行われていることに注意し
てください。OAuthトークンと認証リクエストは `foursquare.com` に対して行
われます。

.. The examples above use /authenticate instead of
   /authorize. Following precedent established by Twitter and
   LinkedIn, the /authenticate page is like /authorize except it will
   automatically redirect if a user has already authorized the calling
   page.

上記の例では `/authorize` の代わりに `/authenticate` を使用しています。
TwitterとLinkedInによる前例にならうと、 /authenticate ページは
/authorize と同じですが、もしユーザが既に認証されている場合は、自動的に
リダイレクトされる点が異なります。

.. The OAuth2 spec provides for Resource Owner Password Credentials,
   exchanging the user's password for a token, but we do not allow
   third-party clients to use this flow for security reasons.

OAuth2の仕様書ではユーザのパスワードをトークンと入れ替える Resource
Owner Password Credentials がありますが、私たちはセキュリティ上の理由に
より、サードパーティのクライアントにこれを使用することを許可していません。

.. One issue you may run into on Android is that foursquare uses a
   wildcard SSL cert. For more information, see this Stack Overflow
   answer.

foursquareがワイルドカードSSL証明書を使用しているため、Android上で動か
す時に、問題があるかもしれません。より詳細な情報は `Stack Overflowの回
ç­”
<http://stackoverflow.com/questions/3135679/android-httpclient-hostname-in-certificate-didnt-match-example-com-exa>`_
を見てください。

.. Although at this time we do not expire OAuth access tokens, you
   should be prepared for this possibility in the future. Also
   remember that a user may revoke access via the foursquare settings
   page at any time.

現在のところOAuthのアクセストークンが期限切れになることはありませんが、
あなたは将来的に期限切れになる可能性に備える必要があります。さらに、ユー
ザはいつでもfoursquareの設定ページでアクセスを中止することが出来る点を
覚えておいてください。