Authentification et autorisation pour l’API Exchange Online Administration

Remarque

Les fonctionnalités décrites dans cet article sont actuellement en préversion, ne sont pas disponibles dans toutes les organisations et sont susceptibles d’être modifiées.

Cet article décrit les exigences d’authentification et d’autorisation pour l’utilisation de points de terminaison pour l’API Exchange Online Administration.

L’API Exchange Online Administration fournit un moyen basé sur REST d’exécuter des applets de commande PowerShell spécifiques, en remplaçant les scénarios EWS (Exchange Web Services) hérités. Pour plus d’informations, consultez Vue d’ensemble de l’API Exchange Online Administration.

Pour accéder à l’API Administration, votre application doit établir son identité, obtenir les autorisations appropriées et suivre les meilleures pratiques pour la gestion sécurisée des jetons. À un niveau élevé, le processus implique les étapes clés suivantes :

Inscrire une application dans Microsoft Entra ID

Créez une inscription d’application pour établir une identité pour votre application et configurer les informations d’identification (clé secrète client ou certificat). Cette inscription permet à votre application de demander des jetons à Microsoft Entra ID.
Attribuer les autorisations d’API requises

Ajoutez les étendues OAuth nécessaires à l’inscription de votre application :
- Flux délégué : Exchange.ManageV2.
- Flux d’application uniquement : Exchange.ManageAsAppV2.
Étape 3 : Attribuer des autorisations RBAC

Exchange Online utilise le contrôle d’accès en fonction du rôle (RBAC) pour déterminer les points de terminaison, les applets de commande et les objets que l’appelant peut gérer. Attribuez les rôles RBAC appropriés à l’utilisateur (pour l’accès délégué) ou au principal de service de l’application (pour l’accès à l’application uniquement).
Étape 4 : Obtenir un jeton d’accès

Utilisez des flux OAuth 2.0 pour acquérir des jetons à partir de Microsoft Entra ID :
- Flux délégué pour l’accès basé sur l’utilisateur.
- Flux d’application uniquement pour l’accès de service à service.
Étape 5 : Utiliser le jeton d’accès

Étape 1 : Inscrire une application dans Microsoft Entra ID

Pour appeler l’API Exchange Online Administration, vous devez d’abord inscrire votre application dans Microsoft Entra ID. Une application est semblable à un objet de classe. Un principal de service est comme un instance de la classe . Pour plus d’informations, consultez Objets application et principal de service dans Microsoft Entra ID. Pour obtenir un flux visuel détaillé sur la création d’applications dans Microsoft Entra ID, consultez https://aka.ms/azuread-app.

Ouvrez le centre d’administration Microsoft Entra à l’adresse https://entra.microsoft.com.
Dans la zone de recherche en haut de la page, entrez inscriptions d'applications et sélectionnez-la dans les résultats.
Sur la page Inscriptions d’applications, sélectionnez Nouvelle inscription.
Dans la page Inscrire une application , configurez les paramètres de l’application :
- Nom : entrez un nom descriptif (par exemple, Exchange Administration API Client).
- Types de comptes pris en charge : sélectionnez l’une des valeurs suivantes :
  - Applications mono organization : sélectionnez Comptes dans cet annuaire organisationnel uniquement.
  - Scénarios délégués multilocataires : sélectionnez Comptes dans n’importe quel annuaire organisationnel.
