Démarrage rapide : Connecter des utilisateurs et appeler des API en aval avec le SDK d’authentification Microsoft Entra ID (sidecar) dans TypeScript

Dans ce guide de démarrage rapide, vous utilisez un exemple d’application web pour apprendre à connecter des utilisateurs ou des agents et à appeler des API en aval à l’aide de sa propre identité. L’exemple d’application utilise le SDK d’authentification Microsoft Entra ID (sidecar) pour valider les jetons des utilisateurs dans le cadre d’un accès délégué et utilise l’identité d’application pour la communication entre services avec des API en aval telles que Microsoft Graph.

Prerequisites

Installez Node.js 18.x ou version ultérieure.
Installez Docker Desktop.
Un compte Azure avec un abonnement actif. Si vous n’en avez pas encore, créez un compte gratuitement.
Ce compte Azure doit disposer des autorisations nécessaires pour gérer les applications. L’un des rôles Microsoft Entra suivants inclut les autorisations requises :
- Administrateur d’application
- Développeur d’applications
Un locataire d’employés. Vous pouvez utiliser votre répertoire par défaut ou configurer un nouveau locataire.

Créer et configurer votre application Microsoft Entra

Pour suivre le reste du guide de démarrage rapide, vous devez d’abord inscrire une application dans Microsoft Entra ID.

Créer un enregistrement d’application

Effectuez les étapes suivantes pour créer l’inscription d’application :

Connectez-vous au centre d’administration Microsoft Entra comme au moins un Application Developer.
Si vous avez accès à plusieurs locataires, utilisez l’icône Paramètres dans le menu supérieur pour basculer vers le locataire dans lequel vous souhaitez inscrire l’application.
Accédez à Entra ID>Inscriptions d'applications et sélectionnez Nouvelle inscription.
Entrez un nom explicite pour votre application, par exemple identity-client-app. Les utilisateurs de l’application voient ce nom et vous pouvez le modifier à tout moment. Vous pouvez avoir plusieurs inscriptions d’applications portant le même nom.

Sous Types de comptes pris en charge, spécifiez qui peut utiliser l’application. Sélectionnez Comptes dans cet annuaire organisationnel uniquement pour la plupart des applications. Pour plus d’informations sur chaque option, reportez-vous au tableau.

Types de comptes pris en charge	Descriptif
Comptes dans cet annuaire organisationnel uniquement	Pour les applications monolocataires destinées uniquement aux utilisateurs (ou invités) de votre abonnement.
Comptes dans n’importe quel annuaire organisationnel	Pour les applications multitenant et si vous souhaitez que des utilisateurs de n'importe quel tenant Microsoft Entra puissent utiliser votre application. Idéal pour les applications SaaS (software-as-a-service) que vous envisagez de fournir à plusieurs organisations.
Accounts dans n’importe quel annuaire organisationnel et comptes de Microsoft personnels	Pour les applications multitenant qui prennent en charge les comptes d’Microsoft organisationnels et personnels (par exemple, Skype, Xbox, Live, Hotmail).
comptes Microsoft personnels	Pour les applications utilisées uniquement par des comptes de Microsoft personnels (par exemple, Skype, Xbox, Live, Hotmail).

Sélectionnez Inscrire pour terminer l’inscription de l’application.
La page Vue d’ensemble de l’application s’affiche. Enregistrez les valeurs suivantes à partir de la page Vue d’ensemble de l’application pour une utilisation ultérieure :
- ID d’application (client)
- ID de l’annuaire (locataire)

Ajouter un URI de redirection

L’exemple d’application TypeScript utilise l’authentification interactive avec un flux de connexion basé sur un navigateur. Configurez un URI de redirection pour gérer la réponse d’authentification :

Dans l’inscription de votre application, sous Gérer, sélectionnez Authentification.
Sélectionnez Ajouter une plateforme.
Sélectionnez Applications mobiles et de bureau.
Sous URI de redirection personnalisé, entrez http://localhost.
Sélectionnez Configurer.

