OAuth 2.0 Web サーバーフローを実装する

メモ

日本語で受講されている方へ
Challenge は日本語の Trailhead Playground で開始し、かっこ内の翻訳を参照しながら進めていってください。Challenge での評価は英語データを対象に行われるため、英語の値のみをコピーして貼り付けるようにしてください。日本語の組織で Challenge が不合格だった場合は、(1) この手順に従って [Locale (地域)] を [United States (米国)] に切り替え、(2) [Language (言語)] を [English (英語)] に切り替えてから、(3) [Check Challenge (Challenge を確認)] ボタンをクリックしてみることをお勧めします。

翻訳版 Trailhead を活用する方法の詳細は、自分の言語の Trailhead バッジを参照してください。

フローの選択

ヘルプデスクユーザー用の顧客注文状況接続アプリケーションを作成したら、アプリケーションのフローを実装する必要があります。接続アプリケーションによって外部の Web サービス (顧客注文状況 Web サイト) と Salesforce API が統合されるため、OAuth 2.0 Web サーバーフローを使用する必要があります。この認証フローでは、認証コード許可種別を使用します。この OAuth 2.0 フローについて再確認が必要な場合は、「接続アプリケーションの基本」モジュールを参照してください。

認証コードを要求する

OAuth 2.0 Web サーバーフローを開始するために、顧客注文状況 Web サービスは接続アプリケーション経由で (認証コード許可種別を使用して) 認証コード要求を Salesforce 認証エンドポイントに POST します。認証コードは、言わば訪問者のバッジです。これを使用することにより、接続アプリケーションは、サイトへの安全な訪問者として認証されていて、アクセストークンを要求する権限を持っていることを証明できます。

コールは、次のような HTTP リダイレクトの形式で行われます。

https://mycompany.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=code

このようなコールの種別を使い慣れていなくても心配はいりません。では、個々のコンポーネントを詳しく見ていきましょう。

コンポーネント 1

https://mycompany.my.salesforce.com/services/oauth2/authorize

このアドレスは、Salesforce インスタンスの OAuth 2.0 認証エンドポイントであり、接続アプリケーションが OAuth 認証要求を送信するエンドポイントです。

コンポーネント 2

client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq

クライアント ID は接続アプリケーションのコンシューマー鍵です。コンシューマー鍵にアクセスするには、接続アプリケーションの [Manage Connected Apps (接続アプリケーションを管理する)] ページで [Manage Consumer Details (コンシューマーの詳細を管理)] をクリックして、ID を確認します。

コンポーネント 3

redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback

リダイレクト URI は、認証に成功した後にユーザーがリダイレクトされる場所です。リダイレクト URI は 接続アプリケーションのコールバック URL であり、接続アプリケーションの [Manage Connected Apps (接続アプリケーションを管理する)] ページでも確認できます。

この画像は、サンプルコードに対応するコールバック URL を示しています。接続アプリケーションには、「単元1: 接続アプリケーションを作成する」で入力したコールバック URL https://openidconnect.herokuapp.com/callback を使用します。

コンポーネント 4

response_type=code

応答種別を指定することによって、接続アプリケーションが要求している OAuth 2.0 許可種別が Salesforce に指示されます。code という応答種別は、接続アプリケーションが認証コードを要求していることを示します。

ユーザーを認証し、アプリケーションにアクセス権を付与する

Salesforce が接続アプリケーションに認証コードを提供する前に、Salesforce 組織にログインして自分自身を認証する必要があります。

ログインに成功したら、[Allow (許可)] をクリックして、接続アプリケーションが Salesforce 組織のデータにアクセスすることを承認します。

コールバックを受信する

アプリケーションを認証したら、Salesforce から認証コードと共にコールバックが接続アプリケーションに送信されます。

https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==

コンポーネント 1

コールバックの最初の部分は、接続アプリケーションのコールバック URL です。

https://www.mycustomerorderstatus.com/oauth2/callback

コンポーネント 2

2 つ目の部分は、アプリケーションを認証する認証コードです。

code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==

