Adam Jones|HomeBlog

How to send Keycloak emails through Google Workspace's SMTP relay

Headshot of Adam Jones

Adam Jones

To support Keycloak's standard email verification and password reset flows, you'll need to configure an SMTP connection.

If you already have a Google Workspace account, you can set up a free SMTP relay in a few minutes. As well as saving you from having to set up a separate SMTP service, this also means that you get all the benefits of your existing email setup from Google Workspace such as DKIM signing.

Google Workspace setup

As a Google Workspace admin:

  1. In the admin console, go to Apps > Google Workspace > Gmail > Routing.
  2. Go to the 'SMTP relay service' section, and click 'Add rule'
  3. Set the following settings:
    • Allowed senders: Only addresses in my domains
    • Authentication: Require SMTP Authentication (specific IP optional)
    • Encryption: Require TLS encryption
As any Google Workspace account:1
  1. In your account settings, go to Security > 2-Step Verification > App passwords
  2. Create a new app password, and copy this value2

Keycloak setup

In the admin console:

  1. Go to Realm settings > Email
  2. In the Template section, set the 'From' address to anything@yourdomain.com
  3. In the Connection & Authentication section, set:
    • Host: smtp-relay.gmail.com
    • Port: 587
    • Encryption: Enable StartTLS
    • Authentication: Enabled
    • Username: The account associated with the app password you copied earlier, e.g. keycloak-svc@yourdomain.com.
    • Password: The app password you copied earlier.

Footnotes

  1. Preferably use a service account so it doesn't break when someone leaves the company, e.g. keycloak-svc@yourdomain.com. Emails don't need to be sent from this account, e.g. keycloak-svc@yourdomain.com can send as noreply@yourdomain.com with no further setup. ↩

  2. The spaces don't matter, as in they can be included or excluded. Presumably Google strips them when authenticating. ↩