[Article] Use Case: Building a Secure Identity Framework with WSO2 Identity Server

  • By Dimuthu Leelarathne
  • 6 Sep, 2016


An organization often deals with different types of identities, such as customers, partners, employees from subsidiaries, and even an open-source community in the case of tech companies. The task at hand is to be able to efficiently manage these multiple identities using a secure identity system. WSO2 too had these exact requirements, so we looked at designing and implementing a state-of-the-art, secure identity and access management (IAM) framework using WSO2 Identity Server (WSO2 IS). This use case will explain how we developed and implemented this framework and the benefits offered to the organization.

Key architecture goals and challenges

WSO2’s identity framework has progressively evolved over the past 10 years catering to varied requirements and adhering to best practices identified by the IT team. Prior to embarking on this project, WSO2 maintained all of its identities in a single LDAP. Most systems were connected to this for authentication and authorization purposes so users can utilize the same username/password in most systems; however, there was no single sign-on (SSO) between the systems.

Enforcing best practices for identity management and SSO - The overall objective of bringing in and leveraging the benefits of WSO2 IS was to adhere to best practices and minimize threats to WSO2’s identity infrastructure. An immediate benefit of the new IAM framework would be the introduction of SSO to all systems, i.e. employees will SSO into all authorized internal and external systems and external users will get access to all authorized external systems; this will be based on WSO2 IS.

Managing identity/application provisioning - WSO2’s Infrastructure Team is responsible for managing all identities in the WSO2 ecosystem. The team provisions user accounts, manages authorizations, de-provisions user accounts, and manages all identity-related configurations across all systems. The new system was aimed at centralizing employee identity management, thus making it easier to manage as well as provide transparency to external identity management infrastructure. Another key aspect of the framework was to develop a centralized provisioning application based on WSO2 IS.

Enforcing two-factor authentication - Two-factor authentication for Gmail and Google apps was another goal of the IAM framework. Email access needed to be highly secure and available as it is the main mode of communication within WSO2. This is a mission-critical system for internal staff. Some employees use multi-factor authentication provided by Gmail while some had saved their Gmail passwords in the browser that resulted in leaks. To avoid all of these problems there was a requirement to provide two-factor authentication for Google apps.

Managing open-source community’s identity - Another drawback of the previous architecture was that an open-source community member’s identity was bound to the user’s email address. If the user loses their email address, his/her identity changes, i.e. all of the JIRA activities would be wiped out. Using a UUID as a username in the LDAP will allow these open-source users to maintain the same identity even if they need to make changes to some attributes at any time.

Identity infrastructure prior to WSO2 IS deployment

Previously WSO2 maintained all of its identities in one single LDAP. Most systems were connected to this LDAP for authentication/authorization purposes. This LDAP was synced between different regions/networks whenever required by an application (Figure 1).

Figure 1: Identity infrastructure prior to deployment of WSO2 IS

Google apps and other cloud services, such as an HR system and ERP system, can have an LDAP being synced periodically. However, as per company policy, WSO2 LDAP passwords were not synced outside of the WSO2 Infra team’s control domain. Therefore, employees had to maintain passwords separately for Google apps and other cloud services. As a result, all cloud-based applications had their own credentials and this required employees to remember several passwords to access various enterprise systems.

Proposed solution architecture

Maintaining all identities in a single LDAP was identified as one of the main weak points in the previous architecture as it is a best practice to maintain two separate user stores for internal and external users.

Employee identity and external identity have different characteristics. Customer identity is distributed identity that can come from social networks and self-registered attributes and the control of that identity lies with the customer. The scale of customer identity can grow significantly and the focus is on individual and user experience driven by market needs, which leads to self-registration and self-maintained profiles. In the WSO2 ecosystem, external users include customers, partners, and the open-source community.

WSO2 employee identity lies with the organization; it has a central point of control as opposed to customer identity that belongs to the customer. Employee identity begins when a person joins an organization and ends upon termination of his/her employment contract. It is validated and verified identity.

Adhering to industry best practices, it was decided to maintain these two types of identities in two separate IAM frameworks. This could mean two credential stores and two identity servers, or one credential store and two identity servers. But we decided to keep the two identity programs completely separate, leading to the architecture depicted in Figure 2; this illustrates the two separate IdPs with two LDAPs for external and internal users.

Figure 2 - Proposed identity infrastructure with WSO2 IS

To achieve the above architecture, the current LDAP needed to be restructured. The employees will be on one LDAP and external users will be in a separate LDAP. Based on these two credential stores, there will be two separate WSO2 IS deployments.

  • All systems used by employees are configured as service providers in the internal IS
  • All external facing systems are configured as service providers in the external IS
  • How do employees now access the external facing system? This will be done with identity federation between the external and internal IS, using WSO2 IS identity bus capabilities. The external IdP will generate an outgoing authentication request to the internal IS whenever a login request is received by the employee (Figure 3).

Figure 3

The following table depicts WSO2’s application portfolio:

