Краткое руководство: Авторизация пользователей и вызов дочерних API с помощью пакета SDK Microsoft Entra для идентификатора агента в TypeScript

В этом кратком руководстве вы используете пример веб-приложения, чтобы узнать, как войти в систему как пользователи или агенты и вызывать подчиненные API, используя свою собственную идентификацию. В примере приложения используется пакет SDK Microsoft Entra для идентификатора агента для проверки маркеров пользователей для делегированного доступа и использования удостоверения приложения для обмена данными между службами с нижестоящими API, такими как Microsoft Graph.

Предпосылки

Установите Node.js 18.x или более поздней версии.
Установите Docker Desktop.
Учетная запись Azure с активной подпиской. Если у вас еще нет учетной записи, создайте бесплатную учетную запись.
Эта Azure учетная запись должна иметь разрешения на управление приложениями. К любым из следующих ролей Microsoft Entra относятся необходимые разрешения:
- Администратор приложений
- Разработчик приложения
Арендатор рабочей силы. Вы можете использовать каталог по умолчанию или настроить новый клиент.

Создание и настройка приложения Microsoft Entra

Чтобы завершить оставшуюся часть инструкции быстрого старта, необходимо сначала зарегистрировать приложение в Microsoft Entra ID.

Создание регистрации приложения

Чтобы зарегистрировать приложение, выполните следующие действия.

Войдите в центр администрирования Microsoft Entra как минимум в роли разработчика приложений.
Если у вас есть доступ к нескольким арендаторам, используйте значок параметров в верхнем меню, чтобы переключиться на арендатора, в котором требуется зарегистрировать приложение.
Перейдите к Entra ID>Регистрация приложений и выберите Новая регистрация.
Введите понятное имя приложения, например identity-client-app. Пользователи приложения видят это имя и вы можете изменить его в любое время. Вы можете иметь несколько регистраций приложений с одинаковым именем.

В разделе "Поддерживаемые типы учетных записей" укажите, кто может использовать приложение. Выберите только учетные записи в этом каталоге организации для большинства приложений. Дополнительные сведения о каждом параметре см. в таблице.

Поддерживаемые типы счетов	Description
Accounts in this organizational directory only (Учетные записи только в этом каталоге организации)	Для приложений с одним арендатором, предназначенных только для пользователей (или гостей) в вашем арендаторе.
Учетные записи в любом каталоге организации	Для приложений multitenant и при этом, вы хотите, чтобы пользователи из любой клиентский организации Microsoft Entra могли использовать ваше приложение. Идеально подходит для приложений SaaS, которые вы планируете предоставлять нескольким организациям.
Учетные записи в любом каталоге организации и личные учетные записи Майкрософт	Для многопользовательских приложений, поддерживающих организационные и личные учетные записи Майкрософт (например, Skype, Xbox, Live, Hotmail).
Персональные учетные записи Майкрософт	Для приложений, используемых только личными учетными записями Майкрософт (например, Skype, Xbox, Live, Hotmail).

Нажмите кнопку "Регистрация", чтобы завершить регистрацию приложения.
Отображается страница обзора приложения . Запишите следующие значения на странице обзора приложения для последующего использования:
- Идентификатор приложения (клиента)
- Идентификатор каталога (арендатора)

Добавьте URI перенаправления

Пример приложения TypeScript использует интерактивную проверку подлинности с потоком входа на основе браузера. Настройте URI перенаправления для обработки ответа проверки подлинности:

В вашей регистрации приложения, в разделе Управление, выберите Аутентификация.
Выберите Добавить платформу.
Выберите мобильные и настольные приложения.
В разделе URI пользовательского перенаправления введите http://localhost.
Выберите и настройте.

Добавление учетных данных клиента

Пакет SDK Microsoft Entra для идентификатора агента использует учетные данные клиента для аутентификации и получения токенов для подчиненных API. Для локальной разработки и тестирования используйте самозаверяющий сертификат для проверки подлинности.

Создание самозаверяющего сертификата

Запустите PowerShell от имени администратора и используйте следующие команды для создания самозаверяющего сертификата:

# Generate a self-signed certificate
$cert = New-SelfSignedCertificate `
    -Subject "CN=AgentID-Client-Certificate" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -KeyAlgorithm RSA `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(7)

# Export public key (CER) for upload to Azure
$cerPath = "agentid-client-certificate.cer"
Export-Certificate -Cert $cert -FilePath $cerPath

# Export private key (PFX) for the Agent ID SDK container
# Replace <your-pfx-password> with a strong password and store it securely (for example, in a secret store).
$pfxPath = "agentid-client-certificate.pfx"
$certPassword = ConvertTo-SecureString -String "<your-pfx-password>" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath $pfxPath -Password $certPassword


Write-Host "Certificate generated successfully!"
Write-Host "CER file (public key): $cerPath"
Write-Host "PFX file (private key): $pfxPath"
Write-Host "Certificate Thumbprint: $($cert.Thumbprint)"

Запишите отпечаток сертификата, отображаемый в выходных данных PowerShell. Необходимо убедиться, чтобы сертификат в центре администрирования Microsoft Entra, совпадал с установленным локально.

Отправка сертификата в Microsoft Entra ID

Выполните следующие действия, чтобы отправить файл .cer, созданный в текущем каталоге, в Центр администрирования Microsoft Entra:

Откройте регистрацию приложения в Центр администрирования Microsoft Entra
В разделе Управление, выберите Сертификаты и секреты.
На вкладке "Сертификаты" выберите " Отправить сертификат".
.cer Выберите созданный файл (например, agentid-client-cert.cer).
Укажите описание (например, "Сертификат локальной разработки AgentID").
Нажмите кнопку "Добавить".
Запишите отображаемый отпечаток сертификата (он должен соответствовать тому, что был получен при генерации вашего сертификата).

Замечание

В рабочих средах используйте сертификаты, выданные доверенным центром сертификации (ЦС), и сохраните их в Azure Key Vault с доступом к управляемому удостоверению. Самозаверяющий сертификат должен использоваться только для локальной разработки и тестирования.

Конфигурация разрешений API

Выполните следующие действия, чтобы настроить делегированные разрешения для Microsoft Graph. С этими разрешениями клиентское приложение может выполнять операции от имени пользователя, вошедшего в систему, например чтение электронной почты.

В регистрации вашего приложения, в разделе Manage выберите разрешения API>Добавить разрешение>Microsoft Graph.
Выберите Делегированные разрешения. Microsoft Graph предоставляет множество разрешений, при этом наиболее часто используемые показаны наверху списка.
В разделе "Выбор разрешений" выберите и добавьте User.Read.

Настройка разрешений приложения

Чтобы протестировать потоки, доступные только для приложений, когда пакет SDK для идентификатора агента вызывает API с помощью собственного удостоверения (без контекста пользователя), настройте разрешения приложения:

На странице разрешений API выберите Добавить разрешение>Microsoft Graph.
Выберите Разрешения приложения.
В разделе "Выбор разрешений" найдите и выберите User.Read.All.
Выберите Добавить разрешения.
Выберите "Предоставить согласие администратора" для [вашего клиента] и подтвердите его.

Замечание

Разрешения приложения требуют согласия администратора. Без этого шага конечные точки приложений в разделе тестирования дают сбой.

Открыть API (для проверки токенов)

