การลิงก์บัญชีกับ OAuth (Dialogflow)

ประเภทการลิงก์ OAuth รองรับขั้นตอน OAuth 2.0 มาตรฐานอุตสาหกรรม 2 ขั้นตอน ได้แก่ ขั้นตอนของรหัสโดยนัยและการให้สิทธิ์

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

ในกระบวนการรหัสการให้สิทธิ์ คุณต้องมีปลายทาง 2 จุด ได้แก่

ปลายทางการให้สิทธิ์ ซึ่งมีหน้าที่นําเสนอ UI การลงชื่อเข้าใช้แก่ผู้ใช้ที่ไม่ได้ลงชื่อเข้าใช้ และยินยอมให้มีการเข้าถึงการเข้าถึงที่ขอในรูปของรหัสการให้สิทธิ์ระยะสั้น
ปลายทางของการแลกเปลี่ยนโทเค็นที่มีหน้าที่รับผิดชอบการแลกเปลี่ยน 2 ประเภท ได้แก่
1. แลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นการรีเฟรชที่ใช้ได้นานและโทเค็นเพื่อการเข้าถึงที่ใช้ได้นาน การแลกเปลี่ยนนี้จะเกิดขึ้นเมื่อผู้ใช้เข้าสู่ กระบวนการเชื่อมโยงบัญชี
2. แลกเปลี่ยนโทเค็นการรีเฟรชที่ใช้ได้นานกับโทเค็นเพื่อการเข้าถึงที่ใช้ได้ในระยะสั้น Exchange นี้จะเกิดขึ้นเมื่อ Google ต้องการโทเค็นเพื่อการเข้าถึงใหม่เนื่องจากโทเค็นหมดอายุ

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

ใช้การลิงก์บัญชี OAuth

หมายเหตุ: หากคุณใช้การลิงก์บัญชีเพื่อจัดการข้อมูลทางการเงิน โปรดทราบว่านโยบายเพิ่มเติมอาจมีผลบังคับใช้กับการดำเนินการของคุณ เราอาจใช้เวลาถึง 6 สัปดาห์ในการตรวจสอบการดำเนินการที่มีการลิงก์บัญชีสำหรับข้อมูลทางการเงิน ดังนั้นโปรดคำนึงถึงเวลาดังกล่าวเมื่อวางแผนกำหนดการเผยแพร่ โปรดตรวจสอบว่าคุณได้ปฏิบัติตามนโยบายบริการทางการเงินก่อนส่งการดำเนินการเข้ารับการตรวจสอบ

เพื่อช่วยให้กระบวนการตรวจสอบง่ายขึ้น

กำหนดค่าโปรเจ็กต์

หากต้องการกำหนดค่าโปรเจ็กต์ให้ใช้การลิงก์บัญชี OAuth ให้ทำตามขั้นตอนต่อไปนี้

เปิดคอนโซล Actions แล้วเลือกโปรเจ็กต์ที่ต้องการใช้
คลิกแท็บพัฒนา และเลือกการลิงก์บัญชี
เปิดใช้สวิตช์ข้างการลิงก์บัญชี
ในส่วนการสร้างบัญชี ให้เลือกไม่ ฉันต้องการอนุญาตให้สร้างบัญชีบนเว็บไซต์เท่านั้น
ในประเภทการลิงก์ ให้เลือก OAuth และโดยนัย
ในส่วนข้อมูลลูกค้า:
- กำหนดค่ารหัสลูกค้าที่ออกโดย Actions to Google เพื่อระบุคำขอที่มาจาก Google
- ใส่ URL สำหรับปลายทางการให้สิทธิ์และการแลกเปลี่ยนโทเค็น

คลิกบันทึก

ใช้งานเซิร์ฟเวอร์ OAuth

บริการของคุณจะกำหนดปลายทางการให้สิทธิ์ให้พร้อมใช้งานทาง HTTPS เพื่อรองรับโฟลว์แบบโดยนัยของ OAuth 2.0 ปลายทางนี้มีหน้าที่ในการตรวจสอบสิทธิ์และขอความยินยอมจากผู้ใช้สำหรับการเข้าถึงข้อมูล ปลายทางการให้สิทธิ์จะแสดง UI การลงชื่อเข้าใช้แก่ผู้ใช้ที่ยังไม่ได้ลงชื่อเข้าใช้และบันทึกคำยินยอมในการเข้าถึงที่ขอ

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

เซสชันโฟลว์แบบไม่เจาะจงปลายทางของ OAuth 2.0 ที่ Google เป็นผู้เริ่มต้นจะมีขั้นตอนดังต่อไปนี้

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

จัดการคำขอการให้สิทธิ์

เมื่อการดำเนินการของคุณจำเป็นต้องลิงก์บัญชีผ่านขั้นตอนโดยนัยของ OAuth2 Google จะส่งผู้ใช้ไปยังปลายทางการให้สิทธิ์พร้อมคำขอที่มีพารามิเตอร์ต่อไปนี้

