TypeSpec for Microsoft 365 Copilot での認証サポート

TypeSpec for Microsoft 365 Copilot では、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 キーを自動的に登録できるほか、Agents Toolkit プロジェクトでm365agents.ymlするapiKey/registerアクションを追加することもできます。

# 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 を使用します。 統合する特定の API に基づいて、 authorizationUrl、 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 構成を自動的に登録し、Agents Toolkit プロジェクトでm365agents.ymlするoauth/registerアクションを追加することもできます。

# 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 サンプルに接続する TypeSpec for Microsoft 365 Copilot を使用するタスク エージェントは、認証コード フローでの OAuth2 の使用を強調しています。

Microsoft Entra SSO 認証

ネイティブ統合シナリオにユーザーの既存の Microsoft 365 セッションを適用する認証。 SSO 登録を完了するには、通常の OAuth2Auth フローを使用し、 手動の手順を実行します。

登録済み認証構成の使用

運用シナリオでは、認証資格情報を TypeSpec コードに直接埋め込むのではなく、Microsoft Teams 開発者ポータルを使用して登録および管理します。 @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">
  • 最終更新: