ขอความยินยอมจากผู้ใช้

สิ่งสำคัญ

ในเดือนมิถุนายน 2022 เราได้แนะนํา การรับรองความถูกต้องโดยใช้หลายปัจจัย เป็นข้อกําหนดสําหรับ Bing Ads คุณอาจยังต้องเปลี่ยนแปลงรหัสเพื่อให้เป็นไปตามข้อกําหนดนี้ Microsoft Advertising กําลังดําเนินการตรวจสอบการบังคับใช้ทางเทคนิคในช่วงต้นเดือนตุลาคม

บล็อกโพสต์นี้ สรุปขั้นตอนที่คุณควรปฏิบัติตามข้อกําหนด

สําหรับข้อมูลเพิ่มเติม โปรดดูคู่มือข้อกําหนดการรับรองความถูกต้องโดยใช้หลายปัจจัย

เมื่อคุณลงทะเบียนแอปพลิเคชันแล้ว คุณต้องได้รับความยินยอมจากผู้ใช้เพื่อจัดการบัญชี Microsoft Advertising ของพวกเขา

เคล็ดลับ

สําหรับความช่วยเหลือในการแก้ไขปัญหา โปรดดูคู่มือข้อผิดพลาด OAuth ทั่วไป

สิ่งสำคัญ

ผู้ใช้แต่ละคนต้องได้รับพร้อมท์และให้ความยินยอมผ่านการควบคุมเว็บเบราว์เซอร์อย่างน้อยหนึ่งครั้งเพื่อให้แอปพลิเคชันของคุณจัดการบัญชี Microsoft Advertising ของพวกเขา นี่คือโฟลว์ OAuth 2.0 มาตรฐานและกําหนดไว้โดยละเอียดในส่วนการให้รหัสการตรวจสอบของข้อมูลจําเพาะ OAuth 2.0

โฟลว์รหัสการตรวจสอบจะเริ่มต้นด้วยไคลเอ็นต์นําผู้ใช้ไปยัง /authorize จุดสิ้นสุด ในการร้องขอนี้ ไคลเอ็นต์จะระบุสิทธิ์ที่จําเป็นต้องได้รับจากผู้ใช้:

หมายเหตุ

แทนที่ your_client_id ด้านล่างด้วย ID แอปพลิเคชัน (ไคลเอ็นต์) ที่พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอปกําหนดให้กับแอปของคุณ

// 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
  1. คัดลอก URL ด้านล่างแล้ววางลงในเบราว์เซอร์ของคุณเพื่อดําเนินการคําขอความยินยอมจากผู้ใช้ในตัวอย่างนี้

หมายเหตุ

แทนที่ your_client_id ใน URL ด้านล่างด้วย ID แอปพลิเคชัน (ไคลเอ็นต์) ที่พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอปกําหนดให้กับแอปของคุณ

<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>
  1. ลงชื่อเข้าใช้ด้วยข้อมูลประจําตัวบัญชี Microsoft ของคุณและยินยอมให้ แอปของคุณ จัดการบัญชี Microsoft Advertising ของคุณ
  2. หลังจากลงชื่อเข้าใช้ เบราว์เซอร์ของคุณควรถูกเปลี่ยนเส้นทางโดย https://localhost/myapp/ กด ใน code แถบที่อยู่ คุณสามารถละเว้นข้อความแสดงข้อผิดพลาดบนหน้าได้
  3. ถัดไป คุณจะใช้รหัสเพื่อรับการเข้าถึงและรีเฟรชโทเค็น

