Connect REST API 開発者ガイド
jWeb サーバー OAuth 認証フロー
通常、このフローを使用するのは、クライアントの秘密を機密扱いで保存できる Web アプリケーションです。Web サーバーフローで非常に重要な点として、アプリケーションがコンシューマーの秘密を保護できる必要があります。
一般的なフローは次のようになります。個々のステップについては、その後に説明します。
OAuth Web サーバーフローの概要を次に説明します。
- リソースの認証を要求するために、クライアントアプリケーションは、エンドユーザーのブラウザーをリソース所有者の認証サーバーでホストされている Web ページにリダイレクトします。この場合は、Salesforce ログインページです。
- エンドユーザーが Salesforce にログインして自分自身を認証します。リソース所有者 (Salesforce) がこの Web ページをホストし、エンドユーザーが Web ページで直接操作しているため、クライアント Web アプリケーションがユーザーのログイン情報を見つけることはありません。エンドユーザーは、クライアントアプリケーションの認証も行います。
- Salesforce は、指定されたコールバック URL を使用して認証コードをクライアントアプリケーションに返送します。
- 認証コードを取得したら、クライアントアプリケーションはアクセストークンを取得するための認証コードを返します。
- 認証コードの確認後、Salesforce はレスポンストークンを返します。エラーがなければ、レスポンストークンには、アクセスコード、更新トークン、追加情報が含まれます。
- 保護されるリソースは Connect REST API エンドポイントです。
Connect REST API および Salesforce による Web サーバーフローの使用
ここでは、OAuth Web サーバーフローを Salesforce および Connect 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 Connect REST API 要求を行うために使用可能なセッション ID。このセッション ID はユーザーインターフェースでは使用できません。このセッション ID は、ユーザーのセッションと同様に扱い、厳重に管理してください。 token_type 値は、アクセストークンを含むすべての応答の Bearer です。 refresh_token 新しいアクセストークン (セッション) を取得するために将来使用できるトークン。 instance_url https://instance_name など、ユーザーの組織のインスタンスを示す URL。 id ユーザーを識別し、ユーザーの詳細を照会するために使用できる ID URL。エンドユーザーに関する詳細な情報を取得するための HTTP 要求で使用できます。 signature 連結 ID と issued_at を含む client_secret (非公開鍵) で署名されている Base64 符��化された HMAC-SHA256 署名。この署名は、サーバーによる送信以降、ID URL が変更されなかったことの確認に使用できます。 issued_at いつ署名が作成されたか。