กําหนดค่าเอเจนต์ .NET ของคุณเพื่อใช้ OAuth

OAuth สําหรับตัวแทน .NET ถูกเตรียมใช้งานบนทรัพยากร Azure Bot ของคุณก่อนและการลงทะเบียนแอปที่สอดคล้องกัน จากนั้นระบบรันไทม์ของเอเจนต์จะจัดการรับและรีเฟรชโทเค็นผู้ใช้ให้กับคุณผ่านความสามารถในการลงชื่อเข้าใช้อัตโนมัติ AgentApplication การลงชื่อเข้าใช้อัตโนมัติสามารถเรียกใช้ส่วนกลาง (ประเภทกิจกรรมทั้งหมด) หรือเลือกเพื่อให้สามารถร้องขอโทเค็นได้เฉพาะเส้นทางหรือกิจกรรมบางประเภทเท่านั้น

คุณสามารถลงทะเบียนตัวจัดการ OAuth หลายตัวในการกําหนดค่าและกําหนดตัวจัดการดังกล่าวให้กับเส้นทางเฉพาะ หรือประกาศตัวจัดการเริ่มต้นเดียวที่ใช้ทุกที่ แต่ละตัวจัดการสามารถเลือกที่จะดำเนินการแลกเปลี่ยน On-Behalf-Of (OBO) เมื่อมีการกำหนดค่าไว้ฝั่ง Azure สําหรับการเริ่มต้นอย่างรวดเร็ว ดู ตัวอย่าง AutoSignIn หรือดัดแปลงการกําหนดค่าที่แสดงที่นี่ลงในตัวแทนที่มีอยู่

ส่วนต่อไปนี้อธิบายวิธีการกำหนดค่า UserAuthorization, ตัดสินใจระหว่างวิธีการแบบรวมศูนย์และตามเส้นทาง, และดึงโทเค็น (ทั้งแบบมาตรฐานและ OBO) ออกมาระหว่างช่วงการประมวลผล นอกจากนี้ยังมีคําแนะนําระดับภูมิภาคสําหรับการปรับใช้ที่ไม่ใช่ในสหรัฐอเมริกา

มีการกําหนดค่าตัวแทน .NET ใน appsettings หรือผ่านโค้ดในProgram.cs เอกสารนี้แสดงรายละเอียดโดยใช้ appsettings

การตั้งค่า

วัตถุ UserAuthorization ภายใน AgentApplication ควบคุมว่าได้รับโทเค็นผู้ใช้มาอย่างไร JSON ต่อไปนี้แสดงโครงสร้างแบบลําดับชั้นตามด้วยตารางที่อธิบายแต่ละคุณสมบัติสําหรับ UserAuthorization และ สําหรับวัตถุที่ Settings ซ้อนกัน

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "{{handler-name}}",
      "AutoSignIn": true | false,
      "Handlers": {
        "{{handler-name}}": {
          "Settings": {
            "AzureBotOAuthConnectionName": "{{azure-bot-connection-name}}",
            "OBOConnectionName": "{{connection-name}}",
            "OBOScopes": [
              "{{obo-scope}}"
            ],
            "Title": "{{signin-card-title}}",
            "Text": "{{signin-card-button-text}}",
            "InvalidSignInRetryMax": {{int}},
            "InvalidSignInRetryMessage": {{invalid-attempt-message}},
            "Timeout": {{timeout-ms}}
          }
        }
      }
    }
  }

คุณสมบัติการอนุญาตผู้ใช้

ตารางต่อไปนี้แสดงรายการคุณสมบัติระดับ UserAuthorization บนสุดที่กําหนดวิธีเลือกตัวจัดการและวิธีรับโทเค็นสําหรับแต่ละกิจกรรมที่เข้ามา

เมื่อต้องการจํากัดกิจกรรมที่นําไปใช้กับการลงชื่อเข้าใช้อัตโนมัติ ให้ตั้งค่าเพรดิเคตที่คล้ายกับ: Options.AutoSignIn = (context, ct) => Task.FromResult(context.Activity.IsType(ActivityTypes.Message));

คุณสมบัติการตั้งค่า

ตารางต่อไปนี้อธิบายวัตถุที่ซ้อนกันที่ Settings นําไปใช้กับตัวจัดการ OAuth แต่ละตัว ควบคุมงานนําเสนอการ์ดลงชื่อเข้าใช้ ลักษณะการทํางานการลองใหม่ การหมดเวลา และการกําหนดค่าการแลกเปลี่ยน OBO ทางเลือก

ต้องการใช้ชนิดใด

