Can I store the SMTP password in a Vault instead of kong.conf?
Yes. If you have a Vault backend configured, you can reference the SMTP password as a Vault secret using the {vault://...} syntax in kong.conf.
Configure Azure Communication Services for SMTP emails in Kong Gateway
Uses:
Kong Gateway
Incompatible with
konnect
Related Documentation
Tags
Related Resources
Minimum Version
Kong Gateway - 3.14
TL;DR
Create an Azure Communication Services resource with an email resource connected, register a Microsoft Entra application with the Communication and Email Service Owner role, and create an SMTP username. Then, configure the SMTP host, port, username, password, and admin_emails_from in your kong.conf file.
Prerequisites
Kong Gateway with RBAC enabled
You need a running Kong Gateway instance with RBAC and authentication enabled.
SMTP emails are used in Kong Manager for workflows like admin invitations and password resets, which require authentication and RBAC to be turned on.
Make sure you’ve copied and renamed the Kong Gateway kong.conf:
cp /etc/kong/kong.conf.default /etc/kong/kong.conf
Copied!
Azure Communication Services resource
You need an Azure Communication Services resource with an Email Communication resource connected and a verified domain.
Follow the Azure SMTP authentication guide to create your SMTP credentials. You’ll need to note the SMTP username and the Microsoft Entra application client secret for the next step.
Configure Kong Gateway with Azure SMTP settings
Add the following SMTP configuration to your kong.conf file.
Replace the placeholder values with the SMTP endpoint, username, and password from the prerequisites:
smtp_mock = off
smtp_host = smtp.azurecomm.net
smtp_port = 587
smtp_starttls = on
smtp_username = YOUR_SMTP_USERNAME
smtp_password = YOUR_ENTRA_CLIENT_SECRET
smtp_auth_type = login
admin_emails_from = YOUR_NAME <verified-sender@example.com>
admin_emails_reply_to = YOUR_NAME <verified-sender@example.com>
lua_ssl_verify_depth = 2
Copied!
Replace the following values:
-
smtp_username: The SMTP username you created in the Azure portal. -
smtp_password: The Microsoft Entra application client secret. -
admin_emails_from: A connected email address from your Azure Communication Services domain. -
admin_emails_reply_to: The reply-to email address for outgoing emails.
Setting
lua_ssl_verify_depth: Azure Communication Services uses a deeper intermediate certificate chain than the default SSL verification depth allows. Setlua_ssl_verify_depthto 2 to resolve SSL handshake errors.
Restart Kong Gateway
After updating kong.conf, restart Kong Gateway to apply the changes:
kong restart
Copied!
Validate
To verify that the SMTP configuration is working correctly, do the following:
- Navigate to Kong Manager in your browser (for example, http://localhost:8002).
- Do one of the following:
- If you have basic authentication enabled, click Forgot Password on the login page and enter a valid admin email address. If the configuration is correct, a password reset email is sent to that address via Azure Communication Services.
- If you’re logged in as a super admin, invite a new admin by navigating to Teams > Admins and clicking Invite Admin. Enter an email address and submit. If the SMTP settings are configured correctly, the invitation email is sent through Azure Communication Services.