Wednesday, December 15, 2010

Installing multi-tenancy support for WSO2 Identity Server

Multi-tenancy is a characteristic of a cloud native platform. WSO2 stratos provides multi-tenancy. In brief, multi-tenancy is to have one instance but customizable service for each tenant isolated from one another. If you want to know more about multi-tenancy, visit which has many resources for learning.

Thanks to the modularity of OSGI; tenant management specific components in WSO2-stratos could be installed in WSO2-carbon based products-Identity Server in this case, and provide it with the multi-tenancy support.

In this blog post, I will explain how I could install multi-tenancy support in WSO2 Identity Server.
  1. Get the Identity Server (IS) binary distribution. Either building from source or downloading binaries from here.
  2. Get the stratos-tenant management specific bundles. We can either build from the source or extract them from the binary packages. Lets go for the latter option here for the convinience. Get the Stratos released packages of from here. Download wso2stratos-manager and wso2stratos-is.
  3. Place following components from the above two packages, into Identity Server-home/repository/ components/dropins:
    • org.wso2.stratos.tenant.mgt-1.0.0.jar
    • org.wso2.stratos.tenant.mgt.ui-1.0.0.jar
    • kaptcha-2.3.0.wso2v1.jar ---these three components will install tenant management feature. But we need other components as well, in getting it fully functioning.
    • org.wso2.stratos.account.mgt.ui-1.0.0.jar
    • org.wso2.stratos.account.mgt-1.0.0.jar ---these two are related to tenant's account management.
    • ---these three will handle notifying tenant admin and e-mail verification after a tenant is registered.
    • org.wso2.stratos.register.ui-1.0.0.jar ---is needed to show the registration complete page after e-mail verification. (Also, it is the ui component which is used in self-tenant registration.)
    • org.wso2.stratos.identity.dashboard.ui-1.0.0.jar
    • org.wso2.stratos.identity.login.ui-1.0.0.jar ---Identity Server's UI s are replaced by these.
    • org.wso2.stratos.redirector.servlet.ui-1.0.0.jar
    • org.wso2.stratos.redirector.servlet-1.0.0.jar ---each tenant will get a url with /t/domain name. In order to handle that redirection, these two are needed.
    • ---services are activated for tenants from stratos-manager. IS and G-Reg services are activated by default.
    • org.wso2.stratos.common-1.0.0.jar
    • org.wso2.stratos.activation-1.0.0.jar
    • org.wso2.stratos.service.activation-1.0.0.jar
    • org.wso2.stratos.theme.mgt.ui-1.0.0.jar
    • org.wso2.stratos.theme.mgt-1.0.0.jar ---These handles tenant's theme management, you also need to copy stratos/services/manager/distribution/resources/allThemes to IS/resources.
            4.  Change the following in configuration files:
    • add following two properties to the UserStoreManager element of user-mgt.xml in IS home/repository/conf folder:
    • false
    • Change the carbon.xml in IS home/repository/conf to contain “WSO2 Stratos Identity” as the product name. This is because, in activating default identity service, service name is given as “WSO2 Stratos Identity”, And when checking whether a service is activated for a particular tenant, the service name is read from the carbon.xml. 
    • Give smtp server information in smtp transport sender section of axis2.xml, found in IS home/repository/conf, in order to actually send e-mail notifications upon registration of tenants by the super admin.
        5.  Copy the following configuration files from stratos-manager home/repository/conf to IS-home/repository/conf:
    • cloud-services-desc.xml
    • email-registration.xml
    • email-registration-complete.xml
    • email-update.xml
That's we are done. Start IS-->log in as super admin with "admin", "admin" credentials and create tenants. Tenant admins of those tenants will be able to log in to their tenants and create users and use other functionalities provided by IS independent of other tenants registered.

I will add some screenshots to illustrate the installed multi-tenancy support in IS stand alone product.
As shown circled in the left panel of following image, multi-tenancy feature is installed in IS.

Following image shows the list of sample tenants accounts that I created for testing purposes of the functionality.

