適用於 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根據您要整合的特定 API 更新 、 tokenUrl、 refreshUrl和scopes。

了解如何使用代理程式工具組自動建立 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 金鑰登錄中指定登錄識別碼。 此方法將身份驗證配置與代碼分開,從而實現更好的安全實踐和跨不同環境的更輕鬆的憑據管理。

範例

// 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">