diff --git a/exchange/docs-conceptual/app-only-auth-powershell-v2.md b/exchange/docs-conceptual/app-only-auth-powershell-v2.md index aeb1a2fd86..fc8820bf2a 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: 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. - Exchange Online PowerShell: @@ -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 . @@ -140,9 +138,9 @@ For a detailed visual flow about creating applications in Azure AD, see [!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 . -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 ], > ``` - 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 **, read the confirmation dialog that opens, and then click **Yes**. + Select **Grant admin consent for \**, read the confirmation dialog that opens, and then select **Yes**. The **Status** value should now be **Granted for \**. ![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: