Inbound SMTP Email Server Configuration

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

2.22.93.23.33.4Email

Table of Contents

• 1 Introduction


• 2 How Email Messages are Handled
  
  
  
  • 2.1 Directly Referenced Nodes
  
  
  • 2.2 Node Aliases
  
  
  • 2.3 Message Handling by Target Node Type
  
  
  • 2.4 Implementing A Custom Node Handler
  
  


• 3 Authentication


• 4 Groups and Permissions


• 5 StartTLS Support


• 6 Configuration
  
  
  
  • 6.1 Older versions of Alfresco
  
  
  • 6.2 Inbound email service
  
  
  • 6.3 Email SMTP Server property values
    
    
    
    • 6.3.1 Allowed senders
    
    
    • 6.3.2 Blocked Senders
    
    
  
  


• 7 In process or external
  
  
  
  • 7.1 In-Process Email Server
  
  
  • 7.2 Remote Email Server
    
    
    
    • 7.2.1 Configuration
    
    
  
  
  • 7.3 Low Level configuration details
    
    
    
    • 7.3.1 Remote-email-service-context.xml
    
    
    • 7.3.2 Email-service-context.xml
    
    
  
  


• 8 Debugging

Introduction

Alfresco supports the ability to email content directly to specific nodes.   For example you can email documents into an alfresco folder.

This document will

• highlight the basic components that make this possible,
  
• give details of the types of behaviour that can be expected,
  
• describe the use of Group Permissions and
  
• describe the samples and how to start and test the email server.
  

This document assumes knowledge of how to extend the repository configuration.

How Email Messages are Handled

When sending an email to Alfresco's SMTP Email Server, the 'to' address is resolved to a node in the system in one of two ways.

Directly Referenced Nodes

If the sys:node-dbid is known, then the node can be addressed directly:

45634@alfresco.com
483@alfresco.com

You can enable the display of an object's DBID to make it easy to identify an object for email purposes.

Node Aliases

A much more convenient method of addressing nodes is by using an email alias (Email Alias aspect which contains the emailserver:alias property).  On a space or file, use the Run Action functionality to add the Email Alias aspect.  Edit the space or file's properties and give the node an email alias.  To set the email alias on the Space, do 'View Details' on the space, in the Properties section, if Email Alias is empty, click the edit on to top right - in line with Properties to provide the alias.
For example, the administrator may add a Space called Inbox to handle inbound emailed content.

Email Alias: Inbox

The Space can be addressed directly:

Inbox@alfresco.com

Notes:
-Aliases are case sensitive.
-The property value within alfresco does not include the '@alfresco.com' part.   So in the example above the Administrator adds 'Inbox' or 'Fred' as the alias.    Emails going to Inbox@alfresco.com and Fred@alfresco.com are delivered accordingly.

Message Handling by Target Node Type

The following table shows the default behaviours for an incoming email to different types of referenced node.  The behaviour can be modified or extended by adding in custom handlers:

Folder(Space)

The content is added with emailed aspect.

Forum(Discussion)

Content specialised to Post with emailed aspect; if email subject matches a topic, then add to topic, otherwise create new topic based on subject.

Topic(Post)

Content specialised to Post with emailed aspect; if referenced node is a Post, add to Post’s parent Topic.

Document(Content)

If discussion exists, same as for forums, otherwise add discussion with email as initial topic and post.

Implementing A Custom Node Handler

To implement your own handler, you'll need to implement org.alfresco.email.server.handler.EmailMessageHandler interface, or extend org.alfresco.email.server.handler.AbstractEmailMessageHandler.  The key method to implement is

  void processMessage(NodeRef nodeRef, EmailMessage message);

Then add the new handler to the Spring config by overriding the emailService bean from CONFIGROOT\emailserver\email-service-context.xml.  More specifically, you'll need to add it to the property emailMessageHandlerMap.  Here is a fragment: 

 <property name='emailMessageHandlerMap'>
  <map>
   <entry key='cm:folder'>
    <ref bean='folderEmailMessageHandler'></ref>
   </entry>
   <entry key='cm:content'>
    <ref bean='documentEmailMessageHandler'></ref>
   </entry>
  </map>
 </property>

Authentication

An experimental feature in Community 4.0 is authentication for SMTP.
If the user authenticates with the SMTP server then there is no need to match on the user's email address or check the EMAIL_CONTRIBUTORS group.

Authentication is turned on by setting the following property,

