keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/email.xml

<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<section id="email-config">
    <title>Email Server Config</title>
    <para>
        To enable Keycloak to send emails you need to provide Keycloak with your SMTP server settings. If you don't have
        a SMTP server you can use one of many hosted solutions (such as Sendgrid or smtp2go).
    </para>

    <para>
        To configure your SMTP server, open the <literal>Keycloak Admin Console</literal>, select your realm from the drop-down box in the top left corner.
        Then click on <literal>Email</literal> in the menu at the top.
    </para>

    <para>
        You are required to fill in the <literal>Host</literal> and <literal>Port</literal> for your SMTP server (the default port for SMTP is 25). You also have
        to specify the sender email address (<literal>From</literal>). The other options are optional.
    </para>

    <para>
        The screenshot below shows a simple example where the SMTP server doesn't use SSL or TLS and doesn't require authentication.
    </para>

    <imagedata fileref="images/email-simple-example.png"/>

    <section>
        <title>Enable SSL or TLS</title>
        <para>
            As emails are used for recovering usernames and passwords it's recommended to use SSL or TLS, especially if the SMTP server
            is on an external network. To enable SSL click on <literal>Enable SSL</literal> or to enable TLS click on <literal>Enable TLS</literal>.
            You will most likely also need to change the <literal>Port</literal> (the default port for SSL/TLS is 465).
        </para>
    </section>

    <section>
        <title>Authentication</title>
        <para>
            If your SMTP server requires authentication click on <literal>Enable Authentication</literal> and insert
            the <literal>Username</literal> and <literal>Password</literal>.
        </para>
    </section>
</section>