Поддержка проверки подлинности в TypeSpec для Microsoft 365 Copilot

TypeSpec для 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 или личных маркеров доступа, применяемых ко всем пространствам имен. Используйте собственный ApiKeyAuth код из TypeSpec.

Пример

@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 действие для 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

Делегированные пользователем разрешения на доступ к данным пользователей в защищенной службе OAuth2. Используйте собственный OAuth2Auth код из TypeSpec. authorizationUrlОбновите , tokenUrl, refreshUrlи scopes на основе конкретного API, с которым вы интегрируете.

Узнайте, как автоматически создать приложение 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, а также добавить oauth/register действие для 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

В примере агента задач, использующего TypeSpec для Microsoft 365 Copilot, который подключается к API Microsoft Graph, подчеркивается использование OAuth2 с потоком кода авторизации.

Проверка подлинности единого входа в Entra ID

Простая проверка подлинности с применением существующего сеанса Microsoft 365 пользователя для сценариев собственной интеграции. Чтобы завершить регистрацию единого входа, используйте обычный 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">
  • Last updated on