ใช้ตารางต่อไปนี้เพื่อตัดสินใจว่าวิธีการใดที่เหมาะสมกับสถานการณ์ของคุณ

ใช้โทเค็นในโค้ด (ไม่ใช่ OBO)

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

การกําหนดค่าเฉพาะการลงชื่อเข้าใช้อัตโนมัติเท่านั้น

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

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
          }
        }
      }
    }
  },

โค้ดเอเจนต์ของคุณจะมีลักษณะดังนี้:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext);

        // use the token 
    }
}

การกำหนดค่าแต่ละเส้นทางเท่านั้น

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

  "AgentApplication": {
    "UserAuthorization": {
      "AutoSignIn": false,
      "Handlers": {
        "messageOauth": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
          }
        }
      }
    }
  },

โค้ดเอเจนต์ของคุณจะมีลักษณะดังนี้:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last, autoSignInHandlers: ["messageOauth"]);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext, "messageOauth");

        // use the token
    }
}

ใช้ GetTurnTokenAsync

เรียกใช้ GetTurnTokenAsync เมื่อใดก็ตามที่คุณต้องการโทเค็นผู้ใช้ในระหว่างการเปลี่ยน คุณสามารถเรียกใช้ได้หลายครั้ง เรียกใช้ทันทีก่อนใช้งานเพื่อให้จัดการตรรกะการรีเฟรช (หากจําเป็น) อย่างโปร่งใส

ใช้โทเค็นในโค้ด (OBO)

On-Behalf-Of (OBO) อาศัยการลงชื่อเข้าใช้ของผู้ใช้เริ่มต้นเพื่อส่งกลับโทเค็นที่สามารถเปลี่ยนได้ ที่กําหนดขอบเขตของการเชื่อมต่อ OAuth เพื่อรวมขอบเขตที่สอดคล้องกับขอบเขตที่เปิดเผยโดย API การสตรีม (ตัวอย่างเช่น ถ้าขอบเขตที่ถูกเปิดเผยคือ defaultScopesขอบเขตที่กําหนดค่าอาจเป็น api://botid-{{clientId}}/defaultScopes) จากนั้น Agents SDK จะดําเนินการแลกเปลี่ยนไลบรารีการรับรองความถูกต้อง Microsoft (MSAL) โดยใช้การเชื่อมต่อที่กําหนดค่าไว้ซึ่งระบุโดย OBOConnectionName และรายการของOBOScopes เมื่อมีทั้ง OBOConnectionName และ OBOScopes ในการกําหนดค่าการแลกเปลี่ยนเกิดขึ้นโดยอัตโนมัติ และคุณได้รับโทเค็นสุดท้ายผ่านGetTurnTokenAsync หากอย่างใดอย่างหนึ่งหายไป คุณสามารถดําเนินการแลกเปลี่ยนอย่างชัดเจนในขณะทํางานด้วย ExchangeTurnTokenAsyncช่วยให้คุณสามารถแก้ไขการเชื่อมต่อหรือรายการขอบเขตแบบไดนามิกได้

OBO ในการกําหนดค่า

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

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
            "OBOConnectionName": "ServiceConnection",
            "OBOScopes": [
              "https://myservicescope.com/.default"
            ]
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "{{ClientId}}",
        "FederatedClientId": "{{ManagedIdentityClientId}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

โค้ดเอเจนต์ของคุณจะมีลักษณะดังนี้:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext);

        // use the token
    }
}

OBO Exchange ที่รันไทม์

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

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
            "OBOConnectionName": "ServiceConnection"
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "{{ClientId}}",
        "FederatedClientId": "{{ManagedIdentityClientId}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

โค้ดเอเจนต์ของคุณจะมีลักษณะดังนี้:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var scopes = GetScopes();

        var exchangedToken = await UserAuthorization.ExchangeTurnTokenAsync(turnContext, exchangeScopes: scopes);

        // use the token
    }
}

การตั้งค่า OAuth ระดับภูมิภาค

สําหรับภูมิภาคที่ไม่ใช่ของสหรัฐอเมริกา คุณจําเป็นต้องอัปเดตตําแหน่งข้อมูลบริการโทเค็นที่ตัวแทนของคุณใช้

เพิ่มรายการต่อไปนี้ลงใน appsettings.json:

"RestChannelServiceClientFactory": {
   "TokenServiceEndpoint": "{{service-endpoint-uri}}"
}

สําหรับ service-endpoint-urlใช้ค่าที่เหมาะสมจากตารางต่อไปนี้สําหรับบอทระบบคลาวด์สาธารณะที่มีที่เก็บข้อมูลในภูมิภาคที่ระบุ