Force.com REST API 開発者ガイド
jWeb サーバ OAuth 認証フローについて
安全なサーバでホストされているアプリケーションでは、Web サーバ認証フローを使用します。Web サーバフローにおける重要な点は、サーバがコンシューマの秘密を保護できる必要があります。また、フロー内の code challenge および code verifier の値を使用して、認証コードの傍受を防ぐこともできます。
このフローでは、クライアントアプリケーションは、ユーザを認証してアプリケーションに認証コードを送信する他の Web サーバまたはリソースにユーザをリダイレクトするように認証サーバに要求します。アプリケーションは認証コードを使用してアクセストークンを要求します。このフローの手順は、次のとおりです。
- アプリケーションはユーザを適切な Salesforce 認証エンドポイント (https://login.salesforce.com/services/oauth2/authorize など) にリダイレクトします。次のパラメータは必須です。
次のパラメータは省略可能です。
パラメータ 説明 response_type この認証フローの場合、code にする必要があります。 client_id 接続アプリケーション定義の [コンシューマ鍵]。 redirect_uri 接続アプリケーション定義の [コールバック URL]。 認証 URL の例は、次のようになります。パラメータ 説明 code_challenge トークン要求で code_verifier 値の SHA256 ハッシュ値を指定して、認証コードの傍受攻撃を防ぐのに役立てます。ハッシュ値は、https://tools.ietf.org/html/rfc4648#section-5 の定義に従って base64url エンコードする必要があります。 - 認証要求で code_challenge 値が指定され、トークン要求で code_verifier 値が指定されている場合、Salesforce により code_challenge が code_verifier と比較されます。code_challenge が無効であるか一致しない場合、ログインが invalid_request エラーコードで失敗します。
- 認証要求で code_challenge 値が指定されていても、トークン要求で code_verifier 値が指定されていない場合、ログインが invalid_grant エラーコードで失敗します。
display ログインページの表示の種類を変更します。有効な値は、次のとおりです。 - page — 全画面のページ認証。これは、値が指定されていない場合のデフォルト値です。
- popup — 最新の Web ブラウザのポップアップウィンドウ用に最適化されたコンパクトなダイアログ。
- touch — Android や iPhone など、最新のスマートフォン用に設計されたモバイル用に最適化されたダイアログ。
- mobile — BlackBerry OS 5 など、タッチスクリーンをサポートしていないスマートフォン用に設計された、モバイル用に最適化されたダイアログ。
immediate ログインと承認についてユーザにプロンプトメッセージを表示するかどうかを決定します。値は、true か false のいずれかです。デフォルトは false です。 - true に設定され、ユーザが現在ログインしており、以前にこのアプリケーションを承認している場合、承認ステップはスキップされます。
- true に設定され、ユーザがログインしていないか、これまでこのアプリケーションを承認したことがない場合、セッションはただちにエラーコード immediate_unsuccessful で終了します。
login_hint ログインページにユーザ名を自動入力するための、有効なユーザ名の値を指定します。たとえば、login_hint=username@company.com です。ユーザのブラウザにすでに有効なセッションがある場合は、login_hint パラメータの影響はなく、有効なユーザセッションが継続されます。 nonce 応答で返される値を指定します。「リプレイ」攻撃の検出に役立ちます。ユーザ ID トークンを取得する場合の openid 範囲に使用できます (省略可能)。 prompt 認証サーバがユーザに再認証および再承認を求める方法を指定します。このパラメータは省略可能です。Salesforce でサポートされる値は、次のとおりです。 - login — 認証サーバがユーザに再認証を求める必要があり、ユーザに強制的に再ログインさせます。
- consent — クライアントに情報を戻す前に、認証サーバがユーザに再認証を求める必要があります。
1?prompt=login%20consentscope アプリケーションがアクセスできるデータを指定します。詳細は、オンラインヘルプの「範囲パラメータの値」を参照してください。 state 承認後にコールバック URL で返される、追加の URL 符号化された状態データを指定します。 1https://login.salesforce.com/services/oauth2/authorize?response_type=code 2&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3X 3HrXDiCQjK1mdgAvhCscA9GE&redirect_uri=https%3A%2F%2Fwww.mysite.com%2F 4code_callback.jsp&state=mystate - ユーザが自分のログイン情報で Salesforce にログインします。ユーザは認証エンドポイントを直接操作するため、アプリケーションがユーザのログイン情報を認識することはありません。ログインに成功したら、ユーザはアプリケーションを認証するように要求されます。ユーザがすでにアプリケーションを認証している場合、このステップはスキップされます。
- クライアントアプリケーションが認証されたことが Salesforce で確認されると、エンドユーザの Web ブラウザは、redirect_uri パラメータで指定されたコールバック URL にリダイレクトされます。Salesforce は、認証情報を次の値でリダイレクト URL に付加します。
認証情報が付属するコールバック URL の例は、次のようになります。
1https://www.mysite.com/authcode_callback?code=aWekysIEeqM9PiT 2hEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D - アプリケーションは認証コードを抽出して、これをアクセストークン要求に含めて Salesforce に渡す必要があります。この要求は、適切な Salesforce トークン要求エンドポイント (https://login.salesforce.com/services/oauth2/token など) に対して送信される POST 要求です。次のパラメータは必須です。
次のパラメータは省略可能です。アクセストークン POST 要求の例は、次のようになります。
パラメータ 説明 client_assertion client_secret を渡す代わりに、client_assertion および client_assertion_type を提供できます。client_secret パラメータが指定されていない場合、Salesforce によって自動的に client_assertion および client_assertion_type がチェックされます。client_assertion の値は、OAuth コンシューマがアップロードした証明書に関連付けられている非公開鍵で署名された一般的な JWT ベアラートークンである必要があります。現在、RS256 アルゴリズムのみがサポートされています。client_assertion の使用についての詳細は、private_key_jwt クライアント認証メソッドの「OpenID Connect の仕様」を参照してください。 client_assertion_type client_assertion パラメータを使用するときにこの値を指定します。client_assertion_type の値は、urn:ietf:params:oauth:client-assertion-type:jwt-bearer でなければなりません。 code_verifier 高エントロピの 128 バイトのランダムなデータを指定して値の推測を困難にすることで、認証コードの傍受攻撃を防ぐのに役立てます。この値も、https://tools.ietf.org/html/rfc4648#section-5 の定義に従って base64url エンコードする必要があります。 - トークン要求で code_verifier 値が指定され、認証要求で code_challenge 値が指定されている場合、Salesforce により code_verifier が code_challenge と比較されます。code_verifier が無効であるか一致しない場合、ログインが invalid_grant エラーコードで失敗します。
- トークン要求で code_verifier 値が指定されていても、認証要求で code_challenge 値が指定されていない場合、ログインが invalid_grant エラーコードで失敗します。
format 期待される戻り形式。デフォルトは json です。値は次のとおりです。 - urlencoded
- json
- xml
- Accept: application/x-www-form-urlencoded
- Accept: application/json
- Accept: application/xml
1POST /services/oauth2/token HTTP/1.1 2Host: login.salesforce.com 3grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ 4VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=3MVG9lKcPoNI 5NVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCs 6cA9GE&client_secret=1955279925675241571& 7redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp - この要求が成功した場合、サーバは次の内容を持つレスポンスボディを返します。
JSON レスポンスボディの例は、次のようになります。
1{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P", 2"issued_at":"1278448101416", 3"refresh_token":"5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xReb54_ 4pZebnUG0h6Sb4KUVDpNtWEofWM39yg==", 5"instance_url":"https://na1.salesforce.com", 6"signature":"CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe+fVg=", 7"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0R 8NBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"} - アプリケーションは、提供されたアクセストークンと更新トークンを使用して保護されたユーザデータにアクセスします。