アクセストークンを要求する

これで、接続アプリケーションで有効な認証コードが取得されました。次に、接続アプリケーションはその認証コードを 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

このコールについても、個々のコンポーネントを見ていきましょう。

コンポーネント 1

POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded

このコンポーネントの最初の 2 行は、Salesforce インスタンスの OAuth 2.0 トークンエンドポイントに対して行われる POST 要求です。このエンドポイントは、接続アプリケーションがアクセストークンと更新トークンの要求を送信する場所です。

2 つ目の 2 行には、要求のコンテンツの長さと種別が表示されています。

コンポーネント 2

grant_type=authorization_code

許可種別では、安全な訪問者であることを証明するために接続アプリケーションが提供できる検証の種別が定義されます。この場合、認証コードが提供されています。

コンポーネント 3

code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA

認証コードは、認証サーバー (この場合は Salesforce) から取得する一時的な値です。接続アプリケーションでは、アクセストークンと引き換えにこのコードが使用されます。この種別の OAuth 2.0 フローは、アプリケーションにアクセストークンを戻すための安全な方法です。

コンポーネント 4

client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq

このコンポーネントも見覚えがあると思います。[Manage Connected Apps (接続アプリケーションを管理する)] ページにある、接続アプリケーションのコンシューマー鍵です。

コンポーネント 5

client_secret=*******************

クライアントの秘密は、接続アプリケーションのコンシューマー鍵と同じです。コンシューマーの秘密には、コンシューマー鍵にアクセスする場合と同じ方法でアクセスします。[Manage Connected Apps (接続アプリケーションを管理する)] ページで、[Manage Consumer Details (コンシューマーの詳細を管理)] をクリックして、ID を確認します。

この画像は、サンプルコードに対応するコールバック URL を示しています。接続アプリケーションには、「単元1: 接続アプリケーションを作成する」で入力したコールバック URL https://openidconnect.herokuapp.com/callback を使用します。

コンポーネント 6

redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback

最初の 2 つコールにおけるこのコンポーネントを覚えていますか? これは接続アプリケーションのコールバック URL です。

アクセストークンを受信する

接続アプリケーションの作成時に、[Require Secret for Web Server Flow (Web サーバーフローの秘密が必要)] オプションを選択しました。この要件は、アプリケーションから有効なコンシューマーの秘密が送信されない限り、Salesforce が接続アプリケーションにアクセストークンを提供できないことを意味します。そこで、このステップでは、Salesforce によって接続アプリケーションの認証コード、コンシューマー鍵、コンシューマーの秘密が検証されます。

Salesforce で接続アプリケーションのログイン情報が検証された後、JSON 形式でアクセストークンが返されます。アクセストークンには、範囲の形態で関連付けられている権限、さらにアプリケーションの ID トークンも含まれています。

