提示
受到推崇的: 从 Work IQ 开发工具 开始,用于受支持的专业代码声明代理和插件方案。 请参阅 WIQD 快速入门。 基于工具包的说明仍然可用于需要它们的现有项目和工作流。 在选择工具之前,请检查 功能和目标体验支持 : WIQD 不面向自定义引擎代理。
适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的 TypeSpec 支持多种身份验证方法,以保护 API 插件并与外部服务集成。 支持的身份验证类型包括:
- 没有对公共终结点进行身份验证
- 用于基于令牌的简单访问的 API 密钥身份验证
- 用于安全非 Microsoft 集成的 OAuth2 授权代码流
- Microsoft Entra单一登录 (SSO) 身份验证,用于 Microsoft 365 标识集成
注意
本文档介绍智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®特定于身份验证方案。 有关全面的 TypeSpec 身份验证文档,包括所有本机身份验证装饰器和模式,请参阅 有关身份验证的 TypeSpec 文档。
匿名) (不进行身份验证
不需要任何身份验证凭据的公共终结点。 API 不需要任何特定内容。 如果没有 @useAuth 修饰器,所有 API 都被视为匿名。
示例
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
namespace API {
// Endpoints
}
API 密钥身份验证
使用应用于整个命名空间的 API 密钥或个人访问令牌进行身份验证。 使用 TypeSpec 中的本机 ApiKeyAuth 。
示例
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">)
namespace API {
// Endpoints
}
Microsoft 365 Agents Toolkit 可以自动注册您的 API 密钥,还可以将操作 apiKey/register 添加到 Agents Toolkit 项目中的 m365agents.yml 。
# m365agents.yml
# After the typespec/compile step
- uses: apiKey/register
with:
name: ApiKeyAuth
appId: ${{TEAMS_APP_ID}}
apiSpecPath: ./appPackage/.generated/api-openapi.yml
writeToEnvironmentFile:
registrationId: APIKEYAUTH_REGISTRATION_ID
使用智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®管理修复示例重点介绍了 API 密钥身份验证的使用。
OAuth2 授权代码流
用户委派的访问受 OAuth 2.0 保护的服务中的用户数据的权限。 使用 TypeSpec 中的本机 OAuth2Auth 。 更新 authorizationUrl、 tokenUrl、 refreshUrl并 scopes 根据要集成的特定 API。
了解如何使用代理工具包自动创建 Microsoft Entra 应用注册,并在注册完成后更新 Microsoft Entra 应用注册。
示例
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
tokenUrl: "https://contoso.com/oauth2/v2.0/token";
refreshUrl: "https://contoso.com/oauth2/v2.0/token";
scopes: ["scope-1", "scope-2"];
}]>)
namespace API {
// Endpoints
}
Agents Toolkit 可以自动注册您的 OAuth2 配置,还可以将操作 oauth/register 添加到 Agents Toolkit 项目中的 m365agents.yml 。
# m365agents.yml
# After the typespec/compile step
- uses: oauth/register
with:
name: OAuth2Auth
appId: ${{TEAMS_APP_ID}}
clientId: ${{AAD_APP_CLIENT_ID}}
clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
apiSpecPath: ./appPackage/.generated/api-openapi.yml
flow: authorizationCode
writeToEnvironmentFile:
configurationId: OAUTH2AUTH_REGISTRATION_ID
任务代理使用连接到 Microsoft Graph API 示例的智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® TypeSpec 突出显示了将 OAuth2 与授权代码流一起使用。
Microsoft Entra SSO 身份验证
将用户的现有 Microsoft 365 会话应用到本机集成方案的身份验证。 要完成 SSO 注册,请使用常规 OAuth2Auth 流并执行 手动步骤。
使用已注册的身份验证配置
对于生产应用场景,请通过 Microsoft Teams 开发人员门户注册和管理身份验证凭据,而不是直接将其嵌入 TypeSpec 代码中。 使用装饰器按 @authReferenceId 其唯一标识符引用预先注册的身份验证配置。 此方法提供了一种安全的方式来处理凭据,而无需在代码库中公开敏感信息。
使用 @authReferenceId时,请从 OAuth 客户端注册或在开发人员门户中配置的 API 密钥注册中指定注册 ID。 这种方法将身份验证配置与代码分开,从而实现更好的安全实践并更轻松地跨不同环境进行凭据管理。
示例
// Reference to OAuth2 client registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
// Endpoints
}
@authReferenceId("NzFmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IyM5NzQ5Njc3Yi04NDk2LTRlODYtOTdmZS1kNDUzODllZjUxYjM=")
model Auth is OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
tokenUrl: "https://contoso.com/oauth2/v2.0/token";
refreshUrl: "https://contoso.com/oauth2/v2.0/token";
scopes: ["scope-1", "scope-2"];
}]>
// Reference to API key registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
// Endpoints
}
@authReferenceId("5f701b3e-bf18-40fb-badd-9ad0b60b31c0")
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">