适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 的 TypeSpec 中的身份验证支持

提示

受到推崇的: 从 Work IQ 开发工具 开始,用于受支持的专业代码声明代理和插件方案。 请参阅 WIQD 快速入门。 基于工具包的说明仍然可用于需要它们的现有项目和工作流。 在选择工具之前,请检查 功能和目标体验支持 : WIQD 不面向自定义引擎代理。

适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的 TypeSpec 支持多种身份验证方法,以保护 API 插件并与外部服务集成。 支持的身份验证类型包括:

注意

本文档介绍智能 智能 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">