Thursday, November 13, 2014

Apache Syncope 1.2 tutorial - part IV

This is the fourth and final post in a series of articles on Apache Syncope 1.2. The previous tutorial looked at some new features relating to the Schema in Apache Syncope 1.2. This post will look at the REST API of Syncope and how it can be queried. We will also look at the new JAAS LoginModule for Apache Syncope that has been developed in Apache Karaf.

1) REST API of Apache Syncope

Apache Syncope features a rich REST API powered by Apache CXF. It is available via the URI "/syncope/rest/". Note that Apache Syncope 1.1 featured two REST APIs, one powered by Spring and another by Apache CXF, which was a refactoring of the former based on RESTful best practices. The Spring based API has been dropped in Apache Syncope 1.2, and only the CXF based API is now available via the "/syncope/rest" URI. Here are some example REST GET URIs for the "User" service in Syncope 1.2, that you can try out in a browser:
  • syncope/rest/users.json - get a list of all users in JSON format
  • syncope/rest/users - get a list of all users in an XML format
  • syncope/rest/users/self - get the authenticated user
Apache Syncope 1.2 uses the WADL generation capabilities of Apache CXF to expose the REST API as a WADL document. This can be accessed by adding "?_wadl" to the URI, for example "syncope/rest/?_wadl":


This document can be converted to HTML, and is available via the URI "/syncope/rest/doc/". Another new feature of the REST API in Apache Syncope 1.2 is support for FIQL. This allows you to easily search for users or roles matching a certain expression. For example:
  • syncope/rest/users/search?_s=lastLoginDate=ge=2014-11-13 - Search for the users who have logged in since 20014/11/13.
  • syncope/rest/users/search?_s=surname==smith - Search for the users with surname 'smith'.

2) JAAS LoginModule for Syncope

In a previous blog post written about the REST API of Apache Syncope, I gave detailed of a github project with some CXF based testcases. The tests showed how a CXF service could use Apache Syncope to authenticate a WS-Security UsernameToken presented by a client (as well as HTTP/BA). In addition, some other tests asked Syncope for the roles associated with the user, and enforced access to the service depending on the result. This github project has now moved to a new location here, and the tests have been updated to use the correct URLs for Apache Syncope 1.2.

In addition, a new test is added that shows how to use the new JAAS LoginModule for Syncope for authentication and authorization. The SyncopeLoginModule was developed for use in Apache Karaf, but can be used in others containers as well. In the testcase, the CXF JAASAuthenticationFeature is set on the service bus, which selects the "karaf" JAAS realm by default. The JAAS configuration file for the test is simply:

karaf {
    org.apache.karaf.jaas.modules.syncope.SyncopeLoginModule required
    debug="true"
    address="http://localhost:8080/syncope/rest";
};

See Jean-Baptiste Onofré's blog for a further description of how to set up and test the SyncopeLoginModule.

8 comments:

  1. Hi Colm, nice post series about Apache Syncope 1.2!

    Just an addition: the HTML view of WADL information is available at "http://host:port/syncope/rest/doc/" and also, for latest release, at http://syncope.apache.org/rest/1.2/index.html

    Bye

    ReplyDelete
  2. Thanks Francesco, I updated the blog.

    Colm.

    ReplyDelete
  3. Hi Colm,
    I need some clarification on SAML token based system. Does syncope core has any endpoints for authorization with SAML tokens??

    ReplyDelete
  4. This comment has been removed by the author.

    ReplyDelete
  5. Hi Colm,
    I am using syncope for IDM purpose and created a java client for integrating with syncope and was able to fetch all the users from syncope. But when I try to fetch a particular user using the below URL

    http://localhost:8080/syncope/rest/users/search?_s=surname==smith the response is getting as below:


    NullPointerException:
    500Unknown

    Am is using the right URL. Any help would be really useful to me.

    ReplyDelete
    Replies
    1. Sorry for the late reply. Yes that URL is correct. Are you using an old version of Syncope that doesn't support FIQL? What is the stacktrace in the logs?

      Delete
  6. Can I use the rest search api to search on derived attributes.

    ReplyDelete
  7. It's not possible: https://issues.apache.org/jira/browse/SYNCOPE-924

    ReplyDelete