จุดสิ้นสุดของแพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะตรวจสอบให้แน่ใจว่าผู้ใช้ยินยอมให้มีสิทธิ์ที่ระบุในพารามิเตอร์คิวscopeรี ถ้าผู้ใช้ไม่ยินยอมให้สิทธิ์ใดๆ เหล่านั้น ผู้ใช้จะขอให้ผู้ใช้ยินยอมให้มีสิทธิ์ที่จําเป็น แม้ว่าคู่มือนี้จะมุ่งเน้นไปที่การจัดการบัญชี Microsoft Advertising เป็นหลัก ผ่านรายละเอียดscope=https://ads.microsoft.com/msads.manageเพิ่มเติมเกี่ยวกับสิทธิ์และความยินยอมในแพลตฟอร์มข้อมูลประจำตัวของ Microsoft มีอยู่ที่นี่

เมื่อผู้ใช้รับรองความถูกต้องและให้ความยินยอมแล้ว จุดสิ้นสุดของแพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะส่งการตอบสนองไปยังแอปของคุณตามที่ระบุ redirect_uriโดยใช้วิธีการที่ระบุในresponse_modeพารามิเตอร์ ตัวอย่างเช่น URI การเรียกกลับมีรหัสการตรวจสอบดังนี้ ถ้าผู้ใช้มอบสิทธิ์ให้แอปพลิเคชันของคุณในการจัดการบัญชี Microsoft Advertising ของพวกเขา: 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 ทั่วไปและรหัสข้อผิดพลาดการรับรองความถูกต้องและการรับรองความถูกต้อง

ตารางต่อไปนี้มีพารามิเตอร์ที่ไคลเอ็นต์ API ของ Bing Ads สามารถรวมไว้ในคําขอความยินยอมได้ สําหรับรายละเอียดเพิ่มเติมเกี่ยวกับพารามิเตอร์เพิ่มเติม โปรดดูเอกสารประกอบโฟลว์รหัสการตรวจสอบ แพลตฟอร์มข้อมูลประจำตัวของ Microsoft OAuth 2.0

พารามิเตอร์ จําเป็น/เพิ่มเติม คำอธิบาย
client_id จําเป็น ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ Azure Portal - พอร์ทัลการลงทะเบียนแอปกําหนดให้กับแอปของคุณ
code_challenge แนะนํา ใช้เพื่อรักษาความปลอดภัยในการให้รหัสการตรวจสอบผ่าน Proof Key for Code Exchange (PKCE) จําเป็นถ้ารวม code_challenge_method อยู่ด้วย สําหรับข้อมูลเพิ่มเติม ให้ดู PKCE RFC ขณะนี้ขอแนะนําวิธีนี้สําหรับแอปพลิเคชันทุกประเภท ไม่ว่าจะเป็นแอปดั้งเดิม, SPA และไคลเอ็นต์ที่เป็นความลับ เช่น เว็บแอป
code_challenge_method แนะนํา เมธอดที่ใช้ในการเข้ารหัสcode_verifiercode_challengeพารามิเตอร์ อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

- plain
- S256

ถ้าไม่รวมไว้ จะ code_challenge ถือว่าเป็นข้อความธรรมดาถ้า code_challenge รวมไว้ด้วย แพลตฟอร์มข้อมูลประจำตัวของ Microsoft สนับสนุนทั้งและ plainS256. สําหรับข้อมูลเพิ่มเติม ให้ดู PKCE RFC
prompt ไม่บังคับ ระบุชนิดของการโต้ตอบกับผู้ใช้ที่แอปพลิเคชันของคุณต้องการ ค่าที่รองรับ ได้แก่
- prompt=login จะบังคับให้ผู้ใช้ใส่ข้อมูลประจําตัวในการร้องขอนั้น ซึ่งเป็นการปฏิเสธการลงชื่อเข้าระบบครั้งเดียว
- prompt=none ตรงกันข้ามกับ "การเข้าสู่ระบบ" กล่าวคือ จะช่วยให้แน่ใจว่าผู้ใช้จะไม่ได้รับพร้อมท์แบบโต้ตอบใดๆ แต่อย่างใด ถ้าไม่สามารถทําให้คําขอเสร็จสมบูรณ์โดยไม่แจ้งให้เสร็จสมบูรณ์ผ่านการลงชื่อเข้าสู่ระบบครั้งเดียว จุดสิ้นสุด แพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะส่งกลับข้อผิดพลาด 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_post

