ユーザーの同意を要求する
重要
2022 年 6 月、Bing広告の要件として 多要素認証 を導入しました。 この要件に準拠するには、引き続きコードの変更が必要な場合があります。 Microsoft Advertising は、10 月初旬に技術的な適用チェックを実行しています。
このブログ投稿 では、コンプライアンスを確保するために実行する必要がある手順について説明します。
詳細については、 多要素認証要件 ガイドを参照してください。
アプリケーションを登録したら、Microsoft Advertising アカウントを管理するためにユーザーの同意を得る必要があります。
ヒント
トラブルシューティングのヘルプについては、 一般的な OAuth エラー ガイドを参照してください。
重要
アプリケーションが Microsoft Advertising アカウントを管理するには、各ユーザーに対して少なくとも 1 回は Web ブラウザー コントロールを通じて同意を求め、同意する必要があります。 これは標準の OAuth 2.0 フローであり、 OAuth 2.0 仕様の承認コード許可セクションで詳細に定義されています。
承認コード フローは、ユーザーを /authorize エンドポイントに誘導するクライアントから始まります。 この要求では、クライアントはユーザーから取得する必要があるアクセス許可を示します。
注:
次 のyour_client_id を、 Azure portal - アプリ登録ポータル によってアプリが割り当てられたアプリケーション (クライアント) ID に置き換えます。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=your_client_id
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&state=12345
- 以下の URL をコピーし、ブラウザーに貼り付けて、このサンプル要求を実行してユーザーの同意を求めます。
注:
次 の URL のyour_client_id を、 Azure portal - アプリ登録ポータル によってアプリが割り当てられたアプリケーション (クライアント) ID に置き換えます。
<https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=your_client_id&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage&state=12345>
- Microsoft アカウントの資格情報でサインインし、Microsoft Advertising アカウントの管理に アプリ の同意を付与します。
- サインイン後、ブラウザーはアドレス バーに
codeを含むhttps://localhost/myapp/にリダイレクトされます。 ページのエラー メッセージは無視できます。 - 次に、コードを使用して アクセス トークンと更新トークンを取得します。
また、Microsoft ID プラットフォーム エンドポイントは、ユーザーが scope クエリ パラメーターに示されているアクセス許可に同意したことを確認します。 ユーザーがこれらのアクセス許可のいずれかに同意していない場合は、必要なアクセス許可に同意するようにユーザーに求められます。 このガイドは主に、 scope=https://ads.microsoft.com/msads.manageを使用した Microsoft Advertising アカウントの管理に重点を置いていますが、 Microsoft ID プラットフォームでのアクセス許可と同意の詳細については、こちらを参照してください。
ユーザーが認証して同意を許可すると、Microsoft ID プラットフォーム エンドポイントは、response_mode パラメーターで指定されたメソッドを使用して、指定されたredirect_uriでアプリへの応答を返します。 たとえば、ユーザーが Microsoft Advertising アカウントを管理するためのアクセス許可をアプリケーションに付与した場合、コールバック URI には次のような承認コードが含http://localhost/myapp/?code=CodeGoesHere&。state=12345。
ユーザーが Microsoft Advertising アカウントを管理するためのアクセス許可をアプリケーションに付与した場合は、次の手順ですぐにコードを使用する必要があります。 承認コードの短い期間 (約 5 分) は変更される可能性があります。 ユーザーが Microsoft Advertising アカウントを管理するためのアプリケーションのアクセス許可を拒否した場合、コールバック URI には、次のようにエラーとエラーの説明フィールドが含http://localhost/myapp/?error=access_denied&。error_description=ERROR_DESCRIPTION&state=ClientStateGoesHere。 OAuth エラーの詳細については、「 一般的な OAuth エラー 」と「 認証と承認のエラー コード」を参照してください。
次の表には、Bing Ads API クライアントが同意要求に含めることができるパラメーターが含まれています。 省略可能なパラメーターの詳細については、Microsoft ID プラットフォーム OAuth 2.0 承認コード フロー のドキュメントを参照してください。
| パラメーター | 必須 / オプション | 説明 |
|---|---|---|
client_id |
必須出席者 | Azure portal - アプリ登録ポータルによってアプリが割り当てられたアプリケーション (クライアント) ID。 |
code_challenge |
推奨 | Proof Key for Code Exchange (PKCE) を使用して承認コード許可をセキュリティで保護するために使用されます。
code_challenge_methodが含まれている場合は必須です。 詳細については、 PKCE RFC を参照してください。 これは、ネイティブ アプリ、SPA、Web アプリなどの機密クライアントなど、すべてのアプリケーションの種類に対して推奨されるようになりました。 |
code_challenge_method |
推奨 |
code_challenge パラメーターのcode_verifierをエンコードするために使用されるメソッド。 次のどちらかの値にすることができます。- plain - S256除外した場合、 code_challengeが含まれている場合、code_challengeはプレーンテキストと見なされます。 Microsoft ID プラットフォームでは、 plain と S256の両方がサポートされています。 詳細については、 PKCE RFC を参照してください。 |
prompt |
省略可能 | アプリケーションで必要なユーザー操作の種類を示します。 サポートされる値は次のとおりです。 - prompt=login では、ユーザーはその要求に対して資格情報を強制的に入力し、シングル サインオンを否定します。- prompt=none は"ログイン" の反対です。つまり、ユーザーに対話型プロンプトが表示されないようにします。 シングル サインオンを使用して要求をサイレント モードで完了できない場合、Microsoft ID プラットフォーム エンドポイントはinteraction_requiredエラーを返します。- prompt=consent は、ユーザーがサインインした後に OAuth 同意ダイアログをトリガーし、ユーザーにアプリへのアクセス許可の付与を求めます。- prompt=select_account では、シングル サインオンが中断され、アカウントの選択エクスペリエンスが提供され、セッション内のすべてのアカウント、または記憶されているアカウント、または別のアカウントを完全に使用することを選択するオプションが一覧表示されます。 |
redirect_uri |
必須 | 認証応答をアプリで送受信できるアプリのredirect_uri。 ポータルに登録したredirect_urisのいずれかと完全に一致する必要があります。ただし、URL エンコードする必要があります。 ネイティブ & モバイル アプリの場合は、既定値の https://login.microsoftonline.com/common/oauth2/nativeclient を使用する必要があります。 |
response_mode |
推奨 | 結果のトークンをアプリに送信するために使用するメソッドを指定します。 次のいずれかを指定できます。 - query- fragment- form_postquery は、リダイレクト URI のクエリ文字列パラメーターとしてコードを提供します。 暗黙的なフローを使用して ID トークンを要求する場合、OpenID 仕様で指定されたqueryを使用することはできません。コードだけを要求する場合は、query、fragment、またはform_postを使用できます。
form_post は、コードを含む POST をリダイレクト URI に実行します。 詳細については、「 OpenID Connect プロトコル」を参照してください。 |
response_type |
必須 | 認可コードのフローに code を含める必要があります。 |
scope |
必須出席者 | ユーザーが同意する スコープ のスペース区切りのリスト。 ユーザーに Microsoft Advertising アクセスを求める https://ads.microsoft.com/msads.manage を必ず含めます。
offline_accessを含め、応答に更新トークンが確実に含まれるようにします。 |
state |
推奨 | トークン応答にも返される要求に含まれる値。 任意のコンテンツの文字列にすることができます。 ランダムに生成された一意の値は、通常、クロスサイト リクエスト フォージェリ攻撃を防止するために使用されます。 値は、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードすることもできます。 |
tenant |
必須出席者 | 要求のパスで {tenant} 値を使用して、アプリケーションにサインインできるユーザーを制御できます。 アプリケーションで MSA 個人用アカウントと Azure AD の職場または学校アカウントの両方がサポートされるようにするには、Bing Ads API 認証のテナントとして common を使用することをお勧めします。アプリケーションに別のテナントが必要な場合は、 Microsoft ID プラットフォーム エンドポイントに関する ページを参照してください。 |