Web アプリケーションインテグレーションの OAuth 2.0 Web サーバーフロー
外部 Web アプリケーションを Salesforce API に統合するには、OAuth 2.0 認証コード許可種別を実装する OAuth 2.0 Web サーバーフローを使用します。このフローでは、Web アプリケーションをホストするサーバーが、クライアント ID とクライアントの秘密で定義された外部クライアントアプリケーションの ID を保護できる必要があります。
必要なエディション
| 使用可能なインターフェース: Salesforce Classic (使用できない組織もあります) および Lightning Experience の両方 |
| 使用可能なエディション: すべてのエディション |
特別なシナリオでは、ユーザーエージェントフローまたはユーザー名パスワードフローの代わりに、コード交換の証明鍵 (PKCE、「ピクシー」と呼ばれる) を使用する Web サーバーフローを使用することをお勧めします。code_challenge および code_verifier パラメーターを使用して、Web サーバーフローで PKCE を実装します。PKCE についての詳細は、Internet Engineering Task Force (IETF) を参照してください。また、すべての外部クライアントアプリケーションでユーザーエージェントフローまたはユーザー名パスワードフローを使用できないようにブロックすることをお勧めします。手順は、「認証フローをブロックしてセキュリティを強化」を参照してください。
Web サーバーフローを実装する使用事例を次に示します。先日、顧客の注文状況に安全にアクセスできる Web サービスを開発したとします。注文状況データは Salesforce CRM プラットフォームに安全に保存されています。ヘルプデスクユーザーに顧客の注文状況の表示を許可するには、注文状況アプリケーションを開発し、Web サーバーフローを使用して外部クライアントアプリケーションとして設定します。
- ヘルプデスクユーザーが、Order Status (注文状況) Web アプリケーションをクリックします。
- 外部クライアントアプリケーションが認証コード要求を Salesforce 認証エンドポイントに POST します。
- ユーザーが Salesforce のログインページにリダイレクトされます。ログインに成功したら、ユーザーはアプリケーションが注文状況データにアクセスすることを承認するように求められます。
- Order Status (注文状況) アプリケーションがデータにアクセスすることをユーザーが承認すると、Salesforce は認証コードを使用して Order Status (注文状況) アプリケーションにコールバックを送信します。
- Order Status (注文状況) アプリケーションがこの認証コードを Salesforce トークンエンドポイントに渡し、アクセストークンを要求します。
- Salesforce が認証コードを検証し、範囲の形式で関連付けられている権限を含むアクセストークンを返します。
- Order Status (注文状況) アプリケーションが、注文状況データへのアクセス要求を Salesforce に返します。この要求には、アクセストークンと関連付けられている範囲が含まれます。
- Salesforce がアクセストークンと関連付けられている範囲を検証します。
- Order Status (注文状況) アプリケーションが保護されているデータにアクセスでき、顧客の注文状況がアプリケーションに表示されます。
メモ アクセストークンが無効になった場合、外部クライアントアプリケーションは更新トークンを使用して新しいアクセストークンを取得できます。
この認証フローの各ステップを詳しく見ていきましょう。
認証コードの要求
OAuth 2.0 Web サーバーフローを開始するために、外部 Web サービスは外部クライアントアプリケーションを介して、認証コード許可種別を使用して認証コード要求を Salesforce 認証エンドポイントに POST します。認証コードを使用すると、外部クライアントアプリケーションは、サイトへの安全な訪問者として認証され、アクセストークンを要求する権限を持っていることを証明することができます。
認証コードは、HTTP リダイレクトの形式です。
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=code認証コード要求に次のパラメーターを含めます。
| パラメーター | 説明 |
|---|---|
Request Header
|
Salesforce OAuth 2.0 認証エンドポイント。外部クライアントアプリケーションは、このエンドポイントに OAuth 認証要求を送信します。 |
client_id
|
外部クライアントアプリケーションのコンシューマー鍵。コンシューマー鍵にアクセスするには、App Manager で外部クライアントアプリケーションを見つけて、ドロップダウンから [表示] を選択します。次に、[コンシューマーの詳細を管理] をクリックします。コンシューマー鍵を表示する前に、ID を検証するように求められることがあります。 |
redirect_uri
|
認証に成功した後にユーザーがリダイレクトされる URL。リダイレクト URI は、外部クライアントアプリケーションの [コールバック URL] 項目のいずれかの値と一致する必要があります。それ以外の場合、承認は失敗します。リダイレクト URI は、外部クライアントアプリケーションの [OAuth 設定] ページにあります。この値は URL エンコードされている必要があります。 |
response_type
|
外部クライアントアプリケーションが要求する OAuth 2.0 許可種別。このフローの値は、外部クライアントアプリケーションが認証コードを要求していることを示す code である必要があります。 |
認証コード要求に次のパラメーターを含めることもできます。
| パラメーター | 説明 |
|---|---|
scope
|
外部クライアントアプリケーションがアクセスできる保護されたリソースの種別を定義する権限。範囲を作成するときに外部クライアントアプリケーションに割り当て、認証フロー中に OAuth トークンに含めます。 このパラメーターを含めない場合、外部クライアントアプリケーションに割り当てられたすべての範囲が要求されます。このパラメーターに渡す範囲は、登録された範囲のサブセットである必要があります。有効なパラメーターについては、「OAuth トークンおよび範囲」を参照してください。 |
sso_provider
|
[私のドメイン] または Experience Cloud サイト用に設定されたシングルサインオン (SSO) ID プロバイダーの開発者名。このパラメーターを使用して、アプリケーションが SSO プロバイダーと統合されているかのような SSO 環境を作成できます。たとえば、このパラメーターを使用して、ヘッドレス ID 実装で SSO を提供できます。詳細は、「アプリケーションでのネイティブシングルサインオン環境の作成」を参照してください。 |
state
|
外部 Web サービスがコールバック URL に送信するように要求する状態。この値は URL エンコードされている必要があります。 |
immediate
|
ログインと承認をユーザーに要求するかどうかを決定する Boolean 値。デフォルト値は
|
code_challenge
|
トークン要求で このパラメーターは、
|
display
|
ログインページと認証ページの表示の種類を変更します。Salesforce は次の値をサポートします。
|
login_hint
|
ログインページにユーザー名を自動入力するための、有効なユーザー名の値 ( Experience Cloud サイトの |
nonce
|
ユーザー ID トークンを要求する場合に openid 範囲で使用します。ユーザー ID トークンは応答で返されます。このパラメーターは省略可能ですが、リプレイ攻撃の検出に役立ちます。
|
prompt
|
認証サーバーがユーザーに再認証および再承認を求める方法を指定します。Salesforce は次の値をサポートします。
ユーザーにログインおよび再認証を求めるには、スペースで区切られた |
Uvid-Hint ヘッダー |
必要に応じて、このフローをヘッドレスゲストフローに接続するには、UVID 値が含まれる JWT ベースのアクセストークンがある アプリケーションでゲストユーザーフローを実装する場合、必要に応じてこのヘッダーを使用して、ゲストユーザーの ID に関連付けられた一意の訪問者 ID (UVID) が含まれる JSON Web トークン (JWT) ベースのアクセストークンを渡すことができます。UVID を指定ユーザーフローに渡すことで、ゲストユーザーセッションから指定ユーザーセッションにユーザーの Cookie 設定などのコンテキスト情報を伝達できます。 |
uvid_hint 本文パラメーター |
プレーン リクエストボディで UVID を渡す代わりに、 |
ユーザーによるアクセスの認証および承認
Salesforce が外部クライアントアプリケーションに認証コードを提供する前に、認証ユーザーは Salesforce にログインするように求められます。
ログインが成功すると、Salesforce はユーザーを承認ページにリダイレクトし、アプリケーションにアクセス権を付与します。
ユーザーがすでにアクセスを承認している場合、アクセスを再度承認する必要はありません。
Salesforce による認証コードの付与
ユーザーが外部クライアントアプリケーションへのアクセスを承認すると、Salesforce はユーザーをコールバック URL にリダイレクトし、そこで認証コードを使用してコールバックを参照できます。
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- コールバックの最初の部分は、外部クライアントアプリケーションのコールバック URL
https://www.mycustomerorderstatus.com/oauth2/callbackです。 - 2 番目の部分は、外部クライアントアプリケーションがアクセストークンを取得するために使用する認証コードです
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==。認証コードの有効期限は 15 分です。
元のクエリ文字列に state パラメーターが含まれている場合、指定された状態が承認ステップに渡されます。
アクセストークンの要求
アクセストークンを要求するために、外部クライアントアプリケーションは認証コードを HTTP POST として Salesforce トークンエンドポイントに渡します。
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
例の POST には、次のパラメーターが含まれています。
| パラメーター | 説明 |
|---|---|
Request Header
|
要求ヘッダーには、次のパラメーターを含めることができます。
要求ヘッダーでは次のパラメーターもサポートされています。
|
grant_type
|
外部クライアントアプリケーションが安全な訪問者であることを証明するために提供できる検証の種別。Web サーバーフローの場合、値は authorization_code である必要があります。 |
code
|
認証サーバーから受信する一時的な認証コード。外部クライアントアプリケーションでは、アクセストークンと引き換えにこのコードが使用されます。この種別の OAuth 2.0 フローは、アクセストークンをアプリケーションに渡すための安全な方法です。 |
client_id
|
外部クライアントアプリケーションのコンシューマー鍵。コンシューマー鍵にアクセスするには、App Manager で外部クライアントアプリケーションを見つけて、ドロップダウンから [表示] を選択します。次に、[コンシューマーの詳細を管理] をクリックします。コンシューマー鍵を表示する前に、ID を検証するように求められることがあります。 |
client_secret
|
外部クライアント・アプリケーションのコンシューマーの秘密。コンシューマーの秘密にアクセスするには、App Manager で外部クライアントアプリケーションを見つけて、ドロップダウンから [表示] を選択します。次に、[コンシューマーの詳細を管理] をクリックします。コンシューマーの秘密を表示する前に、ID を検証するように求められることがあります。 このパラメータは、外部クライアントアプリケーションで [Web サーバーフローの秘密が必要(Require Secret for Web Server Flow)] が有効になっていない限り必要です。 |
redirect_uri
|
認証に成功した後にユーザーがリダイレクトされる URL。リダイレクト URI は、外部クライアントアプリケーションの [コールバック URL] 項目のいずれかの値と一致する必要があります。それ以外の場合、承認は失敗します。リダイレクト URI は、外部クライアントアプリケーションの [OAuth 設定] ページまたは外部クライアントアプリケーションの定義にあります。この値は URL エンコードされている必要があります。 |
次のパラメーターを含めることもできます。
| パラメーター | 説明 |
|---|---|
client_assertion
|
client_secret を渡す代わりに、client_assertion と client_assertion_type を指定できます。client_secret パラメーターが指定されていない場合、Salesforce は client_assertion と client_assertion_type をチェックします。「client_secret の代わりに client_assertion を使用する」を参照してください。 |
client_assertion_type
|
|
code_verifier
|
code_challenge パラメーターが認証要求で指定された場合にのみ必要です。
|
format
|
要求のヘッダーに含まれていない場合、予測される戻り形式を指定できます。
|
client_secret の代わりに client_assertion を使用します。client_secret ではなく client_assertion を指定する場合、client_assertion の値に次のパラメーターを含める必要があります。
iss—外部クライアントアプリケーション定義からのclient_id。sub—外部クライアントアプリケーション定義からのclient_id。aud— トークンサーブレット URL: https://hostname/services/oauth2/token。exp— 5 分以内のアサーションの有効期限 (UTC で測定された 1970-01-01T0:0:0Z からの秒数として表記)。
client_assertion も、OAuth コンシューマーがアップロードした証明書に関連付けられている非公開鍵で署名される必要があります。RS256 アルゴリズムのみサポートされています。private_key_jwt クライアント認証方式については、OpenID Connect の仕様を参照してください。
POST の本文でクライアントのログイン情報をパラメーターとして送信する代わりに、Salesforce では 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: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id と client_secret が POST の本文で送信される場合、認証ヘッダーは無視されます。Salesforce によるアクセストークンの付与
Salesforce は、外部クライアントアプリケーションのログイン情報を検証したら、アクセストークンを含む応答を返します。この例では、応答は JSON 形式です。
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
応答には、次のパラメーターが含まれます。
| パラメーター | 説明 |
|---|---|
access_token
|
外部クライアントアプリケーションが、クライアントアプリケーションの代わりに保護されたリソースへのアクセスを要求するために使用する OAuth トークン。範囲の形式の追加権限にはアクセストークンが付随することがあります。 |
signature
|
client_secret で署名されている Base64 エンコードされた HMAC-SHA256 署名。署名には連結された ID と issued_at value を含めることができます。これらを使用して ID URL がサーバーから送信された後に変更されていないことを確認できます。 |
scope
|
アクセストークンに関連付けられている範囲。 範囲は、クライアントがアクセスできる保護されたリソースの種別をさらに定義します。範囲を作成するときに外部クライアントアプリケーションに割り当て、認証フロー中に OAuth トークンに含めます。 有効なパラメーターについては、「OAuth トークンおよび範囲」を参照してください。 |
id_token
|
ユーザーの一意の識別子、トークンがいつ発行されたかを示すタイムスタンプなど、認証済みユーザーの属性が含まれる署名済みデータ構造。ID トークンによって要求元のクライアントアプリケーションも識別されます。「OpenID Connect の仕様」を参照してください。 このパラメーターは、scope パラメーターに |
instance_url
|
ユーザーの組織のインスタンスを示す URL。例: https://yourInstance.salesforce.com/。
|
id
|
ユーザーを識別し、ユーザーの詳細を照会するために使用できる ID URL。「ID URL」を参照してください。 |
token_type
|
Bearer トークン種別。アクセストークンを含むすべての応答で使用します。
|
issued_at
|
署名が作成されたときのタイムスタンプ (ミリ秒)。 |
応答には次のパラメーターを含めることもできます。