Чтобы вызвать конечную точку SDK /validate для идентификатора агента с токенами, выданными специально для вашего приложения (используя область api://<application-client-id>/access_as_user), необходимо выполнить этот шаг. Если вы тестируете только сценарии Microsoft Graph с делегированными разрешениями, можно пропустить этот раздел. Выполните следующие действия, чтобы предоставить API, содержащий необходимые области:

В разделе "Управление" выберите "Предоставить API".
В верхней части страницы нажмите кнопку "Добавить рядом с URI идентификатора приложения". Это значение по умолчанию равно api://<application-client-id>. URI идентификатора приложения выступает в качестве префикса для областей, на которые вы будете ссылаться в коде API, и должен быть глобально уникальным. Нажмите кнопку "Сохранить".
Выберите "Добавить область", как показано ниже.
Затем укажите атрибуты области в панели «Добавить область», как показано ниже.
- Имя области: access_as_user
- Кто может предоставить согласие: администраторы и пользователи
- Отображаемое имя согласия администратора: доступ к пакету SDK идентификатора агента от имени пользователя
- Описание согласия администратора: Разрешить доступ к API SDK идентификаторов агента в качестве вошедшего в систему пользователя
- Состояние: включено
Выберите Добавить область.

Запустите пакет SDK Microsoft Entra для AgentID

Пакет SDK Microsoft Entra для идентификатора агента — это контейнеризированная веб-служба, которая обрабатывает получение токенов, их валидацию и выполнение защищенных нижестоящих вызовов API. Он работает как вспомогательный контейнер вместе с вашим приложением, что позволяет выгрузить логику идентификации в выделенную службу.

Создание файла конфигурации

Пакету SDK идентификатора агента необходим конфигурационный файл для подключения к вашему приложению Microsoft Entra. Создайте каталог для конфигурации и создайте appsettings.json файл:

# Create a directory for the Agent ID SDK configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

# Create the appsettings.json file
New-Item -ItemType File -Path "appsettings.json"

Откройте appsettings.json в предпочитаемом текстовом редакторе и добавьте следующую конфигурацию, заменив значения заполнителей сведениями о приложении Microsoft Entra:

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "YOUR_TENANT_ID_HERE",
        "ClientId": "YOUR_CLIENT_ID_HERE",
        "ClientCredentials": [
            {
                "SourceType": "Path",
                "CertificateStorePath": "agentid-client-certificate.pfx",
                "CertificateDistinguishedName": "<your-pfx-password>"
            }
        ]
    },
    "DownstreamApis": {
        "me": {
            "BaseUrl": "https://graph.microsoft.com/v1.0/",
            "RelativePath": "me",
            "Scopes": [ "User.Read" ]
        }
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*"
}

Загрузка и запуск контейнера SDK Agent ID

SDK идентификаторов агентов доступен в виде готового образа контейнера из Реестра контейнеров Майкрософт (MCR). Перед извлечением образа контейнера убедитесь, что Docker Desktop запущен. Если Docker не запущен, откройте Docker Desktop и дождитесь отображения состояния "Docker Desktop запущено".

Перейдите в каталог конфигурации и выполните следующие команды:

# Navigate to your config directory
cd agentid-config

# Pull the Agent ID SDK container image from MCR
docker pull mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Run the container
docker run -d `
    --name agentid-sdk `
    -p 5178:8080 `
    -e ASPNETCORE_ENVIRONMENT=Development `
    mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Copy configuration files into the container
docker cp appsettings.json agentid-sdk:/app/appsettings.json
docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx

# Restart the container to apply the configuration
docker restart agentid-sdk

Замечание

Для узлов Windows используйте вариант контейнера Windows: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

Вы можете управлять контейнером пакета SDK для идентификаторов агента с помощью следующих команд Docker:

Просмотр журналов контейнеров: docker logs agentid-sdk
Просмотр журналов в режиме реального времени: docker logs -f agentid-sdk
Остановите контейнер: docker stop agentid-sdk
Снова запустите контейнер: docker start agentid-sdk
Удалите контейнер: docker rm agentid-sdk

Убедитесь, что контейнер запущен

Можно проверить, работает ли контейнер пакета SDK для идентификатора агента правильно, вызвав конечную точку проверки работоспособности:/healthz

Invoke-RestMethod -Uri "http://localhost:5178/healthz" -ErrorAction SilentlyContinue