query ให้โค้ดเป็นพารามิเตอร์สตริงคิวรีบน URI การเปลี่ยนเส้นทางของคุณ หากคุณกําลังร้องขอโทเค็น ID โดยใช้โฟลว์โดยนัย คุณจะไม่สามารถใช้ตาม query ที่ระบุไว้ใน สเปค OpenID ได้ หากคุณกําลังร้องขอเฉพาะรหัส คุณสามารถใช้ query, fragment, หรือ form_post. form_post จะดําเนินการ POST ที่มีโค้ดไปยัง URI การเปลี่ยนเส้นทางของคุณ สําหรับข้อมูลเพิ่มเติม ให้ดูโพรโทคอล OpenID Connect
response_type จําเป็น ต้องรวมสําหรับ code ขั้นตอนรหัสการตรวจสอบ
scope จําเป็น รายการ ขอบเขต ที่คั่นด้วยช่องว่างที่คุณต้องการให้ผู้ใช้ยินยอม ตรวจสอบให้แน่ใจว่าได้รวมไว้ https://ads.microsoft.com/msads.manage เพื่อพร้อมท์ผู้ใช้สําหรับการเข้าถึง Microsoft Advertising รวมทั้งเพื่อให้แน่ใจว่า offline_access โทเค็นรีเฟรชรวมอยู่ในการตอบกลับ
state แนะนํา ค่าที่รวมอยู่ในคําขอที่จะถูกส่งกลับในการตอบสนองโทเค็น ซึ่งอาจเป็นสตริงของเนื้อหาใดก็ได้ที่คุณต้องการ โดยทั่วไปแล้วค่าที่ไม่ซ้ํากันที่สร้างขึ้นแบบสุ่มจะใช้เพื่อป้องกันการโจมตีด้วยการปลอมแปลงคําขอข้ามไซต์ ค่ายังสามารถเข้ารหัสข้อมูลเกี่ยวกับสถานะของผู้ใช้ในแอปก่อนที่จะมีการร้องขอการรับรองความถูกต้อง เช่น หน้าหรือมุมมองที่พวกเขาเปิดอยู่
tenant จําเป็น {tenant}ค่าในพาธของคําขอสามารถใช้เพื่อควบคุมว่าใครสามารถลงชื่อเข้าใช้แอปพลิเคชันได้บ้าง เพื่อให้แน่ใจว่าแอปพลิเคชันของคุณสนับสนุนทั้งบัญชีส่วนบุคคล MSA และบัญชีที่ทํางานหรือโรงเรียน Azure AD เราขอแนะนําให้คุณใช้เป็นผู้commonเช่าสําหรับการรับรองความถูกต้อง Bing Ads API

ในกรณีที่แอปพลิเคชันของคุณต้องการผู้เช่าอื่น ให้ดูจุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft สําหรับข้อมูลเพิ่มเติม

ขั้นตอนถัดไป (Entra ID)

หลังจากลงทะเบียนแอปพลิเคชันของคุณกับ Google OAuth คุณต้องขอความยินยอมจากผู้ใช้เพื่ออนุญาตให้แอปพลิเคชันของคุณรับรองความถูกต้องของผู้ใช้และเรียกใช้ Microsoft Advertising API ในนามของพวกเขา กระบวนการนี้ใช้ โฟลว์รหัสการอนุญาต OAuth 2.0 มาตรฐานที่ Google จัดหาให้

ผู้ใช้แต่ละคนต้องดําเนินการขั้นตอนการยินยอมให้เสร็จสมบูรณ์อย่างน้อยหนึ่งครั้งในเว็บเบราว์เซอร์ก่อนที่แอปพลิเคชันของคุณจะสามารถเข้าถึงบัญชี Microsoft Advertising ของพวกเขาได้