Ajouter des informations d’identification client

Le kit SDK d’Microsoft Entra ID Auth (sidecar) utilise les informations d’identification du client pour authentifier et acquérir des jetons pour les API en aval. Pour le développement et les tests locaux, utilisez un certificat auto-signé pour l’authentification.

Générer un certificat auto-signé

Exécutez PowerShell en tant qu’administrateur et utilisez les commandes suivantes pour générer un certificat auto-signé :

# 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 Entra ID Auth SDK (sidecar) 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)"

Enregistrez l’empreinte numérique du certificat affichée dans la sortie PowerShell. Vous devez vérifier que le certificat du centre d'administration de Microsoft Entra correspond à celui installé localement.

Charger le certificat dans Microsoft Entra ID

Procédez comme suit pour charger le fichier .cer créé dans votre répertoire actif dans le centre d’administration Microsoft Entra :

Ouvrez l’inscription de votre application dans le centre d’administration Microsoft Entra
Sous Gérer, sélectionnez Certificats et secrets.
Dans l’onglet Certificats, sélectionnez Charger un certificat.
Sélectionnez le .cer fichier que vous avez généré (par exemple). agentid-client-cert.cer
Fournissez une description (par exemple, « Certificat de développement local AgentID »).
Sélectionnez Ajouter.
Enregistrez l’empreinte numérique du certificat affichée (elle doit correspondre à celle de votre génération de certificat).

Note

Pour les environnements de production, utilisez des certificats émis par une autorité de certification approuvée et stockez-les dans Azure Key Vault avec l’accès aux identités managées. Les certificats auto-signés ne doivent être utilisés que pour le développement et les tests locaux.

Configurez les autorisations d’API

Suivez ces étapes pour configurer les autorisations déléguées pour Microsoft Graph. Avec ces autorisations, votre application cliente peut effectuer des opérations pour le compte de l’utilisateur connecté, telles que la lecture de son e-mail.

Dans l’inscription de votre application, sous Manage, sélectionnez API permissions>Add a permission>Microsoft Graph.
Sélectionnez Autorisations déléguées. Microsoft Graph expose de nombreuses autorisations, avec le plus couramment utilisé en haut de la liste.
Sous Sélectionner des autorisations, sélectionnez et ajoutez User.Read.

Configurer les autorisations d’application

Pour tester les flux d’application uniquement où le sdk d’Entra ID Auth (sidecar) appelle des API à l’aide de sa propre identité (sans contexte utilisateur), configurez les autorisations d’application :

Dans la page API, sélectionnez Add une autorisation>Microsoft Graph.
Sélectionnez Autorisations de l’application.
Sous Sélectionner des autorisations, recherchez et sélectionnez User.Read.All.
Sélectionnez Ajouter des autorisations.
Sélectionnez Accorder le consentement de l’administrateur pour [Votre locataire] et confirmez.

Note

Les autorisations d’application nécessitent le consentement de l’administrateur. Sans cette étape, les points de terminaison réservés uniquement à l'application dans la section de test échouent.

Exposer une API (pour les tests de validation de jeton)

