Email¶

Before you start¶

Goal

Connect Altair SLC Hub to an existing SMTP server for both Altair SLC Hub services and Keycloak.

Prerequisites

Have the setting and credentials for the running SMTP server.
Altair SLC Hub configuration privileges for the host.
Have an email address to receive a test email.
Access to the Keycloak Admin Console. See Admin Console

Overview¶

Email in Altair SLC Hub must be configured in two places:

Hub services — used for operational emails such as job completion and failure notifications. Configured via the configuration files under [etc directory]/config.d/.
Keycloak — used for user-facing emails such as account invitations, password resets, and account lockout notifications. Configured in the Keycloak Admin Console.

Both configurations must be completed for all email functionality to work correctly.

Configuring email server connection¶

Various pieces of Altair SLC Hub functionality rely on the ability to send emails to users, for example, the forgotten password functionality, or password reset functionality.

The email settings are in the mail configuration section. The mail settings can be viewed with the hubctl config print command:

hubctl config print mail

A list of the configuration settings and guidance about their use is found in the Altair SLC Hub configuration file [etc directory]/config.d/mail.yaml. If any settings require modification, create a new file in the same directory with a lexicographically greater name such as [etc directory]/config.d/mail_custom.yaml and add customisation requirements to that file.

Vault credentials¶

As an alternative to specifying credentials directly in the config file, it is possible to configure Altair SLC Hub to retrieve SMTP credentials from a HashiCorp Vault secret by setting mail.vaultSecretPath to the path of the secret. The secret must contain username and password values. Only the static KV secrets engine is supported.

Warning

Vault-based credential storage applies to Altair SLC Hub services only. Keycloak does not support reading credentials from Vault — SMTP credentials for Keycloak must be entered directly in the Keycloak Admin Console as described below.

Configuring Keycloak email¶

Keycloak handles user-facing emails such as account invitations, password resets, and account lockout notifications. These are configured separately in the Keycloak Admin Console and are independent of the Altair SLC Hub services email configuration above.

To configure email in Keycloak:

Navigate to the Keycloak Admin Console at:
```
<hub-url>/keycloak/admin/slchub/console
```
Log in with your Keycloak admin credentials.
In the left menu, select Realm Settings.
Click the Email tab.

Fill in the following settings:

Field	Description
From	The sender email address that appears on outgoing emails.
From display name	Optional display name shown alongside the sender address.
Reply to	Optional reply-to address.
Host	The hostname of the SMTP server.
Port	The SMTP port. Common values are `587` for STARTTLS, `465` for SSL, or `25` for unencrypted SMTP. Use the port specified by your SMTP server provider.
Enable StartTLS	Enable if the SMTP server requires STARTTLS encryption.
Enable SSL	Enable if the SMTP server requires SSL.
Enable Authentication	Enable if the SMTP server requires credentials, then provide the username and password.

Click Test connection to verify the settings before saving.
Click Save.

Note

The SMTP settings in Keycloak should match those in mail.yaml for consistency, as both Altair SLC Hub services and Keycloak connect to the same SMTP server in most deployments.

Keycloak Documentation

For full details on Keycloak email configuration, see the Keycloak Server Administration Guide.

Trusting a private Certificate Authority¶

If your SMTP server uses a certificate signed by a private or internal Certificate Authority (CA), Keycloak must be configured to trust that CA, otherwise email sending from Keycloak will fail.

There are two ways to add a trusted CA certificate to Keycloak:

Option 1 — Truststores directory (recommended)¶

Place the certificate file (PEM or PKCS12 format) in the <hubhome>/libexec/keycloak/conf/truststores/ directory on the Keycloak host. Keycloak automatically includes all certificates found in this directory on startup. For full details, see Configuring trusted certificates in the Keycloak documentation.

Option 2 — Truststore paths configuration¶

Add the following line to <hubhome>/etc/keycloak/keycloak.conf:

truststore-paths=<path to certificate file or directory>

This tells Keycloak to include the specified certificate file or directory in its truststore on startup.

For mTLS and outgoing HTTP request configuration, see Configuring outgoing HTTP requests in the Keycloak documentation.

Note

A restart of Altair SLC Hub is required after modifying the Keycloak truststore configuration for the changes to take effect.

Hub services certificate configuration

The certificate options in mail.yaml (rootCA, rootCAData, clientCert, clientKey) apply to Altair SLC Hub services only and are not used by Keycloak. If your SMTP server uses a private CA, you must configure the Keycloak truststore separately as described above.

Verification¶

Verify E-mails can be sent

run the hubctl verify email command
run the hubctl testemail command

To verify Altair SLC Hub service email settings, use the command:

hubctl verify email

To send a test email through Altair SLC Hub services, use the command:

hubctl testemail [email protected]

This sends a test email to the given address and prints any errors that occur.

Note

These commands verify the Altair SLC Hub services email configuration only. To verify that Keycloak email is working correctly, use the Test connection button in Realm Settings > Email in the Keycloak Admin Console.

Restart Altair SLC Hub¶

Having successfully configured the email settings, it is necessary to restart Altair SLC Hub:

hubctl service restart