You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: exchange/docs-conceptual/app-only-auth-powershell-v2.md
+33-25Lines changed: 33 additions & 25 deletions
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ description: "Learn how to configure app-only authentication (also known as cert
21
21
22
22
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.
23
23
24
-
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.
24
+
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.
25
25
26
26
> [!NOTE]
27
27
>
@@ -51,7 +51,7 @@ Certificate based authentication (CBA) or app-only authentication as described i
51
51
52
52
## How does it work?
53
53
54
-
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.
54
+
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 Microsoft Entra ID 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.
55
55
56
56
## Connection examples
57
57
@@ -126,39 +126,41 @@ The following examples show how to use the Exchange Online PowerShell module wit
126
126
127
127
## Set up app-only authentication
128
128
129
-
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).
129
+
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 Microsoft Entra ID](/azure/active-directory/develop/app-objects-and-service-principals).
130
130
131
-
For a detailed visual flow about creating applications in Azure AD, see <https://aka.ms/azuread-app>.
131
+
For a detailed visual flow about creating applications in Microsoft Entra ID, see <https://aka.ms/azuread-app>.
132
132
133
-
1. [Register the application in Azure AD](#step-1-register-the-application-in-azure-ad).
133
+
1. [Register the application in Microsoft Entra ID](#step-1-register-the-application-in-azure-ad).
134
134
135
135
2. [Assign API permissions to the application](#step-2-assign-api-permissions-to-the-application).
136
136
137
137
An application object has the **Delegated** API permission **Microsoft Graph** \> **User.Read** by default. For the application object to access resources in Exchange, it needs the **Application** API permission **Office 365 Exchange Online** \> **Exchange.ManageAsApp**.
138
138
139
139
3. [Generate a self-signed certificate](#step-3-generate-a-self-signed-certificate)
140
140
141
-
- 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 with the permissions granted to the app.
141
+
- For app-only authentication in Microsoft Entra ID, you typically use a certificate to request access. Anyone who has the certificate and its private key can use the app with the permissions granted to the app.
142
142
143
-
- 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.
143
+
- Create and configure a self-signed X.509 certificate, which is used to authenticate your Application against Microsoft Entra ID, while requesting the app-only access token.
144
144
145
145
- This procedure is similar to generating a password for user accounts. The certificate can be self-signed as well. See [this section](#step-3-generate-a-self-signed-certificate) later in this article for instructions to generate certificates in PowerShell.
146
146
147
147
> [!NOTE]
148
148
> Cryptography: Next Generation (CNG) certificates aren't supported for app-only authentication with Exchange. CNG certificates are created by default in modern versions of Windows. You must use a certificate from a CSP key provider. [This section](#step-3-generate-a-self-signed-certificate) section covers two supported methods to create a CSP certificate.
149
149
150
-
4. [Attach the certificate to the Azure AD application](#step-4-attach-the-certificate-to-the-azure-ad-application)
150
+
4. [Attach the certificate to the Microsoft Entra application](#step-4-attach-the-certificate-to-the-azure-ad-application)
151
151
152
-
5. [Assign Azure AD roles to the application](#step-5-assign-azure-ad-roles-to-the-application)
152
+
5. [Assign Microsoft Entra roles to the application](#step-5-assign-azure-ad-roles-to-the-application)
153
153
154
-
The application needs to have the appropriate RBAC roles assigned. Because the apps are provisioned in Azure AD, you can use any of the supported built-in roles.
154
+
The application needs to have the appropriate RBAC roles assigned. Because the apps are provisioned in Microsoft Entra ID, you can use any of the supported built-in roles.
### Step 1: Register the application in Microsoft Entra ID
157
159
158
160
> [!NOTE]
159
161
> If you encounter problems, check the [required permissions](/azure/active-directory/develop/howto-create-service-principal-portal#required-permissions) to verify that your account can create the identity.
160
162
161
-
1. Open the Azure AD portal at <https://portal.azure.com/>.
163
+
1. Open the Microsoft Entra admin center at <https://portal.azure.com/>.
162
164
163
165
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.
164
166
@@ -177,7 +179,7 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
177
179
- **Supported account types**: Verify that **Accounts in this organizational directory only (\<YourOrganizationName\> only - Single tenant)** is selected.
178
180
179
181
> [!NOTE]
180
-
> To make the application multi-tenant for **Exchange Online** delegated scenarios, select the value **Accounts in any organizational directory (Any Azure AD directory - Multitenant)**.
182
+
> To make the application multi-tenant for **Exchange Online** delegated scenarios, select the value **Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)**.
181
183
182
184
- **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings:
183
185
- **Platform**: Select **Web**.
@@ -348,7 +350,9 @@ Create a self-signed x.509 certificate using one of the following methods:
### Step 4: Attach the certificate to the Microsoft Entra application
352
356
353
357
After you register the certificate with your application, you can use the private key (`.pfx` file) or the thumbprint for authentication.
354
358
@@ -390,21 +394,25 @@ If you made the application multi-tenant for **Exchange Online** delegated scena
390
394
391
395
For more information about the URL syntax, see [Request the permissions from a directory admin](/azure/active-directory/develop/v2-admin-consent#request-the-permissions-from-a-directory-admin).
392
396
393
-
### Step 5: Assign Azure AD roles to the application
### Step 5: Assign Microsoft Entra roles to the application
394
400
395
401
You have two options:
396
402
397
-
-**Assign Azure AD roles to the application**
403
+
-**Assign Microsoft Entra roles to the application**
398
404
-**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#rest-api-connections-in-the-exo-v3-module). Security & Compliance PowerShell supports REST API mode in v3.2.0 or later.
399
405
400
406
> [!NOTE]
401
-
> 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.
407
+
> 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.
402
408
>
403
409
> For multi-tenant applications in **Exchange Online** delegated scenarios, you need to assign permissions in each customer tenant.
@@ -424,16 +432,16 @@ The supported Azure AD roles are described in the following table:
424
432
>
425
433
> The Security Administrator role does not have the necessary permissions for those same tasks.
426
434
427
-
For general instructions about assigning roles in Azure AD, see [View and assign administrator roles in Azure Active Directory](/azure/active-directory/roles/manage-roles-portal).
435
+
For general instructions about assigning roles in Microsoft Entra ID, see [View and assign administrator roles in Microsoft Entra ID](/azure/active-directory/roles/manage-roles-portal).
428
436
429
437
> [!NOTE]
430
438
> The following steps are slightly different for Exchange Online PowerShell vs. Security & Compliance PowerShell. The steps for both environments are shown. To configure roles for both environments, repeat the steps in this section.
431
439
432
-
1. In Azure AD portal at <https://portal.azure.com/>, start typing **roles and administrators** in the **Search** box at the top of the page, and then select **Azure AD roles and administrators** from the results in the **Services** section.
440
+
1. In Microsoft Entra admin center at <https://portal.azure.com/>, 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.
433
441
434
-

442
+

435
443
436
-
Or, to go directly to the **Azure AD roles and administrators** page, use <https://portal.azure.com/#view/Microsoft_AAD_IAM/AllRolesBlade>.
444
+
Or, to go directly to the **Microsoft Entra roles and administrators** page, use <https://portal.azure.com/#view/Microsoft_AAD_IAM/AllRolesBlade>.
437
445
438
446
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.
439
447
@@ -482,7 +490,7 @@ For information about creating custom role groups, see [Create role groups in Ex
482
490
483
491
To assign custom role groups to the application using service principals, do the following steps:
484
492
485
-
1. In [Microsoft Graph PowerShell](/powershell/microsoftgraph/installation), run the following commands to store the details of the Azure AD application that you registered in [Step 1](#step-1-register-the-application-in-azure-ad) in a variable:
493
+
1. In [Microsoft Graph PowerShell](/powershell/microsoftgraph/installation), run the following commands to store the details of the Microsoft Entra application that you registered in [Step 1](#step-1-register-the-application-in-azure-ad) in a variable:
@@ -501,7 +509,7 @@ To assign custom role groups to the application using service principals, do the
501
509
For detailed syntax and parameter information, see [Get-MgServicePrincipal](/powershell/module/microsoft.graph.applications/get-mgserviceprincipal).
502
510
503
511
2. In the same PowerShell window, connect to [Exchange Online PowerShell](connect-to-exchange-online-powershell.md) or [Security & Compliance PowerShell](connect-to-scc-powershell.md) and run the following commands to:
504
-
- Create a service principal object for the Azure AD application.
512
+
- Create a service principal object for the Microsoft Entra application.
505
513
- Store the details of the service principal in a variable to use in the next step.
0 commit comments