Pour appeler le point de terminaison /validate du SDK Auth Entra ID (sidecar) avec des jetons émis spécifiquement pour votre application (en utilisant la portée api://<application-client-id>/access_as_user), vous devez effectuer cette étape. Si vous testez uniquement des scénarios Microsoft Graph avec des autorisations déléguées, vous pouvez ignorer cette section. Procédez comme suit pour exposer une API contenant les étendues requises :

Sous Gérer, sélectionnez Exposer une API.
En haut de la page, sélectionnez Ajouter à côté d’URI D’ID d’application. Cette valeur est définie par défaut sur api://<application-client-id>. L’URI d’ID d’application, qui doit être globalement unique, fait office de préfixe pour les étendues que vous référencerez dans le code de votre API. Cliquez sur Enregistrer.
Sélectionnez Ajouter une étendue comme indiqué :
Ensuite, spécifiez les attributs de l’étendue dans le volet Ajouter une étendue , comme suit :
- Nom de l’étendue : access_as_user
- Qui peut donner son consentement : Administrateurs et utilisateurs
- Nom d’affichage du consentement de l’administrateur : Accédez au kit SDK d’Entra ID Auth (sidecar) en tant qu’utilisateur
- Description du consentement de l’administrateur : autoriser l’accès aux API du SDK d’authentification Entra ID (sidecar) en tant qu’utilisateur connecté
- État : activé
Sélectionnez Ajouter une étendue.

Démarrez le Kit de développement logiciel (SDK) d’authentification Microsoft Entra ID (sidecar)

Le Microsoft Entra ID Auth SDK (sidecar) est un service web conteneurisé qui gère l’acquisition de jetons, la validation et les appels sécurisés à des API en aval. Il s’exécute en tant que conteneur complémentaire en même temps que votre application, ce qui vous permet de décharger la logique d’identité sur un service dédié.

Créer un fichier de configuration

Le sdk d’Entra ID Auth (sidecar) nécessite un fichier de configuration pour se connecter à votre application Microsoft Entra. Créez un répertoire pour votre configuration et créez un appsettings.json fichier :

# Create a directory for the Entra ID Auth SDK (sidecar) configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

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

Ouvrez appsettings.json dans votre éditeur de texte préféré et ajoutez la configuration suivante, en remplaçant les valeurs d’espace réservé par les détails de votre application 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": "*"
}

Téléchargez et exécutez le conteneur sidecar du SDK d’authentification Entra ID

Le SDK d’authentification Entra ID (sidecar) est disponible sous forme d’image conteneur pré-générée depuis le Microsoft Container Registry (MCR). Avant d’extraire l’image conteneur, vérifiez que Docker Desktop est en cours d’exécution. Si Docker n’est pas en cours d’exécution, ouvrez Docker Desktop et attendez que l’état indique « Docker Desktop est en cours d’exécution ».

Accédez à votre répertoire de configuration et exécutez les commandes suivantes :

# Navigate to your config directory
cd agentid-config

# Set the recommended sidecar image version
$sidecarVersion = "1.1.2-preview"
$sidecarImage = "mcr.microsoft.com/entra-sdk/auth-sidecar:${sidecarVersion}-azurelinux3.0-distroless"

# Pull the Entra ID Auth SDK (sidecar) container image from MCR
docker pull $sidecarImage

# Run the container
docker run -d `
    --name agentid-sdk `
    -p 5178:8080 `
    -e ASPNETCORE_ENVIRONMENT=Development `
    $sidecarImage

# 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

Note

Sur les hôtes Windows, définissez $sidecarImage = "mcr.microsoft.com/entra-sdk/auth-sidecar:${sidecarVersion}-windows" avant de récupérer et d’exécuter le conteneur.

Vous pouvez gérer le conteneur Entra ID SDK Auth (sidecar) à l’aide des commandes Docker suivantes :

Afficher les journaux de conteneur : docker logs agentid-sdk
Afficher les journaux en temps réel : docker logs -f agentid-sdk
Arrêtez le conteneur : docker stop agentid-sdk
Démarrez à nouveau le conteneur : docker start agentid-sdk
Supprimez le conteneur : docker rm agentid-sdk

Vérifier que le conteneur est en cours d’exécution

Vous pouvez vérifier si le conteneur SDK d’authentification Entra ID (sidecar) fonctionne correctement en appelant le point de terminaison/healthz de vérification d’intégrité :

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

Ce point de terminaison renvoie Healthy, ce qui confirme que le kit de développement logiciel (SDK) d’authentification Entra ID (sidecar) s’exécute correctement et est prêt à traiter les requêtes. Ne terminez pas le SDK d’authentification Entra ID (sidecar) pendant les tests. Le conteneur doit continuer à s’exécuter en arrière-plan pour que tous les appels d’authentification et d’API de l’exemple d’application TypeScript fonctionnent.

