Securing WSO2 ESB proxies with Kerberos - part 1 (WSO2 Identity Server as a KDC)

WSO2 Enterprise Service Bus proxies can be secured in various security mechanisms. There are around 20 out of the box security schemes that we can use to secure proxies. Kerberos is one of them. In this post and next we go through the setup and configuration of the Kerberos with two options.

• WSO2 Identity Server (IS) as Key Distribution Center (KDC)

• Active directory (AD) as the KDC

In this post we shall look into the first option and see how we can invoke a secured proxy using a Java client. This post is a supplementary to some awesome posts that WSO2 folks have written in the past. Notable posts are the [1], [2] and [3]. I wanted to write this post to show the steps in the latest (or recent) versions of the products. Some configurations and locations have been changed and I encountered few issues setting this up. So I wanted to compile them up in one location. Hope this would be helpful for anyone wanting to know how to use Kerberos security with WSO2 Enterprise Service Bus (ESB) for proxies, hence for SOAP calls. In the next post I'll show you how to use a Java and a .Net [Windows Communication Foundation (WCF) ] client to invoke a secured proxy.

I would like to thank Prabath for permitting me to copy and modify some of the code he used to demonstrate in his posts.

WSO2 Identity Server (IS) as the Key Distribution Center (KDC)

In this procedure we need to have WSO2 IS and WSO2 ESB setup in two server machines. (You may try this with the same server with two different port offsets for WSO2 IS and WSO2 ESB). It’s assumed that you have configured the two servers beyond this point. Look at ESB and IS documentation for reference at [4] and [5]. WSO2 IS can be used in a standalone mode (without any external database setup) for you to work on this.

In WSO2 IS (here we used IS version 5.0.0), let’s setup the KDC.

First we have to enable the KDC. Open embedded-ldap.xml and enable KDC as below.

  <KDCServer>
    <Property name="name">defaultKDC</Property>
    <Property name="enabled">true</Property>
    <Property name="protocol">UDP</Property>
    <Property name="host">localhost</Property>
    <Property name="port">${Ports.EmbeddedLDAP.KDCServerPort}</Property>
    <Property name="maximumTicketLifeTime">8640000</Property>
    <Property name="maximumRenewableLifeTime">604800000</Property>
    <Property name="preAuthenticationTimeStampEnabled">false</Property>
  </KDCServer> 

If you want to change the default realm of the KDC, change the “realm” property. By default it’s WSO2.ORG. We’ll keep it as it’s in this case for simplicity.

<Property name="realm">WSO2.ORG</Property>

We can also enable the KDC setting in the user-mgt.xml. Enable the following property in the UserStoreManager.

<Property name="kdcEnabled">true</Property>

Create a file named jaas.conf with following contents and place inside <IS_HOME>/repository/conf/security directory.

Server {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=false
storeKey=true
useTicketCache=false
isInitiator=false;
};

Client {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=false;
};

Create a file name krb5.conf with following contents and place it in <IS_HOME>/repository/conf/security directory. This says your KDC locates in the current machine.

[libdefaults]
        default_realm = WSO2.ORG
        default_tkt_enctypes = rc4-hmac des-cbc-md5
        default_tgs_enctypes = rc4-hmac des-cbc-md5
        dns_lookup_kdc = true
        dns_lookup_realm = false

[realms]
        WSO2.ORG = {
            kdc = 127.0.0.1
   }

Now let’s start the WSO2 IS Server.

Once started the server, we have to create a Service Principal (SPN) and a client principal to use with kerberos ticket granting system (TGS). Once the server is started, navigate to Configure -> Kerberos KDC -> Service Principals and click “Add new Service Principal”. Provide a service principal name, description and a password. In this case we used the following service principal name.

SPN Name : esb/localhost@WSO2.ORG

Now create a new user by navigating to Configure -> Users and Roles -> Users -> Add User.

In our case I have added a user name “test” with a password. This will be the client principal.

That’s all with WSO2 IS KDC configuration.

Let’s now configure security in a sample proxy in WSO2 ESB (We used WSO2 ESB 4.8.1). In my case I’ve secured the default echo proxy. You may do the same for any other proxy.

Configuring ESB for kerberos.

Add the following into jass.conf file and place it in <ESB_HOME>/repository/conf/security directory. Note the principal name configuration

