アクセストークンを使用した安全性の確保

学習の目的

この単元を完了すると、次のことができるようになります。

Marketing Cloud Engagement API と安全に連携する。
REST API と SOAP API の両方にアクセストークンを使用する。
トークンを更新すべき状況を認識する。

トークンの取得

Salesforce はセキュリティの問題に真剣に取り組んでいます。Marketing Cloud Engagement の REST API や SOAP API もその例外ではありません。Marketing Cloud Engagement は、API 要求の安全を確保するために、テナント固有のエンドポイントを提供しています (この後詳述します)。さらに、これらのエンドポイントへのアクセスには OAuth トークンの使用が義務付けられています。

こうしたエンドポイントとトークンを取得するには、いくつかの手順を実行する必要があります。REST API と SOAP API のどちらも、インストール済みパッケージを使用した Marketing Cloud Engagement との API 連携が必要です。Marketing Cloud Engagement アカウントでインストール済みパッケージを作成したら、クライアント ID と秘密を使用してアクセストークンを要求できます。開発者が作成するどのアプリケーションも、このトークンを抽出して、Marketing Cloud Engagement のリソースへのアクセスに使用します。では、インストール済みパッケージを作成して、エンドポイントを見つける手順を見ていきましょう。

この単元の例では REST API を使用します。Marketing Cloud Engagement とやりとりする推奨の方法であるためです。

インストール済みパッケージの作成

Marketing Cloud Engagement は、ユーザーと API 要求の認証にインストール済みパッケージを使用します。このステップでは、Marketing Cloud Engagement アカウントにアクセスする必要があります(サポートが必要な場合は、Marketing Cloud Engagement 管理者にお問い合わせください)。

Marketing Cloud Engagement で、[Setup (セットアップ)] に移動します。
[アプリケーション] をクリックします。
[インストール済みパッケージ] をクリックします。
[新規] をクリックします。
パッケージに名前を付け、説明を入力します。
拡張機能を使用してパッケージを作成します。
パッケージを保存します。
[コンポーネント] で、[コンポーネントの追加] をクリックし、[API 連携] を選択します。
連携の種別を選択します。
- サーバー間/クライアント資格情報許可種別
- Web アプリケーションと公開アプリケーション連携/認証コード許可種別
連携のプロパティ (Web アプリケーションと公開アプリケーションの範囲やリダイレクト URI など) を設定します。ローカルテスト用の有効なリダイレクト URI には https://127.0.0.1:80/ を使用します。
コンポーネントを保存します。

エンドポイントの確認

前述のとおり、Salesforce の API はテナント固有のエンドポイントを使用します。つまり、すべての要求を 1 つのエンドポイントに転送する代わりに、エンドポイントにテナント固有のサブドメインが含まれます。このため、1 つのエンドポイントのトラフィック量が減少し、API 要求のパフォーマンスも向上します。スピードアップするうえに安全性も向上するため、良いこと尽くめです。

Marketing Cloud Engagement アカウントに、エンドポイントの実装に必要な情報が含まれます。アカウントに直接アクセスできない場合は、Marketing Cloud Engagement 管理者に連絡して、作業の開始にあたって必要な情報を確認してください。

サーバー間連携

Marketing Cloud Engagement とシステム間の REST API/SOAP API インタラクションを設定する場合は、サーバー間連携を使用します。この連携はわずか 3 つのステップで設定できます。

ステップ 1 — クライアント ID と秘密を使用してアクセストークンを要求する。

連携の作成時に、インストール済みパッケージでこれらの値が生成されます。次の例は、この REST API 要求に記載される情報を示しています。クライアント ID と秘密を安全な場所に保存します。この情報を JavaScript 経由でクライアント側に公開しないでください。また、モバイルアプリケーションにも保存しないでください。

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "7a9j47upktedde30uedl822p",
"client_secret": "1955278925675241571",
"scope": "email_read email_write email_send",
"account_id": "12345"
}

ステップ 2 — Marketing Cloud Engagement がアクセストークンを返す。

このトークンを抽出して使用できるようにします。このトークンも、ユーザー名やパスワードと同様の取り扱いで保護します。つまり、公開メッセージボードに投稿したり、システム内の暗号化されていないドキュメントに記したままにしないでください。

HTTP/1.1 200 OK
{
"access_token":"eyJhbLciOiJIPzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIifQ.eyJhY2Nlc3NfdG9rZW4iOiJhYmJUQTlpSHZqRjkyd3Jkb0xWZEFCaloiLCJjbGllbnRfaWQiOiI3ZTRmYW1xaWUzcWtzdzlhNDRrcmxvZDgiLCJlaWQiOjEwNzU3Njc2LCJzdGFja19rZXkiOiJRQTFTMSJ9.wSFfEdeNrkoiU_tnmJ2ihm8iUqnJKlZoI3GlavTGBhs.hU4EsiC1e9txh_TCt90YlI2l7xZZ5E6_oa0xku3Jj9CCk1B72M4bhO3kUIyhwfVuB0MFbL0y9KD_RRFzg-nuqPgjPyONnby-iWopdZPBHd-3woupxCMST5-vfJO9qAED9qiUfYLS4WmHRuJTCX4NPScyu8BdROTVEe-D3iAoAeFoJX_rLZ9d5eEhIn1AvkYgoj9siuxAprHEvmySTgNIXkQA6uT_IQ-H1dbfOyJmlFKpYzvhvHb0KH7NJ24zy5bd2MQ5",
"expires_in":1200,
"token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
"scope": "email_read email_write email_send"
}

ステップ 3 — REST API/SOAP API のリソースにアクセスする。

