REST API 開発者ガイド
jWeb サーバ OAuth 認証フローでのアプリケーションの認証
セキュアなサーバ上でホストされているアプリケーションは、Web サーバ認証フローを使用します。Web サーバフローでの重要な点は、サーバがコンシューマの秘密を保護できる必要があるということです。また、フロー内でコード確認と検証値を使用して、認証コードの傍受を防ぐことができます。
このフローでは、クライアントアプリケーションは、他の Web サーバまたはリソースにユーザをリダイレクトするように認証サーバに要求します。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 — クライアントに情報を戻す前に、認証サーバがユーザに再認証を求める必要があります。
scope アプリケーションがアクセスできるデータを指定します。詳細は、Salesforce ヘルプの「範囲パラメータの値」を参照してください。 state 承認後にコールバック URL で返される、追加の URL 符号化された状態データを指定します。 - ユーザが自分のログイン情報で Salesforce にログインします。ユーザは認証エンドポイントを直接操作するため、アプリケーションがユーザのログイン情報を認識することはありません。ログインに成功したら、ユーザはアプリケーションを認証するように要求されます。ユーザがすでにアプリケーションを認証している場合、このステップはスキップされます。
- クライアントアプリケーションが認証されたことが Salesforce で確認されると、エンドユーザの Web ブラウザは、redirect_uri パラメータで指定されたコールバック URL にリダイレクトされます。Salesforce は、認証情報を次の値でリダイレクト URL に付加します。
次の例は、認証情報が付属するコールバック URL を示しています。
パラメータ 説明 code コンシューマがアクセストークンと更新トークンを取得するために使用する必要がある認証コード。認証コードの有効期限は 15 分です。 state 最初の要求の一部として渡される状態値 (該当する場合のみ)。 - アプリケーションは認証コードを抽出して、これをアクセストークン要求に含めて Salesforce に渡す必要があります。この要求は、適切な Salesforce トークン要求エンドポイント (https://login.salesforce.com/services/oauth2/token など) に対して送信される POST 要求です。次のパラメータは必須です。
次のパラメータは省略可能です。次の例は、本文で client_id と client_secret を送信するアクセストークン 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
POST 要求の本文でクライアントのログイン情報をパラメータとして送信する代わりに、Salesforce では HTTP 基本認証スキームがサポートされています。このスキーマでは、次のように要求の認証ヘッダーに client_id と client_secret が必要です。
Authorization: Basic64Encode(client_id:secret)
client_id と client_secret はコロン (:) で区切ります。詳細は、「OAuth 2.0 認証フレームワーク」を参照してください。
次の例は、(POST 要求の本文でクライアントのログイン情報を送信する代わりに) HTTP 基本認証スキームを使用するアクセストークン POST 要求を示します。
- この要求が成功した場合、サーバは次の内容を持つレスポンスボディを返します。
次の例は、JSON レスポンスボディを示しています。
- アプリケーションは、提供されたアクセストークンと更新トークンを使用して保護されたユーザデータにアクセスします。