Server {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=false
storeKey=true
useTicketCache=true
isInitiator=false
principal="esb/localhost@WSO2.ORG";
};

Add the following to the krb5.conf and place it in in <ESB_HOME>/repository/conf/security directory. Configure the ip address of the WSO2 IS in kdc section. If the WSO2 IS is running in the same server as WSO2 ESB, this is the loop back address 127.0.0.1, which is the case in my scenario. Remember to use all caps for the default_realm.

[libdefaults]
        default_realm = WSO2.ORG
        default_tgs_enctypes = des-cbc-md5
        default_tkt_enctypes = des-cbc-md5
        permitted_enctypes = des-cbc-md5
        allow_weak_crypto = true

[realms]
        WSO2.ORG = {
                kdc = 127.0.0.1:8000
        }

[domain_realm]
        .wso2.ORG = WSO2.ORG
        wso2.ORG = WSO2.ORG

[login]
        krb4_convert = true
        krb4_get_tickets = false

Start the ESB server and navigate to the proxy list.

Click the echo proxy to navigate into the dashboard

Click the security button

Select ‘yes’ in the security section

Select the kerberos security mechanism (Item number 16) and click next

Provide the SPN name you configured in the WSO2 IS together with its password and click Finish

Now you can try invoking the echo proxy using soap ui and it should fail saying “security header does not found”. This is because the request didn’t contain any security information, such as the kerberos ticket etc. In fact it’s difficult to create a soap ui project to work with kerberos, as the specification requires a format for the soap request, such as signing the message payload from kerberos ticket, having a time stamp and so on.

We have written a java client to cater this (Thanks Prabath, once again for permitting me to use and modify your client). Clients need to incorporate same mechanism to call a kerberos secured proxy in the Java code. Please find the client here. We shall discuss about a .Net client in the next post.

Open this project in IntelliJIDEA or your favorite IDE.

Navigate to the config.properties and configure the keyStorePath, keyStorePassword, axis2ClientPath, policyFilePath and servicEndpoint according to your setup. We are using the default keystore in this setup and the configuration is like the following.

# Kerberos configs
keyStorePath=/home/shazni/ProjectFiles/kerberosJavaClient/repo/resources/wso2carbon.jks
keyStorePassword=wso2carbon
axis2ClientPath=/home/shazni/ProjectFiles/kerberosJavaClient/repo/conf/client.axis2.xml
policyFilePath=/home/shazni/ProjectFiles/kerberosJavaClient/repo/conf/policy.xml
serviceEndpoint=https://localhost:9448/services/KerberosTestReg

Note my ESB run on port offset of 5 hence the port 9448.

Next, open up the policy.xml file and make the rampart configuration changes for client.principal.name, client.principal.password (This should be the user you created in the WSO2 IS), service.principal.name, java.security.krb5.conf, java.security.auth.login.config and javax.security.auth.useSubjectCredsOnly. In my case it’s like the following.

<rampart:RampartConfig xmlns:rampart="http://ws.apache.org/rampart/policy">        

      <rampart:timestampPrecisionInMilliseconds>true</rampart:timestampPrecisionInMilliseconds>
      <rampart:timestampTTL>300</rampart:timestampTTL>
      <rampart:timestampMaxSkew>300</rampart:timestampMaxSkew>
      <rampart:timestampStrict>false</rampart:timestampStrict>
      <rampart:nonceLifeTime>300</rampart:nonceLifeTime>

      <rampart:kerberosConfig>
           <rampart:property name="client.principal.name">test_carbon.super</rampart:property>
           <rampart:property name="client.principal.password">test123</rampart:property>
           <rampart:property name="service.principal.name">esb/localhost@WSO2.ORG</rampart:property>
           <rampart:property name="java.security.krb5.conf">repo/conf/krb5.conf</rampart:property>
           <rampart:property name="java.security.auth.login.config">repo/conf/jaas.conf</rampart:property>
           <rampart:property name="javax.security.auth.useSubjectCredsOnly">true</rampart:property>
      </rampart:kerberosConfig>

    </rampart:RampartConfig>

Also open up the krb5.conf file located in the client code and configure your kdc ip address. In this case the ip address of the WSO2 IS server.

Now if you run the client you should see the response of the echo service. You should see an output like the following in the console.

