Chatter REST API 開発者ガイド
jWeb サーバ OAuth 認証フロー
通常、このフローを使用するのは、クライアントの秘密を機密扱いで保存できる Web アプリケーションです。Web サーバフローで非常に重要な点として、アプリケーションがコンシューマの秘密を保護できる必要があります。
一般的なフローは次のようになります。個々のステップについては、その後に説明します。
OAuth Web サーバフローの概要を次に説明します。
- リソースの認証を要求するために、クライアントアプリケーションは、エンドユーザのブラウザをリソース所有者の認証サーバでホストされている Web ページにリダイレクトします。この場合は、Salesforce ログインページです。
- エンドユーザが Salesforce にログインして自分自身を認証します。リソース所有者 (Salesforce) がこの Web ページをホストし、エンドユーザが Web ページで直接操作しているため、クライアント Web アプリケーションがユーザのログイン情報を見つけることはありません。エンドユーザは、クライアントアプリケーションの認証も行います。
- Salesforce は、指定されたコールバック URL を使用して認証コードをクライアントアプリケーションに返送します。
- 認証コードを取得したら、クライアントアプリケーションはアクセストークンを取得するための認証コードを返します。
- 認証コードの確認後、Salesforce はレスポンストークンを返します。エラーがなければ、レスポンストークンには、アクセスコード、更新トークン、追加情報が含まれます。
- 保護されるリソースは Chatter REST API エンドポイントです。
Chatter REST API および Salesforce による Web サーバフローの使用
ここでは、OAuth Web サーバフローを Salesforce および Chatter REST API で使用する場合の詳細を具体的に説明します。
- 次の要求パラメータを指定して、クライアントの Web ブラウザをページ https://login.instance_name/services/oauth2/authorize に転送します。
パラメータ 説明 response_type この認証フローの場合、必ず code にする client_id このアプリケーション用に定義された接続アプリケーションからの [コンシューマ鍵] 値 redirect_uri このアプリケーション用に定義された接続アプリケーションからの [コールバック URL] 値 必要に応じて、次の要求パラメータを含めることもできます。パラメータ 説明 state 承認後にコールバック URL で返される、URL 符号化された状態データを指定します。 immediate ログインと承認についてユーザにプロンプトを表示するかどうかを決定します。値は、true か false のいずれかです。デフォルトは false です。 - true に設定され、ユーザがログインしており、以前にこのアプリケーションを承認している場合、承認ステップはスキップされます。
- true に設定され、ユーザがログインしていないか、これまでこのアプリケーションを承認したことがない場合、セッションはただちにエラーコード immediate_unsuccessful で終了します。
display 提供される Web ページの種別を示します。有効な値は、次のとおりです。 - page — 全画面のページ認証。これは、値が指定されていない場合のデフォルト値です。
- popup — 最新の Web ブラウザのポップアップウィンドウ用に最適化されたコンパクトなダイアログ。
- touch — Android や iPhone など、最新のスマートフォン用に設計されたモバイル用に最適化されたダイアログ。
- mobile — BlackBerry OS 5 など、機能の少ないスマートフォン用に設計されたモバイル用に最適化されたダイアログ。
- ログインに成功したら、ユーザはアプリケーションを認証するように要求されます。 ユーザがすでにアプリケーションを認証している場合、このステップはスキップされます。
- クライアントアプリケーションが認証されたことが Salesforce で確認されると、エンドユーザの Web ブラウザは、コールバック URL にリダイレクトされます。redirect_uri パラメータでコールバック URL を指定し、そのクエリ文字列に次の値を追加します。
クライアントアプリケーションサーバが redirect_uri Web ページをホストしていると想定されます。
パラメータ 説明 code アクセストークンと更新トークンを取得するために渡される認証コード state 最初の要求の一部として渡される状態値 (該当する場合のみ)。 - クライアントアプリケーションサーバは、認証コードを抽出して、次のクエリパラメータで URL、https://login.instance_name/services/oauth2/token に対して POST を使用し、これを含めたアクセストークン要求を Salesforce に渡す必要があります。
パラメータ 説明 grant_type このフローの値は authorization_code である必要があります。 client_id 接続アプリケーション定義のコンシューマ鍵。 client_secret 接続アプリケーション定義のコンシューマの秘密。client_secret が必須ではなくても、接続アプリケーションが認証要求で送信した場合は、Salesforce は認証を試みます。 redirect_uri 承認後にユーザをリダイレクトする URI。この URI は、接続アプリケーション定義の [コールバック URL] 項目の値に完全に一致している必要があります。また、最初のリダイレクトによって送信された値と同じ値です。 code 承認後にコールバックから取得される認証コード。 format 期待される戻り形式。このパラメータは省略可能です。デフォルトは、json です。値は次のとおりです。 - urlencoded
- json
- xml
- この要求が成功した場合、サーバは次の内容を保持するレスポンスボディを返します。
パラメータ 説明 access_token Chatter REST API 要求を行うために使用可能なセッション ID。このセッション ID はユーザインターフェースでは使用できません。このセッション ID は、ユーザのセッションと同様に扱い、厳重に管理してください。 refresh_token 新しいアクセストークン (セッション) を取得するために将来使用できるトークン。 instance_url https://instance_name など、ユーザの組織のインスタンスを示す URL。 id ユーザを識別し、ユーザの詳細をクエリするために使用できる ID URL。エンドユーザに関する詳細な情報を取得するための HTTP 要求で使用できます。 signature 連結 ID と issued_at を含むコンシューマの非公開キーで署名されている Base64 符号化された HMAC-SHA256 署名。この署名は、サーバによる送信以降、ID URL が変更されなかったことの確認に使用できます。 issued_at いつ署名が作成されたか。