Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 le gestionnaire de package UV. UV est un installateur et résolveur de paquets Python rapide, écrit en Rust.
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 Python 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 obtenir 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
.cerfichier 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. Utilisez des certificats auto-signés uniquement 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é
-
Nom de l’étendue :
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
# Pull the Entra ID Auth SDK (sidecar) 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
Note
Pour les hôtes Windows, utilisez la variante de conteneur Windows : mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows
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 tous les appels d’authentification et d’API à partir de l’application Python pour fonctionner.
Exécuter l’exemple d’application Python
L’exemple d’application Python montre comment utiliser le Kit de développement logiciel (SDK) Auth (sidecar) Microsoft Entra ID pour les appels d’API et d’authentification. Le sdk d’Entra ID Auth (sidecar) s’exécute en tant que service web local et agit comme proxy d’authentification. Il valide les jetons d’utilisateur et appelle des API en aval comme Microsoft Graph en votre nom.
L’exemple inclut Python scripts qui présentent deux modèles d’authentification :
- Autorisations déléguées : l’Entra ID SDK Auth (sidecar) valide votre jeton utilisateur et appelle des API pour le compte de l’utilisateur connecté.
- Autorisations d’application : le sdk d’Entra ID Auth (sidecar) utilise sa propre identité pour appeler des API sans contexte utilisateur.
Cette approche centralise la gestion des jetons et l’accès aux API dans un seul service que vos applications peuvent consommer via des requêtes HTTP simples.
Cloner ou télécharger l’exemple d’application Python
Téléchargez l'application d'exemple Python 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
cd microsoft-identity-web/tests/DevApps/SidecarAdapter/python
L’exemple d’application contient les scripts Python suivants :
-
get_token.py: acquiert des jetons d’accès utilisateur via le Microsoft Authentication Library (MSAL). -
main.py– Interface de ligne de commande qui appelle les points de terminaison du SDK d’Entra ID Auth (sidecar) et affiche les réponses JSON. -
MicrosoftIdentityWebSidecarClient.py– Encapsuleur client HTTP pour les points de terminaison/Validate,/AuthorizationHeaderet/DownstreamApidu SDK d’authentification Entra ID (sidecar).
Les scripts Python utilisent le paramètre me lors de l’appel des points de terminaison du SDK d’authentification Entra ID (sidecar). Ce paramètre fait référence à la configuration de l’API en aval nommée « moi » dans le sdk d’Entra ID Auth (sidecar) :appsettings.json
"DownstreamApis": {
"me": {
"BaseUrl": "https://graph.microsoft.com/v1.0/",
"RelativePath": "me",
"Scopes": [ "User.Read" ]
}
}
Lorsque vous appelez un point de terminaison Entra ID Sdk Auth (sidecar) avec le me paramètre, le SDK utilise l'URL de base et le chemin relatif de la configuration pour construire le point de terminaison d'API complet, demande les étendues spécifiées et appelle le point de terminaison Microsoft Graph /me pour récupérer le profil de l'utilisateur connecté. Vous pouvez ajouter des configurations d’API en aval supplémentaires à appsettings.json sous différents noms et points de terminaison pour appeler des API supplémentaires.
Tester l’interaction entre le SDK Microsoft Entra ID Auth (sidecar) et l’application Python
Ce guide de démarrage rapide illustre un modèle d’authentification à trois niveaux :
- Authentification utilisateur : vous obtenez un jeton d’accès utilisateur à l’aide de MSAL pour Python. Ce jeton prouve l’identité de l’utilisateur.
- Validation du jeton : le kit SDK d'Entra ID Auth (sidecar) valide le jeton utilisateur pour s'assurer qu'il est authentique et émis pour votre application.
- Échange de jetons : le sdk d’authentification Entra ID (sidecar) utilise le flux On-Behalf-Of (OBO) pour échanger le jeton utilisateur d’un nouveau jeton étendu à Microsoft Graph, puis appelle l’API.
Pour les scénarios avec application uniquement, le SDK d’authentification Entra ID (sidecar) contourne l’authentification utilisateur et utilise ses propres informations d’identification du client pour obtenir directement des jetons. Le Kit de développement logiciel (SDK) centralise cette logique d’authentification. Par conséquent, votre application Python doit uniquement effectuer des requêtes HTTP simples sans gérer les flux OAuth complexes.
Acquérir un jeton d’accès utilisateur
Avant de tester les points de terminaison Entra ID SDK Auth (sidecar), obtenez un jeton d’accès valide. Le script get_token.py utilise MSAL pour Python pour acquérir des jetons de manière interactive via un flux de connexion basé sur un navigateur.
Étendues et publics cibles des jetons :
La portée que vous demandez détermine le destinataire du jeton (aud revendication), qui doit correspondre au point de terminaison que vous appelez :
-
Pour les tests de validation de jetons, utilisez
api://<client-id>/access_as_userpour tester le/validatepoint de terminaison - Pour les tests de Microsoft Graph, acquérir un nouveau jeton avec portée pour tester les points de terminaison
User.Readet/authorizationheader.
Utilisez les commandes suivantes pour définir vos variables de configuration et acquérir un jeton :
# Set your configuration
$clientId = "YOUR_CLIENT_ID_HERE"
$tenantId = "YOUR_TENANT_ID_HERE"
$authority = "https://login.microsoftonline.com/$tenantId"
# For testing Entra ID Auth SDK (sidecar) APIs (if you exposed the API)
$scope = "api://$clientId/access_as_user"
# Or for testing Microsoft Graph directly
# $scope = "User.Read"
# Acquire token
$token = uv run --with msal get_token.py --client-id $clientId --authority $authority --scope $scope
Lorsque vous exécutez la commande d’acquisition de jeton, le script lance un flux de connexion interactif basé sur un navigateur. Cette authentification du navigateur se produit uniquement lors de la première exécution. Une fois l’authentification réussie, le jeton est mis en cache localement pour une utilisation ultérieure. Le jeton d’accès est ensuite imprimé dans la console et stocké dans la $token variable PowerShell à utiliser dans les commandes suivantes.
Tester les points de terminaison du SDK d’authentification Microsoft Entra ID (sidecar) à l’aide d’autorisations déléguées
Une fois que vous avez obtenu un jeton utilisateur valide, vous pouvez tester les principaux points de terminaison du SDK d’authentification Entra ID (sidecar). Ces opérations utilisent des autorisations déléguées, de sorte que le SDK agit pour le compte de l’utilisateur connecté.
Tout d’abord, définissez l’URL de base du Kit de développement logiciel (SDK) :
$side_car_url = "http://localhost:5178"
1. Valider le jeton utilisateur
Le /validate point de terminaison nécessite un jeton émis spécifiquement pour votre application en utilisant le périmètre api://<client-id>/access_as_user. Avant de tester la validation des jetons, vérifiez que vous effectuez les étapes décrites dans la section « Exposer une API ». Utilisez la commande suivante pour appeler le /validate point de terminaison.
uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" validate
Réponse attendue :
Le /validate point d'accès vérifie que le jeton est valide et extrait les informations des assertions :
{
"protocol": "Bearer",
"token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6...",
"claims": {
"aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"iss": "https://login.microsoftonline.com/...",
"name": "Your Name",
"upn": "your.email@domain.com"
}
}
Cette réponse confirme que :
- Le format du jeton est correct (jeton du porteur)
- Le jeton est émis par l’autorité attendue
- Le public (
aud) correspond à votre application - Les revendications d’identité utilisateur sont présentes et valides
2. Obtenir un en-tête d’autorisation pour Microsoft Graph
Le /authorizationheader point de terminaison récupère un en-tête d’autorisation correctement mis en forme pour appeler des API en aval :
uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" get-auth-header me
Ce point de terminaison :
- Valide le jeton utilisateur entrant
- Acquiert un nouveau jeton pour Microsoft Graph au nom de l’utilisateur
- Retourne l’en-tête d’autorisation mis en forme
3. Appeler Microsoft Graph via le SDK d’authentification Microsoft Entra ID (sidecar)
Le point de terminaison /downstreamapi appelle directement Microsoft Graph et retourne la réponse :
uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" invoke-downstream me
Réponse attendue :
{
"statusCode": 200,
"headers": {...},
"content": {
"displayName": "Your Name",
"mail": "your.email@domain.com",
"userPrincipalName": "your.email@domain.com"
}
}
Le me paramètre correspond à la configuration de l’API en aval que vous avez définie dans appsettings.json. Kit de développement logiciel (SDK) d’authentification Entra ID (sidecar) :
- Valide votre jeton utilisateur
- Acquiert un nouveau jeton pour Microsoft Graph à l’aide du flux OBO (on-behalf-of)
- Appelle le point de terminaison
/mesur Microsoft Graph - Retourne les données de profil utilisateur
4. Remplacer les scopes par défaut et ajouter un corps de requête
Vous pouvez personnaliser les appels d’API en remplaçant les étendues par défaut configurées dans appsettings.json ou en fournissant un corps de requête pour les opérations d’écriture.
uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" --scope <scopes> invoke-downstream <api-name> --body-file <path-to-file>
Cette approche est utile quand :
- Test de différents niveaux d’autorisation. Par exemple, vous pouvez spécifier différentes étendues telles que --scope
User.Read Mail.Readpour demander des autorisations supplémentaires - L’API en aval nécessite que les étendues ne soient pas configurées par défaut
- Vous devez demander des autorisations supplémentaires dynamiquement
- Lors de l’appel d’API qui nécessitent un corps de requête (par exemple, la création ou la mise à jour de ressources), vous ajoutez le paramètre facultatif
--body-fileutilisé pour les opérations POST/PUT
Tester des points de terminaison uniquement pour l'application
Le SDK d’authentification Microsoft Entra ID (sidecar) prend également en charge les flux d’application uniquement. Dans ces flux, le sdk d’Entra ID Auth (sidecar) utilise son propre identité d’application au lieu d’agir au nom d’un utilisateur. Ces points de terminaison ne nécessitent pas d’en-tête d’autorisation utilisateur.
Note
Les flux d’application uniquement nécessitent que votre inscription d’application dispose d’autorisations d’application (par exemple, User.Read.All) dans Microsoft Entra ID, pas seulement les autorisations déléguées. Un administrateur doit accorder son consentement à ces autorisations avant de pouvoir tester ces points de terminaison.
Obtenir l’en-tête d’autorisation sans contexte utilisateur
Utilisez ce point de terminaison pour récupérer un en-tête d’autorisation afin d’appeler Microsoft Graph en utilisant la propre identité du SDK d’authentification Entra ID (sidecar) :
uv run --with requests main.py --base-url $side_car_url get-auth-header-unauth me
Ce point de terminaison :
- Utilise les informations d’identification du client du SDK d’authentification Entra ID (sidecar) (identité d’application) pour s’authentifier.
- Acquiert un jeton d’accès d’application uniquement pour Microsoft Graph
- Retourne l’en-tête d’autorisation
Appeler Microsoft Graph sans contexte utilisateur
Utilisez ce point de terminaison pour appeler Microsoft Graph directement en utilisant l’identité Entra ID Auth SDK (sidecar) :
uv run --with requests main.py --base-url $side_car_url invoke-downstream-unauth me
Cet exemple illustre la communication de service à service où :
- Aucun utilisateur n’est impliqué dans le flux d’authentification
- Le SDK Entra ID Auth (sidecar) s’authentifie à l’aide de son propre ID client et de son propre certificat.
- L’appel d’API utilise des autorisations d’application, et non des autorisations déléguées
- Ce modèle est idéal pour les services en arrière-plan, le traitement par lots ou les tâches automatisées
Comprendre les réponses
Structure de réponse de validation de jeton
La réponse de validation fournit des informations détaillées sur le jeton :
| Terrain | Descriptif |
|---|---|
protocol |
Schéma d’authentification (toujours « Porteur » pour les jetons OAuth 2.0) |
token |
Jeton d'accès initial (tronqué dans les exemples) |
claims |
Paires clé-valeur extraites de la charge utile du jeton |
claims.aud |
Audience prévue (votre ID client) |
claims.iss |
Émetteur de jeton (Microsoft Entra ID) |
claims.name |
Nom d'affichage de l'utilisateur connecté |
claims.upn |
Nom d’utilisateur principal (adresse e-mail) |
structure de réponse d’appel Microsoft Graph
| Terrain | Descriptif |
|---|---|
statusCode |
Code d’état HTTP de Microsoft Graph (200 = réussite) |
headers |
En-têtes de réponse de l’appel d’API |
content |
Données réelles retournées par Microsoft Graph |
content.displayName |
Nom d'affichage de l’utilisateur dans le répertoire |
content.mail |
Adresse e-mail de l’utilisateur |
content.userPrincipalName |
UPN de l’utilisateur |
Dépannage des problèmes courants
Si vous rencontrez des erreurs lors du test des points de terminaison Microsoft Entra ID SDK Auth (sidecar), vérifiez les solutions suivantes aux problèmes courants :
| Problème | Solution |
|---|---|
| Erreurs « Connexion refusée » | Vérifiez que le conteneur Entra ID SDK Auth (sidecar) est en cours d’exécution : docker ps -a. Si l’état du conteneur indique « Quitté », vérifiez les journaux : docker logs agentid-sdk. Redémarrez le conteneur : docker start agentid-sdk et testez le point de terminaison d’intégrité : Invoke-RestMethod -Uri "http://localhost:5178/healthz". |
| Le conteneur retourne une erreur de serveur interne 500 | Affichez les journaux de conteneur pour obtenir des erreurs détaillées : docker logs agentid-sdk. Causes courantes : json non valide dans appsettings.json, chemin d’accès de certificat incorrect, mot de passe de certificat incorrect ou valeurs TenantId/ClientId manquantes. |
| Erreurs de certificat non trouvées | Vérifiez que le fichier PFX a été copié correctement : docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx. Si elle est manquante, copiez-la à nouveau : docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx et redémarrez : docker restart agentid-sdk. |
| Erreurs « Jeton non valide » ou « Échec de la validation du public » | Vérifiez que l’audience de votre jeton (aud revendication) correspond à votre ID client. Pour le /validate point de terminaison, utilisez l’étendue api://<client-id>/access_as_user . Pour les appels Microsoft Graph, utilisez User.Read. Effacez le cache de jetons : Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue. |
| appsettings.json ne se charge pas | Vérifiez que le fichier a été copié dans le conteneur : docker exec agentid-sdk cat /app/appsettings.json. Vérifiez que le json est valide (aucun commentaire, syntaxe appropriée). Si le fichier est manquant ou incorrect, copiez-le à nouveau et redémarrez le conteneur. |
| Le conteneur ne démarre pas après les modifications de configuration | Arrêtez et supprimez le conteneur : docker stop agentid-sdk && docker rm agentid-sdk. Réexécutez le conteneur avec les fichiers de configuration mis à jour en suivant la section « Pull and run the Entra ID Auth SDK (sidecar) container ». |