Calling service with parameter - Hello Shazni!!!!!!!
Request = <p:echoString xmlns:p="http://echo.services.core.carbon.wso2.org"><in>Hello Shazni!!!!!!!</in></p:echoString>
The response is : <ns:echoStringResponse xmlns:ns="http://echo.services.core.carbon.wso2.org"><return>Hello Shazni!!!!!

This client contacts the WSO2 IS KDC to get a kerberos ticket and then uses the rampart library to build the request as compliant to the WS-Security specification and send the request to the proxy. At the ESB server end, the rampart resolves the request and wss4j validates the ticket by decryption and validating the signature of the request payload and call the backend service, if those validation passes. Subsequently gets the response and sign it back with the kerberos key and send the response back, once again in compliance with the WS-Security.

That's all the configurations you got to do. This is a very simple example on how to use keberos security scheme in WSO2 ESB with WSO2 IS.

In the next post I'll show how to configure the ESB with AD based KDC (specifically with a keyTab file, instead of using the SPN and it's password as used in this post)

[1] http://wso2.com/library/articles/2012/07/kerberos-authentication-using-wso2-products/
[2] http://blog.facilelogin.com/2010/12/kerberos-authentication-with-wso2-esb.html
[3] https://malalanayake.wordpress.com/2012/12/13/how-to-invoke-the-echo-service-secured-by-kerberos-in-wso2-esb/
[4] https://docs.wso2.com/display/ESB490/WSO2+Enterprise+Service+Bus+Documentation
[5] https://docs.wso2.com/display/IS510/WSO2+Identity+Server+Documentation

Unleashing the Git - part 6 - git branching

Branching is a function to launch separate, similar copy of the present workspace for different usage requirements. It's a line of development which exists independent of another, where both share a commom history.

Let's understand branching related commands with an example.

$ git init        // Execute on a preferred location

Add a file list.txt and add the following content

abc
123
def
456

then,

$ git add .
$ git add -m "Initial commit of list.txt"
$ git checkout -b mybranch  // Create a new branch called mybranch with exact level of master.
$ git checkout -b 64868c9   // Create a new branch called mybranch from the point of the given commit id

Above is equivalent to following two commands.

$ git branch mybranch
$ git checkout mybranch
$ git branch   // Shows available branches with the current branch with an *. Now you'll be in mybranch
$ git branch -r // Shows only remote branches.
$ git branch -a // Shows all available branches
$ git branch --merged // Shows all branches merges into the current branch
$ git branch --no-merged // Shows available branches that are not merged with the current branch
$ git branch --contains <commit id> // Shows the branch that contains the commit id

Now suppose you openned list.txt and modified it by adding a new line, making it

abc
123
def
456
ghi

$ git add .
$ git commit -m "Adding a new line in the mybranch"
$ git checkout master  // Switch back to master. Now list.txt won't have your new line

$ git merge mybranch  // merges mybranch with the master branch. This would succeed as there was no conflict in lines. We just added a new line, so git would have no problem in merging. Updating 53a7908..3fd44bc Fast-forward  list.txt | 1 +  1 file changed, 1 insertion(+) Also git automatically commit while merging. If you do not want the commit to happen, you can use the following command.

$ git merge --no-commit master

// Now in the master branch remove the first line and commit it. Then switch to mybranch and open list.txt. You would still see the initial first line we removed in the master. Now modify that line in mybranch to change it to xyz from abc and commit it. Say now you want to merge the files in this branch from master. Issue the following command.

$ git merge master
Auto-merging list.txt
CONFLICT (content): Merge conflict in list.txt
Automatic merge failed; fix conflicts and then commit the result.

There will be a conflict as both branches have modified the first line.

// Now if you try to switch to master, you won't be allowed until you fix the conflicts.

$ git checkout master
list.txt: needs merge
error: you need to resolve your current index first

Now open the list.txt in mybranch. You would see following.

<<<<<<< HEAD
xyz
=======
>>>>>>> master
123
def
456
ghi

What does this say? HEAD is pointing to your current branch. i.e. mybranch. Whatever you have between <<<<<<< HEAD to ======= is the the contents of the mybranch offending to the conflict. i.e. your xyz modification. Whatever between ======= and >>>>>>> master is what master has for the offending conflict. In this case it's empty meaning there's an empty line.

Now you may decide to keep the xyz change and commit it. What needs to exist, what needs to remove is all up to you. You may even choose remove both. So once you switch to master branch, you won't see the line. Issue the following command in master branch.

