Merge branch 'main' into DTBC-chrisda

Author: chrisda

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: dansimp
-ms.date: 5/3/2023
+ms.date: 6/19/2023
 ms.audience: Admin
 audience: Admin
 ms.topic: article
@@ -14,12 +14,12 @@ ms.collection: Strat_EX_Admin
 ms.custom:
 ms.assetid:
 search.appverid: MET150
-description: "Learn about using the Exchange Online PowerShell V2 module and V3 module in scripts and other long-running tasks with modern authentication and app-only authentication (also known a certificate based authentication or CBA)."
+description: "Learn how to configure app-only authentication (also known as certificate based authentication or CBA) using the Exchange Online PowerShell V3 module in scripts and other long-running tasks."
 ---
 
 # 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 is not 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 that's 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 Azure AD apps and self-signed certificates.
 
@@ -49,7 +49,7 @@ Certificate based authentication (CBA) or app-only authentication as described i
 
 ## How does it work?
 
-The Exchange Online PowerShell module uses the Active Directory Authentication Library to fetch an app-only token using the application Id, tenant Id (organization), and certificate thumbprint. The application object provisioned inside Azure AD has a Directory Role assigned to it, which is returned in the access token. The session's role based access control (RBAC) is configured using the directory role information that's available in the token.
+The Exchange Online PowerShell module uses the Active Directory Authentication Library to fetch an app-only token using the application ID, tenant ID (organization), and certificate thumbprint. The application object provisioned inside Azure AD has a Directory Role assigned to it, which is returned in the access token. The session's role based access control (RBAC) is configured using the directory role information that's available in the token.
 
 ## Connection examples
 
@@ -60,9 +60,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:
 >