Application name Description Primary IdP User provisioning Role management Cloud/on-premise
AppM App portal of WSO2 Internal Prov app LDAP On-premise
Salesforce CRM of WSO2 Internal Manual Within app Public cloud
Concur Travel expense management Internal Manual Within app Public cloud
People HR HRM of WSO2 Internal Prov app Within app Public cloud
Google apps Business apps of WSO2 Internal Prov app Within app Public cloud
Redmine Feature management of WSO2 products Internal Prov app LDAP On-premise
Netsuite ERP of WSO2 Internal Prov app Within app Public cloud
Support portal Support client provisioning tool. Bespoke app. Internal Manual LDAP WSO2 cloud
PMT Patch management system. Bespoke app. Internal Prov app LDAP On-premise
Confluence Wiki hosting docs Internal Manual Within app On-premise
WiFi WiFi for WSO2 None Prov app LDAP On-premise
Internal SVN Code with fixes Internal Manual Within app On-premise
OT Jira Open source JIRA External JIT for external usersapp Within app
Support JIRA Online support system for clients External Support portal Within app On-premise
Certificate partner portal Bespoke apps External Manual Within app On-premise
wso2.com/Drupal wso2.com site External JIT for external users/app with roles Within app On-premise

In terms of the open source community, the code is another important aspect. The code is maintained in GitHub and the subscription package that is used by WSO2 does not allow identity integration.

Provisioning and access control

Applications require users to be provisioned and proper access control policies to be enforced. The application portfolio in WSO2 uses RBAC. Different applications require different roles and user groups for authorizations. In the previous architecture, user groups were created in LDAP as much as possible for different applications. Whenever it was not possible they were maintained within applications.

WSO2 IS has a comprehensive framework that allows provisioning users to other applications on user first login(JIT) and/or user addition (Figure 4). It can also provision users to its user stores as well, which is called inbound provisioning. The key requirement for the WSO2 use case was outbound provisioning. The plugin components that provision users are called provisioning adapters. Out-of-the-box provisioning adapters include SCIM, SPML, Google apps, and Salesforce.

Figure 4

Internal applications - Cloud-based systems provisioning can be done by writing adaptors to WSO2 IS, eliminating the need to do it manually. This is a best practice when it comes to provisioning users across different domains. It was decided to keep existing LDAP syncing infrastructure for all on-premise applications. For each internal application, user groups are defined as BUs and app groups.

External applications - Authorizations and provisioning to external applications require more work, as both external parties and employees are required to log in to the external applications. Employees have special permissions in the external applications, such as admin privileges, e.g. employees will be able to manage projects in a JIRA system while external users are only able to create tickets, comment, and resolve issues. User groups are created in the internal LDAP for employees and external LDAP for external users. Whenever an application is capable of handling more than one LDAP these are configured to the application and authorizations are configured properly. The WSO2 support portal is one such system where both groups are assigned.

Google apps and multi-factor authentication (MFA)

One of the goals of the new IAM framework was to provide MFA for Google apps. The first factor of authentication would be the username/password. The second factor of authentication is chosen as the SMSOTP. What happens if a person forgets his/her phone? One set of backup codes is given to be downloaded.

The WSO2 IS authentication framework has step authentication for MFA scenarios. There can be an infinite number of steps that are connected by “AND” operations and the authenticators within the step are connected by “OR” operations. For WSO2, the first step of the authentication is username/password and the second step is SMSOTP. If the user session has already done the first step then only the second step will be presented to the end user (Figure 5).

Figure 5

Profile updates

WSO2 employees will use the WSO2 IS dashboard to update their profiles. This allows them to manage their profile information including MFA preferences, such as add/modify FIDO (Fast IDentity Online) devices and download backup codes by visiting their profile. External users can update profiles by via the wso2.com website, which calls the SCIM APIs of the external IS to update the attribute values as shown in the Figure 2 architecture diagram.

Another primary objective of the architecture was to enable the open source community to change their email address and still retain the history of their open source activities. Let’s consider the open source community application hosted by WSO2 which is a JIRA. For the open source JIRA, UUID will be configured as the username. This allows the user to change their email address but retain the activity history.

Deployment architecture

There will be two identity server clusters - one for internal and the other for external. The internal identity server deployment is done in AWS in two availability zone (Figure 6). Each availability zone has 2 identity servers configured in active/active mode without state replication. At each layer, IP hashing is used to “session management”. It works well with the used protocol is SAML2.0.

Figure 6

The databases are synched in the following manner:

  • RegDB - RDS multizone syncing
  • User DB - RDS multizone syncing
  • Identity DB - Primary-secondary synching excluding the session table. The session table should not be synced as the session ID should not be overridden as the existing user sessions will be invalidated.

The external IS deployment will follow the same model.

Current status and outlook

As the first phase of the project, the internal identity server deployment has been completed. SSO is configured for all of the internal applications and Google apps MFA has been implemented as well. The team is now in the process of restructuring the LDAPs. The next steps of the project will be to deploy the external IdP and configure SSO for external applications.

Post successful implementation of Phase 1, all WSO2 employees log into their applications using WSO2 IS. It offers employees an efficient and hassle-free user experience, providing a one-click app store to all users (Figure 7).

Figure 7

In Phase 2, the external community of WSO2 will benefit by being able to have SSO between different systems and change all of their identity attributes including their email address.


Prior to this project, WSO2 maintained all identities in the same LDAP. As identified this is not a best practice and that was fixed by establishing two LDAPs with two IDPs. All the internal systems are now connected to a single LDAP and SSO is provided by WSO2 IS. Provisioning and account management will be made easy with the designed provisioning app. Once the external LDAP is set up, external parties such as the open-source community, partners and customers will also enjoy SSO and an identity that’s independent of its attributes.