Поддержка аутентификации в TypeSpec для Microsoft 365 Copilot

Совет

Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.

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 в вашем проекте Agents Toolkit.

# 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. Используйте нативный OAuth2Auth из TypeSpec. Обновите , tokenUrlrefreshUrl, authorizationUrlи 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 действие в m365agents.yml в проекте Agents Toolkit.

# 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 с потоком кода авторизации.

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

Проверка подлинности, применяющая существующий сеанс пользователя 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">