ดูภาพรวมของกระบวนการยินยอมและการอนุญาต OAuth ของ Google

คําขออนุญาต

หากต้องการขอความยินยอมจากผู้ใช้ ให้เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยังจุดสิ้นสุดการอนุญาต Google OAuth 2.0 ด้วยพารามิเตอร์คิวรีที่จําเป็น

https://accounts.google.com/o/oauth2/v2/auth?
  client_id={GOOGLE_CLIENT_ID}
  &response_type=code
  &redirect_uri={REGISTERED_REDIRECT_URI}
  &scope=profile email
  &access_type=offline
  &prompt=consent
  &state={STATE}

พารามิเตอร์การร้องขอการอนุญาต

พารามิเตอร์ คำอธิบาย
client_id รหัสไคลเอ็นต์ Google OAuth ที่ได้รับจาก Google Cloud Console
response_type ต้องตั้งค่าเพื่อรับ code รหัสการอนุญาต
redirect_uri ต้องตรงกับหนึ่งใน URI การเปลี่ยนเส้นทางที่ลงทะเบียนสําหรับไคลเอ็นต์ Google OAuth
scope ขอบเขต OAuth ที่ร้องขอจาก Google (ตัวอย่างเช่น profile email)
access_type=offline ร้องขอโทเค็นรีเฟรชเพื่อให้แอปพลิเคชันสามารถรับโทเค็นการเข้าถึงใหม่โดยไม่ต้องมีการโต้ตอบของผู้ใช้
prompt=consent บังคับให้แสดงหน้าจอความยินยอมเพื่อให้แน่ใจว่ามีการออกโทเค็นรีเฟรชแล้ว
state ค่าที่แนะนําที่ใช้เพื่อรักษาสถานะการร้องขอและป้องกันการโจมตี CSRF

สําหรับรายการทั้งหมดของพารามิเตอร์ที่สนับสนุน ให้ดู:
https://developers.google.com/identity/protocols/oauth2/web-server

  1. ระบบจะนําผู้ใช้ไปยังจุดสิ้นสุดการอนุญาตของ Google
  2. ผู้ใช้ลงชื่อเข้าใช้ด้วยบัญชี Google ของตน หากยังไม่ได้ลงชื่อเข้าใช้
  3. Google จะแสดงหน้าจอความยินยอมที่อธิบายสิทธิ์ที่แอปพลิเคชันของคุณร้องขอ
  4. หากผู้ใช้ให้ความยินยอม Google จะเปลี่ยนเส้นทางเบราว์เซอร์ไปยังระบบของคุณด้วย redirect_uri รหัสการอนุญาต ดังนี้
https://yourapp.com/oauth/callback?code=AUTH_CODE&state={STATE}

หากผู้ใช้ปฏิเสธการยินยอม การเปลี่ยนเส้นทางจะมีพารามิเตอร์ข้อผิดพลาดแทนรหัสการอนุญาต

ขั้นตอนถัดไป (Google OAuth)

หลังจากได้รับรหัสการอนุญาต แอปพลิเคชันของคุณต้องแลกเปลี่ยนเป็นโทเค็นการเข้าถึงและโทเค็นรีเฟรชโดยใช้จุดสิ้นสุดโทเค็นของ Google จากนั้นโทเค็นการเข้าถึงจะถูกใช้เมื่อทําการเรียก Microsoft Advertising API

หมายเหตุ

การใช้ Google OAuth จะมีผลเฉพาะกับวิธีที่ผู้ใช้รับรองความถูกต้องเท่านั้น
ส่วนหัวของคําขอ Microsoft Advertising API, ข้อกําหนดโทเค็นสําหรับนักพัฒนา และการตรวจสอบสิทธิ์ยังคงไม่เปลี่ยนแปลง

ดูเพิ่มเติม

เริ่มต้นใช้งาน