Exécuter l’exemple d’application TypeScript

L’exemple d’application TypeScript montre comment utiliser le Kit de développement logiciel (SDK) d’authentification Microsoft Entra ID (sidecar) pour valider les jetons utilisateur. L’application est un serveur Express.js qui valide les requêtes entrantes par le biais du SDK d’authentification Entra ID (sidecar). Le sdk d’Entra ID Auth (sidecar) peut également appeler des API en aval comme Microsoft Graph en votre nom.

Cloner ou télécharger l’exemple d’application

Téléchargez l’exemple d’application TypeScript et extrayez-la dans un répertoire local. Vous pouvez également cloner le référentiel en ouvrant une invite de commandes, en accédant à l’emplacement de votre projet souhaité et en exécutant la commande suivante :

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

Après avoir cloné le référentiel, accédez à l’exemple d’application TypeScript :

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

L’exemple d’application TypeScript se compose de trois fichiers principaux qui fonctionnent ensemble pour illustrer les modèles d’authentification avec le SDK d’Microsoft Entra ID Auth (sidecar).

sidecar.ts : fournit la SidecarClient classe, qui est un client TypeScript qui communique avec le conteneur Entra ID SDK Auth (sidecar). Il envoie des jetons du porteur au point de terminaison /Validate du SDK d’authentification Entra ID (sidecar), reçoit en retour le jeton validé ainsi que les revendications utilisateur, et gère les erreurs de validation des jetons.

app.ts : serveur web Express.js qui authentifie les requêtes entrantes. Il extrait les jetons Bearer ou les informations d’identification SHR PoP d’application uniquement de l’en-tête Authorization et les valide à l’aide de SidecarClient. Pour PoP, il transfère original-method et original-uri afin que le sidecar puisse valider la liaison à la requête. Si le sidecar rejette les informations d’identification, le serveur propage le code d’état du sidecar. En cas d’échec de connectivité du sidecar, un code 502 est renvoyé, tandis qu’en cas d’erreur inattendue de l’application, un code 500 est renvoyé. Lorsque la validation réussit, elle associe les claims renvoyés à l’objet de la requête via req.sidecarValidation pour qu’ils soient utilisés par les gestionnaires de routes en aval.

Important

L’exemple de développement déduit le protocole externe et le nom d’hôte à partir de la requête Express entrante. Avant la mise en production, remplacez ces valeurs par une origine externe canonique issue d’une configuration de confiance, et préservez la cible de requête encodée à la frontière du serveur ou du proxy de confiance.

sidecar.test.ts : contient des tests d’intégration automatisés qui vérifient le flux d’authentification complet. La suite de tests commence par lancer le serveur Express, puis utilise MSAL Node pour effectuer l’authentification interactive du navigateur et acquérir un jeton d’accès avec les étendues requises. Il effectue ensuite une requête HTTP sur le serveur avec le jeton acquis et vérifie que le sdk d’authentification (sidecar) Entra ID valide correctement le jeton avant de retourner les revendications utilisateur attendues.

Installer des dépendances

Accédez à l’exemple de répertoire TypeScript et installez les packages requis :

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

Configurer l’exemple d’application

Avant d’exécuter l’exemple d’application, configurez-la avec les détails de votre application comme suit :

Ouvrez sidecar.test.ts et mettez à jour l’ID client, l’ID de locataire et les étendues pour correspondre à votre enregistrement d'application.
Créez un .env fichier dans le répertoire des variables d’environnement typescript :
```
# Create .env file
New-Item -ItemType File -Path ".env" -Force
```
Ajoutez la configuration suivante à .env:
```
PORT=5555
SIDECAR_BASE_URL=http://localhost:5178
```

Démarrer le serveur Express

Démarrez l’exemple d’application TypeScript en exécutant npm start. Le serveur démarre http://localhost:5555 et est prêt à accepter les demandes authentifiées. Vous devez voir un résultat similaire à :

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

