Merge pull request #286727 from ddouglas-msft/ddouglas-msft/smtp-auth-update-permissions

Update custom role permissions for smtp auth

Author: Jill Grant

articles/communication-services/quickstarts/email/media/smtp-custom-role-add-permissions.png

@@ -2,7 +2,7 @@
 title: How to use SMTP to send an email with Azure Communication Services.
 titleSuffix: An Azure Communication Services quick start guide.
 description: Learn about how to use SMTP to send emails to Email Communication Services.
-author: ddouglas
+author: ddouglas-msft
 services: azure-communication-services
 ms.author: ddouglas
 ms.date: 10/18/2023

articles/communication-services/quickstarts/email/media/smtp-custom-role-review.png

@@ -2,7 +2,7 @@
 title: How to create authentication credentials for sending emails using SMTP
 titleSuffix: An Azure Communication Services Quickstart
 description: Learn about how to use a service principal to create authentication credentials for sending emails using SMTP.
-author: ddouglas
+author: ddouglas-msft
 services: azure-communication-services
 ms.author: ddouglas
 ms.date: 10/18/2023
@@ -19,16 +19,16 @@ In this quick start, you learn about how to use an Entra application to create t
 - An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). 
 - An Azure Communication Email Resource created and ready with a provisioned domain [Get started with Creating Email Communication Resource](../create-email-communication-resource.md)
 - An active Azure Communication Services Resource connected with Email Domain and a Connection String. [Get started by Connecting Email Resource with a Communication Resource](../connect-email-communication-resource.md)
