Quickstart: How to create authentication credentials for sending emails using SMTP

In this quick start, you learn about how to use an Entra application to create the authentication credentials for using SMTP to send an email using Azure Communication Services.

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• An Azure Communication Email Resource created and ready with a provisioned domain Get started with Creating Email Communication Resource
• An active Azure Communication Services Resource connected with Email Domain and a Connection String. Get started by Connecting Email Resource with a Communication Resource
• A Microsoft Entra application with access to the Azure Communication Services Resource. 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

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 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 Microsoft Entra application

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).
2. Click the Roles tab to see a list of all the built-in and custom roles.
3. Search for a role you want to clone such as the Reader role.
4. At the end of the row, click the ellipsis (...) and then click Clone.
5. Click the Basics tab and give a name to the new role.
6. Click the Permissions tab and click Add permissions. Search for Microsoft.Communication and select Azure Communication Services
7. Select the Microsoft.Communication/CommunicationServices Read, Microsoft.Communication/CommunicationServices Write, and the Microsoft.Communication/EmailServices Write permissions. Click Add.
8. Review the permissions for the new role. Click Review + create and then Create on the next page.

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

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).
2. Click +Add and then select Add role assignment.
3. On the Role tab, select the custom role created for sending emails using SMTP and click Next.
4. On the Members tab, choose User, group, or service principal and then click +Select members.
5. Use the search box to find the Microsoft Entra application that you'll use for authentication and select it. Then click Select.
6. After confirming the selection, click Next.
7. After confirming the scope and members, click Review + assign.

Creating the SMTP credentials from the Microsoft Entra application information.

SMTP Authentication Username

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.
2. The Microsoft Entra Application ID.
3. The Microsoft Entra Tenant ID.

Dot-delimited Format:

username: <Azure Communication Services Resource name>.<Microsoft Entra Application ID>.<Microsoft Entra Tenant ID>

Pipe-delimited Format:

username: <Azure Communication Services Resource name>|<Microsoft Entra Application ID>|<Microsoft Entra Tenant ID>

SMTP Authentication Password

The password is one of the Microsoft Entra application's client secrets.

Requirements for SMTP AUTH client submission

• 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.
• DNS: Use the DNS name smtp.azurecomm.net. Don't use an IP address for the Microsoft 365 or Office 365 server, as IP Addresses aren't supported.

How to set up SMTP AUTH client submission

Enter the following settings directly on your device or in the application as their guide instructs (it might use different terminology than this article). Provided your scenario aligns with the prerequisites for SMTP AUTH client submission, these settings allow you to send emails from your device or application using SMTP Commands.