これで準備が整いました! 要求の計画を立てて記述します。

Web と公開の連携

この方式を使用すると、特定のユーザーが認証を使用して Marketing Cloud Engagement からアプリケーションにアクセスできます。Web アプリケーションにはクライアントの秘密を安全に保存できますが、公開アプリケーションには安全に保存できません。

ステップ 1 — ユーザーの Web ブラウザーを Marketing Cloud Engagement にリダイレクトする。

連携用の Marketing Cloud Engagement 認証 URL へのリダイレクトを実行するコードをアプリケーションに追加します。次の例を見てください。

https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com/v2/authorize?response_type=code&client_id=vqwyswrlzzfk024ivr682esb&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcode_callback.jsp&scope=email_read%20email_write%20email_send&state=mystate

ステップ 2 — 認証コードを抽出する。

認証に成功すると、認証コードを記載した応答が返されます。応答から次のような認証コードを抽出します。

https://www.example.com/code_callback.jsp?state=mystate&tssd={YOUR_MARKETING_CLOUD_SUBDOMAIN}
&code=aWekysIEeqM9PiThEfm0Cnr0MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w

ステップ 3 — トークンを要求する。

トークンの要求は次のようになります。

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
   "grant_type": "authorization_code",
   "code":
"eyJhbZciOiJIUzI1NiIsImtpZCI6IjIiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJhY2Nlc3NfdG9rZW4iOiJhY0tlbEVIaTdzVERNNWd5VVR1VGdsS1YiLCJjbGllbnRfaWQiOiJmaG0yd2lsb2d2ajhqNXdzcWprZmgwejUiLCJlaWQiOjEwNzcxNzA2LCJzdGFja19rZXkiOiJRQTFTMSIsInBsYXRmb3JtX3ZlcnNpb24iOjIsImNsaWVudF90eXBlIjoiU2VydmVyVG9TZXJ2ZXIifQ.Q0qyABvInOiz3PfGsTDbj1coVTTdD8A4pCZS395P3Qo.DoROxfr3CQlMVMtVd5gYERWFYWoiNWojKObHxOq_5BqR98CDSAqfExfH-mv3PFMzy0U2NntttdgZK5wTL0UejXCxxH_XlcgL5k1TWzv_K-uTlPmliK2eI0LnaR1ti-TSqG36RnfUWzZ8KlAuGlqdGv-wgJtLeQTCEqE97yuqnlppgLLOB",
   "client_id": "7a8j47upktedde30uedl822p",
   "client_secret": "lYkAjPxnmHP4Zarpv1U4cLf0"
   "redirect_uri": "http://www.example.com/code_callback.jsp/",
   "scope": "email_read email_write email_send offline"
}

この要求によって Marketing Cloud Engagement がトークンを返します。この場合も、トークンの保護に細心の注意を払います。

HTTP/1.1 200 OK
{
"access_token":"eyJhbZciOiJIUzI1NiIsImtpZCI6IjEiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJhY2Nlc3NfdG9rZW4iOiJjZ3RHRklkUjUydnY4WHhLRHZaTDU2VHAiLCJjbGllbnRfaWQiOiI5b2xhcnI3emEyZHplaWtlaTBxZ2Z0dm0iLCJlaWQiOjEwODU1ODQsInN0YWNrX2tleSI6IlFBM1MxIiwicGxhdGZvcm1fdmVyc2lvbiI6MiwiY2xpZW50X3R5cGUiOiJDb25maWRlbnRpYWwifQ.Hp6gLSnlvBsx9FI6qXwJ12HJVzStWLIJdlzrx4XIIN4.t2kCu9YBNHVask49MQZXMlKGvYMXEc50QkRTc3y5_ylEWC8hPyEkU9sIanqL0ALSwFNyhQmMF6aajnmSrsD5obIl-NjXNfIwYWmnDqZU6HFBgbMoR3ofuEGIhrGokqUbD8nHZtgp-otgQSOg5Qj_RqUHUC0N0Fo4BUCXTq5BiM_EjP_djIKZF",
"refresh_token":"eyJhbZciOiJIUzI1NiIsImtpZCI6IjEiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJyZWZyZXNoX3Rva2VuIjoiY2JINUE0aUdnTnBQVmJzOTlCUlZnNmh6IiwiY2xpZW50X2lkIjoiOW9sYXJyN3phMmR6ZWlrZWkwcWdmdHZtIiwiZWlkIjoxMDg1NTg0LCJzdGFja19rZXkiOiJRQTNTMSIsInBsYXRmb3JtX3ZlcnNpb24iOjIsImNsaWVudF90eXBlIjoiQ29uZmlkZW50aWFsIn0.-kScEfPhdz2g75b-KgTnmYKK9YTbUu9m9AhDTKkYFr4.mFd_EyLlPeAmfmwqqiBi_0HrAL5Ndtj1R9zWMj0Y80FOjB9n_EPYR0nKGKkNeijVuxmdMNgnOSF_isxGDwqjDoor2x4B-gP9Erl0gl4u58yzAXcjesNoJ1L96HJ3kjg-Jwke4p4K1MEWoB0fsrbDUaIAkg2Tf5THwrTLAxKRhn-ANltUDwUt",
   "expires_in":1200,
   "token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
   "scope": "email_read email_write email_send"
}

ステップ 4 — REST API/SOAP API のリソースにアクセスします。

トークンを手に入れたら、REST API 要求または SOAP API 要求を実行できます!

両方の API に安全にアクセスできるようになったところで、それぞれを詳しく見ていきます。最初は REST API です。