email.server.auth.enabled=true

The following SMTP authentication methods are implemented: PLAIN, LOGIN, PASSWORD

Groups and Permissions

An authentication group,  EMAIL_CONTRIBUTORS , must be created to allow  permissions to be handled  at a high level by the administrator.   By default the server creates  EMAIL_CONTRIBUTORS group and adds “admin' user to this group.

Only alfresco accounts that are contained by EMAIL_CONTRIBUTORS can email via SMTP.

As email arriving at the Alfresco email server is unauthenticated.  When an email comes into the system, the only identification is the sender's From email address.  The alfresco user is looked-up based on the email address.

• If a matching user is found then the current user is the matching alfresco user.
  
• If a matching user is not found, then the current user is set to the 'unknownUser' specified by the email.inbound.unknownUser property.
  
• If unknownUser doesn't exist in Alfresco, then the email is rejected as authentication will not be possible.
  
• If the user selected is not part of email contributor's group, then the email is rejected.
  
• If the user is part of email contributor's group then the email may be received.
  

The current request's user is set and all subsequent processes are run as the authenticated user.  If any type of authentication errors are generated, then the email is rejected.  The authentication will also imply that the authenticated user may not have visibility of the target node, in which case the email is also rejected.  Effectively, the target recipient of the email doesn't exist - at least not for the sender.

StartTLS Support

STARTTLS  is an extension to plain text communication protocols, which offers a way to upgrade a plain text connection to an encrypted TLS or  SSLconnection instead of using a separate port for encrypted communication.

You can configure whether the SMTP server reports that it supports TLS, whether TLS is enabled or whether TLS is required by setting one of the below properties to true.

email.server.hideTLS=false

email.server.enableTLS=true

email.server.requireTLS=false

For STARTTLS support to work for inbound email, you must configure SSL for Java. You can identify if you are having this problem by turning on DEBUG logging for the class 'org.subethamail' in your log4j.properties file.

startTLS() failed: no cipher suites in common

