次の方法で共有

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 キーを自動的に登録でき、エージェント ツールキット プロジェクトの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 認証コード フロー

OAuth2 で保護されたサービスのユーザー データにアクセスするためのユーザー委任アクセス許可。 TypeSpec のネイティブ OAuth2Auth を使用します。 統合する特定の API に基づいて、 authorizationUrl、 tokenUrl、 refreshUrl、 scopes を更新します。

エージェント ツールキットを使用して Entra ID アプリを自動的に作成し、登録が完了したら Entra ID アプリを更新する方法について説明します。

例

@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
}

Microsoft 365 Agents Toolkit では、OAuth2 構成を自動的に登録でき、エージェント ツールキット プロジェクトの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 に接続するMicrosoft 365 Copilotに TypeSpec を使用する Tasks エージェントのサンプルでは、承認コード フローでの OAuth2 の使用が強調されています。

Entra ID 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">
  • Last updated on