Saturday, July 30, 2016

Securing WSO2 ESB proxies with Kerberos - part 2 (Active directory (AD) as the KDC)

In a previous post, we looked at how to secure a WSO2 ESB proxy services using kerberos in which  Key Distribution Center (KDC) is the WSO2 identity server. In this post we'll look at securing WSO2 ESB proxy services when the KDC is the Active Directory (AD).

When the Key Distribution Center (KDC) is the Active Directory (AD), the SPN is usually attached with a service account. Contact your Windows Administrators to create an SPN and a service account and generate a key tab file against that. The main difference from WSO2 IS and AD based KDC is that, in AD the SPN doesn’t provide a text password, rather it’s in the keyTab file.

To create an SPN for a related service account, use the following command.
setspn -s HTTP/ us\us-wso2esb
setspn -s HTTP/USESB us\us-wso2esb
Change the SPN and service account accordingly.

Ask the administrators to create the keytab using the following command.
ktpass /out wso2.keytab /princ HTTP/USESB@YOUR.DOMAIN.COM /mapuser us\us-wso2esb /pass password /crypto All /ptype KRB5_NT_PRINCIPAL

This will create a keyTab file named wso2.keytab

Get the keytab file and place it in a location accessible by the WSO2 ESB.

In our case the KDC hostname is The ESB configuration is same as like the previous case. But make the following changes in the krb5.conf


        default_realm = US.YOUR.DOMAIN.COM
        default_tgs_enctypes = rc4-hmac des-cbc-crc des-cbc-md5 aes256-sha1 aes128-aha1
        default_tkt_enctypes = rc4-hmac des-cbc-crc des-cbc-md5 aes256-sha1 aes128-aha1
        permitted_enctypes = rc4-hmac des-cbc-crc des-cbc-md5 aes256-sha1 aes128-aha1
        allow_weak_crypto = true 

                US.YOUR.DOMAIN.COM = {
                        kdc =
                        default_domain = US.YOUR.DOMAIN.COM


        krb4_convert = true
        krb4_get_tickets = false
Have the jaas.conf contents be like the below.
Server { required
Note the useKeyTab and the keyTab property, which is different from the WSO2 IS as a KDC scenario. Provide the path of the keyTab file location to the keyTab parameter.

Next when you secure the proxy, you have to provide the SPN name as the AD configured SPN. In our case the SPN is HTTP/USESB@US.YOUR.DOMAIN.COM

Also note since you have no password for the SPN, you can provide the service account password which was created at the AD end. In fact that won’t be used in this case, since the password will get resolved from the keyTab file. Once the proxy is secured, we need to do one more change for Java 7. Go to the proxy dashboard and click Policies. In both, Binding echoSoap11Binding and Binding echoSoap12Binding policies add the following line below the service principal name.
<rampart:property name="kdc.ticket.decoder">org.wso2.carbon.krb.Java7.TicketDecoder</rampart:property>

This is required to be added due to a bug that was identified in the implementation and require a patch from WSO2. If you are a support customer of WSO2, you may open a support ticket to request the patch WSO2-CARBON-PATCH-4.2.0-1811.
If you are not a support customer, you can run the ESB using JRE 1.6.

That’s it in ESB end.

When you start the server, start the ESB with the following system property,

./ /carbon/wso2/esb/wso2esb-4.8.1/repository/resources/security/krb5.conf start

You may insert that property in the file as well.

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 WS-Security spec demands a format for the soap request, such as signing the message payload from kerberos ticket and so on.

We have written a java client to cater this. Clients need to incorporate same mechanism to call a kerberos secured proxy. Please find the Java client here.

Note: however the Java client should be running in a machine where it can connect to the AD based KDC.

Testing with a Java client

Change the krb5.conf of the java client as the following in the java client.
        default_realm = US.YOUR.DOMAIN.COM
        default_tgs_enctypes = rc4-hmac
        default_tkt_enctypes = rc4-hmac
        permitted_enctypes = rc4-hmac
        allow_weak_crypto = true

         kdc =
Note the KDC ip address. Change accordingly. Also change the to match the windows server.
serviceEndpoint=https://<ip-address or domain name>:9443/services/echo
If you are using a custom keystore, use that keystore path and password instead.

The rampart configuration of policy should be changed. Client principal name in this case would be the logged in user. In our case we have the following configurations.
<rampart:RampartConfig xmlns:rampart="">


    <rampart:property name="">smohamednazeer@US.YOUR.DOMAIN.COM</rampart:property    <rampart:property name="client.principal.password">xxxxxxxxxxxx</rampart:property>
    <rampart:property name="">HTTP/USESB@US.YOUR.DOMAIN.COM</rampart:property>
    <rampart:property name="">C:\Users\smohamednazeer\Documents\codes\kerberospocsolution\kerberosJavaClient\repo\conf\krb5.conf</rampart:property>
    <rampart:property name="">C:\Users\smohamednazeer\Documents\codes\kerberospocsolution\kerberosJavaClient\repo\conf\jaas.conf</rampart:property>
    <rampart:property name="">true</rampart:property>
    <rampart:property name="kdc.ticket.decoder">org.wso2.carbon.krb.Java7.TicketDecoder</rampart:property>

Enter the username you use to login to Windows machine as the, or you have to enter a username that exists in your AD. Enter the password that you use to login to the Windows machine for the client.principal.password, or enter the password of the respective AD user.

Note the Java7.TicketDecoder property, if you are running the ESB in Java 7 (Note: To use with Java 7, you'll need to have above mentioned patch applied in the ESB 4.8.1 and ESB 4.9.0) If you are running in Java 6, you may remove that line.

If your server is using a custom keystore (which is normally the case), following needs to be done.

1.  Use the same keystore, its alias and password of primary keystore for RegistryKeyStore. This is due to a known issue in the system (see [1]). This will get fixed in the future releases.


2.  Change the of the Java client to use the new keystore and the password

To build this project you have to point the project to the plugins directory of the WSO2 ESB 4.8.1. You may copy the plugins directory somewhere else and point the project to that and build. If you are running the server in Java 7, make sure the plugins directory also contain the patched jars of the above mentioned issue; wss4j, rampart and TicketDecoder.

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=""><in>Hello Shazni!!!!!!!</in></p:echoString>

The response is : <ns:echoStringResponse xmlns:ns=""><return>Hello Shazni!!!!!!!</return></ns:echoStringResponse>

Testing with a Windows Communication Foundation (WCF) client

The WCF client used to test the echo proxy is located here.

The WCF client creates a form with a button, when clicked it calls the echo proxy. Open App.Config in the Visual Studio.
      <endpoint address="http://<ip address or domain name>:8280/services/echo" behaviorConfiguration=""
        binding="customBinding" bindingConfiguration="customTextMessageEncoding"
          <servicePrincipalName value="HTTP/USESB@US.YOUR.DOMAIN.COM" />
Note the endpoint address and the servicePrincipalName.

The client executable is located in EchoWcfClientServiceVisualStudio\EchoClient\bin\Debug

If the executable is not found, you’ll have to build the project in Visual Studio.

Either run the executable or run the client within Visual Studio. This should bring up a form. Click the echo button. The response should be shown in the message box.

You might have noticed that we used the http address. If you want to use the https endpoint for SSL, you have to add the following element in the app.config.
<httpsTransport authenticationScheme="Anonymous" bypassProxyOnLocal="false"
           hostNameComparisonMode="StrongWildcard" proxyAuthenticationScheme="Anonymous"
           realm="" useDefaultWebProxy="true" />
instead of the following http binding,
<httpTransport authenticationScheme="Anonymous" bypassProxyOnLocal="false" 
hostNameComparisonMode="StrongWildcard" proxyAuthenticationScheme="Anonymous" 
realm="" useDefaultWebProxy="true" />
And when you run the WCF client in the Windows machine, you would get an SSL error if you haven’t imported the ESB servers' primary keystore’s certificate to the Windows trusted certificates. Assuming you have generated your keystores and exported the certificate out of it, follow the steps here to import the certificate file to the Windows server.

Once the certificates are imported, you should be able to call the proxy with the https endpoint.

Tuesday, July 26, 2016

Importing a certificate in Windows

In Windows start menu,
  • open the run window and type “mmc” (without quotes). This will open a console window. 
  • Click File -> Add/Remove Snap-in. 
  • Click “Certficates” and click Add. 
  • Select “Computer account” and click next. 
  • Click Finish. 
  • Click certificates and click ok. 
  • Click “Certificates (Local Computer)”
  • Click “Trusted RootCertification Authorities” and then certificates
 his should show all the trusted certificates of the system. Assuming that you have the certificate with you in .cer format. To import the certificate,
  • Right click Certificates of the Trusted Root Certification Authorities in the left pane and All Tasks -> Import
  • Click next and browse your certificate file in the file system and complete the import

Saturday, July 23, 2016

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.
    <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>
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 { required

Client { required

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.

        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

        WSO2.ORG = {
            kdc =

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 { required
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, which is the case in my scenario. Remember to use all caps for the default_realm.

        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

        WSO2.ORG = {
                kdc =

        .wso2.ORG = WSO2.ORG
        wso2.ORG = WSO2.ORG

        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 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
    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.password (This should be the user you created in the WSO2 IS),,, and In my case it’s like the following.

    <rampart:RampartConfig xmlns:rampart="">        
               <rampart:property name="">test_carbon.super</rampart:property>
               <rampart:property name="client.principal.password">test123</rampart:property>
               <rampart:property name="">esb/localhost@WSO2.ORG</rampart:property>
               <rampart:property name="">repo/conf/krb5.conf</rampart:property>
               <rampart:property name="">repo/conf/jaas.conf</rampart:property>
               <rampart:property name="">true</rampart:property>

    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=""><in>Hello Shazni!!!!!!!</in></p:echoString>
    The response is : <ns:echoStringResponse xmlns:ns=""><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)


    Tuesday, July 5, 2016

    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


    $ 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

    $ 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
    >>>>>>> master
    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
     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