{
"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://mydomain.my.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}

手順を確認する

さて、次は OAuth 2.0 Web サーバーフローをテストしてみましょう。このフローでは、Salesforce インスタンスとコールバック URL の間で機密情報が渡されるため、この情報が任意の場所に渡されないようにすることが非常に重要です。認証フローの安全なデモを行うため、この目的のためだけに構築された安全な OpenID Connect の Playground が使用されます。OpenID Connect の Playground は、データを保護しながら認証フローを表示する安全な Heroku サーバーでホストされています。

このフローを実際に実装する場合、データが安全に保存されるように、コールバック URL には安全なホストを使用することが不可欠です。

それでは始めましょう。まず、このプロジェクトの 1 つ目のステップで作成した接続アプリケーションについて、次の情報を収集します。

• コンシューマー鍵
  
• コンシューマーの秘密
  
• コールバック URL
  

また、Trailhead Playground の私のドメイン URL も必要です。これは [Setup (設定)] | [My Domain (私のドメイン)] で確認できます。

試してみる

1. OpenID Connect の [Playground] を開きます。
   
2. Trailhead Playground の私のドメイン URL をコピーして、ログインホストとして https:// の後に貼り付けます。
   
3. 接続アプリケーションのコンシューマー鍵を貼り付けます。
   
4. 接続アプリケーションのコンシューマーの秘密を貼り付けます。(OpenID Connect の [Playground] では情報の送信に POST が使用されます。つまり、クライアントの秘密はログに記録されません。)
   
5. 接続アプリケーションのコールバック URL が、リダイレクト URI (コールバック URL) と一致していることを確認します。ヒント: このコールバック URL は、このプロジェクトの 1 つ目のステップで入力しました。
   

6. [Next (次へ)] をクリックして、認証コードの要求を送信します。OpenID Connect の Playground が Trailhead Playground にアクセスすることを許可するよう求めるプロンプトが表示されたら、[Allow (許可)] をクリックします。要求に成功すると、認証コードが送信されます。ページの右側には、認証要求と Heroku サーバーの応答が表示され、上述の要求と応答のようになります。
   

7. [Next (次へ)] をクリックして、アクセストークンを要求します。要求に成功すると、アクセストークンと ID トークンの両方が送信されます。ページの右側には、アクセストークン要求と Heroku サーバーの応答が表示され、上述の要求と応答のようになります。 
   

8. [Next (次へ)] を再度クリックして、Heroku サーバーにアクセストークンを渡します。Heroku サーバーは、接続アプリケーションのメタデータを使用して応答します。
   

追加課題: 注文状況データにアクセスする

お疲れさまでした。OAuth 2.0 Web サーバーフローを正常に実装できました。これで、顧客注文状況接続アプリケーションで、Salesforce 組織に要求を送信し、特定の注文の注文状況データにアクセスできるようになりました。接続アプリケーションの要求には、アクセストークンが含まれています。Salesforce 組織は、アクセストークンとその関連付けられている範囲を検証した後、アプリケーションに注文状況データへのアクセス権を付与します。

このトレイルの対象範囲を超える場合は、次の手順を実行して注文状況を取得することができます。

1. Trailhead Playground で注文を作成します。Salesforce ヘルプの「注文」を参照してください。
   
2. 適切な cURL クエリを使用して、Salesforce REST API を介して新しい注文の状況を取得します。 ヒント macOS プラットフォームでは、Windows 10 ビルド 17063 と同様に cURL が自動的にサポートされます。プラットフォームに cURL がまだインストールされていない場合は、https://curl.haxx.se/ からダウンロードできます。
   Linux など、macOS や Windows 以外のプラットフォームを使用している場合は、プラットフォームの要件に準拠するように、必要に応じて cURL クエリを変更してください。
   Mac cURL クエリ: curl https://<your_trailhead_domain>/services/data/v55.0/sobjects/Order/<order_ID>\?fields\=Status -H 'Authorization: Bearer <access_token>' -H "X-PrettyPrint:1"
   Windows cURL クエリ: curl https://<your_trailhead_domain>/services/data/v55.0/sobjects/Order/<order_ID>?fields=Status -H “Authorization: Bearer <access_token>” -H "X-PrettyPrint:1"
   cURL クエリでは、必ず次のように置き換えてください。
   

• <your_trailhead_domain> を Trailhead Playground のドメイン名に置き換える。
  
• <order_ID> を [Order (注文)] ページの URL 内にある注文 ID に置き換える。 
  

• <access_token> を OpenID Connect の Playground から受信したアクセストークンと置き換える。
  

3. クエリが正常に実行されると、次のような応答が返ってきます。
   

   {
   "attributes" : {
   "type" : "Order",
   "url" : "/services/data/v55.0/sobjects/Order/8014P000001s9OLXXX"
   },
   "Status" : "Draft",
   "Id" : "8014P000001s9OLXXX"
   }

接続アプリケーションを管理する

今度は、Salesforce システム管理者の役割を担ってみましょう。次のステップでは、接続アプリケーションへのアクセスを管理します。

リソース

• Salesforce ヘルプ: OAuth 認証フロー
  
• Salesforce ヘルプ: Web アプリケーションインテグレーションの OAuth 2.0 Web サーバーフロー
  
• Trailhead: API の基本