The following process outlines one methodology for creation of a self-signed certificate and is adapted from [http://stilius.net/java/java_ssl.php]. However this may differ between JVM vendors, so consult your JVM documentation for more information if required.

1. Create a suitable key and certificate:

keytool -genkey -keystore mySrvKeystore -keyalg RSA

2. Add the following somewhere in your Tomcat configuration. In RHEL 5 this file would be located at /etc/tomcat5/tomcat5.conf for example.

JAVA_OPTS='$JAVA_OPTS -Djavax.net.ssl.keyStore=mySrvKeystore -Djavax.net.ssl.keyStorePassword=123456'

Note: This methodology explains how to create a self-signed certificate only. SSL vendors can provide certificates signed by an authority and may be more suitable for production use.

Configuration

Alfresco versions 3.2+ are configured though alfresco-global.properties.

If the configuration of the subsystem needs to be overidden to add custom message handlers, then copy
InboundSMTP-context.xml to
<ext-config>/alfresco/extension/subsystems/email/InboundSMTP/inboundSMTP-context.xml

Older versions of Alfresco

custom-repository.properties The properties file can be modified to change the behaviour of the Email Server and Email Service.

<ext-config>/alfresco/extension/custom-email-server.properties

Inbound email service

The inbound email service deals with incomming email messages.

email.inbound.enabled=true

1. Enable/Disable the inbound email service.  The service could be used by processes other than
   

the Email Server (e.g. direct RMI access) so this flag is independent of the Email Service.

email.inbound.unknownUser=anonymous

1. The username to authenticate with when the sender address is not recognised in alfresco.
   

Email SMTP Server property values

The following properties are used to configured the inbound SMTP email server.

email.server.enabled=true : whether the inbound SMTP server is enabled or not true/false

email.server.port=25 : the tcp port number to listen on, normally 25 for a SMTP server.

email.server.domain=alfresco.com : the tcp hostname to bind the inbound SMTP service to.

email.server.connections.max=3: The maximum number of connections allowed.  Increase this number to favour the email subsystem at the expense of the rest of alfresco.

email.server.auth.enabled=true: Enable authentication for inbound SMTP.

email.server.hideTLS=false : On the EHLO command, Hide the fact that the server supports TLS,  TLS will still be accepted and work if the client uses TLS.

email.server.enableTLS=true : On the EHLO command, Announce the fact that the server supports TLS.

email.server.requireTLS=false : Require TLS authentication.

email.handler.folder.overwriteDuplicates=true hould duplicate messages to a folder overwrite each other or be named with a (number)

Allowed senders

A comma separated list of email REGEX patterns of allowed senders.
If there are any values in the list then all sender email addresses
must match.  For example:

  .*\@alfresco\.com, .*\@alfresco\.org

email.server.allowed.senders: list of patterns to allow.

Blocked Senders

A comma separated list of email REGEX patterns of blocked senders.  The list of blocked senders has priority over the allowed senders.

If the sender email address matches this then the message will be rejected.
For example:

  .*\@hotmail\.com, .*\@googlemail\.com

email.server.blocked.senders: list of patterns to block.

In process or external

There are two methods of running Alfresco SMTP email server.

In-Process Email Server

The  first is to run the Email Server process in the same JVM context as the  repository itself.   This is how practically everyone will run  alfresco.

EmailServerEmbedded.png

Remote Email Server

The  second is to run the Email Server remotely and have it communicate with  the repository over RMI. Note: details are not provided to  configure the proxy. This may need updating for 3.2.

EmailServerRMI.png

Configuration

To  enable the remote alfresco SMTP email server,  locate and unzip the  sample configuration in custom-email-server.sample.zip.  This will  provide two files; custom-email-server-context.xml and  custom-email-server.properties. 

custom-repository.properties The properties file can be modified to change the behaviour of the Email Server and Email Service.

<ext-config>/alfresco/extension/custom-email-server.properties

Note: Details are not provided to configure and start the remote proxy.

Low Level configuration details

The following sections are low level details that you should not need to touch.

The email service is configured via the email-service-context.xml file in the WEB-INF\classes\alfresco folder.
Email server is able to run on separate JVM and server interacts with Alfresco Server with the help of RMI system. RMI is configured with via remote-email-service-context.xml config file.

Remote-email-service-context.xml

The configuration file contains “emailService' bean which specifies the related RMI configuration:

<serviceUrl> </serviceUrl>

- Specifies the valid RMI Url.  Full description you can read at springframework site: http://www.springframework.org/docs/api/org/springframework/remoting/rmi/RmiProxyFactoryBean.html

<serviceInterface>

<beans>

   <bean id='remoteEmailServiceProperties' singleton='true'

  class='org.springframework.beans.factory.config.PropertyPlaceholderConfigurer'>

       <property name='ignoreUnresolvablePlaceholders'>
           <value>true</value>
       </property>
       <property name='locations'>
           <list>
               <value>classpath:alfresco/remote-email-service-test-context.properties</value>
           </list>
       </property>
   </bean>

   <bean id='emailServer' class='org.alfresco.email.server.impl.subetha.SubethaEmailServer'>
       <constructor-arg>
          <ref bean='emailServerConfiguration'/>
       </constructor-arg>
   </bean>

<bean id='emailServerConfiguration'
  class='org.alfresco.email.server.EmailServerConfiguration'>

  <property name='domain' value='alfresco.mycompany.com' />
  <property name='port' value='25' />

  <property name='enabled' value='true'/>

  <property name='blockedSenders'>
   <list>
    <value>*mail.ru</value>
   </list>
  </property>

  <property name='allowedSenders'>
   <list>
    <value>*alfresco.com</value>
   </list>
  </property>

  <property name='emailService'>
   <ref bean='emailService' />
  </property>
</bean>

   <bean id='emailService' class='org.springframework.remoting.rmi.RmiProxyFactoryBean'>
       <property name='serviceUrl'>
           <value>rmi://${email.service.remote.host}:${email.service.remote.port}/emailService</value>
       </property>
       <property name='serviceInterface'>
           <value>org.alfresco.service.cmr.email.EmailService</value>
       </property>
       <property name='refreshStubOnConnectFailure'>
           <value>true</value>
       </property>
   </bean>

</beans>

Email-service-context.xml

Configuration file defines spring beans. Properties of the bean with id = “emailServerConfiguration' contains values for email server configuration:

<domain> </domain>

- Specifies the domain e.g. alfresco.mycompany.com

<port> </port>

– Specifies the port that the email server listens for incoming connections on. Defaults to port 25. On some platforms ports below 1024 require the server to be run under a privileged account.

<blockedSenders></blockedSenders>

- Specifies the domains of  block list.

<allowedSenders>

<beans>

  <bean id='emailResourceBundles' class='org.alfresco.i18n.ResourceBundleBootstrapComponent'>
       <property name='resourceBundles'>
           <list>
               <value>alfresco.messages.email-service</value>
           </list>
       </property>
  </bean>

<bean class='org.springframework.remoting.rmi.RmiServiceExporter'>

       <property name='service'>
           <ref bean='emailService'/>
       </property>
       <property name='serviceInterface'>
           <value>org.alfresco.service.cmr.email.EmailService</value>
       </property>
       <property name='serviceName'>
           <value>emailService</value>
       </property>
       <property name='registryPort'>
           <value>${avm.remote.port}</value>
       </property>
   </bean>

<bean id='emailService' class='org.alfresco.email.server.EmailServiceImpl'>

  <property name='mailInboundEnabled'>
   <value>${mail.inbound.enabled}</value>
  </property>

  <property name='unknownUser' value='admin' />

  <property name='emailMessageHandlerMap'>
   <map>
    <entry key='folder'>
     <ref bean='folderEmailMessageHandler'></ref>
    </entry>
    <entry key='forum'>
     <ref bean='forumEmailMessageHandler'></ref>
    </entry>
    <entry key='discussion'>
     <ref bean='forumEmailMessageHandler'></ref>
    </entry>
    <entry key='topic'>
     <ref bean='topicEmailMessageHandler'></ref>
    </entry>
    <entry key='post'>
     <ref bean='topicEmailMessageHandler'></ref>
    </entry>
    <entry key='content'>
     <ref bean='documentEmailMessageHandler'></ref>
    </entry>
   </map>
  </property>

  <property name='nodeService'>
   <ref bean='nodeService' />
  </property>
  <property name='searchService'>
   <ref bean='searchService' />
  </property>

  <property name='retryingTransactionHelper'>
   <ref bean='retryingTransactionHelper' />
  </property>

</bean>

<bean id='emailServiceTransactionInterceptor'
  class='org.springframework.transaction.interceptor.TransactionInterceptor'>
  <property name='transactionManager'>
   <ref bean='transactionManager' />
  </property>
  <property name='transactionAttributes'>
   <props>
    <prop key='importMessage'>PROPAGATION_REQUIRED</prop>
   </props>
  </property>
</bean>

<bean id='folderEmailMessageHandler'
  parent='emailMessageHandlerBase'
  class='org.alfresco.email.server.handler.FolderEmailMessageHandler' />

<bean id='forumEmailMessageHandler'
  parent='emailMessageHandlerBase'
  class='org.alfresco.email.server.handler.ForumEmailMessageHandler' />

<bean id='documentEmailMessageHandler'
  parent='emailMessageHandlerBase'
  class='org.alfresco.email.server.handler.DocumentEmailMessageHandler' />

<bean id='topicEmailMessageHandler'
  parent='emailMessageHandlerBase'
  class='org.alfresco.email.server.handler.TopicEmailMessageHandler' />

<bean id='emailMessageHandlerBase' abstract='true'>
  <property name='authenticationService'>
   <ref bean='authenticationService' />
  </property>
  <property name='authenticationComponent'>
   <ref bean='authenticationComponent' />
  </property>
  <property name='nodeService'>
   <ref bean='nodeService' />
  </property>
  <property name='personService'>
   <ref bean='personService' />
  </property>
  <property name='searchService'>
   <ref bean='searchService' />
  </property>
  <property name='contentService'>
   <ref bean='contentService' />
  </property>
</bean>

<bean id='emailServerConfiguration'
  class='org.alfresco.email.server.EmailServerConfiguration'>

  <property name='domain' value='alfresco.mycompany.com' />
  <property name='port' value='25' />

  <property name='enabled' value='false'/>

  <property name='blockedSenders'>
   <list>
    <value>*mail.ru</value>
   </list>
  </property>

  <property name='allowedSenders'>
   <list>
    <value>*alfresco.com</value>
   </list>
  </property>

  <property name='emailService'>
   <ref bean='emailService' />
  </property>
</bean>

<bean id='alisableAspect'
  class='org.alfresco.email.server.AliasableAspect'
  init-method='initialise'>
  <property name='nodeService'>
   <ref bean='nodeService' />
  </property>
  <property name='searchService'>
   <ref bean='searchService' />
  </property>
  <property name='policyComponent'>
   <ref bean='policyComponent' />
  </property>
</bean>

</beans>

Debugging

The following log4j setting will help to log the inbound smtp connection.


log4j.logger.org.subethamail.smtp.server.ConnectionHandler=debug