Alfresco MTLS Configuration Deep Dive

cancel
Showing results for 
Search instead for 
Did you mean: 

Alfresco MTLS Configuration Deep Dive

Alfresco Employee
4 4 3,128

solr_certificates.png

 

When setting MTLS configuration between SOLR and Repository, some steps need to be done:

  1. Generate certificates for Repository (ssl.repo) and SOLR (ssl.repo.client) using a CA (alfresco.ca)
  2. Configure Tomcat Repository in order to manage incoming HTTPs requests from SOLR
  3. Configure Alfresco Repository WAR in order to build request to Jetty SOLR
  4. Configure Jetty SOLR in order to manage incoming HTTPs requests from Repository
  5. Configure SOLR WAR in order to build requests to Tomcat Repository

1. Generating certificates

Several certificates are required:

  • alfresco.ca is the public certificate of the CA used to generate ssl.repo and ssl.repo.client certificates
  • ssl.repo is the certificate (private and public) to be used for the Repository
  • ssl.repo.client is the certificate (private and public) to be used for SOLR

Keystore (private keys) and Truststore (public keys) files are required for the Repository and SOLR. Supported formats for these stores are JKS, JCEKS and PKCS12. The contents for every store are described below:

  • Repository Keystore (ssl.keystore) contains ssl.repo private key.
  • Repository Truststore (ssl.truststore) contains alfresco.ca and ssl.repo.client public keys.
  • SOLR Keystore (ssl.repo.client.keystore) contains ssl.repo.client private key.
  • SOLR Truststore (ssl.repo.client.truststore) contains alfresco.ca, ssl.repo and ssl.repo.client public keys.

These files can be generated manually but it's easier to use the Alfresco SSL Generator Tool.

2. Configuring Tomcat Repository

Tomcat Repository is handling secure tracking requests from SOLR WAR, so a new Tomcat Connector must be added to /usr/local/tomcat/conf/server.xml file.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
    connectionTimeout="20000"
    SSLEnabled="true" maxThreads="150" scheme="https"
    keystoreFile="/usr/local/tomcat/alf_data/keystore/ssl.keystore"
    keystorePass="kT9X6oe68t" keystoreType="JCEKS" secure="true"
    truststoreFile="/usr/local/tomcat/alf_data/keystore/ssl.truststore"
    truststorePass="kT9X6oe68t" truststoreType="JCEKS" clientAuth="want" sslProtocol="TLS">
</Connector>

3. Configuring Alfresco Repository WAR

Alfresco Repository WAR requires to be configured in order to build secure requests to Jetty SOLR when performing searching operations. Add following settings to /usr/local/tomcat/shared/classes/alfresco-global.properties file.

solr.port.ssl=8983
solr.secureComms=https

dir.keystore=/usr/local/tomcat/alf_data/keystore
encryption.ssl.keystore.type=JCEKS
encryption.ssl.truststore.type=JCEKS

Inside dir.keystore folder following files are required: ssl.keystore, ssl.truststore, ssl-keystore-password.properties, ssl-truststore-password.properties.

4. Configuring Jetty SOLR

Jetty SOLR is handling secure searching operations from the Repository. Following configuration is required to be added to SOLR starting script solr.in.sh (Linux) or solr.in.cmd (Windows) under folder /opt/alfresco-search-services/

SOLR_SSL_TRUST_STORE=/opt/alfresco-search-services/keystore/ssl.repo.client.truststore
SOLR_SSL_TRUST_STORE_PASSWORD=kT9X6oe68t
SOLR_SSL_TRUST_STORE_TYPE=JCEKS
SOLR_SSL_KEY_STORE=/opt/alfresco-search-services/keystore/ssl.repo.client.keystore
SOLR_SSL_KEY_STORE_PASSWORD=kT9X6oe68t
SOLR_SSL_KEY_STORE_TYPE=JCEKS
SOLR_SSL_NEED_CLIENT_AUTH=true
SOLR_OPTS="$SOLR_OPTS -Dsolr.allow.unsafe.resourceloading=true -Dsolr.ssl.checkPeerName=false -Dsolr.data.dir.root=$DIST_DIR/data -Dsolr.solr.model.dir=$DIST_DIR/data/alfrescoModels"

5. Configuring SOLR WAR

SOLR WAR requires to be configured in order to build secure requests to Tomcat Repository when performing tracking operations. Following lines must be added to both SOLR cores (alfresco and archive) in the following locations:

  • /opt/alfresco-search-services/solrhome/alfresco/conf/solrcore.properties
  • /opt/alfresco-search-services/solrhome/archive/conf/solrcore.properties
alfresco.secureComms=https
alfresco.port.ssl=8443

alfresco.encryption.ssl.truststore.location=/opt/alfresco-search-services/keystore/ssl.repo.client.truststore
alfresco.encryption.ssl.keystore.provider=JCEKS
alfresco.encryption.ssl.truststore.type=
alfresco.encryption.ssl.keystore.location=/opt/alfresco-search-services/keystore/ssl.repo.client.keystore
alfresco.encryption.ssl.truststore.provider=JCEKS
alfresco.encryption.ssl.truststore.passwordFileLocation=/opt/alfresco-search-services/keystore/ssl-truststore-passwords.properties
alfresco.encryption.ssl.keystore.type=
alfresco.encryption.ssl.keystore.passwordFileLocation=/opt/alfresco-search-services/keystore/ssl-keystore-passwords.properties

