Skip to content

Commit 2304352

Browse files
committed
[BULK] - DocuTune - Rebranding of Azure Active Dir
1 parent 8b82507 commit 2304352

30 files changed

+92
-78
lines changed

exchange/docs-conceptual/app-only-auth-powershell-v2.md

Lines changed: 33 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ description: "Learn how to configure app-only authentication (also known as cert
2121

2222
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.
2323

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.
2525

2626
> [!NOTE]
2727
>
@@ -51,7 +51,7 @@ Certificate based authentication (CBA) or app-only authentication as described i
5151
5252
## How does it work?
5353

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.
5555

5656
## Connection examples
5757

@@ -126,39 +126,41 @@ The following examples show how to use the Exchange Online PowerShell module wit
126126
127127
## Set up app-only authentication
128128
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).
130130
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>.
132132
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).
134134
135135
2. [Assign API permissions to the application](#step-2-assign-api-permissions-to-the-application).
136136
137137
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**.
138138
139139
3. [Generate a self-signed certificate](#step-3-generate-a-self-signed-certificate)
140140
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.
142142
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.
144144
145145
- 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.
146146
147147
> [!NOTE]
148148
> 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.
149149
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)
151151
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)
153153
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.
155155
156-
### Step 1: Register the application in Azure AD
156+
<a name='step-1-register-the-application-in-azure-ad'></a>
157+
158+
### Step 1: Register the application in Microsoft Entra ID
157159
158160
> [!NOTE]
159161
> 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.
160162
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/>.
162164
163165
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.
164166
@@ -177,7 +179,7 @@ For a detailed visual flow about creating applications in Azure AD, see <https:/
177179
- **Supported account types**: Verify that **Accounts in this organizational directory only (\<YourOrganizationName\> only - Single tenant)** is selected.
178180
179181
> [!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)**.
181183
182184
- **Redirect URI (optional)**: This setting is optional. If you need to use it, configure the following settings:
183185
- **Platform**: Select **Web**.
@@ -348,7 +350,9 @@ Create a self-signed x.509 certificate using one of the following methods:
348350
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2021-01-06 -EndDate 2022-01-06
349351
```
350352

351-
### Step 4: Attach the certificate to the Azure AD application
353+
<a name='step-4-attach-the-certificate-to-the-azure-ad-application'></a>
354+
355+
### Step 4: Attach the certificate to the Microsoft Entra application
352356

353357
After you register the certificate with your application, you can use the private key (`.pfx` file) or the thumbprint for authentication.
354358

@@ -390,21 +394,25 @@ If you made the application multi-tenant for **Exchange Online** delegated scena
390394

391395
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).
392396

393-
### Step 5: Assign Azure AD roles to the application
397+
<a name='step-5-assign-azure-ad-roles-to-the-application'></a>
398+
399+
### Step 5: Assign Microsoft Entra roles to the application
394400

395401
You have two options:
396402

397-
- **Assign Azure AD roles to the application**
403+
- **Assign Microsoft Entra roles to the application**
398404
- **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.
399405

400406
> [!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.
402408
>
403409
> For multi-tenant applications in **Exchange Online** delegated scenarios, you need to assign permissions in each customer tenant.
404410
405-
#### Assign Azure AD roles to the application
411+
<a name='assign-azure-ad-roles-to-the-application'></a>
412+
413+
#### Assign Microsoft Entra roles to the application
406414

407-
The supported Azure AD roles are described in the following table:
415+
The supported Microsoft Entra roles are described in the following table:
408416

409417
|Role|Exchange Online<br>PowerShell|Security & Compliance<br>PowerShell|
410418
|---|:---:|:---:|
@@ -424,16 +432,16 @@ The supported Azure AD roles are described in the following table:
424432
>
425433
> The Security Administrator role does not have the necessary permissions for those same tasks.
426434
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).
428436

429437
> [!NOTE]
430438
> 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.
431439
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.
433441

434-
![Screenshot that shows Azure AD 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)
442+
![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)
435443

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>.
437445

438446
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.
439447

@@ -482,7 +490,7 @@ For information about creating custom role groups, see [Create role groups in Ex
482490

483491
To assign custom role groups to the application using service principals, do the following steps:
484492

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:
486494

487495
```powershell
488496
Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All
@@ -501,7 +509,7 @@ To assign custom role groups to the application using service principals, do the
501509
For detailed syntax and parameter information, see [Get-MgServicePrincipal](/powershell/module/microsoft.graph.applications/get-mgserviceprincipal).
502510

503511
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.
505513
- Store the details of the service principal in a variable to use in the next step.
506514

507515
```powershell

0 commit comments

Comments
 (0)