$ git merge mybranch
Updating a64cb6d..87fd36d
Fast-forward
 list.txt | 1 +
 1 file changed, 1 insertion(+) 

Now you should see the xyz line in the master branch as well.

Following are few additional commands that is are useful.

$ git merge --log development // Adding a one line log message from each merge commit to the merge message
$ git merge --no-ff development // Force creation of a merge commit
$ git merge -m "Forced commit message that from the merging branch" mybranch

You can use git commit --amend to modify the commit message after the fact too. Here’s an example:

$ git merge --log --no-ff development
$ git commit --amend -c HEAD  // Editor launches
$ git branch -d mybranch  // Deletes the mybranch. If there are unmerged files, git will warn you about it.
$ git branch -D mybranch // Git doesn't warn you about unmerged files. It just deletes the branch
$ git push origin :beta // Remove a remote origin's branch named beta

$ git push <remote name> <branch name>
$ git push origin master:production  // Push changes from local master branch to remote origin's production branch
$ git push --force or git push -f   // To push changes even  if you don't have ceratin changes from the remote. Warning: Use this with extreme caution because it can cause others to get

out of sync with the repository to which you are pushing.

As an alternative to 'git pull', we can also use 'git fetch' followed by 'git merge @{u}'

Some more useful commands

$ git checkout -b <branch> --track <remote>/<branch> // Checkout a remote branch to your local filesystem
$ git pull <remote name> <remote branch>   // Pulls changes from the <remote branch> of <remote name> into the current local branch
$ git pull <remote name> <remote branch>:<local branch> // Pulls changes from the <remote branch> of <remote name> into the <local branch>
    // e.g: git pull origin development:team-dev
$ git pull --rebase origin master // rebasing the current locak branch on top of remote origin's master branch

Unleashing the Git - part 5 - git stashing

More often than not, there can be situations where you have done some changes and you need to temporarily hide those from the working tree since those changes are not completely ready yet. Stashing comes into play in such situations. May be when you have done some changes in a branch and you want to switch to another branch without committing your changes in the current branch. Stash is the easiest option for that.

Say you have changed some files. Issuing the git status would show what has changed.

$ git stash // Temporarily hide your changes. Now issue git status. You won't see the modifications. Equivalent to $ git stash save
$ git stash save --patch // Opens the text editor to choose what portion to stash
$ git stash apply // Apply the last stashed change and keep the stash in stack. But this is normally not done. Instead following is done
$ git stash pop // Apply the last stashed change and remove it from stack
$ git stash list // Shows available stashes.

Stashes have name in the format of stash@{#} where # is 0 for most recent one and 1 for the second recent and so on.

$ git stash drop <stash name>   // e.g: git stash drop stash@{0} to remove the first stash
$ git stash clear // Remove all the stashed changes
$ git stash branch <stash name>  // Create a branch from an existing stash

In the next part of this series we'll discuss git branching in detail.

Unleashing the Git - part 4 - Git Tagging

Tagging comes very handy in managing a repository. Tags and branches are similar concepts. But tags are read only. There are two types of tags. 1) Lightweight 2) Annotated

$ git tag Basic_Features    // Creates a Basic_Features tag.
$ git tag            // Shows available tags
Basic_Features
$ git show Basic_Features   // Which show the details of the commit on which Basic_Feature tag is added
$ git tag beta1 HEAD^ // Creates a tag from next to last commit

Earlier I showed how to check out code with commit id. We can also use the tags to checkout code of a particular stage using the following command.

$ git checkout Basic_Feature

All of the above are lightweight/unannotated tag. Creating an annotated tag is as simple as creating lightweight tag as below,

$ git tag -a Basic_Messaging_Annotated -m "Annotated tag at Messaging"
$ git show Basic_Messaging_Annotated   // this will provide the details of the tagger as well.

Deleting a tag is same for both tag types.

$ git tag -d Basic_Messaging_Annotated  // Deletes the annotated tag we created.
$ git push origin v1.0 // Push local tag v1.0 to remote origin.
$ git push --tags origin // Push all the local tags to remote origin
$ git fetch --tags origin // fetches all the remote origins tags to local repository. Note: If you have a local tag with same name as a remote tag, it'll be overwritten