-- An Entra application with access to the Azure Communication Services Resource. [Register an application with Microsoft Entra ID and create a service principal](/entra/identity-platform/howto-create-service-principal-portal#register-an-application-with-microsoft-entra-id-and-create-a-service-principal)
-- A client secret for the Entra application with access to the Azure Communication Service Resource. [Create a new client secret](/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret)
+- A Microsoft Entra application with access to the Azure Communication Services Resource. [Register an application with Microsoft Entra ID and create a service principal](/entra/identity-platform/howto-create-service-principal-portal#register-an-application-with-microsoft-entra-id-and-create-a-service-principal)
+- A client secret for the Microsoft Entra application with access to the Azure Communication Service Resource. [Create a new client secret](/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret)
 
 ## Using a Microsoft Entra application with access to the Azure Communication Services Resource for SMTP
 
-Application developers who build apps that send email using the SMTP protocol need to implement secure, modern authentication. Azure Communication Services does this by leveraging Entra application service principals. Combining the Azure Communication Services Resource and the Entra application service principal's information, the SMTP services undertakes authentication with Entra on the user's behalf to ensure a secure and seamless email transmission.
+Application developers who build apps that send email using the SMTP protocol need to implement secure, modern authentication. Azure Communication Services does this by leveraging Microsoft Entra application service principals. Combining the Azure Communication Services Resource and the Microsoft Entra application service principal's information, the SMTP services undertakes authentication with Microsoft Entra on the user's behalf to ensure a secure and seamless email transmission.
 
-### Creating a custom email role for the Entra application
+### Creating a custom email role for the Microsoft Entra application
 
-The Entra application must be assigned a role with both the **Microsoft.Communication/CommunicationServices/Read** and the **Microsoft.Communication/EmailServices/write** permissions on the Azure Communication Service Resource. This can be done either by using the **Contributor** role, or by creating a **custom role**. Follow these steps to create a custom role by cloning an existing role.
+The Microsoft Entra application must be assigned a role with both the **Microsoft.Communication/CommunicationServices/Read**, **Microsoft.Communication/CommunicationServices/Write**, and the **Microsoft.Communication/EmailServices/write** permissions on the Azure Communication Service Resource. This can be done either by using the **Contributor** role, or by creating a **custom role**. Follow these steps to create a custom role by cloning an existing role.
 
 1. In the portal, a custom role can be created by first navigating to the subscription, resource group, or Azure Communication Service Resource where you want the custom role to be assignable and then open **Access control (IAM)**.
     :::image type="content" source="../media/smtp-custom-role-iam.png" alt-text="Screenshot that shows Access control.":::
@@ -40,14 +40,14 @@ The Entra application must be assigned a role with both the **Microsoft.Communic
     :::image type="content" source="../media/smtp-custom-role-basics.png" alt-text="Screenshot that shows creating a name for a new custom role.":::
 1. Click the **Permissions** tab and click **Add permissions**. Search for **Microsoft.Communication** and select **Azure Communication Services**
     :::image type="content" source="../media/smtp-custom-role-permissions.png" alt-text="Screenshot that shows adding permissions for a new custom role.":::
-1. Select the **Microsoft.Communication/CommunicationServices** **Read** and the **Microsoft.Communication/EmailServices** **Write*** permissions. Click **Add**.
+1. Select the **Microsoft.Communication/CommunicationServices** **Read**, **Microsoft.Communication/CommunicationServices** **Write**, and the **Microsoft.Communication/EmailServices** **Write** permissions. Click **Add**.
     :::image type="content" source="../media/smtp-custom-role-add-permissions.png" alt-text="Screenshot that shows adding Azure Communication Services' permissions.":::
 1. Review the permissions for the new role. Click **Review + create** and then **Create** on the next page.
     :::image type="content" source="../media/smtp-custom-role-review.png" alt-text="Screenshot that shows reviewing the new custom role.":::
 
-When assigning the Entra application a role for the Azure Communication Services Resource, the new custom role will be available. For more information on creating custom roles, see [Create or update Azure custom roles using the Azure portal](../../../../role-based-access-control/custom-roles-portal.md)
+When assigning the Microsoft Entra application a role for the Azure Communication Services Resource, the new custom role will be available. For more information on creating custom roles, see [Create or update Azure custom roles using the Azure portal](../../../../role-based-access-control/custom-roles-portal.md)
 
-### Assigning the custom email role to the Entra application
+### Assigning the custom email role to the Microsoft Entra application
 1. In the portal, navigate to the subscription, resource group, or Azure Communication Service Resource where you want the custom role to be assignable and then open **Access control (IAM)**.
     :::image type="content" source="../media/smtp-custom-role-iam.png" alt-text="Screenshot that shows Access control.":::
 1. Click **+Add** and then select **Add role assignment**.
@@ -56,39 +56,39 @@ When assigning the Entra application a role for the Azure Communication Services
     :::image type="content" source="../media/email-smtp-select-custom-role.png" alt-text="Screenshot that shows selecting the custom role.":::
 1. On the **Members** tab, choose **User, group, or service principal** and then click **+Select members**.
     :::image type="content" source="../media/email-smtp-select-members.png" alt-text="Screenshot that shows choosing select members.":::
-1. Use the search box to find the **Entra** application that you'll use for authentication and select it. Then click **Select**.
-    :::image type="content" source="../media/email-smtp-select-entra.png" alt-text="Screenshot that shows selecting the Entra application.":::
+1. Use the search box to find the **Microsoft Entra** application that you'll use for authentication and select it. Then click **Select**.
+    :::image type="content" source="../media/email-smtp-select-entra.png" alt-text="Screenshot that shows selecting the Microsoft Entra application.":::
 1. After confirming the selection, click **Next**.
     :::image type="content" source="../media/email-smtp-select-review.png" alt-text="Screenshot that shows reviewing the assignment.":::
 1. After confirming the scope and members, click **Review + assign**.
     :::image type="content" source="../media/email-smtp-select-assign.png" alt-text="Screenshot that shows assigning the custom role.":::
 
-### Creating the SMTP credentials from the Entra application information.
+### Creating the SMTP credentials from the Microsoft Entra application information.
 #### SMTP Authentication Username
-Azure Communication Services allows the credentials for an Entra application to be used as the SMTP username and password. The username consists of the following three parts and can be pipe or dot delimited.
+Azure Communication Services allows the credentials for a Microsoft Entra application to be used as the SMTP username and password. The username consists of the following three parts and can be pipe or dot delimited.
 1. The Azure Communication Service Resource name.
     :::image type="content" source="../media/email-smtp-resource-name.png" alt-text="Screenshot that shows finding the resource name.":::
-1. The Entra Application ID.
-    :::image type="content" source="../media/email-smtp-entra-details.png" alt-text="Screenshot that shows finding the Entra Application ID.":::
-1. The Entra Tenant ID.
-    :::image type="content" source="../media/email-smtp-entra-tenant.png" alt-text="Screenshot that shows finding the Entra Tenant ID.":::
+1. The Microsoft Entra Application ID.
+    :::image type="content" source="../media/email-smtp-entra-details.png" alt-text="Screenshot that shows finding the Microsoft Entra Application ID.":::
+1. The Microsoft Entra Tenant ID.
+    :::image type="content" source="../media/email-smtp-entra-tenant.png" alt-text="Screenshot that shows finding the Microsoft Entra Tenant ID.":::
 
 **Dot-delimited Format:**
 ```
-username: <Azure Communication Services Resource name>.<Entra Application ID>.<Entra Tenant ID>
+username: <Azure Communication Services Resource name>.<Microsoft Entra Application ID>.<Microsoft Entra Tenant ID>
 ```
 **Pipe-delimited Format:**
 ```
-username: <Azure Communication Services Resource name>|<Entra Application ID>|<Entra Tenant ID>
+username: <Azure Communication Services Resource name>|<Microsoft Entra Application ID>|<Microsoft Entra Tenant ID>
 ```
 
 #### SMTP Authentication Password
-The password is one of the Entra application's client secrets.
-    :::image type="content" source="../media/email-smtp-entra-secret.png" alt-text="Screenshot that shows finding the Entra client secret.":::
+The password is one of the Microsoft Entra application's client secrets.
+    :::image type="content" source="../media/email-smtp-entra-secret.png" alt-text="Screenshot that shows finding the Microsoft Entra client secret.":::
 
 ### Requirements for SMTP AUTH client submission
 
-- **Authentication**: Username and password authentication is supported using Entra application details as the credentials. The Azure Communication Services SMTP service will use the Entra application details to get an access token on behalf of the user and use that to submit the email. Because the Entra token isn't cached, access can be revoked immediately by either changing the Entra application client secret or by changing the access controls for the Azure Communication Services Resource.
+- **Authentication**: Username and password authentication is supported using the Microsoft Entra application details as the credentials. The Azure Communication Services SMTP service will use the Microsoft Entra application details to get an access token on behalf of the user and use that to submit the email. Because the Microsoft Entra token isn't cached, access can be revoked immediately by either changing the Microsoft Entra application client secret or by changing the access controls for the Azure Communication Services Resource.
 - **Azure Communication Service**: An Azure Communication Services Resource with a connected Azure Communication Email Resource and domain is required.
 - **Transport Layer Security (TLS)**: Your device must be able to use TLS version 1.2 and above.
 - **Port**: Port 587 is required and must be unblocked on your network. Some network firewalls or ISPs block ports because that's the port that email servers use to send mail.
@@ -103,4 +103,4 @@ Enter the following settings directly on your device or in the application as th
 |Server / smart host | smtp.azurecomm.net |
 |Port |Port 587|
 |TLS / StartTLS | Enabled|
-|Username and password | Enter the Entra application credentials from an application with access to the Azure Communication Services Resource |
+|Username and password | Enter the Microsoft Entra application credentials from an application with access to the Azure Communication Services Resource |