Friday, July 26, 2013

Apache Syncope tutorial - part I

Apache Syncope is a new open source Identity Management project at Apache. This is the first of a planned four-part set of tutorials on how to get Apache Syncope up and running, how to integrate it with various backends, and how to interact with its REST API.

In this tutorial we will explain how to create a new Apache Syncope project and how to deploy it to a container. We will also cover how to set up internal storage with a database, and how to install Connector bundles to communicate with backend resources. Please note that if you wish to download and play around with Apache Syncope, without going through the steps detailed in this tutorial to set it up for a standalone deployment, it is possible to download the 1.1.3 distribution and use an embedded Tomcat instance. In that case you can completely skip this tutorial and go straight to the next one.

1) Set up a database for Internal Storage

The first step in setting up a standalone deployment of Apache Syncope is to decide what database to use for Internal Storage. Apache Syncope persists internal storage to a database via Apache OpenJPA. In this article we will set up MySQL, but see here for more information on using PostgreSQL, Oracle, etc. Install MySQL in $SQL_HOME and create a new user for Apache Syncope. We will create a new user "syncope_user" with password "syncope_pass". Start MySQL and create a new Syncope database:
  • Start: sudo $SQL_HOME/bin/mysqld_safe --user=mysql
  • Log on: $SQL_HOME/bin/mysql -u syncope_user -p
  • Create a Syncope database: create database syncope; 
2) Set up a container to host Apache Syncope

The next step is to figure out in what container to deploy Syncope to. In this demo we will use Apache Tomcat, but see here for more information about installing Syncope in other containers. Install Apache Tomcat to $CATALINA_HOME. Now we will add a datasource for internal storage in Tomcat's 'conf/context.xml'. When Syncope does not find a datasource called 'jdbc/syncopeDataSource', it will connect to internal storage by instantiating a new connection per request, which carries a performance penalty. Add the following to 'conf/context.xml':

<Resource name="jdbc/syncopeDataSource" auth="Container"
    testWhileIdle="true" testOnBorrow="true" testOnReturn="true"
    validationQuery="SELECT 1" validationInterval="30000"
    maxActive="50" minIdle="2" maxWait="10000" initialSize="2"
    removeAbandonedTimeout="20000" removeAbandoned="true"
    logAbandoned="true" suspectTimeout="20000"
    timeBetweenEvictionRunsMillis="5000" minEvictableIdleTimeMillis="5000"
    username="syncope_user" password="syncope_pass"

Uncomment the "<Manager pathname="" />" configuration in context.xml as well. Next, download the JDBC driver jar for MySQL and put it in Tomcat's 'lib' directory. As we will be configuring a connector for a Derby resource in a future tutorial, also download the JDBC driver jar for Apache Derby and put it in Tomcat's 'lib' directory as well.

3) Create a new Apache Syncope project

To create a new Apache Syncope project, we must start with a Maven Archetype. For the purposes of this tutorial we will use Apache Syncope 1.1.3. Create a new directory to hold all of the project artifacts ($SYNCOPE_HOME). Create a new project in this directory as follows:

mvn archetype:generate

Enter values as requested for the 'groupId', 'artifactId', 'version', 'package' and 'secretKey'. A new Syncope project will be created in a directory corresponding to the value entered for 'artifactId'. Build the project by going into the newly created directory and typing "mvn clean package". To launch Syncope in "embedded" mode, go into the "console" subdirectory and type "mvn -Pembedded". This provides a quick way to start up Syncope with some test data and connectors pre-installed, along with a H2 instance for internal storage. However, instead of doing this we will set up a proper standalone deployment.

4) Install ConnId bundles

Apache Syncope uses bundles supplied by the ConnId project to communicate with backend resources. In part III of this series of tutorials we will cover importing users from a database backend, and part IV will cover using a directory backend. Therefore, we need two ConnId bundles to handle these scenarios. Create two new directories in $SYNCOPE_HOME, one called "bundles" to store the ConnId bundles, and another called "logs" to store logging information. Go to the ConnId download page, and download the relevant jars to the bundles directory you have created. It should have the following files:
  • org.connid.bundles.ldap-1.3.6.jar
  • org.connid.bundles.db.table-2.1.5.jar.
5) Configure the Apache Syncope project

After creating the Apache Syncope project, we need to configure it to use the ConnId bundles we have downloaded, the logging directory we have created, and the MySQL instance for internal storage.

Edit 'core/src/main/resources/' in your Syncope project, and replace the existing configuration with the following:


Edit 'core/src/main/webapp/WEB-INF/web.xml' and uncomment the "resource-ref" section (this is required as we are using a DataSource in Tomcat). If your Tomcat instance is starting on a port other than 8080, edit 'console/src/main/resources/' and change the port number.

6) Deploy Apache Syncope to Tomcat

Package everything up by executing the following command from the Syncope project:

mvn clean package${bundles.dir}${log.dir}

Deploy 'core/target/syncope.war' and 'console/target/syncope-console.war' to the Tomcat 7 container. Start Tomcat and point a browser at "localhost:8080/syncope-console", logging in as "admin/password". You should see the following:

At this point you should have successfully deployed Apache Syncope in the Apache Tomcat container, using MySQL as the internal storage. If this is not the case then consult the Tomcat logs, as well as the Syncope logs in the directory you have configured. In the next couple of tutorials we will look at importing data into our Syncope application from various backend resources.


  1. Hi Colm O hEigeartaigh !

    I set up an embedded Apache Syncope.
    I can't Run this by Maven project.
    What version of Linux do I need for this tutorial?
    I want to use Apache Syncope in my project, but I do not know what way to connect Apache Syncope to my site.
    Thank you for this tutorial ....


  2. Please query the Syncope users mailing list about starting with Apache Syncope:


    1. Hi Colm,

      Its so nice to read your blog very helpful. I am working with Identity Management just want to know how can I use Syncope to implement ws-federation and single sign on?

    2. Hi
      Syncope doesn't Support WS-Federation and SSO. I've set up Apache Syncope combined with Apache CXF Fediz ( Syncope is used to manage the users in the user stores like LDAP, DB and Fediz IDP is used to authenticate users and provide SSO to your web applications. I'll blog in one or two weeks where I provide the Fediz IDP, Syncope and Apache DS as a Service in the cloud for demo purposes. Stay tuned...

    3. Can you please provide the url where you have integrated syncope with Fediz as we are not able to integrate fediz with Syncope.

  3. Hi Colm,

    Great blog and one of the few about apache syncope.
    We are running a syncope instance which was installed using the Talend Installer.
    We run into problems when we want to configure the connid bundles for ldap.
    It doesnot see any bundles when we try to create a new connector.
    We put the jar files in bundles directory and configured the file as follows:

    It looks like we miss something in the set up. Do you have any ideas?

    1. Hi fcweeber, please post your question to user mailing list (


  4. We followed the above steps but while going throug browser it is giving alert :

    Session expired: please login again.

    Would you tell us what could be the wrong??

    Thanks in advance

    1. Check the at syncope-console/WEB-INF/classes

      The host and port should match your Tomcat

    2. i don't see a file in syncope-console/WEB-INF/classes
      I am getting error
      Session expired: please login again.

    3. Try instead. If it doesn't work for you then please send a mail instead to the Syncope mailing list asking for help (


  5. Please ask your question to the Syncope users mailing list.


  6. This comment has been removed by a blog administrator.

  7. I know this is an older set of blog pages, but thank you very much for them. Very helpful!