Unleashing the Git - part 3 - Working with remote repositories

More often we need to share the files that we modify and make it available for other users. This is typically the case in Software development projects, where several people work on a set of files and all needs to modify and do changes. The solution is to have the repository in a centralised place and each and every one work with there own copies before they commit it to the central place. There are many online git repository providers. Examples are GitHub, BitBucket etc.

Choose, whatever best suites for you and sign up for an account. Most online repositories provide free accounts. I've a created a one in bitbucket and have created a repository named online_workbench.

$ git remote add origin https://shazni@bitbucket.org/shazni/online_workbench.git  // Syntax is git remote add <name> <repository URL>
$ git remote rm <name> // To remove a remote from your local repository
$ git push -u origin master
Password for 'https://shazni@bitbucket.org':
Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 88.01 KiB, done.
Total 4 (delta 0), reused 0 (delta 0)
To https://shazni@bitbucket.org/shazni/online_workbench.git
 * [new branch]      master -> master

Branch master set up to track remote branch master from origin.

After you entered your password, you'll have your repository online and its local location is your local $HOME/example directory.

'git push -u origin master' is to make the git aware, that all the pull and push operations to default to the master branch. If in case '-u origin master' is not specified, each and every time you issue a 'pull' or 'push' command, you will have to specify the origin.

Ok.. Now if someone needs to get a local copy and work on this remote repository, what he/she needs to do? Only few steps are involved.

First we need to clone the repository into a directory. Navigate or create a new directory where you need the local clone of the repository and issue the following command.

$ git clone <remote repository location> <Path you want the clone to be>

If you omit the <Path you want the clone to be>, it will be in the current directory.

Depending on how the firewall on your computer or local area network (LAN) is configured, you might get an error trying to clone a remote repository over the network. Git uses SSH by default to transfer changes
over the network, but it also uses the Git protocol (signified by having git:// at the beginning of the URI) on port 9418. Check with your local network administrator to make sure communication on ports 22—the port SSH communicates on—and 9418 are open if you have trouble communicating with a remote repository.

$ git clone --depth 50 <remote repository location>  // Create a shallow clone with the last fifty commits

Then, if we do the modification to the files or added files, next we need to stage it for commits. Issue the following commands.

$ git add *            // Stages and add all your changes, This is similar to git add -A 
// If you specify git add -u will only previously added and updated files will be staged. -p parameter will present you with sections so that you are given option to include a change or not.
$ git commit –m 'My commit comment'     // Commit the changes to the local repository
$ git pull        // checks whether there are any unsinced updates in the remote location and if exist syncs local and the server
$ git push        // Add the changes made by you to the server

Building boost C++ library

Boost is a well written portable C++ source library. It's a very popular and flexible library set to use in you C++ applications. It has a huge set of libraries spanning across many utilities and uses. Good thing about Boost is that, the libraries available in Boost are either already available in C++ standard or likely to end up in it one day. Note however, not all libraries are accepted. Nevertheless, all the libraries are proven and well tested.

Download the latest boost library from http://www.boost.org/

In this short guide I'll walk you through the process to easily build boost for you to generate the header and library files for you to use in your C++ application.

Once you download the boost, extract it into a directory. Navigate into the extracted directory and issue the following commands. Make sure you have a C++ compiler available in your system (e.g: g++ in GNU/Linux). Look here (which is a generic post, however) to see how to install C/C++ compilers.

$ ./bootstrap.sh --prefix=path/to/installation/prefix

$ ./b2 install

Depending on your system tools, you may not have all the libraries built. For example, if you do not have python dev packages installed, boost python library won't build. But this won't stop building other libraries.

You are done!!! You should be able to find two directories inside the directory you specified in the PREFIX; namely includes and libs. These contain header files and .so (or .dll in Windows) shared library files to link in your C++ application.

WSO2 Microservices Framework for Java (MSF4J) 1.0.0 is released

WSO2 is pleased to announce that it has released the very first version 1.0.0 of the WSO2 Microservices Framework for Java (MSF4J). You can get more details from the following location.

[1] http://wso2.com/products/microservices-framework-for-java/

It gives you a lightweight fast runtime together with an annotation based programming model to create your micro services. Browse the following location for a quick start guide.

[2] https://docs.wso2.com/display/MSF4J100/Quick+Start+Guide

Enjoy creating your microservices!!!