-> - You can use REST API cmdlets or original remote PowerShell cmdlets. For more information, see [Updates for the EXO V3 module)](exchange-online-powershell-v2.md#updates-for-the-exo-v3-module).
->
->   Remote PowerShell support in Exchange Online PowerShell will be deprecated. For more information, see [Announcing Deprecation of Remote PowerShell (RPS) Protocol in Exchange Online PowerShell](https://aka.ms/RPSDeprecation).
+> Remote PowerShell support in Exchange Online PowerShell will be deprecated. For more information, see [Announcing Deprecation of Remote PowerShell (RPS) Protocol in Exchange Online PowerShell](https://aka.ms/RPSDeprecation).
 >
 > - Microsoft 365 GCC High or Microsoft 365 DoD environments require the following additional parameters and values:
 >   - **Connect-ExchangeOnline in GCC High**: `-ExchangeEnvironmentName O365USGovGCCHigh`.
@@ -93,7 +91,7 @@ The following examples show how to use the Exchange Online PowerShell module wit
 
 - **Connect using a certificate object**:
 
-  The certificate does not need to be installed on the computer where you're running the command. You can store the certificate object remotely. The certificate is fetched when the script is run.
+  The certificate doesn't need to be installed on the computer where you're running the command. You can store the certificate object remotely. The certificate is fetched when the script is run.
 
   - <u>Exchange Online PowerShell</u>:
 
@@ -126,7 +124,7 @@ The following examples show how to use the Exchange Online PowerShell module wit
 
 ## Set up app-only authentication
 
-An initial onboarding is required for authentication using application objects. Application and service principal are used interchangeably, but an application is like a class object while a service principal is like an instance of the class. You can learn more about this at [Application and service principal objects in Azure Active Directory](/azure/active-directory/develop/app-objects-and-service-principals).
+An initial onboarding is required for authentication using application objects. Application and service principal are used interchangeably, but an application is like a class object while a service principal is like an instance of the class. For more information, see [Application and service principal objects in Azure Active Directory](/azure/active-directory/develop/app-objects-and-service-principals).
 
 For a detailed visual flow about creating applications in Azure AD, see <https://aka.ms/azuread-app>.
 
@@ -140,9 +138,9 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
 
    - For app-only authentication in Azure AD,  you typically use a certificate to request access. Anyone who has the certificate and its private key can use the app, and the permissions granted to the app.
 
-   - Create and configure a self-signed X.509 certificate, which will be used to authenticate your Application against Azure AD, while requesting the app-only access token.
+   - Create and configure a self-signed X.509 certificate, which is used to authenticate your Application against Azure AD, while requesting the app-only access token.
 
-   - This is similar to generating a password for user accounts. The certificate can be self-signed as well. See the [Appendix](#step-3-generate-a-self-signed-certificate) section later in this article for instructions for generating certificates in PowerShell.
+   - This procedure is similar to generating a password for user accounts. The certificate can be self-signed as well. See the [Appendix](#step-3-generate-a-self-signed-certificate) section later in this article for instructions for generating certificates in PowerShell.
 
      > [!NOTE]
      > Cryptography: Next Generation (CNG) certificates are not supported for app-only authentication with Exchange. CNG certificates are created by default in modern Windows versions. You must use a certificate from a CSP key provider. The [Appendix](#step-3-generate-a-self-signed-certificate) section covers two supported methods to create a CSP certificate.
@@ -166,7 +164,7 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
 
    Or, to go directly to the **App registrations** page, use <https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade>.
 
-3. On the **App registrations** page, click **New registration**.
+3. 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)
 
@@ -186,7 +184,7 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
 
      ![Register an application.](media/exo-app-only-auth-register-app.png)
 
-   When you're finished, click **Register**.
+   When you're finished on the **App registrations** page, select **Register**.
 
 4. Leave the app page that you return to open. You'll use it in the next step.
 
@@ -234,9 +232,9 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
    > ],
    > ```
 
-   When you're finished, click **Save**.
+   When you're finished on the **Manifest** page, select **Save**.
 
-3. Still on the **Manifest** page, under **Management**, select **API permissions**.
+3. Still on the **Manifest** page, select **API permissions** under **Management**.
 
    ![Select API permissions on the application properties page.](media/exo-app-only-auth-select-api-permissions.png)
 
@@ -251,13 +249,13 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
 
      ![Original incorrect API permissions.](media/exo-app-only-auth-original-permissions.png)
 
-     Select **Grant admin consent for \<Organization\>**, read the confirmation dialog that opens, and then click **Yes**.
+     Select **Grant admin consent for \<Organization\>**, read the confirmation dialog that opens, and then select **Yes**.
 
      The **Status** value should now be **Granted for \<Organization\>**.
 
      ![Admin consent granted.](media/exo-app-only-auth-admin-consent-granted.png)
 
-4. Close the current **API permissions** page (not the browser tab) to return to the **App registrations** page. You'll use it in an upcoming step.
+4. 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
 
@@ -296,15 +294,15 @@ After you register the certificate with your application, you can use the privat
 
    ![Select Certificates & Secrets on the application properties page.](media/exo-app-only-auth-select-certificates-and-secrets.png)
 
-3. On the **Certificates & secrets** page that opens, click **Upload certificate**.
+3. On the **Certificates & secrets** page that opens, 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).
 
-   ![Browse to the certificate and then click Add.](media/exo-app-only-auth-upload-certificate-dialog.png)
+   ![Browse to the certificate and then select Add.](media/exo-app-only-auth-upload-certificate-dialog.png)
 
-   When you're finished, click **Add**.
+   When you're finished, select **Add**.
 
    The certificate is now shown in the **Certificates** section.
 
@@ -328,8 +326,8 @@ For more information about the URL syntax, see [Request the permissions from a d
 
 You have two options:
 
-- **Assign Azure AD roles to the application**: This method is supported in Exchange Online PowerShell and Security & Compliance PowerShell.
-- **Assign custom Exchange Online role groups to the application using service principals**: This method is supported only when you connect in [REST API mode](exchange-online-powershell-v2.md#updates-for-the-exo-v3-module).
+- **Assign Azure AD roles to the application**
+- **Assign custom role groups to the application using service principals**: 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#updates-for-the-exo-v3-module). Security & Compliance PowerShell supports REST API mode in v3.2.0-Preview4 or later.
 
 > [!NOTE]
 > You can also combine both methods to assign permissions. For example, you can use Azure AD roles for the "Exchange Recipient Administrator" role and also assign your custom RBAC role to extend the permissions.
@@ -379,7 +377,7 @@ For general instructions about assigning roles in Azure AD, see [View and assign
 
      ![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, click **Add assignments**.
+3. On the **Assignments** page that opens, select **Add assignments**.
 
    - **Exchange Online PowerShell**:
 
@@ -393,7 +391,7 @@ For general instructions about assigning roles in Azure AD, see [View and assign
 
    ![Find and select your app on the Add assignments flyout.](media/exo-app-only-auth-find-add-select-app-for-assignment.png)
 
-   When you're finished, click **Add**.
+   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.
 
@@ -405,14 +403,14 @@ For general instructions about assigning roles in Azure AD, see [View and assign
 
      ![The role assignments page after to added the app to the role for Security & Compliance PowerShell.](media/exo-app-only-auth-app-assigned-to-role-scc.png)
 
-#### Assign custom Exchange Online role groups to the application using service principals
+#### 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 is 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 won'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 in [REST API mode](exchange-online-powershell-v2.md#updates-for-the-exo-v3-module).
+>  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#updates-for-the-exo-v3-module). Security & Compliance PowerShell supports REST API mode in v3.2.0-Preview4 or later.
 
-For information about creating custom role groups, see [Create role groups](/exchange/permissions-exo/role-groups#create-role-groups). The custom role group that you assign to the application can contain any combination of built-in and custom roles.
+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 365 Defender portal](/microsoft-365/security/office-365-security/mdo-portal-permissions#create-email--collaboration-role-groups-in-the-microsoft-365-defender-portal). The custom role group that you assign to the application can contain any combination of built-in and custom roles.
 
 To assign custom role groups to the application using service principals, do the following steps:
 

exchange/docs-conceptual/connect-exo-powershell-managed-identity.md

@@ -92,10 +92,10 @@ Connect-ExchangeOnline -ManagedIdentity -Organization contoso.onmicrosoft.com
 After you've [created and configured a user-assigned managed identity](#create-and-configure-a-user-assigned-managed-identity), use the following syntax to connect to Exchange Online PowerShell:
 
 ```powershell
-Connect-ExchangeOnline -ManagedIdentity -Organization <YourDomain>.onmicrosoft.com -ManagedIdentityAccountId <UserAssignedManagedIdentityPrincipalIdValue>
+Connect-ExchangeOnline -ManagedIdentity -Organization <YourDomain>.onmicrosoft.com -ManagedIdentityAccountId <UserAssignedManagedIdentityClientIdValue>
 ```
 
-You get the \<UserAssignedManagedIdentityPrincipalIdValue\> value from [Step 3: Store the user-assigned managed identity in a variable](#step-3-store-the-user-assigned-managed-identity-in-a-variable).
+You get the \<UserAssignedManagedIdentityClientIdValue\> value from [Step 3: Store the user-assigned managed identity in a variable](#step-3-store-the-user-assigned-managed-identity-in-a-variable).
 
 The rest of this section explains how to connect using supported Azure resources. For example:
 
@@ -134,7 +134,7 @@ After you've successfully created the PowerShell runbook, do the following steps
 In a Windows PowerShell window in the Azure VM, use the command as described in the beginning of this section. For example:
 
 ```powershell
-$MI_ID = (Get-AzUserAssignedIdentity -Name "ContosoMI1" -ResourceGroupName "ContosoRG2").PrincipalId
+$MI_ID = (Get-AzUserAssignedIdentity -Name "ContosoMI1" -ResourceGroupName "ContosoRG2").ClientId
 
 Connect-ExchangeOnline -ManagedIdentity -Organization contoso.onmicrosoft.com -ManagedIdentityAccountId $MI_ID
 ```
@@ -518,10 +518,10 @@ For instructions, see the following articles:
 
 ### Step 3: Store the user-assigned managed identity in a variable
 
-Use the following syntax in [Azure Az PowerShell](/powershell/azure/install-az-ps) to store the PrincipalId value of the user-assigned managed identity in variable that you'll use in the upcoming steps:
+Use the following syntax in [Azure Az PowerShell](/powershell/azure/install-az-ps) to store the ClientId value of the user-assigned managed identity in variable that you'll use in the upcoming steps:
 
 ```powershell
-$MI_ID = (Get-AzUserAssignedIdentity -Name "<UserAssignedMI>" -ResourceGroupName "<MIResourceGroupName>").PrincipalId
+$MI_ID = (Get-AzUserAssignedIdentity -Name "<UserAssignedMI>" -ResourceGroupName "<MIResourceGroupName>").ClientId
 ```
 
 - \<UserAssignedMI\> is the name of the user-assigned managed identity.
@@ -530,7 +530,7 @@ $MI_ID = (Get-AzUserAssignedIdentity -Name "<UserAssignedMI>" -ResourceGroupName
 For example:
 
 ```powershell
-$MI_ID = (Get-AzUserAssignedIdentity -Name "ContosoMI1" -ResourceGroupName "ContosoRG2").PrincipalId
+$MI_ID = (Get-AzUserAssignedIdentity -Name "ContosoMI1" -ResourceGroupName "ContosoRG2").ClientId
 ```
 
 To verify that the variable was captured successfully, run the command `$MI_ID`. The output should be a GUID value (for example, bf6dcc76-4331-4942-8d50-87ea41d6e8a1).