Skip to main content

Configure Mailcow to Use Keycloak for User Authentication

Prerequisites: Ensure Keycloak is deployed and configured as described in Keycloak Server Deployment and Keycloak Configuration, and that Mailcow is installed and reachable.

This guide explains how to integrate Mailcow with Keycloak using OpenID Connect. After configuration, LDAP users can authenticate through Keycloak and log in to Mailcow with Single Sign-On (SSO).

1. Create a Keycloak Client for Mailcow​

  1. Log in to the Keycloak admin console and select the example-sso realm.

  2. Open the Clients menu and click Create client.

  3. Configure the client with the following values:

    • Client ID: mailcow
    • Client Protocol: openid-connect
    • Client Authentication: On
    • Standard Flow Enabled: On
    • Direct Access Grants Enabled: Off
    • Service Accounts Enabled: Off

  4. Save the client.

Add Mailcow Client

  1. In the client settings, set a valid redirect URI. Use the URI provided by Mailcow, for example:

    https://mail.example.com/oidc/callback

    If Mailcow indicates a different callback path, use that value instead.

  2. Open the Credentials tab and copy the Client Secret.

Copy Credentials

2. Create a Mailcow Client Scope​

  1. From the Keycloak left-hand menu, select Client scopes.

  2. Click Create client scope and enter:

    • Name: mailcow-dedicated-scope
    • Protocol: openid-connect

  3. Save the client scope.

  4. Select the new scope and open the Mappers tab.

  5. Add the following mapper:

    • Name: mailcow_username
    • Mapper Type: User Property
    • Property: username
    • Token Claim Name: preferred_username
    • Claim JSON Type: String

Add Mapper

  1. Edit the mailcow client and add mailcow-dedicated-scope under the Client scopes section.

3. Configure Mailcow to Use Keycloak​

  1. Log in to the Mailcow admin interface as the administrator user.

  2. Go to System > Configuration.

  3. Choose Access > Identity Provider.

  4. Configure the provider with these values:

    • Provider: OpenID Connect
    • Issuer URL: https://keycloak.example.com/realms/example-sso
    • Client ID: mailcow
    • Client Secret: (paste the secret from Keycloak)
    • Scopes: openid email profile
    • Username attribute: preferred_username
    • Email attribute: email
    • Name attribute: name

  5. Save the configuration.

Mailcow Configuration

4. Verify User Login​

  1. Visit the Mailcow login page at https://mail.example.com/.

  2. Confirm that the Single Sign-On button is visible.

    SSO Login Button

  3. Click the button and sign in with an LDAP user account from Keycloak, for example mailuser.

  4. After successful authentication, you should be redirected back to Mailcow and logged in as that user.

5. Troubleshooting​

  • If the redirect fails, verify the Keycloak valid redirect URI matches the Mailcow callback URL exactly.
  • Confirm the Issuer URL uses the Keycloak realm root: https://keycloak.example.com/realms/example-sso.
  • Ensure openid, email, and profile scopes are enabled in Mailcow.
  • Check the Keycloak client secret is entered correctly in Mailcow.
  • Review Mailcow and Keycloak logs for authentication or callback errors.