Эта конечная точка возвращает Healthyзначение, которое подтверждает, что пакет SDK идентификатора агента работает правильно и готов к обработке запросов. Не останавливайте Agent ID SDK во время тестирования. Контейнер должен продолжать работать в фоновом режиме для всех вызовов проверки подлинности и API из примера приложения TypeScript.

Запуск примера приложения TypeScript

Пример приложения на TypeScript демонстрирует, как использовать SDK Microsoft Entra для Agent ID для проверки токенов пользователей. Приложение — это сервер Express.js, который проверяет входящие запросы с помощью пакета SDK идентификатора агента. Пакет SDK для идентификаторов агента также может вызывать подчиненные API, такие как Microsoft Graph от вашего имени.

Клонирование или скачивание примера приложения

Скачайте пример приложения TypeScript и извлеките его в локальный каталог. Кроме того, клонируйте репозиторий, открыв командную строку, перейдя в нужное расположение проекта и выполнив следующую команду:

git clone https://github.com/AzureAD/microsoft-identity-web.git

После клонирования репозитория перейдите к примеру приложения TypeScript:

cd microsoft-identity-web/tests/DevApps/SidecarAdapter/typescript

Пример приложения TypeScript состоит из трех основных файлов, которые работают вместе для демонстрации шаблонов проверки подлинности с помощью пакета SDK Microsoft Entra для AgentID.

sidecar.ts: Предоставляет класс SidecarClient, являющийся клиентом TypeScript, который взаимодействует с контейнером Agent ID SDK. Он отправляет токены-носители в конечную точку SDK /Validate идентификатора агента, получает проверенный токен вместе с заявками пользователя и обрабатывает ошибки проверки токена.

app.ts: веб-сервер Express.js, который выполняет проверку подлинности всех входящих запросов. Он извлекает маркеры носителя из заголовка авторизации и проверяет их с помощью SidecarClient. Если проверка завершается ошибкой, сервер возвращает 401 несанкционированный ответ. При успешной проверке он присоединяет утверждения пользователя к объекту запроса через req.sidecarValidation,для использования в подчиненных обработчиках маршрутов.

sidecar.test.ts. Содержит автоматические тесты интеграции, которые проверяют полный поток проверки подлинности. Набор тестов начинается с запуска сервера Express, а затем использует MSAL Node для интерактивной аутентификации через браузер и получения токена доступа с необходимыми разрешениями. Затем выполняется HTTP-запрос к серверу с приобретенным токеном, и проверяется, что SDK идентификатора агента корректно валидирует токен перед возвратом утвержденных данных пользователя.

Установка зависимостей

Перейдите к примеру каталога TypeScript и установите необходимые пакеты:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm install

Настройка примера приложения

Перед запуском примера приложения настройте его с сведениями о приложении следующим образом:

Откройте sidecar.test.ts и обновите идентификатор клиента, идентификатор арендатора и области, чтобы соответствовать регистрации вашего приложения.
Создайте файл в каталоге .envtypescript для переменных среды:
```
# Create .env file
New-Item -ItemType File -Path ".env" -Force
```
Добавьте следующую конфигурацию .env:
```
PORT=5555
SIDECAR_BASE_URL=http://localhost:5178
```

Запуск сервера Express

Запустите пример приложения TypeScript, выполнив команду npm start. Сервер запускается http://localhost:5555 и готов принимать прошедшие проверку подлинности запросы. Выходные данные должны выглядеть примерно так:

Server listening on port 5555
Sidecar base URL: http://localhost:5178

Откройте это окно терминала. Сервер Express должен продолжать работать, чтобы обрабатывать тестовые запросы в следующем разделе.

Тестирование примера приложения TypeScript

Теперь, когда запущен контейнер пакета SDK для идентификаторов агента и сервер Express, можно протестировать сценарии проверки подлинности и вызовов API.

Тестирование с помощью делегированных пользователем разрешений

В этом сценарии показано, как выполнить вход пользователя, получить токен и вызвать сервер Express с этим токеном.

Получение токена пользователя

