From 2f5121733223a5f2c23bf3db2036cc4b914ea261 Mon Sep 17 00:00:00 2001 From: Nick Robinson <45213023+nickjrobinson@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:27:02 -0700 Subject: [PATCH 1/6] Learn Editor: Update app-only-auth-powershell-v2.md --- .../app-only-auth-powershell-v2.md | 168 +++++++++--------- 1 file changed, 85 insertions(+), 83 deletions(-) diff --git a/exchange/docs-conceptual/app-only-auth-powershell-v2.md b/exchange/docs-conceptual/app-only-auth-powershell-v2.md index ff65554923..e07d4d767c 100644 --- a/exchange/docs-conceptual/app-only-auth-powershell-v2.md +++ b/exchange/docs-conceptual/app-only-auth-powershell-v2.md @@ -24,37 +24,39 @@ Auditing and reporting scenarios in Microsoft 365 often involve unattended scrip Certificate based authentication (CBA) or app-only authentication as described in this article supports unattended script and automation scenarios by using Microsoft Entra apps and self-signed certificates. > [!NOTE] -> -> - Did you know that you can connect to Exchange Online PowerShell using managed identities in Azure? Check out [Use Azure managed identities to connect to Exchange Online PowerShell](connect-exo-powershell-managed-identity.md). -> -> - The features and procedures described in this article require the following versions of the Exchange Online PowerShell module: -> - **Exchange Online PowerShell (Connect-ExchangeOnline)**: Version 2.0.3 or later. -> - **Security & Compliance PowerShell (Connect-IPPSSession)**: Version 3.0.0 or later. -> -> For instructions on how to install or update the module, see [Install and maintain the Exchange Online PowerShell module](exchange-online-powershell-v2.md#install-and-maintain-the-exchange-online-powershell-module). For instructions on how to use the module in Azure automation, see [Manage modules in Azure Automation](/azure/automation/shared-resources/modules). -> -> - CBA or app-only authentication is available in Office 365 operated by 21Vianet in China. -> -> - REST API connections in the Exchange Online PowerShell V3 module require the PowerShellGet and PackageManagement modules. For more information, see [PowerShellGet for REST-based connections in Windows](exchange-online-powershell-v2.md#powershellget-for-rest-api-connections-in-windows). -> -> If the procedures in this article don't work for you, verify that you don't have Beta versions of the PackageManagement or PowerShellGet modules installed by running the following command: `Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions`. -> -> - In Exchange Online PowerShell, you can't use the procedures in this article with the following Microsoft 365 Group cmdlets: -> - [New-UnifiedGroup](/powershell/module/exchangepowershell/new-unifiedgroup) -> - [Remove-UnifiedGroup](/powershell/module/exchangepowershell/remove-unifiedgroup) -> - [Remove-UnifiedGroupLinks](/powershell/module/exchangepowershell/remove-unifiedgrouplinks) -> - [Add-UnifiedGroupLinks](/powershell/module/exchangepowershell/add-unifiedgrouplinks) -> -> You can use Microsoft Graph to replace most of the functionality from those cmdlets. For more information, see [Working with groups in Microsoft Graph](/graph/api/resources/groups-overview). -> -> - In Security & Compliance PowerShell, you can't use the procedures in this article with the following Microsoft 365 Group cmdlets: -> - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) -> - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) +- Did you know that you can connect to Exchange Online PowerShell using managed identities in Azure? Check out [Use Azure managed identities to connect to Exchange Online PowerShell](connect-exo-powershell-managed-identity.md). + +- The features and procedures described in this article require the following versions of the Exchange Online PowerShell module: + - **Exchange Online PowerShell (Connect-ExchangeOnline)**: Version 2.0.3 or later. + - **Security & Compliance PowerShell (Connect-IPPSSession)**: Version 3.0.0 or later. + + For instructions on how to install or update the module, see [Install and maintain the Exchange Online PowerShell module](exchange-online-powershell-v2.md#install-and-maintain-the-exchange-online-powershell-module). For instructions on how to use the module in Azure automation, see [Manage modules in Azure Automation](/azure/automation/shared-resources/modules). + +- CBA or app-only authentication is available in Office 365 operated by 21Vianet in China. + +- REST API connections in the Exchange Online PowerShell V3 module require the PowerShellGet and PackageManagement modules. For more information, see [PowerShellGet for REST-based connections in Windows](exchange-online-powershell-v2.md#powershellget-for-rest-api-connections-in-windows). + + If the procedures in this article don't work for you, verify that you don't have Beta versions of the PackageManagement or PowerShellGet modules installed by running the following command: `Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions`. + +- In Exchange Online PowerShell, you can't use the procedures in this article with the following Microsoft 365 Group cmdlets: + - [New-UnifiedGroup](/powershell/module/exchangepowershell/new-unifiedgroup) + - [Remove-UnifiedGroup](/powershell/module/exchangepowershell/remove-unifiedgroup) + - [Remove-UnifiedGroupLinks](/powershell/module/exchangepowershell/remove-unifiedgrouplinks) + - [Add-UnifiedGroupLinks](/powershell/module/exchangepowershell/add-unifiedgrouplinks) + + You can use Microsoft Graph to replace most of the functionality from those cmdlets. For more information, see [Working with groups in Microsoft Graph](/graph/api/resources/groups-overview). + +> - In Security & Compliance PowerShell, you can't use the procedures in this article with the following Microsoft Purview cmdlets: + - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) + - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) > - [Start-ComplianceSearch](/powershell/module/exchangepowershell/start-compliancesearch) -> -> - Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multi-tenant applications when CSP relationships are not created with the customer. The required steps for using multi-tenant applications are called out within the regular instructions in this article. -> -> - Use the _SkipLoadingFormatData_ switch on the **Connect-ExchangeOnline** cmdlet if you get the following error when using the Windows PowerShell SDK to connect: `The term 'Update-ModuleManifest' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.` +> + [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction?view=exchange-ps) +> +- Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multi-tenant applications when CSP relationships are not created with the customer. The required steps for using multi-tenant applications are called out within the regular instructions in this article. + +- Use the _SkipLoadingFormatData_ switch on the **Connect-ExchangeOnline** cmdlet if you get the following error when using the Windows PowerShell SDK to connect: `The term 'Update-ModuleManifest' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.` + ## How does it work? @@ -172,26 +174,26 @@ For a detailed visual flow about creating applications in Microsoft Entra ID, se 1. Open the Microsoft Entra admin center at . -2. In the **Search** box at the top of the page, start typing **App registrations**, and then select **App registrations** from the results in the **Services** section. +1. In the **Search** box at the top of the page, start typing **App registrations**, and then select **App registrations** from the results in the **Services** section. ![Screenshot that shows App registrations in the Search results on the home page of the Azure portal.](media/exo-app-only-auth-find-app-registrations.png) + + Or, to go directly to the **App registrations** page, use . - Or, to go directly to the **App registrations** page, use . - -3. On the **App registrations** page, select **New registration**. +1. On the **App registrations** page, select **New registration**. ![Select New registration on the App registrations page.](media/exo-app-only-auth-new-app-registration.png) + + On the **Register an application** page that opens, configure the following settings: - On the **Register an application** page that opens, configure the following settings: + - **Name**: Enter something descriptive. For example, ExO PowerShell CBA. - - **Name**: Enter something descriptive. For example, ExO PowerShell CBA. - - - **Supported account types**: Verify that **Accounts in this organizational directory only (\ only - Single tenant)** is selected. + - **Supported account types**: Verify that **Accounts in this organizational directory only (\ only - Single tenant)** is selected. > [!NOTE] > To make the application multi-tenant for **Exchange Online** delegated scenarios, select the value **Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)**. - - **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings: + - **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings: - **Platform**: Select **Web**. - **URI**: Enter the URI where the access token is sent. @@ -200,7 +202,7 @@ For a detailed visual flow about creating applications in Microsoft Entra ID, se ![Register an application.](media/exo-app-only-auth-register-app.png) - When you're finished on the **App registrations** page, select **Register**. + When you're finished on the **App registrations** page, select **Register**. 4. You're taken to the **Overview** page of the app you just registered. Leave this page open. You'll use it in the next step. @@ -216,39 +218,39 @@ Choose **one** of the following methods in this section to assign API permission 1. On the app **Overview** page, select **API permissions** from the **Manage** section. ![Select API permissions on the application overview page.](media/exo-app-only-auth-select-manifest.png) - -2. On the app **API Permissions** page, select **Add a permission**. + +1. On the app **API Permissions** page, select **Add a permission**. ![Select Add a permission on the API permissions page of the application.](media/exo-app-only-auth-api-permissions-add-a-permission.png) - -3. In the **Request API permissions** flyout that opens, select the **APIs my organization uses** tab, start typing **Office 365 Exchange Online** in the **Search** box, and then select it from the results. + +1. In the **Request API permissions** flyout that opens, select the **APIs my organization uses** tab, start typing **Office 365 Exchange Online** in the **Search** box, and then select it from the results. ![Find and select Office 365 Exchange Online on the APIs my organization uses tab.](media/exo-app-only-auth-api-permissions-select-o365-exo.png) - + 4. On the **What type of permissions does your application require?** flyout that appears, select **Application permissions**. -5. In the permissions list that appears, expand **Exchange**, select **Exchange.ManageAsApp**, and then select **Add permissions**. +1. In the permissions list that appears, expand **Exchange**, select **Exchange.ManageAsApp**, and then select **Add permissions**. ![Find and select Exchange.ManageAsApp permissions from the Application permission tab.](media/exo-app-only-auth-api-permissions-select-exchange-manageasapp.png) - -6. Back on the app **API permissions** page, verify **Office 365 Exchange Online** \> **Exchange.ManageAsApp** is listed and contains the following values: + +1. Back on the app **API permissions** page, verify **Office 365 Exchange Online** > **Exchange.ManageAsApp** is listed and contains the following values: - **Type**: **Application**. - **Admin consent required**: **Yes**. - - **Status**: The current incorrect value is **Not granted for \**. - - Change this value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. + - **Status**: The current incorrect value is **Not granted for **. + + Change this value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. ![Admin consent required but not granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-original-permissions.png) + + The **Status** value is now **Granted for \**. - The **Status** value is now **Granted for \**. + ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) - ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) - -7. For the default **Microsoft Graph** \> **User.Read** entry, select **...** \> **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. +1. For the default **Microsoft Graph** > **User.Read** entry, select **...** > **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. ![Admin consent removed from default Microsoft Graph User.Read permissions.](media/exo-app-only-auth-admin-consent-removed-from-graph.png) - + 8. Close the current **API permissions** page (not the browser tab) to return to the **App registrations** page. You use the **App registrations** page in an upcoming step. #### Modify the app manifest to assign API permissions @@ -259,7 +261,7 @@ Choose **one** of the following methods in this section to assign API permission 1. On the app **Overview** page, select **Manifest** from the **Manage** section. ![Select Manifest on the application overview page.](media/exo-app-only-auth-select-manifest.png) - + 2. On the app **Manifest** page, find the `requiredResourceAccess` entry (on or about line 42), and make the entry look like the following code snippet: ```json @@ -313,28 +315,28 @@ Choose **one** of the following methods in this section to assign API permission When you're finished on the **Manifest** page, select **Save**. -3. Still on the **Manifest** page, select **API permissions** from the **Manage** section. +1. Still on the **Manifest** page, select **API permissions** from the **Manage** section. ![Select API permissions from the Manifest page.](media/exo-app-only-auth-manifest-select-api-permissions.png) - -4. On the **API permissions** page, verify **Office 365 Exchange Online** \> **Exchange.ManageAsApp** is listed and contains the following values: + +1. On the **API permissions** page, verify **Office 365 Exchange Online** > **Exchange.ManageAsApp** is listed and contains the following values: - **Type**: **Application**. - **Admin consent required**: **Yes**. - - **Status**: The current incorrect value is **Not granted for \** for the **Office 365 Exchange Online** \> **Exchange.ManageAsApp** entry. - - Change the **Status** value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. + - **Status**: The current incorrect value is **Not granted for ** for the **Office 365 Exchange Online** > **Exchange.ManageAsApp** entry. + + Change the **Status** value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. ![Admin consent required but not granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-original-permissions.png) + + The **Status** value is now **Granted for \**. - The **Status** value is now **Granted for \**. + ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) - ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) - -5. For the default **Microsoft Graph** \> **User.Read** entry, select **...** \> **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. +1. For the default **Microsoft Graph** > **User.Read** entry, select **...** > **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. ![Admin consent removed from default Microsoft Graph User.Read permissions.](media/exo-app-only-auth-admin-consent-removed-from-graph.png) - + 6. Close the current **API permissions** page (not the browser tab) to return to the **App registrations** page. You use the **App registrations** page in an upcoming step. ### Step 3: Generate a self-signed certificate @@ -369,25 +371,25 @@ After you register the certificate with your application, you can use the privat If you need to get back to **Apps registration** page, use , verify the **Owned applications** tab is selected, and then select your application. ![Apps registration page where you select your app.](media/exo-app-only-auth-app-registration-page.png) - -2. On the application page that opens, select **Certificates & secrets** from the **Manage** section. + +1. On the application page that opens, select **Certificates & secrets** from the **Manage** section. ![Select Certificates & Secrets on the application properties page.](media/exo-app-only-auth-select-certificates-and-secrets.png) - -3. On the **Certificates & secrets** page, select **Upload certificate**. + +1. On the **Certificates & secrets** page, select **Upload certificate**. ![Select Upload certificate on the Certificates & secrets page.](media/exo-app-only-auth-select-upload-certificate.png) - - In the dialog that opens, browse to the self-signed certificate (`.cer` file) that you created in [Step 3](#step-3-generate-a-self-signed-certificate). + + In the dialog that opens, browse to the self-signed certificate (`.cer` file) that you created in [Step 3](#step-3-generate-a-self-signed-certificate). ![Browse to the certificate and then select Add.](media/exo-app-only-auth-upload-certificate-dialog.png) + + When you're finished, select **Add**. - When you're finished, select **Add**. - - The certificate is now shown in the **Certificates** section. + The certificate is now shown in the **Certificates** section. ![Application page showing that the certificate was added.](media/exo-app-only-auth-certificate-successfully-added.png) - + 4. Close the current **Certificates & secrets** page, and then the **App registrations** page to return to the main page. You'll use it in the next step. ### Step 4b: Exchange Online delegated scenarios only: Grant admin consent for the multi-tenant app @@ -446,8 +448,8 @@ For general instructions about assigning roles in Microsoft Entra ID, see [Assig 1. In Microsoft Entra admin center at , start typing **roles and administrators** in the **Search** box at the top of the page, and then select **Microsoft Entra roles and administrators** from the results in the **Services** section. ![Screenshot that shows Microsoft Entra roles and administrators in the Search results on the on the home page of the Azure portal.](media/exo-app-only-auth-find-roles-and-administrators.png) - - Or, to go directly to the **Microsoft Entra roles and administrators** page, use . + + Or, to go directly to the **Microsoft Entra roles and administrators** page, use . 2. On the **Roles and administrators** page that opens, find and select one of the supported roles by _clicking on the name of the role_ (not the check box) in the results. @@ -459,16 +461,16 @@ For general instructions about assigning roles in Microsoft Entra ID, see [Assig ![Find and select a supported Security & Compliance PowerShell role by clicking on the role name.](media/exo-app-only-auth-find-and-select-supported-role-scc.png) -3. On the **Assignments** page that opens, select **Add assignments**. +1. On the **Assignments** page that opens, select **Add assignments**. - **Exchange Online PowerShell**: ![Select Add assignments on the role assignments page for Exchange Online PowerShell.](media/exo-app-only-auth-role-assignments-click-add-assignments.png) - **Security & Compliance PowerShell**: - + ![Select Add assignments on the role assignments page for Security & Compliance PowerShell.](media/exo-app-only-auth-role-assignments-click-add-assignments-scc.png) - + 4. In the **Add assignments** flyout that opens, find and select the app that you created in [Step 1](#step-1-register-the-application-in-microsoft-entra-id). ![Find and select your app on the Add assignments flyout.](media/exo-app-only-auth-find-add-select-app-for-assignment.png) From 70a02c878e9bbb87c420163025ca0f02bc4fc273 Mon Sep 17 00:00:00 2001 From: Nick Robinson <45213023+nickjrobinson@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:27:13 -0700 Subject: [PATCH 2/6] Learn Editor: Update app-only-auth-powershell-v2.md From 899b483a1c354311db82ebede7d54c885ab03e67 Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Fri, 24 Oct 2025 10:57:13 -0700 Subject: [PATCH 3/6] Update app-only-auth-powershell-v2.md --- .../app-only-auth-powershell-v2.md | 177 +++++++++--------- 1 file changed, 85 insertions(+), 92 deletions(-) diff --git a/exchange/docs-conceptual/app-only-auth-powershell-v2.md b/exchange/docs-conceptual/app-only-auth-powershell-v2.md index e07d4d767c..2a43d66c67 100644 --- a/exchange/docs-conceptual/app-only-auth-powershell-v2.md +++ b/exchange/docs-conceptual/app-only-auth-powershell-v2.md @@ -3,7 +3,7 @@ title: App-only authentication in Exchange Online PowerShell and Security & Comp ms.author: chrisda author: chrisda manager: orspodek -ms.date: 08/11/2025 +ms.date: 10/24/2025 ms.audience: Admin audience: Admin ms.topic: article @@ -24,39 +24,37 @@ Auditing and reporting scenarios in Microsoft 365 often involve unattended scrip Certificate based authentication (CBA) or app-only authentication as described in this article supports unattended script and automation scenarios by using Microsoft Entra apps and self-signed certificates. > [!NOTE] -- Did you know that you can connect to Exchange Online PowerShell using managed identities in Azure? Check out [Use Azure managed identities to connect to Exchange Online PowerShell](connect-exo-powershell-managed-identity.md). - -- The features and procedures described in this article require the following versions of the Exchange Online PowerShell module: - - **Exchange Online PowerShell (Connect-ExchangeOnline)**: Version 2.0.3 or later. - - **Security & Compliance PowerShell (Connect-IPPSSession)**: Version 3.0.0 or later. - - For instructions on how to install or update the module, see [Install and maintain the Exchange Online PowerShell module](exchange-online-powershell-v2.md#install-and-maintain-the-exchange-online-powershell-module). For instructions on how to use the module in Azure automation, see [Manage modules in Azure Automation](/azure/automation/shared-resources/modules). - -- CBA or app-only authentication is available in Office 365 operated by 21Vianet in China. - -- REST API connections in the Exchange Online PowerShell V3 module require the PowerShellGet and PackageManagement modules. For more information, see [PowerShellGet for REST-based connections in Windows](exchange-online-powershell-v2.md#powershellget-for-rest-api-connections-in-windows). - - If the procedures in this article don't work for you, verify that you don't have Beta versions of the PackageManagement or PowerShellGet modules installed by running the following command: `Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions`. - -- In Exchange Online PowerShell, you can't use the procedures in this article with the following Microsoft 365 Group cmdlets: - - [New-UnifiedGroup](/powershell/module/exchangepowershell/new-unifiedgroup) - - [Remove-UnifiedGroup](/powershell/module/exchangepowershell/remove-unifiedgroup) - - [Remove-UnifiedGroupLinks](/powershell/module/exchangepowershell/remove-unifiedgrouplinks) - - [Add-UnifiedGroupLinks](/powershell/module/exchangepowershell/add-unifiedgrouplinks) - - You can use Microsoft Graph to replace most of the functionality from those cmdlets. For more information, see [Working with groups in Microsoft Graph](/graph/api/resources/groups-overview). - +> - Did you know that you can connect to Exchange Online PowerShell using managed identities in Azure? Check out [Use Azure managed identities to connect to Exchange Online PowerShell](connect-exo-powershell-managed-identity.md). +> +> - The features and procedures described in this article require the following versions of the Exchange Online PowerShell module: +> - **Exchange Online PowerShell (Connect-ExchangeOnline)**: Version 2.0.3 or later. +> - **Security & Compliance PowerShell (Connect-IPPSSession)**: Version 3.0.0 or later. +> +> For instructions on how to install or update the module, see [Install and maintain the Exchange Online PowerShell module](exchange-online-powershell-v2.md#install-and-maintain-the-exchange-online-powershell-module). For instructions on how to use the module in Azure automation, see [Manage modules in Azure Automation](/azure/automation/shared-resources/modules). +> +> - CBA or app-only authentication is available in Office 365 operated by 21Vianet in China. +> +> - REST API connections in the Exchange Online PowerShell V3 module require the PowerShellGet and PackageManagement modules. For more information, see [PowerShellGet for REST-based connections in Windows](exchange-online-powershell-v2.md#powershellget-for-rest-api-connections-in-windows). +> +> If the procedures in this article don't work for you, verify that you don't have Beta versions of the PackageManagement or PowerShellGet modules installed by running the following command: `Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions`. +> +> - In Exchange Online PowerShell, you can't use the procedures in this article with the following Microsoft 365 Group cmdlets: +> - [New-UnifiedGroup](/powershell/module/exchangepowershell/new-unifiedgroup) +> - [Remove-UnifiedGroup](/powershell/module/exchangepowershell/remove-unifiedgroup) +> - [Remove-UnifiedGroupLinks](/powershell/module/exchangepowershell/remove-unifiedgrouplinks) +> - [Add-UnifiedGroupLinks](/powershell/module/exchangepowershell/add-unifiedgrouplinks) +> +> You can use Microsoft Graph to replace most of the functionality from those cmdlets. For more information, see [Working with groups in Microsoft Graph](/graph/api/resources/groups-overview). +> > - In Security & Compliance PowerShell, you can't use the procedures in this article with the following Microsoft Purview cmdlets: - - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) - - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) -> - [Start-ComplianceSearch](/powershell/module/exchangepowershell/start-compliancesearch) -> - [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction?view=exchange-ps) -> -- Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multi-tenant applications when CSP relationships are not created with the customer. The required steps for using multi-tenant applications are called out within the regular instructions in this article. - -- Use the _SkipLoadingFormatData_ switch on the **Connect-ExchangeOnline** cmdlet if you get the following error when using the Windows PowerShell SDK to connect: `The term 'Update-ModuleManifest' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.` - +> - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) +> - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) +> - [Start-ComplianceSearch](/powershell/module/exchangepowershell/start-compliancesearch) +> - [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction?view=exchange-ps) +> +> - Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multi-tenant applications when CSP relationships are not created with the customer. The required steps for using multi-tenant applications are called out within the regular instructions in this article. +> +> - Use the _SkipLoadingFormatData_ switch on the **Connect-ExchangeOnline** cmdlet if you get the following error when using the Windows PowerShell SDK to connect: `The term 'Update-ModuleManifest' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.` ## How does it work? @@ -174,37 +172,35 @@ For a detailed visual flow about creating applications in Microsoft Entra ID, se 1. Open the Microsoft Entra admin center at . -1. In the **Search** box at the top of the page, start typing **App registrations**, and then select **App registrations** from the results in the **Services** section. +2. In the **Search** box at the top of the page, start typing **App registrations**, and then select **App registrations** from the results in the **Services** section. ![Screenshot that shows App registrations in the Search results on the home page of the Azure portal.](media/exo-app-only-auth-find-app-registrations.png) - - Or, to go directly to the **App registrations** page, use . -1. On the **App registrations** page, select **New registration**. + Or, to go directly to the **App registrations** page, use . - ![Select New registration on the App registrations page.](media/exo-app-only-auth-new-app-registration.png) - - On the **Register an application** page that opens, configure the following settings: +3. On the **App registrations** page, select **New registration**. - - **Name**: Enter something descriptive. For example, ExO PowerShell CBA. + ![Select New registration on the App registrations page.](media/exo-app-only-auth-new-app-registration.png) - - **Supported account types**: Verify that **Accounts in this organizational directory only (\ only - Single tenant)** is selected. +4. On the **Register an application** page that opens, configure the following settings: + - **Name**: Enter something descriptive. For example, ExO PowerShell CBA. + - **Supported account types**: Verify that **Accounts in this organizational directory only (\ only - Single tenant)** is selected. - > [!NOTE] + > [!TIP] > To make the application multi-tenant for **Exchange Online** delegated scenarios, select the value **Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)**. - - **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings: + - **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings: - **Platform**: Select **Web**. - **URI**: Enter the URI where the access token is sent. - > [!NOTE] + > [!TIP] > You can't create credentials for [native applications](/entra/identity/app-proxy/application-proxy-configure-native-client-application), because you can't use native applications for automated applications. - ![Register an application.](media/exo-app-only-auth-register-app.png) + ![Register an application.](media/exo-app-only-auth-register-app.png) - When you're finished on the **App registrations** page, select **Register**. + When you're finished on the **App registrations** page, select **Register**. -4. You're taken to the **Overview** page of the app you just registered. Leave this page open. You'll use it in the next step. +5. You're taken to the **Overview** page of the app you just registered. Leave this page open. You use it in the next step. ### Step 2: Assign API permissions to the application @@ -218,39 +214,38 @@ Choose **one** of the following methods in this section to assign API permission 1. On the app **Overview** page, select **API permissions** from the **Manage** section. ![Select API permissions on the application overview page.](media/exo-app-only-auth-select-manifest.png) - -1. On the app **API Permissions** page, select **Add a permission**. + +2. On the app **API Permissions** page, select **Add a permission**. ![Select Add a permission on the API permissions page of the application.](media/exo-app-only-auth-api-permissions-add-a-permission.png) - -1. In the **Request API permissions** flyout that opens, select the **APIs my organization uses** tab, start typing **Office 365 Exchange Online** in the **Search** box, and then select it from the results. + +3. In the **Request API permissions** flyout that opens, select the **APIs my organization uses** tab, start typing **Office 365 Exchange Online** in the **Search** box, and then select it from the results. ![Find and select Office 365 Exchange Online on the APIs my organization uses tab.](media/exo-app-only-auth-api-permissions-select-o365-exo.png) - + 4. On the **What type of permissions does your application require?** flyout that appears, select **Application permissions**. -1. In the permissions list that appears, expand **Exchange**, select **Exchange.ManageAsApp**, and then select **Add permissions**. +5. In the permissions list that appears, expand **Exchange**, select **Exchange.ManageAsApp**, and then select **Add permissions**. ![Find and select Exchange.ManageAsApp permissions from the Application permission tab.](media/exo-app-only-auth-api-permissions-select-exchange-manageasapp.png) - -1. Back on the app **API permissions** page, verify **Office 365 Exchange Online** > **Exchange.ManageAsApp** is listed and contains the following values: + +6. Back on the app **API permissions** page, verify **Office 365 Exchange Online** \> **Exchange.ManageAsApp** is listed and contains the following values: - **Type**: **Application**. - **Admin consent required**: **Yes**. - - **Status**: The current incorrect value is **Not granted for **. - - Change this value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. + + Change this value by selecting **Grant admin consent for \**, read the confirmation dialog that opens, and then select **Yes**. ![Admin consent required but not granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-original-permissions.png) - - The **Status** value is now **Granted for \**. - ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) + The **Status** value is now **Granted for \**. + + ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) -1. For the default **Microsoft Graph** > **User.Read** entry, select **...** > **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. +7. For the default **Microsoft Graph** \> **User.Read** entry, select **...** \> **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. ![Admin consent removed from default Microsoft Graph User.Read permissions.](media/exo-app-only-auth-admin-consent-removed-from-graph.png) - + 8. Close the current **API permissions** page (not the browser tab) to return to the **App registrations** page. You use the **App registrations** page in an upcoming step. #### Modify the app manifest to assign API permissions @@ -261,7 +256,7 @@ Choose **one** of the following methods in this section to assign API permission 1. On the app **Overview** page, select **Manifest** from the **Manage** section. ![Select Manifest on the application overview page.](media/exo-app-only-auth-select-manifest.png) - + 2. On the app **Manifest** page, find the `requiredResourceAccess` entry (on or about line 42), and make the entry look like the following code snippet: ```json @@ -315,28 +310,27 @@ Choose **one** of the following methods in this section to assign API permission When you're finished on the **Manifest** page, select **Save**. -1. Still on the **Manifest** page, select **API permissions** from the **Manage** section. +3. Still on the **Manifest** page, select **API permissions** from the **Manage** section. ![Select API permissions from the Manifest page.](media/exo-app-only-auth-manifest-select-api-permissions.png) - -1. On the **API permissions** page, verify **Office 365 Exchange Online** > **Exchange.ManageAsApp** is listed and contains the following values: + +4. On the **API permissions** page, verify **Office 365 Exchange Online** \> **Exchange.ManageAsApp** is listed and contains the following values: - **Type**: **Application**. - **Admin consent required**: **Yes**. + - **Status**: The current incorrect value is **Not granted for \** for the **Office 365 Exchange Online** \> **Exchange.ManageAsApp** entry. - - **Status**: The current incorrect value is **Not granted for ** for the **Office 365 Exchange Online** > **Exchange.ManageAsApp** entry. - - Change the **Status** value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. + Change the **Status** value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. ![Admin consent required but not granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-original-permissions.png) - - The **Status** value is now **Granted for \**. - ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) + The **Status** value is now **Granted for \**. -1. For the default **Microsoft Graph** > **User.Read** entry, select **...** > **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. + ![Admin consent granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-admin-consent-granted.png) + +5. For the default **Microsoft Graph** \> **User.Read** entry, select **...** \> **Revoke admin consent**, and then select **Yes** in the confirmation dialog that opens to return **Status** back to the default blank value. ![Admin consent removed from default Microsoft Graph User.Read permissions.](media/exo-app-only-auth-admin-consent-removed-from-graph.png) - + 6. Close the current **API permissions** page (not the browser tab) to return to the **App registrations** page. You use the **App registrations** page in an upcoming step. ### Step 3: Generate a self-signed certificate @@ -371,25 +365,25 @@ After you register the certificate with your application, you can use the privat If you need to get back to **Apps registration** page, use , verify the **Owned applications** tab is selected, and then select your application. ![Apps registration page where you select your app.](media/exo-app-only-auth-app-registration-page.png) - -1. On the application page that opens, select **Certificates & secrets** from the **Manage** section. + +2. On the application page that opens, select **Certificates & secrets** from the **Manage** section. ![Select Certificates & Secrets on the application properties page.](media/exo-app-only-auth-select-certificates-and-secrets.png) - -1. On the **Certificates & secrets** page, select **Upload certificate**. + +3. On the **Certificates & secrets** page, select **Upload certificate**. ![Select Upload certificate on the Certificates & secrets page.](media/exo-app-only-auth-select-upload-certificate.png) - - In the dialog that opens, browse to the self-signed certificate (`.cer` file) that you created in [Step 3](#step-3-generate-a-self-signed-certificate). + + In the dialog that opens, browse to the self-signed certificate (`.cer` file) that you created in [Step 3](#step-3-generate-a-self-signed-certificate). ![Browse to the certificate and then select Add.](media/exo-app-only-auth-upload-certificate-dialog.png) - - When you're finished, select **Add**. - The certificate is now shown in the **Certificates** section. + When you're finished, select **Add**. + + The certificate is now shown in the **Certificates** section. ![Application page showing that the certificate was added.](media/exo-app-only-auth-certificate-successfully-added.png) - + 4. Close the current **Certificates & secrets** page, and then the **App registrations** page to return to the main page. You'll use it in the next step. ### Step 4b: Exchange Online delegated scenarios only: Grant admin consent for the multi-tenant app @@ -448,8 +442,8 @@ For general instructions about assigning roles in Microsoft Entra ID, see [Assig 1. In Microsoft Entra admin center at , start typing **roles and administrators** in the **Search** box at the top of the page, and then select **Microsoft Entra roles and administrators** from the results in the **Services** section. ![Screenshot that shows Microsoft Entra roles and administrators in the Search results on the on the home page of the Azure portal.](media/exo-app-only-auth-find-roles-and-administrators.png) - - Or, to go directly to the **Microsoft Entra roles and administrators** page, use . + + Or, to go directly to the **Microsoft Entra roles and administrators** page, use . 2. On the **Roles and administrators** page that opens, find and select one of the supported roles by _clicking on the name of the role_ (not the check box) in the results. @@ -461,16 +455,15 @@ For general instructions about assigning roles in Microsoft Entra ID, see [Assig ![Find and select a supported Security & Compliance PowerShell role by clicking on the role name.](media/exo-app-only-auth-find-and-select-supported-role-scc.png) -1. On the **Assignments** page that opens, select **Add assignments**. - +3. On the **Assignments** page that opens, select **Add assignments**. - **Exchange Online PowerShell**: ![Select Add assignments on the role assignments page for Exchange Online PowerShell.](media/exo-app-only-auth-role-assignments-click-add-assignments.png) - **Security & Compliance PowerShell**: - + ![Select Add assignments on the role assignments page for Security & Compliance PowerShell.](media/exo-app-only-auth-role-assignments-click-add-assignments-scc.png) - + 4. In the **Add assignments** flyout that opens, find and select the app that you created in [Step 1](#step-1-register-the-application-in-microsoft-entra-id). ![Find and select your app on the Add assignments flyout.](media/exo-app-only-auth-find-add-select-app-for-assignment.png) From cfffa9992b1c83a573ce165603a1da72474fa755 Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Fri, 24 Oct 2025 11:09:08 -0700 Subject: [PATCH 4/6] Revise app-only auth documentation for clarity Updated the documentation for app-only authentication in Exchange Online PowerShell to improve clarity and accuracy regarding version requirements and other details. --- .../app-only-auth-powershell-v2.md | 57 ++++++++++--------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/exchange/docs-conceptual/app-only-auth-powershell-v2.md b/exchange/docs-conceptual/app-only-auth-powershell-v2.md index 2a43d66c67..b9b2fbcd6d 100644 --- a/exchange/docs-conceptual/app-only-auth-powershell-v2.md +++ b/exchange/docs-conceptual/app-only-auth-powershell-v2.md @@ -19,24 +19,25 @@ description: "Learn how to configure app-only authentication (also known as cert # App-only authentication for unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell -Auditing and reporting scenarios in Microsoft 365 often involve unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell. In the past, unattended sign in required you to store the username and password in a local file or in a secret vault that's accessed at run-time. But, as we all know, storing user credentials locally isn't a good security practice. +Auditing and reporting scenarios in Microsoft 365 often involve unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell. In the past, unattended sign in required you to store the username and password in a local file or in a secret vault accessed at run-time. But, as we all know, storing user credentials locally isn't a good security practice. Certificate based authentication (CBA) or app-only authentication as described in this article supports unattended script and automation scenarios by using Microsoft Entra apps and self-signed certificates. > [!NOTE] +> > - Did you know that you can connect to Exchange Online PowerShell using managed identities in Azure? Check out [Use Azure managed identities to connect to Exchange Online PowerShell](connect-exo-powershell-managed-identity.md). > > - The features and procedures described in this article require the following versions of the Exchange Online PowerShell module: -> - **Exchange Online PowerShell (Connect-ExchangeOnline)**: Version 2.0.3 or later. -> - **Security & Compliance PowerShell (Connect-IPPSSession)**: Version 3.0.0 or later. +> - **Exchange Online PowerShell (Connect-ExchangeOnline)**: Version 2.0.4 or later. +> - **Security & Compliance PowerShell (Connect-IPPSSession)**: Version 3.0.0 or later. > -> For instructions on how to install or update the module, see [Install and maintain the Exchange Online PowerShell module](exchange-online-powershell-v2.md#install-and-maintain-the-exchange-online-powershell-module). For instructions on how to use the module in Azure automation, see [Manage modules in Azure Automation](/azure/automation/shared-resources/modules). +> For instructions on how to install or update the module, see [Install and maintain the Exchange Online PowerShell module](exchange-online-powershell-v2.md#install-and-maintain-the-exchange-online-powershell-module). For instructions on how to use the module in Azure Automation, see [Manage modules in Azure Automation](/azure/automation/shared-resources/modules). > > - CBA or app-only authentication is available in Office 365 operated by 21Vianet in China. > > - REST API connections in the Exchange Online PowerShell V3 module require the PowerShellGet and PackageManagement modules. For more information, see [PowerShellGet for REST-based connections in Windows](exchange-online-powershell-v2.md#powershellget-for-rest-api-connections-in-windows). > -> If the procedures in this article don't work for you, verify that you don't have Beta versions of the PackageManagement or PowerShellGet modules installed by running the following command: `Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions`. +> If the procedures in this article don't work for you, verify that you don't have preview versions of the PackageManagement or PowerShellGet modules installed by running the following command: `Get-InstalledModule PackageManagement -AllVersions; Get-InstalledModule PowerShellGet -AllVersions`. > > - In Exchange Online PowerShell, you can't use the procedures in this article with the following Microsoft 365 Group cmdlets: > - [New-UnifiedGroup](/powershell/module/exchangepowershell/new-unifiedgroup) @@ -47,12 +48,12 @@ Certificate based authentication (CBA) or app-only authentication as described i > You can use Microsoft Graph to replace most of the functionality from those cmdlets. For more information, see [Working with groups in Microsoft Graph](/graph/api/resources/groups-overview). > > - In Security & Compliance PowerShell, you can't use the procedures in this article with the following Microsoft Purview cmdlets: -> - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) -> - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) -> - [Start-ComplianceSearch](/powershell/module/exchangepowershell/start-compliancesearch) -> - [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction?view=exchange-ps) +> - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) +> - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) +> - [Start-ComplianceSearch](/powershell/module/exchangepowershell/start-compliancesearch) +> - [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction?view=exchange-ps) > -> - Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multi-tenant applications when CSP relationships are not created with the customer. The required steps for using multi-tenant applications are called out within the regular instructions in this article. +> - Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multitenant applications when CSP relationships aren't created with the customer. The required steps for using multitenant applications are called out within the regular instructions in this article. > > - Use the _SkipLoadingFormatData_ switch on the **Connect-ExchangeOnline** cmdlet if you get the following error when using the Windows PowerShell SDK to connect: `The term 'Update-ModuleManifest' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.` @@ -69,7 +70,7 @@ The following examples show how to use the Exchange Online PowerShell module wit > > The following connection commands have many of the same options available as described in [Connect to Exchange Online PowerShell](connect-to-exchange-online-powershell.md) and [Connect to Security & Compliance PowerShell](connect-to-scc-powershell.md). For example: > -> - Microsoft 365 GCC High, Microsoft 365 DoD or Microsoft 365 China (operated by 21Vianet) environments require the following additional parameters and values: +> - Microsoft 365 GCC High, Microsoft 365 DoD, or Microsoft 365 China (operated by 21Vianet) environments require the following extra parameters and values: > - **Microsoft 365 GCC High** > - `Connect-ExchangeOnline -ExchangeEnvironmentName O365USGovGCCHigh` > - `Connect-IPPSSession -ConnectionUri https://ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us` @@ -82,7 +83,7 @@ The following examples show how to use the Exchange Online PowerShell module wit > - `Connect-ExchangeOnline -ExchangeEnvironmentName O365China` > - `Connect-IPPSSession -ConnectionUri https://ps.compliance.protection.partner.outlook.cn/powershell-liveid -AzureADAuthorizationEndpointUri https://login.chinacloudapi.cn/common` > -> - If a **Connect-IPPSSession** command presents a login prompt, run the command: `$Global:IsWindows = $true` before the **Connect-IPPSSession** command. +> - If a **Connect-IPPSSession** command presents a sign in prompt, run the command: `$Global:IsWindows = $true` before the **Connect-IPPSSession** command. - **Connect using a certificate thumbprint**: @@ -186,17 +187,17 @@ For a detailed visual flow about creating applications in Microsoft Entra ID, se - **Name**: Enter something descriptive. For example, ExO PowerShell CBA. - **Supported account types**: Verify that **Accounts in this organizational directory only (\ only - Single tenant)** is selected. - > [!TIP] - > To make the application multi-tenant for **Exchange Online** delegated scenarios, select the value **Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)**. + > [!NOTE] + > To make the application multitenant for **Exchange Online** delegated scenarios, select the value **Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)**. - **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings: - **Platform**: Select **Web**. - **URI**: Enter the URI where the access token is sent. - > [!TIP] + > [!NOTE] > You can't create credentials for [native applications](/entra/identity/app-proxy/application-proxy-configure-native-client-application), because you can't use native applications for automated applications. - ![Register an application.](media/exo-app-only-auth-register-app.png) + ![Register an application.](media/exo-app-only-auth-register-app.png) When you're finished on the **App registrations** page, select **Register**. @@ -207,7 +208,7 @@ For a detailed visual flow about creating applications in Microsoft Entra ID, se Choose **one** of the following methods in this section to assign API permissions to the app: - Select and assign the API permissions from the portal. -- Modify the app manifest to assign API permissions. (Microsoft 365 GCC High and DoD organizations should use this method) +- Modify the app manifest to assign API permissions. (Microsoft 365 GCC High and DoD organizations should use this method). #### Select and assign the API permissions from the portal @@ -337,7 +338,7 @@ Choose **one** of the following methods in this section to assign API permission Create a self-signed x.509 certificate using one of the following methods: -- (Recommended) Use the [New-SelfSignedCertificate](/powershell/module/pki/new-selfsignedcertificate), [Export-Certificate](/powershell/module/pki/export-certificate) and [Export-PfxCertificate](/powershell/module/pki/export-pfxcertificate) cmdlets in an elevated (run as administrator) Windows PowerShell session to request a self-signed certificate and export it to `.cer` and `.pfx` (SHA1 by default). For example: +- (Recommended) Use the [New-SelfSignedCertificate](/powershell/module/pki/new-selfsignedcertificate), [Export-Certificate](/powershell/module/pki/export-certificate), and [Export-PfxCertificate](/powershell/module/pki/export-pfxcertificate) cmdlets in an elevated (run as administrator) Windows PowerShell session to request a self-signed certificate and export it to `.cer` and `.pfx` (SHA1 by default). For example: ```powershell # Create certificate @@ -384,16 +385,16 @@ After you register the certificate with your application, you can use the privat ![Application page showing that the certificate was added.](media/exo-app-only-auth-certificate-successfully-added.png) -4. Close the current **Certificates & secrets** page, and then the **App registrations** page to return to the main page. You'll use it in the next step. +4. Close the current **Certificates & secrets** page, and then the **App registrations** page to return to the main page. You use it in the next step. -### Step 4b: Exchange Online delegated scenarios only: Grant admin consent for the multi-tenant app +### Step 4b: Exchange Online delegated scenarios only: Grant admin consent for the multitenant app -If you made the application multi-tenant for **Exchange Online** delegated scenarios in [Step 1](#step-1-register-the-application-in-microsoft-entra-id), you need to grant admin consent to the Exchange.ManageAsApp permission so the application can run cmdlets in Exchange Online **in each tenant organization**. To do this, generate an admin consent URL for each customer tenant. Before anyone uses the multi-tenant application to connect to Exchange Online in the tenant organization, an admin in the customer tenant should open the following URL: +If you made the application multitenant for **Exchange Online** delegated scenarios in [Step 1](#step-1-register-the-application-in-microsoft-entra-id), you need to grant admin consent to the Exchange.ManageAsApp permission so the application can run cmdlets in Exchange Online **in each tenant organization**. You need to generate an admin consent URL for each customer tenant. Before anyone uses the multitenant application to connect to Exchange Online in the tenant organization, an admin in the customer tenant should open the following URL: `https://login.microsoftonline.com//adminconsent?client_id=&scope=https://outlook.office365.com/.default` - `` is the customer's tenant ID. -- `` is the ID of the multi-tenant application. +- `` is the ID of the multitenant application. - The default scope is used to grant application permissions. For more information about the URL syntax, see [Request the permissions from a directory admin](/entra/identity-platform/v2-admin-consent#request-the-permissions-from-a-directory-admin). @@ -408,13 +409,13 @@ You have two options: > [!NOTE] > You can also combine both methods to assign permissions. For example, you can use Microsoft Entra roles for the "Exchange Recipient Administrator" role and also assign your custom RBAC role to extend the permissions. > -> For multi-tenant applications in **Exchange Online** delegated scenarios, you need to assign permissions in each customer tenant. +> For multitenant applications in **Exchange Online** delegated scenarios, you need to assign permissions in each customer tenant. #### Assign Microsoft Entra roles to the application The supported Microsoft Entra roles are described in the following table: -|Role|Exchange Online
PowerShell|Security & Compliance
PowerShell| +|Role|Exchange Online
PowerShell|Security & Compliance
PowerShell| |---|:---:|:---:| |[Compliance Administrator](/entra/identity/role-based-access-control/permissions-reference#compliance-administrator)|✔|✔| |[Exchange Administrator](/entra/identity/role-based-access-control/permissions-reference#exchange-administrator)¹|✔|| @@ -430,7 +431,7 @@ The supported Microsoft Entra roles are described in the following table: - Recipient management. - Security and protection features. For example, anti-spam, anti-malware, anti-phishing, and the associated reports. -The Security Administrator role does not have the necessary permissions for those same tasks. +The Security Administrator role doesn't have the necessary permissions for those same tasks. ² Microsoft recommends that you use roles with the fewest permissions. Using lower permissioned accounts helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role. @@ -470,7 +471,7 @@ For general instructions about assigning roles in Microsoft Entra ID, see [Assig When you're finished in the **Add assignments** flyout, select **Add**. -5. Back on the **Assignments** page, verify that the role has been assigned to the app. +5. Back on the **Assignments** page, verify that the role is assigned to the app. - **Exchange Online PowerShell**: @@ -483,9 +484,9 @@ For general instructions about assigning roles in Microsoft Entra ID, see [Assig #### Assign custom role groups to the application using service principals > [!NOTE] -> You need to connect to Exchange Online PowerShell or Security & Compliance PowerShell _before_ completing steps to create a new service principal. Creating a new service principal without connecting to PowerShell won't work (your Azure App ID and Object ID are needed to create the new service principal). +> You need to connect to Exchange Online PowerShell or Security & Compliance PowerShell _before_ completing steps to create a new service principal. Creating a new service principal without connecting to PowerShell doesn't work (your Azure App ID and Object ID are needed to create the new service principal). > -> This method is supported only when you connect to Exchange Online PowerShell or Security & Compliance PowerShell in [REST API mode](exchange-online-powershell-v2.md#rest-api-connections-in-the-exo-v3-module). Security & Compliance PowerShell supports REST API mode in v3.2.0 or later. +> This method is supported only when you connect to Exchange Online PowerShell or Security & Compliance PowerShell in [REST API mode](exchange-online-powershell-v2.md#rest-api-connections-in-the-exo-v3-module). Security & Compliance PowerShell supports REST API mode in v3.2.0 or later. For information about creating custom role groups, see [Create role groups in Exchange Online](/exchange/permissions-exo/role-groups#create-role-groups) and [Create Email & collaboration role groups in the Microsoft Defender portal](/defender-office-365/mdo-portal-permissions#create-email--collaboration-role-groups-in-the-microsoft-defender-portal). The custom role group that you assign to the application can contain any combination of built-in and custom roles. From d1ecd20ba014d4506eb7fb9e47282bb6673b597b Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Fri, 24 Oct 2025 11:12:48 -0700 Subject: [PATCH 5/6] Fix grammar in admin consent instructions --- exchange/docs-conceptual/app-only-auth-powershell-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exchange/docs-conceptual/app-only-auth-powershell-v2.md b/exchange/docs-conceptual/app-only-auth-powershell-v2.md index b9b2fbcd6d..a4bef8e2e7 100644 --- a/exchange/docs-conceptual/app-only-auth-powershell-v2.md +++ b/exchange/docs-conceptual/app-only-auth-powershell-v2.md @@ -320,7 +320,7 @@ Choose **one** of the following methods in this section to assign API permission - **Admin consent required**: **Yes**. - **Status**: The current incorrect value is **Not granted for \** for the **Office 365 Exchange Online** \> **Exchange.ManageAsApp** entry. - Change the **Status** value by selecting **Grant admin consent for \**, reading the confirmation dialog that opens, and then selecting **Yes**. + Change the **Status** value by selecting **Grant admin consent for \**, read the confirmation dialog that opens, and then select **Yes**. ![Admin consent required but not granted for Exchange.ManageAsApp permissions.](media/exo-app-only-auth-original-permissions.png) From c4690c3d13433a67e888491650397bca6b59e761 Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Fri, 24 Oct 2025 11:16:20 -0700 Subject: [PATCH 6/6] Fix formatting issues in PowerShell auth documentation --- exchange/docs-conceptual/app-only-auth-powershell-v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/exchange/docs-conceptual/app-only-auth-powershell-v2.md b/exchange/docs-conceptual/app-only-auth-powershell-v2.md index a4bef8e2e7..c58163fc0e 100644 --- a/exchange/docs-conceptual/app-only-auth-powershell-v2.md +++ b/exchange/docs-conceptual/app-only-auth-powershell-v2.md @@ -51,7 +51,7 @@ Certificate based authentication (CBA) or app-only authentication as described i > - [Get-ComplianceSearchAction](/powershell/module/exchangepowershell/get-compliancesearchaction) > - [New-ComplianceSearch](/powershell/module/exchangepowershell/new-compliancesearch) > - [Start-ComplianceSearch](/powershell/module/exchangepowershell/start-compliancesearch) -> - [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction?view=exchange-ps) +> - [New-ComplianceSearchAction](/powershell/module/exchangepowershell/new-compliancesearchaction) > > - Delegated scenarios are supported in Exchange Online. The recommended method for connecting with delegation is using GDAP and App Consent. For more information, see [Use the Exchange Online PowerShell v3 Module with GDAP and App Consent](/powershell/partnercenter/exchange-online-gdap-app). You can also use multitenant applications when CSP relationships aren't created with the customer. The required steps for using multitenant applications are called out within the regular instructions in this article. > @@ -233,7 +233,7 @@ Choose **one** of the following methods in this section to assign API permission 6. Back on the app **API permissions** page, verify **Office 365 Exchange Online** \> **Exchange.ManageAsApp** is listed and contains the following values: - **Type**: **Application**. - **Admin consent required**: **Yes**. - - **Status**: The current incorrect value is **Not granted for **. + - **Status**: The current incorrect value is **Not granted for \**. Change this value by selecting **Grant admin consent for \**, read the confirmation dialog that opens, and then select **Yes**.