Following image shows the console of IS when user 'hasini' of tenant: '' has signed into the IS. Notice the url circled with the part '../t/' which is specific to that particular tenant.

When multi-tenancy/tenant management feature is installed in IS, either JDBC or embedded-ldap user-store could be used. I will explain in a future post how to configure it to use tenant aware-embedded-ldap as the user store in tenant management.


  1. We are using IS version 3.2.
    Do you think your instructions are still ok for this?

    Also, if we want to use our own JDBC store and do not need ability to create tenants (just to use the ones we already have and will continue to create using our application) do we still need Stratos components or there is a way to just configure Carbom?

  2. Hi,

    For your requirements, you do not have to follow this post.

    And of course, any WSO2 product is shipped to be used out of the box in stand alone mode. Default user store is an embedded ApacheDS LDAP.
    You can download the IS pack, extract it and configure 'user-mgt.xml' file inside [IS_Home]/repository/conf to connect to your existing JDBC based user store and run the IS server.
    You will be able to manage users/roles through the management console of Identity Server.
    You also can connect to your user store in read-only mode if you wish to.

    Hope this helps.

  3. Hi,

    If we want to connect two JDBC based store in the Identity Server, How to configure 'user-mgt.xml' or how can we do this? I try to modify 'user-mgt.xml' , but I only got one connection...


  4. You can connect only one user store at a time.

  5. I am trying to do this with IS 3.2.3 and the files for stratos are no longer named as mentioned in this article. What are the new names for the jar files?

  6. The one file I can not find a match for in the current version is


    what is the new name on this one?

  7. I am sorry, this post applies to IS 3.0.1 and Stratos 1.0.

    Tenant Management feature will be available as a separately installable feature through carbon feature manager - from next release (Carbon 4.0) onwards.
    So that you do not have to copy jars like this separately.

    However, there is a IS 3.2.2 pack with tenant management features installed from Stratos 1.5.2 which can be downloaded from

  8. Thank you. This is what I needed. I have been able to get this to saml sso into another instance of wso2 stratos identity server on the same machine using external ldap as user store.

    The only problem i now have is that attempting to login with tenant admin using username like gives a warning like that below and failure to login.

    TID: [0] [WSO2 Stratos Manager] [2012-04-24 16:34:51,817] WARN {org.wso2.carbon.identity.sso.saml.processors.AuthnRequestProcessor} - Issuer details are not valid. Issuer details should be registered in advance {org.wso2.carbon.identity.sso.saml.processors.AuthnRequestProcessor}

    Do you know what this problem could be?

  9. Hi Timothy,

    First of all, I am not clear why do you have two instances -
    one Standalone IS with multi tenancy features installed - and another Stratos Identity Server...

    However, the above error is due to not having some configurations..

    To get SAML SSO work between two WSO2 carbon servers, you need to do some configurations both at SAML SSO IdP end and consumer end.

    At the consumer end, you need to edit "authenticators.xml" to add ServiceProviderID and IdentityProviderSSOServiceURL.

    Then in Identity Provider side - which is Stratos Identity Server in your case, you need to go to: Configure → SAML SSO menu to access the SAML 2 IdP configuration page.

    There you need to provide details of the trusted service provider:
    Issuer - which is the ServiceProviderID you gave in authenticators.xml above.
    Assertion Consumer URL - https://:/acs
    Check "Enable Assertion Signing" & "Enable Single Logout".

    Let me know if you find any issues.. If you can let me know the exact use case you are trying to implement, I might be able to provide more insight..


  10. Hasini,
    Thanks. That did work.

  11. Hasini,
    I have one other question. When I click the Configure->Account menu item I view a blank page.
    The logs show the following:

    Exception occurred while trying to invoke service method getCustomerWithName

    Do you know what this could be?

    I suspect some configuration issue.

  12. Hasini,
    I figured out my problem. I had an incorrect billing-config.xml . Thanks for this great article and the help you gave.

  13. Hi Thimothy,

    Great that you figured it out.
    Let me know if you have any further queries...
    BTW.. What is the use case that you are using WSO2 Identity Server for?



Note: Only a member of this blog may post a comment.