Пример включает в себя автоматизированный тест, который получает токен пользователя с помощью MSAL. Откройте новое окно PowerShell (продолжайте работу сервера Express) и выполните следующую команду:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm test

Эта команда запускает тест интеграции, который:

Открывает окно браузера для интерактивной проверки подлинности
Получает токен доступа с областью api://<your-client-id>/access_as_user
Вызывает сервер Express с токеном
Проверяет, что SDK идентификатора агента успешно валидирует маркер.

При первом запуске вам будет предложено войти с помощью учетных данных Microsoft Entra. Окно браузера открывается автоматически. После успешной проверки подлинности вы можете закрыть браузер.

Ручное тестирование с помощью curl

Если вы предпочитаете ручное тестирование, вы можете получить маркер и вызвать сервер Express напрямую:

# First, get a token (you'll need to implement token acquisition or extract from test output)
$token = "YOUR_ACCESS_TOKEN_HERE"

# Call the Express server
Invoke-RestMethod -Uri "http://localhost:5555/api/protected" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Method Get

Ожидаемый ответ:

message                                                  protocol token          claims
-------                                                  -------- -----          ------
Request authenticated via Microsoft Identity Web Sidecar Bearer   ***redacted*** @{aud=api://"Your client ID"; iss=https://sts.win…

Проверка аутентификации только для приложений

В этом сценарии показано, как вызывать внешние API с помощью собственного удостоверения приложения без использования контекста пользователя.

В окне PowerShell вызовите пакет Agent ID SDK непосредственно для тестирования потока, предназначенного только для приложений.

# Call Microsoft Graph using application identity
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/me" `
    -Method Get

Эта конечная точка:

Выполняет проверку подлинности с помощью сертификата приложения (настроено в appsettings.json)
Получает токен доступа только для приложений для Microsoft Graph
Вызывает конечную точку API Graph /me
Возвращает информацию об учетной записи службы

Замечание

Для этого сценария требуется User.Read.All разрешение приложения с согласием администратора (настроено ранее в кратком руководстве).

Тестирование пользовательских вызовов API нижнего потока

Вы можете протестировать настраиваемые конфигурации дочернего API, добавив их в пакет SDK идентификатора агента appsettings.json.

"DownstreamApis": {
    "me": {
        "BaseUrl": "https://graph.microsoft.com/v1.0/",
        "RelativePath": "me",
        "Scopes": [ "User.Read" ]
    },
    "users": {
        "BaseUrl": "https://graph.microsoft.com/v1.0/",
        "RelativePath": "users",
        "Scopes": [ "User.Read.All" ]
    }
}

Затем перезапустите контейнер пакета SDK для идентификатора агента и проверьте новую конечную точку:

# Restart container to reload configuration
docker restart agentid-sdk

# Test the new endpoint
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/users" `
    -Method Get

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-19

Вход для пользователей и вызов дочерних API с помощью SDK Microsoft Entra в TypeScript для идентификатора агента.

Предпосылки

Создание и настройка приложения Microsoft Entra

Создание регистрации приложения

Добавьте URI перенаправления

Добавление учетных данных клиента

Создание самозаверяющего сертификата

Отправка сертификата в Microsoft Entra ID

Конфигурация разрешений API

Настройка разрешений приложения

Открыть API (для проверки токенов)

Запустите пакет SDK Microsoft Entra для AgentID

Создание файла конфигурации

Загрузка и запуск контейнера SDK Agent ID

Убедитесь, что контейнер запущен

Запуск примера приложения TypeScript

Клонирование или скачивание примера приложения

Установка зависимостей

Настройка примера приложения

Запуск сервера Express

Тестирование примера приложения TypeScript

Тестирование с помощью делегированных пользователем разрешений

Получение токена пользователя

Ручное тестирование с помощью curl

Проверка аутентификации только для приложений

Тестирование пользовательских вызовов API нижнего потока

Связанный контент

Обратная связь

Дополнительные ресурсы