- URI de redirection (facultatif) : requis pour le flux délégué.
  - Plateforme : sélectionnez Web.
  - URI : entrez l’URL où le jeton d’accès est envoyé (par exemple, https://localhost à des fins de test).
Lorsque vous avez terminé d’accéder à la page Inscrire une application , sélectionnez Inscrire.

Vous accédez à la page Vue d’ensemble de l’application que vous avez inscrite. Restez sur la page pour l’étape suivante.

Remarque

Vous ne pouvez pas créer d’informations d’identification pour les applications natives, car elles ne peuvent pas être utilisées pour les appels automatisés de service à service.

Étape 2 : Attribuer les autorisations d’API requises

Dans la page Vue d’ensemble de l’application que vous avez créée à l’étape précédente, sélectionnez Autorisations d’API dans la section Gérer .
Dans la page Autorisations de l’API pour l’application, sélectionnez Ajouter une autorisation.
Dans le menu volant Demander des autorisations d’API qui s’ouvre, sélectionnez l’onglet API que mon organization utilise, entrez Office 365 Exchange Online dans la zone de recherche, puis sélectionnez-la dans les résultats.
Dans le menu volant De quel type d’autorisations votre application a-t-elle besoin ? , effectuez l’une des sélections suivantes :
- Flux d’application uniquement : sélectionnez Autorisations d’application, développez Exchange, exchange.ManageAsAppV2, puis sélectionnez Ajouter des autorisations.
- Flux délégué : sélectionnez Autorisations déléguées, développez Exchange, exchange.ManageV2, puis Ajouter des autorisations.
De retour dans la page Autorisations de l’API , vérifiez que les sélections de l’étape précédente sont répertoriées :
- > Office 365 Exchange Online Exchange.ManageAsApp :
  - Type : Application
  - Administration consentement requis : Oui
- > Office 365 Exchange Online Exchange.ManageV2 :
  - Type : Délégué
  - Administration consentement requis : Oui
Sélectionnez Accorder le consentement de l’administrateur pour, passez en revue la boîte de dialogue de confirmation, puis sélectionnez Oui.

Étape 3 : Attribuer des autorisations RBAC

Après avoir inscrit votre application et accordé des autorisations d’API, vous devez configurer des rôles RBAC Exchange. Les étendues OAuth permettent à votre application d’obtenir des jetons, mais RBAC détermine les applets de commande et les objets que l’appelant peut gérer. Sans les attributions de rôle RBAC appropriées, même les jetons valides échouent avec l’erreur 403 Interdit.

Suivez les étapes de l’une des sous-sections suivantes en fonction de la nature de votre application.

Autorisations pour le flux délégué (utilisateur)

Pour les scénarios délégués, l’utilisateur au nom duquel l’application acquiert le jeton doit disposer des rôles RBAC nécessaires attribués dans Exchange Online. Exemples de rôles courants :

Gestion des destinataires pour les opérations de boîte aux lettres et de dossier.
Gestion de l’organisation pour les paramètres de niveau organization.
Gestion de l’organisation en affichage seul pour les opérations d’organisation en lecture seule.

Attribuez ces rôles via le Centre d’administration Exchange ou Exchange Online PowerShell. Pour obtenir des instructions, consultez Gérer les groupes de rôles dans Exchange Online.

Autorisations pour le flux d’application uniquement

Pour les scénarios d’application uniquement, le principal de service représentant votre application doit disposer des autorisations suffisantes. Vous avez le choix parmi les options suivantes :

Attribuer des rôles Microsoft Entra (recommandé par souci de simplicité) : accordez un rôle de Microsoft Entra intégré à l’application d’entreprise. Par exemple, Administrateur Exchange pour les autorisations de Exchange Online complètes :
1. Dans le centre d’administration Microsoft Entra , https://entra.microsoft.comsélectionnez Rôles & administrateurs.
2. Sur les rôles et les administrateurs | Tous les rôles, sélectionnez le rôle Administrateur Exchange en cliquant n’importe où dans la ligne autre que la zone case activée en regard de la première colonne.
3. Sur l’administrateur Exchange | Page Affectations qui s’ouvre, sélectionnez Ajouter des affectations, choisissez votre application, puis sélectionnez Confirmer.
Attribuer des groupes de rôles RBAC Exchange intégrés ou personnalisés (privilège minimum) : créez ou utilisez des groupes de rôles personnalisés existants dans Exchange Online qui contiennent uniquement les applets de commande dont votre application a besoin et ajoutez le principal de service à ces groupes. Cette approche évite les privilèges étendus et s’aligne sur la sécurité des privilèges minimum. Pour plus d’informations, consultez Authentification d’application uniquement dans Exchange Online PowerShell.

Le tableau suivant répertorie le rôle RBAC intégré requis pour chaque point de terminaison.

Point de terminaison	Groupe de rôles Exchange requis
/OrganizationConfig /AcceptedDomain	Gestion de l'organisation en affichage seul
/Boîte aux lettres /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	Gestion des destinataires

Pour un contrôle encore plus précis, envisagez d’utiliser des groupes de rôles personnalisés qui incluent uniquement les rôles de gestion spécifiques (jeux d’applets de commande) dont votre application a besoin. Cette approche suit la sécurité des privilèges minimum et réduit les risques par rapport aux rôles étendus tels que l’administrateur Exchange ou l’administrateur général, qui dépassent l’étendue requise pour les opérations d’API Administration classiques.

Étape 4 : Obtenir un jeton d’accès

Pour appeler l’API Exchange Online Administration, votre application doit obtenir un jeton d’accès OAuth 2.0 à partir de Microsoft Entra ID. Comme mentionné précédemment, Administration API prend en charge les flux suivants :

Flux de code d’autorisation (délégué) avec jeton d’actualisation : votre application agit au nom d’un utilisateur connecté et peut également obtenir un jeton d’actualisation pour le renouvellement silencieux si la demande inclut l’étendue offline_access .
Flux d’informations d’identification du client (application uniquement) : votre application agit comme elle-même (aucun utilisateur). Utilisé pour les scénarios de service/en arrière-plan. Les jetons d’actualisation ne sont pas émis dans ce flux.

Utilisez l’étendue /.default de la ressource lors de la demande de jetons (par exemple, https://outlook.office365.com/.default). Cette méthode indique Microsoft Entra ID d’émettre un jeton contenant les autorisations d’application (rôles) précédemment accordées pour cette ressource.

Flux de code d’autorisation (délégué) avec jeton d’actualisation

Utilisez ce flux lorsque vous avez besoin de contexte utilisateur. Pour obtenir un jeton d’actualisation, vous devez demander offline_access dans les demandes d’autorisation et de jeton. Pour plus d’informations, consultez Jetons d’actualisation dans le Plateforme d'identités Microsoft et Étendues et autorisations dans le Plateforme d'identités Microsoft.

L’utilisateur doit autoriser l’application à agir en son nom. L’application redirige l’utilisateur vers le point de /authorize terminaison dans le Plateforme d'identités Microsoft. Par le biais de ce point de terminaison, Microsoft Entra ID connecte l’utilisateur et demande son consentement pour les autorisations que l’application demande. Après le consentement, Microsoft Entra ID retourne un code d’autorisation à l’application. L’application peut ensuite échanger ce code au point /token de terminaison du Plateforme d'identités Microsoft contre un jeton d’accès.

L’exemple suivant montre une requête au point de /authorize terminaison. Dans l’URL de la requête, vous appelez le point de /authorize terminaison et spécifiez les propriétés requises et recommandées en tant que paramètres de requête. Par exemple :

GET https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/authorize
    ?client_id=<ClientID>
    &response_type=code
    &redirect_uri=<RedirectURI> # must exactly match the app registration
    &response_mode=query
    &scope=https://outlook.office365.com/.default offline_access
    &state=12345

Les paramètres sont décrits dans le tableau suivant :

Paramètre	Obligatoire	Description
TenantID	Requis	Organization où vous demandez l’autorisation. La valeur peut être le GUID tenantID ou le nom convivial.
client_id	Requis	ID client attribué à l’application par le portail d’inscription. Également appelé appId.
response_type	Requis	Doit inclure la valeur `code` du flux de code d’autorisation OAuth 2.0.
redirect_uri	Recommandé	URI de redirection de l’application au format encodé en URL, où les réponses d’authentification sont envoyées et reçues par l’application. Il doit correspondre à l’un des URI de redirection que vous avez inscrits dans le portail d’inscription d’application.
étendue	Requis	Liste séparée par des espaces des autorisations d’API Exchange Online Administration que vous souhaitez que l’utilisateur donne son consentement. Ces autorisations peuvent inclure des autorisations de ressources (`https://outlook.office365.com/.default` dans ce scénario) et des étendues OIDC, telles que `offline_access`, ce qui indique que l’application a besoin d’un jeton d’actualisation pour l’accès de longue durée aux ressources.
response_mode	Recommandé	Spécifie la méthode pour renvoyer le jeton obtenu à l’application. Les valeurs valides sont `query` ou `form_post`.
state	Recommandé	Valeur incluse dans la requête qui est également retournée dans la réponse du jeton. Il peut s’agir d’une chaîne de n’importe quel contenu. En règle générale, vous utilisez une valeur unique et aléatoire pour empêcher les attaques de falsification de requête intersites. Cette propriété encode également des informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, telles que la page ou la vue sur laquelle il se trouve.

L’utilisateur se connecte et donne son consentement. Microsoft Entra ID redirige vers votre redirect_uri avec ?code=<authorization_code>.
L’utilisation offline_access permet d’émettre un jeton d’actualisation ultérieurement. Pour plus d’informations, consultez Jetons d’actualisation dans le Plateforme d'identités Microsoft et Étendues et autorisations dans le Plateforme d'identités Microsoft.

Étape 2 : Utiliser le code d’autorisation pour les jetons

L’application utilise le code d’autorisation de l’étape précédente pour demander un jeton d’accès en envoyant une requête POST au point de /token terminaison.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                  # confidential clients only
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<RedirectURI>
&scope=https://outlook.office365.com/.default offline_access

Les paramètres sont décrits dans le tableau suivant :

Paramètre	Obligatoire	Description
TenantID	Requis	Organization où vous demandez l’autorisation. La valeur peut être le GUID tenantID ou le nom convivial.
client_id	Requis	ID client attribué à l’application par le portail d’inscription. Également appelé appId.
grant_type	Requis	La valeur doit être `authorization_code` pour le flux de code d’autorisation.
étendue	Requis	Liste d’étendues séparées par des espaces. Les étendues demandées par votre application doivent être équivalentes ou un sous-ensemble des étendues demandées à l’étape 1 : Envoyer l’utilisateur pour se connecter et donner son consentement.
code	Requis	Le code d’autorisation que vous avez obtenu à l’étape 1 : Envoyer l’utilisateur pour se connecter et donner son consentement.
redirect_uri	Obligatoire	La même valeur d’URI de redirection que celle utilisée pour acquérir le code d’autorisation à l’étape 1 : Envoyer l’utilisateur pour se connecter et donner son consentement.
client_secret	Obligatoire pour les applications web	Clé secrète client que vous avez créée dans le portail d’inscription de l’application pour votre application.

Une réponse réussie inclut :

access_token:Porteur. En règle générale, environ 60 minutes.
refresh_token: Présent, car offline_access a été demandé.
id_token:Optionnel. Retourné si l’étendue openid a été demandée. Pour plus d’informations, consultez Plateforme d'identités Microsoft types d’applications et les flux d’authentification et Actualiser les jetons dans le Plateforme d'identités Microsoft.

Conseil

Stockez la valeur TenantID (tid) à partir des revendications de jeton. Vous en avez besoin pour former Administration URL d’API et les demandes de jeton futures. Pour plus d’informations, consultez Plateforme d'identités Microsoft types d’applications et les flux d’authentification.

Étape 3 : Actualiser le jeton d’accès en mode silencieux (aucune invite de l’utilisateur)

Les jetons d’accès sont de courte durée et l’application doit les actualiser après leur expiration pour continuer à accéder aux ressources. L’application actualise un jeton d’accès en envoyant une autre requête POST au point de /token terminaison :

Fournissez au refresh_token lieu du dans le corps de code la demande.
Spécifiez refresh_token au lieu de authorization_code comme grant_type.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>
&grant_type=refresh_token
&refresh_token=<refresh_token>
&scope=https://outlook.office365.com/.default offline_access

Les paramètres sont décrits dans le tableau suivant :

Paramètre	Obligatoire	Description
TenantID	Requis	Organization où vous demandez l’autorisation. La valeur peut être le GUID tenantID ou le nom convivial.
client_id	Requis	ID client attribué à l’application par le portail d’inscription. Également appelé appId.
grant_type	Requis	La valeur doit être `refresh_token`.
refresh_token	Requis	Le refresh_token votre application a obtenu lors de la demande de jeton à l’étape 2 : Utiliser le code d’autorisation pour les jetons.
étendue	Requis	Liste d’étendues séparées par des espaces. Les étendues demandées par votre application doivent être équivalentes ou un sous-ensemble des étendues demandées à l’Étape 2 : Utiliser le code d’autorisation contre des jetons.
client_secret	Obligatoire pour les applications web	Clé secrète client que vous avez créée dans le portail d’inscription de l’application pour votre application.

Une réponse réussie inclut les résultats suivants :

Retourne une nouvelle access_token et souvent une nouvelle refresh_token pour remplacer l’ancienne.
Les jetons d’actualisation durent plus longtemps que les jetons d’accès. La valeur par défaut est d’environ 90 jours pour les clients confidentiels et de 24 heures pour les URI de redirection SPA. Les jetons qu’ils peuvent être révoqués à tout moment, gérez donc la réauthentification si nécessaire. Pour plus d’informations, consultez Actualiser les jetons dans le Plateforme d'identités Microsoft.

Flux d’informations d’identification du client (application uniquement)

Utilisez ce flux pour les appels de service à service sans utilisateur. Après le consentement de l’administrateur aux autorisations d’application (par exemple, Exchange.ManageAsAppV2) et l’attribution des rôles RBAC requis, demandez un jeton à l’aide des propres informations d’identification de l’application. Aucun jeton d’actualisation n’est émis. Demandez de nouveaux jetons d’accès si nécessaire.

Pour acquérir un jeton d’accès, envoyez une requête POST au point de terminaison de la plateforme d’identité /token . Dans cette requête, le client utilise la clé secrète client.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                   # or client assertion (certificate)
&grant_type=client_credentials
&scope=https://outlook.office365.com/.default

Les paramètres sont décrits dans le tableau suivant :

Paramètre	Condition	Description
TenantID	Requis	Organization où vous demandez l’autorisation. La valeur peut être le GUID tenantID ou le nom convivial.
client_id	Requis	ID d’application attribué à l’application par le portail d’inscription.
étendue	Requis	URI d’ID d’application de la ressource avec le `.default` suffixe . Pour l’API Exchange Online Administration, l’URI de l’ID d’application de ressource est `https://outlook.office365.com/`, de sorte que la valeur de l’étendue est `https://outlook.office365.com/.default`. Cette valeur indique au point de terminaison Plateforme d'identités Microsoft d’inclure toutes les autorisations au niveau de l’application que l’administrateur a consentées dans le jeton d’accès.
client_secret	Requis	Clé secrète client que vous avez générée pour votre application dans le portail d’inscription de l’application. Vérifiez que la valeur est encodée url.
grant_type	Requis	La valeur doit être `client_credentials`.

Étape 5 : Utiliser le jeton d’accès

Après avoir obtenu un jeton d’accès comme décrit à l’Étape 4 : Obtenir un jeton d’accès, incluez le jeton d’accès dans l’en-tête Authorization pour chaque appel d’API suivant :

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json

 { "CmdletInput": { "CmdletName": "Get-OrganizationConfig" } }

Utiliser la bibliothèque d’authentification Microsoft (MSAL)

Cet article contient les détails du protocole requis lorsque vous créez manuellement un problème de requêtes HTTP brutes pour obtenir des jetons pour les secrets client. Dans les applications de production, utilisez une bibliothèque d’authentification intégrée ou prise en charge pour obtenir des jetons de sécurité et appeler des API web protégées. Par exemple, la bibliothèque d’authentification Microsoft (MSAL).

MsAL et les autres bibliothèques d’authentification prises en charge simplifient le processus en gérant les détails afin que vous puissiez vous concentrer sur les fonctionnalités de votre application. Par exemple :

Validation.
Gestion des cookies.
Mise en cache des jetons.
Connexions sécurisées.

Microsoft gère un large éventail d’exemples de code qui illustrent les bibliothèques d’authentification prises en charge avec les Plateforme d'identités Microsoft. Pour accéder à ces exemples de code, consultez Plateforme d'identités Microsoft exemples de code.

Pour obtenir des exemples sur la façon d’obtenir des jetons à l’aide de certificats, consultez Plateforme d'identités Microsoft et le flux d’informations d’identification du client OAuth 2.0.

Last updated on 2025-11-17

Partager via

Authentification et autorisation pour l’API Exchange Online Administration

Étape 1 : Inscrire une application dans Microsoft Entra ID

Étape 2 : Attribuer les autorisations d’API requises

Étape 3 : Attribuer des autorisations RBAC

Autorisations pour le flux délégué (utilisateur)

Autorisations pour le flux d’application uniquement

Étape 4 : Obtenir un jeton d’accès

Flux de code d’autorisation (délégué) avec jeton d’actualisation

Étape 1 : Envoyer l’utilisateur pour se connecter et donner son consentement

Étape 2 : Utiliser le code d’autorisation pour les jetons

Étape 3 : Actualiser le jeton d’accès en mode silencieux (aucune invite de l’utilisateur)

Flux d’informations d’identification du client (application uniquement)

Étape 5 : Utiliser le jeton d’accès

Utiliser la bibliothèque d’authentification Microsoft (MSAL)

Ressources supplémentaires