พารามิเตอร์ปลายทางการให้สิทธิ์
`client_id`	รหัสไคลเอ็นต์ที่คุณกำหนดให้ Google
`redirect_uri`	URL ที่คุณส่งการตอบกลับคำขอนี้
`state`	ค่าการทำบัญชีที่ส่งกลับไปยัง Google โดยไม่มีการเปลี่ยนแปลงใน URI การเปลี่ยนเส้นทาง
`response_type`	ประเภทของค่าที่จะส่งคืนในคำตอบ สำหรับขั้นตอนโดยปริยายของ OAuth 2.0 ประเภทการตอบกลับจะเป็น `token` เสมอ

ตัวอย่างเช่น หากปลายทางการให้สิทธิ์พร้อมใช้งานที่ https://myservice.example.com/auth คำขออาจมีลักษณะดังนี้

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

หากต้องการให้ปลายทางการให้สิทธิ์จัดการคำขอลงชื่อเข้าใช้ ให้ทำตามขั้นตอนต่อไปนี้

ยืนยันค่า client_id และ redirect_uri เพื่อป้องกันการให้สิทธิ์เข้าถึงแอปไคลเอ็นต์ที่ไม่ได้ตั้งใจหรือกำหนดค่าไม่ถูกต้อง
- ยืนยันว่า client_id ตรงกับรหัสไคลเอ็นต์ที่กำหนดให้กับ Google
- ยืนยันว่า URL ที่ระบุโดยพารามิเตอร์ redirect_uri มีรูปแบบต่อไปนี้
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
```
  YOUR_PROJECT_ID คือรหัสที่อยู่ในหน้าการตั้งค่าโปรเจ็กต์ของคอนโซล Actions
ตรวจสอบว่าผู้ใช้ลงชื่อเข้าใช้บริการของคุณหรือไม่ หากผู้ใช้ไม่ได้ลงชื่อเข้าใช้ ให้ทำตามขั้นตอนการลงชื่อเข้าใช้หรือลงชื่อสมัครใช้บริการให้เสร็จสิ้น
สร้างโทเค็นเพื่อการเข้าถึงที่ Google จะใช้เพื่อเข้าถึง API ของคุณ โทเค็นเพื่อการเข้าถึงอาจเป็นค่าสตริงใดก็ได้ แต่จะต้องแสดงถึงผู้ใช้และไคลเอ็นต์ที่โทเค็นนั้นใช้ได้โดยไม่ซ้ำกันและต้องคาดเดาไม่ได้
ส่งการตอบกลับ HTTP ที่เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยัง URL ที่พารามิเตอร์ redirect_uri ระบุไว้ รวมพารามิเตอร์ต่อไปนี้ทั้งหมดในส่วนย่อยของ URL
- access_token: โทเค็นเพื่อการเข้าถึงที่คุณเพิ่งสร้าง
- token_type: สตริง bearer
- state: ค่าสถานะที่ไม่มีการแก้ไขจากคำขอเดิม ต่อไปนี้คือตัวอย่างของ URL ที่ได้
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
```

ตัวแฮนเดิลการเปลี่ยนเส้นทาง OAuth 2.0 ของ Google จะได้รับโทเค็นเพื่อการเข้าถึงและยืนยันว่าค่า state ไม่มีการเปลี่ยนแปลง หลังจาก Google ได้รับโทเค็นเพื่อการเข้าถึงสำหรับบริการของคุณแล้ว Google จะแนบโทเค็นนั้นกับการเรียกการดำเนินการของคุณในภายหลังโดยเป็นส่วนหนึ่งของ AppRequest

เริ่มขั้นตอนการตรวจสอบสิทธิ์

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

ใช้ Intent ตัวช่วยในการลงชื่อเข้าใช้บัญชี เพื่อเริ่มขั้นตอนการตรวจสอบสิทธิ์ ข้อมูลโค้ดต่อไปนี้อธิบายวิธีส่งคำตอบใน Dialogflow และ Actions SDK เพื่อใช้ตัวช่วยนี้

Dialogflow:

Node.js

const {dialogflow, SignIn} = require('actions-on-google');
const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
// Intent that starts the account linking flow.
app.intent('Start Signin', (conv) => {
  conv.ask(new SignIn('To get your account details'));
});

Java

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

JSON

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "PLACEHOLDER"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}",
      "systemIntent": {
        "intent": "actions.intent.SIGN_IN",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec",
          "optContext": "To get your account details"
        }
      }
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}

Actions SDK

Node.js

const {actionssdk, SignIn} = require('actions-on-google');
const app = actionssdk({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
// Intent that starts the account linking flow.
app.intent('actions.intent.TEXT', (conv) => {
  conv.ask(new SignIn('To get your account details'));
});

Java

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

JSON

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "PLACEHOLDER"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.SIGN_IN",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec",
            "optContext": "To get your account details"
          }
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

จัดการคำขอเข้าถึงข้อมูล

หากคำขอ Assistant มีโทเค็นเพื่อการเข้าถึง ก่อนอื่นให้ตรวจสอบว่าโทเค็นเพื่อการเข้าถึงถูกต้อง (และยังไม่หมดอายุ) แล้วจึงเรียกข้อมูลบัญชีผู้ใช้ที่เชื่อมโยงจากฐานข้อมูล