Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Совет
Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.
TypeSpec для Microsoft 365 Copilot поддерживает несколько методов проверки подлинности для защиты плагинов API и интеграции с внешними службами. Поддерживаются следующие типы проверки подлинности:
- Отсутствие проверки подлинности для общедоступных конечных точек
- Проверка подлинности ключа API для простого доступа на основе маркеров
- Поток кода авторизации OAuth2 для безопасных интеграций сторонних поставщиков
- Единый вход (SSO) в Microsoft Entra для интеграции удостоверений Microsoft 365
Примечание
Эта документация охватывает сценарии проверки подлинности, характерные для 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">