更新セッションの OAuth 2.0 更新トークンフロー
OAuth 2.0 更新トークンフローは、OAuth 2.0 Web サーバーフローまたは OAuth 2.0 ユーザーエージェントフローによって発行されたアクセストークンを更新します。
必要なエディション
| 使用可能なインターフェース: Salesforce Classic (使用できない組織もあります) および Lightning Experience の両方 |
| 使用可能なエディション: すべてのエディション |
クライアントは、接続アプリケーション経由でアクセストークンを取得すると、現在のセッションの期限が切れたときに更新トークンを使用して新しいセッションを取得できます。接続アプリケーションのセッションタイムアウト値によって、アクセストークンを無効にするタイミングおよび更新トークンを使用して新しいトークンを適用するタイミングが決まります。
セキュリティを強化するために、接続アプリケーションまたは外部クライアントアプリケーションで OAuth 設定を定義するときに更新トークンのローテーションを有効にします。この設定を有効にすると、フローが呼び出されるたびに、接続アプリケーションはアクセストークンと共に新しい更新トークンを発行します。以前の更新トークンは自動的に無効になります。更新トークンのローテーションにより、各更新トークンがユーザーごとに 1 回のみ使用されるため、更新トークンを使用して新しいアクセストークンを取得することはできません。循環から外れた更新トークンを使用しようとすると、Salesforce は現在の更新トークンおよび関連付けられているアクセストークンを無効にします。新しい更新トークンを取得するには、クライアントが新しいフローを完了する必要があります。
- 接続アプリケーションは既存の更新トークンを使用して、新しいアクセストークンを要求します。
- 要求の確認後、Salesforce はクライアントに新しいアクセストークンを付与します。
更新されたアクセストークンの要求
接続アプリケーションは更新トークンを使用して、次のいずれかの更新トークン POST 要求を Salesforce トークンエンドポイントに送信することで、新しいアクセストークンを取得できます。
接続アプリケーションは、次のように更新トークン POST 要求の本文で client_id と client_secret を送信することができます。
POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com/
grant_type=refresh_token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=1955279925675241571&
refresh_token=your token here 更新トークン POST 要求の本文でクライアントのログイン情報をパラメーターとして送信する代わりに、HTTP 基本認証スキームを使用できます。このスキームの形式では、次のように POST の認証ヘッダーに client_id と client_secret が必要です。
Authorization:
Basic64Encode(client_id:secret)
client_id と client_secret はコロン (:) で区切ります。詳細は、「OAuth 2.0 認証フレームワーク」を参照してください。
次の例は、POST 要求の本文でクライアントのログイン情報を送信する代わりに HTTP 基本認証スキームを使用する更新トークン POST 要求を示しています。
POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com
Authorization: Basic
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&
client_secret=1955279925675241571
grant_type=refresh_token&
refresh_token=your token here 
client_id と client_secret が POST の本文で送信される場合、認証ヘッダーは無視されます。同じ更新トークンが含まれる要求を同時に送信しないでください。クライアントが同時に同一の要求を送信すると、一部の要求が断続的に失敗し、[ログイン履歴] の [状況] 列に「失敗: トークン要求はすでに処理中です」と表示されます。新しいアクセストークンの要求を継続的に送信する代わりに、トークンをキャッシュして再利用します。同じ更新トークンを使用して同時に要求を送信する場合は (推奨されません)、このエラーが発生したときに要求を再試行する方法を開発します。
いずれかの更新トークン POST 要求形式を使用して、次のパラメーターを含めます。
| パラメーター | 説明 |
|---|---|
client_id
|
接続アプリケーションのコンシューマー鍵。コンシューマー鍵にアクセスするには、アプリケーションマネージャーで接続アプリケーションを検索し、ドロップダウンから [表示] を選択します。次に、[コンシューマーの詳細を管理] をクリックします。コンシューマー鍵を表示する前に、ID を検証するように求められることがあります。 |
client_secret
|
接続アプリケーションのコンシューマーの秘密。コンシューマーの秘密にアクセスするには、アプリケーションマネージャーで接続アプリケーションを検索し、ドロップダウンから [表示] を選択します。次に、[コンシューマーの詳細を管理] をクリックします。コンシューマーの秘密を表示する前に、ID を検証するように求められることがあります。 |
grant_type
|
接続アプリケーションが要求する OAuth 2.0 許可種別。このフローの値は refresh_token である必要があります。 |
refresh_token
|
Web サーバー、ユーザーエージェント、またはハイブリッドアプリケーショントークンフローから取得したトークン。この値は秘密です。適切な対策を講じて保護してください。このパラメーターは、refresh_token 範囲を使用して接続アプリケーションが設定されている場合にのみ返されます。 |
client_assertion
|
client_secret を渡す代わりに、client_assertion と client_assertion_type を指定できます。client_secret パラメーターが指定されていない場合、Salesforce は client_assertion と client_assertion_type をチェックします。「client_secret の代わりに client_assertion を使用する」を参照してください。 |
client_assertion_type
|
|
format
|
要求のヘッダーに含まれていない場合、予測される戻り形式を指定できます。
|
Salesforce による新しいアクセストークンの付与
要求の確認後、Salesforce は新しいアクセストークンが含まれる応答を接続アプリケーションに送信します。
Salesforce からの JSON 応答の例を次に示します。
{
"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448384422",
"instance_url":"https://yourInstance.salesforce.com/",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4",
"token_type":"Bearer",
"scope":"id api refresh_token"
}XML 応答の例を次に示します。
<Oauth>
<access_token>00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNB
aT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4
</access_token>
<token_type>Bearer
</token_type>
<scope>id api refresh_token
</scope>
<instance_url>https://yourInstance.salesforce.com/</instance_url>
<id>https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P</id>
<issued_at>1278448101416</issued_at>
<signature>CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe+fVg=</signature>
</Oauth>次の例は、URL エンコードされた応答を示しています。
access_token=00Dx0000000BV7z%21AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7TrqoDjoNIWQ2
ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4
&token_type=Bearer&scope=id%20api%20refresh_token
&instance_url=https%3A%2F%2FyourInstance.salesforce.com
&id=https://login.salesforce.com%2Fid%2F00Dx0000000BV7z%2F005x00000012Q9P
&issued_at=1278448101416
&signature=CMJ4l%2BCCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe%2BfVg%3D接続アプリケーションまたは外部クライアントアプリケーションで更新トークンの循環が有効になっている場合、応答には新しい更新トークンが含まれます。更新トークンの循環が有効になっている場合の JSON 応答の例を次に示します。
{
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7T...",
"refresh_token":"CjAwRHgwMDAwMDAwQlY3eiFBUjhBUVAwaklUTjgwRVNFc2o1RWJhWl...",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"scope":"id api refresh_token",
"instance_url":"https://yourInstance.salesforce.com/",
"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P"
"token_type":"Bearer",
"issued_at":"1278448384422",
}次のパラメーターはレスポンスボディに含めることができます。
| パラメーター | 説明 |
|---|---|
access_token
|
接続アプリケーションがクライアントアプリケーションの代わりに保護されたリソースへのアクセスを要求するために使用する OAuth トークン。範囲の形式の追加権限にはアクセストークンが付随することがあります。 |
refresh_token
|
新しい更新トークン。次回更新トークンフローを呼び出すときに新しいアクセストークンを取得するには、更新トークンを使用します。このパラメーターは、接続アプリケーションまたは外部クライアントアプリケーションで更新トークンの循環を有効にする場合にのみ含まれます。 |
token_type
|
Bearer トークン種別。アクセストークンを含むすべての応答で使用します。 |
token_format
|
接続アプリケーションまたは外部クライアントアプリケーションで JSON Web トークン (JWT) ベースのアクセストークンの発行が有効になっている場合、応答にはアクセストークンの形式を示す次のパラメーターが含まれます。値は アプリケーションが不透明アクセストークンを発行する場合、このパラメーターは含まれません。 |
instance_url
|
ユーザーの組織のインスタンスを示す URL。例: https://yourInstance.salesforce.com/。 |
id
|
ユーザーを識別し、ユーザーの詳細を照会するために使用できる ID URL。「ID URL」を参照してください。 |
issued_at
|
署名が作成されたときのタイムスタンプ (ミリ秒)。 |
signature
|
client_secret で署名されている Base64 エンコードされた HMAC-SHA256 署名。署名には連結 ID と issued_at value 値を含めることができます。これらを使用して ID URL がサーバーから送信された後に変更されていないことを確認できます。 |
sfdc_site_url
|
ユーザーが Experience Cloud のメンバーである場合、サイトの URL が提供されます。 |
sfdc_site_id
|
ユーザーが Experience Cloud のメンバーである場合、ユーザーのサイト ID が提供されます。 |
