About this repository

This repository contains a sample Java EE web application leveraging the SAML 2.0 Service Provider extension available since the upcoming Apache Syncope 2.0.3.

Once an Apache Syncope deployment - enabled with such extension - is properly configured, and the Syncope Core application is running, the Syncope Admin UI and the Syncope Enduser UI can be enabled to allow SAML-based SSO. The global result is that Admin UI and / or Enduser UI can be accessed after user authentication against (one of configured) SAML 2.0 Identity Provider(s).

The web application in this repository shows how to enable any third party Java EE web application to act like as the Syncope Admin UI and Enduser UI, e.g. to allow SAML-based SSO.

Preparation

Apache Syncope

First of all, an Apache Syncope deployment must be set up:

1. download the SNAPSHOT Standalone Distribution
2. put it at work
3. access http://localhost:9080/syncope-console and log in as admin / password

The procedure above is just the most straightforward to get quickly Apache Syncope up and running, provided with the required extension: for any production environment, it is strongly suggested to proceed with Maven project generation from archetype, instead.

Import SAML 2.0 Identity Provider metadata into Syncope

From Admin UI, go to Extensions > SAML 2.0 SP > Identity Providers and click on the + button on the lower right corner: you can then upload the metadata provided by your SAML 2.0 Identity Provider of choice. There are free ones available, as TestShib or SSOCircle, or you might want to try yourself with a Docker-ized SimpleSAMLPHP instance.

Now click on the pencil icon to finetune the IdP configuration. You can optionally change its label from the first screen, but the most important setting is revealed after hitting the Next button: you will need to define the mapping between internal users (e.g. users in Apache Syncope) and external users (e.g. users from the IdP); some sample values are reported below:

SAML 2.0 Identity Provider	Internal attribute	External attribute
TestShib	username	uid
SSOCircle	email	EmailAddress
Docker-ized SimpleSAMLPHP instance	email	email

Finally, be sure that users exist in Syncope matching the ones you are targeting from Identity Providers.

Java EE web application

Adjust the content of src/main/resources/saml2sp-agent.properties to match your actual Apache Syncope deployment, then

$ mvn tomcat7:run

At this point the web application is available at http://your.host.name:8080/syncopeSAML2SP/

Send metadata to the SAML 2.0 Identity Provider

Access http://your.host.name:8080/syncopeSAML2SP/saml2sp/metadata and an XML response will be shown.

Now hand off such XML content to your reference SAML 2.0 Identity Provider, as said above.

Please note that the actual URLs contained in the metadata will automatically adjust depending on the hostname referenced for access: within this regard, using localhost is discouraged in favor of FQDN as http://your.host.name:8080/syncopeSAML2SP/saml2sp/metadata

Run

1. Browse to http://your.host.name:8080/syncopeSAML2SP/saml2sp/login
2. You will be redirected to the selected IdP's login form
3. Log in with the provided credentials
4. You will be greeted by a similar page (this was obtained from TestShib after logging in as myself):

Exploit

The sample content shown above is the result of the default landing page being used in case of successful login. It proves that the SAML-based SSO went out fine, and that a valid JWT for further operations with Syncope Core is available.

To be effecive in real cases, however, some items should be addressed:

• configure the various landing pages to match your actual web application URLs - see this web.xml for reference:
  • saml2sp.login.success.url - which URL, related to the saml2sp/ path, the user should be redirect to, in case of successful login
  • saml2sp.login.error.url - which URL, related to the saml2sp/ path, the user should be redirect to, in case of login errors
  • saml2sp.logout.success.url - which URL, related to the saml2sp/ path, the user should be redirect to, in case of successful logout
  • saml2sp.logout.error.url - which URL, related to the saml2sp/ path, the user should be redirect to, in case of logout errors
• make the web application, after successful login, to fetch the JWT obtained at the end of the SAML exchange: it is stored in the saml2sp.jwt session attribute
• if the IdP of choice is supporting it, log out by browsing to http://your.host.name:8080/syncopeSAML2SP/saml2sp/logout