Troubleshooting

If you are experimenting problems when searching from Alfresco or Share web applications, check steps 3 and 4.

If you are experimenting problems when indexing / tracking from SOLR web applications, check steps 2 and 5.

About the Author
Angel Borroy is Senior Software Engineer in Alfresco. Over the last 15 years, he has been working as a software architect on Java, BPM, document management and electronic signatures. He has been working with Alfresco during the last years to customize several implementations in large organizations and to provide add-ons to the Community based on Record Management and Electronic Signature. He writes (sometimes) on his personal blog http://angelborroy.wordpress.com. He is (proud) member of the Order of the Bee. Angel Borroy is Engineer at Alfresco.
4 Comments
Member II

Angel,

We are deploying Alfresco ACS as an internal document repository within a larger solution. Can we deploy ACS without encrypted connections between SOLR and ACS ?

 

Rgs

Shaun

Alfresco Employee

Shaun,

Always that your security has been granted, you can use plain connections. But be aware of the risks and prevent the endpoints from being accessed by unwanted users.

Please, check also the following link to understand how to configure the system in a safe way.

https://hub.alfresco.com/t5/alfresco-content-services-blog/alfresco-6-1-is-coming-with-mutual-tls-au...

Partner

Hi @angelborroy,

When I update the keystore of Alfresco (generated with  Alfresco SSL Generator Tool ) I have this error

2020-08-12 19:04:47,590  ERROR [web.context.ContextLoader] [localhost-startStop-1] Context initialization failed
org.alfresco.error.AlfrescoRuntimeException: 07120001 Keystores are invalid
        at org.alfresco.encryption.EncryptionChecker$1.execute(EncryptionChecker.java:78)
        at org.alfresco.encryption.EncryptionChecker$1.execute(EncryptionChecker.java:1)
        at org.alfresco.repo.transaction.RetryingTransactionHelper.doInTransaction(RetryingTransactionHelper.java:450)
        at org.alfresco.repo.transaction.RetryingTransactionHelper.doInTransaction(RetryingTransactionHelper.java:319)
        at org.alfresco.encryption.EncryptionChecker.onBootstrap(EncryptionChecker.java:67)
        at org.springframework.extensions.surf.util.AbstractLifecycleBean.onApplicationEvent(AbstractLifecycleBean.java:56)
        at org.alfresco.repo.management.SafeApplicationEventMulticaster.multicastEventInternal(SafeApplicationEventMulticaster.java:221)
        at org.alfresco.repo.management.SafeApplicationEventMulticaster.multicastEvent(SafeApplicationEventMulticaster.java:186)
        at org.alfresco.repo.management.SafeApplicationEventMulticaster.multicastEvent(SafeApplicationEventMulticaster.java:206)
        at org.springframework.context.support.AbstractApplicationContext.publishEvent(AbstractApplicationContext.java:402)
        at org.springframework.context.support.AbstractApplicationContext.publishEvent(AbstractApplicationContext.java:359)
        at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:896)
        at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:552)
        at org.springframework.web.context.ContextLoader.configureAndRefreshWebApplicationContext(ContextLoader.java:401)
        at org.springframework.web.context.ContextLoader.initWebApplicationContext(ContextLoader.java:292)
        at org.springframework.web.context.ContextLoaderListener.contextInitialized(ContextLoaderListener.java:103)
        at org.alfresco.web.app.ContextLoaderListener.contextInitialized(ContextLoaderListener.java:70)
        at org.apache.catalina.core.StandardContext.listenerStart(StandardContext.java:4699)
        at org.apache.catalina.core.StandardContext.startInternal(StandardContext.java:5165)
        at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:150)
        at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:743)
        at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:719)
        at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:714)
        at org.apache.catalina.startup.HostConfig.deployWAR(HostConfig.java:970)
        at org.apache.catalina.startup.HostConfig$DeployWar.run(HostConfig.java:1841)
        at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
        at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
        at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
        at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
        at java.base/java.lang.Thread.run(Thread.java:834)
Caused by: org.alfresco.encryption.InvalidKeystoreException: The key with alias metadata has been changed, re-instate the previous keystore
        at org.alfresco.encryption.AlfrescoKeyStoreImpl.validateKeys(AlfrescoKeyStoreImpl.java:922)
        at org.alfresco.encryption.AlfrescoKeyStoreImpl.validateKeys(AlfrescoKeyStoreImpl.java:188)
        at org.alfresco.encryption.KeyStoreChecker.validateKeyStores(KeyStoreChecker.java:49)
        at org.alfresco.encryption.EncryptionChecker$1.execute(EncryptionChecker.java:73)
        ... 29 more


Do you know what I need to do in this case ?

Regards,
O.

Partner

Great article man,

I was struggling before to have a working configuration because some concepts were not so clear for me.

Just a small note (for me and people having the same issue):

I had to change from:
alfresco.encryption.ssl.truststore.provider=JCEKS
to:
alfresco.encryption.ssl.truststore.provider=SunJCE

and from:
alfresco.encryption.ssl.truststore.type=
to:
alfresco.encryption.ssl.truststore.type=JCEKS

and also the same thing for the keystore part.

Thanks again for your article :-)