Laissez cette fenêtre de terminal ouverte. Le serveur Express doit continuer à s’exécuter pour gérer les demandes de test dans la section suivante.

Tester l’exemple d’application TypeScript

Maintenant que le conteneur Entra ID SDK Auth (sidecar) et le serveur Express s’exécutent, vous pouvez tester les scénarios d’authentification et d’appel d’API.

Tester avec des autorisations déléguées par l’utilisateur

Ce scénario montre comment connecter un utilisateur, acquérir un jeton et appeler le serveur Express avec ce jeton.

Acquérir un jeton utilisateur

L’exemple inclut un test automatisé qui acquiert un jeton utilisateur à l’aide de MSAL. Ouvrez une nouvelle fenêtre PowerShell (conservez le serveur Express en cours d’exécution) et exécutez :

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

Cette commande exécute le test d’intégration qui :

Ouvre une fenêtre de navigateur pour l’authentification interactive
Acquiert un jeton d’accès avec le périmètre api://<your-client-id>/access_as_user
Appelle le serveur Express avec le jeton
Vérifie que le SDK d’authentification Entra ID (sidecar) valide correctement le jeton

Lors de la première exécution, vous êtes invité à vous connecter avec vos informations d'identification Microsoft Entra. La fenêtre du navigateur s’ouvre automatiquement. Une fois l’authentification réussie, vous pouvez fermer le navigateur.

Tests manuels avec curl

Si vous préférez effectuer des tests manuels, vous pouvez acquérir un jeton et appeler directement le serveur 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

La réponse attendue est la suivante :

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

Tester l’authentification d’application uniquement

Ce scénario montre comment appeler des API en aval à l’aide de l’identité de l’application sans contexte utilisateur.

À partir de votre fenêtre PowerShell, appelez directement le Kit de développement logiciel (SDK) d’authentification (sidecar) Entra ID pour tester le flux d’application uniquement :

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

Ce point de terminaison :

S’authentifie à l’aide du certificat de l’application (configuré dans appsettings.json)
Acquiert un jeton d’accès d’application uniquement pour Microsoft Graph
Appelle l'endpoint de l'API Graph /me
Retourne les informations du service principal

Note

Ce scénario nécessite l’autorisation User.Read.All d’application avec le consentement de l’administrateur (configurée précédemment dans le guide de démarrage rapide).

Tester les appels d’API en aval personnalisés

Vous pouvez tester des configurations personnalisées d’API en aval en les ajoutant à appsettings.jsondu SDK d’authentification Entra ID (sidecar) :

"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" ]
    }
}

Redémarrez ensuite le conteneur Entra ID SDK Auth (sidecar) et testez le nouveau point de terminaison :

# Restart container to reload configuration
docker restart agentid-sdk

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

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-09-15

Connecter des utilisateurs et appeler des API en aval avec le SDK d’Microsoft Entra ID Auth (sidecar) dans TypeScript

Prerequisites

Créer et configurer votre application Microsoft Entra

Créer un enregistrement d’application

Ajouter un URI de redirection

Ajouter des informations d’identification client

Générer un certificat auto-signé

Charger le certificat dans Microsoft Entra ID

Configurez les autorisations d’API

Configurer les autorisations d’application

Exposer une API (pour les tests de validation de jeton)

Démarrez le Kit de développement logiciel (SDK) d’authentification Microsoft Entra ID (sidecar)

Créer un fichier de configuration

Téléchargez et exécutez le conteneur sidecar du SDK d’authentification Entra ID

Vérifier que le conteneur est en cours d’exécution

Exécuter l’exemple d’application TypeScript

Cloner ou télécharger l’exemple d’application

Installer des dépendances

Configurer l’exemple d’application

Démarrer le serveur Express

Tester l’exemple d’application TypeScript

Tester avec des autorisations déléguées par l’utilisateur

Acquérir un jeton utilisateur

Tests manuels avec curl

Tester l’authentification d’application uniquement

Tester les appels d’API en aval personnalisés

Contenu connexe

Commentaires

Ressources supplémentaires