[Article] WSO2 Identity Server 5.1.0 Workflow Feature and Use Cases

  • By Lasitha Wattaladeniya
  • 2 Sep, 2015

Table of contents

  1. Introduction
  2. Applies To
  3. Deployment overview
  4. Steps to configure the workflow feature
  5. Use case
  6. Configurations to implement the use case
  7. Testing the workflow
  8. Workflow extensions
  9. Summary


Introducing the workflow feature to the WSO2 IS is required in order to add more control to the tasks that are executed in it. For example, with the workflow feature you can add another constraint to the ‘User Add’ operation in the identity server. These are workflows where the operations go through a predefined path. These types of tasks can be done through the WSO2 Business Process Server (WSO2 BPS) but this new feature adds that capability to the identity server as well. This article describes how it can be used in some use cases.

Applies to

WSO2 Identity Server 5.1.0 (yet to be released)
WSO2 Business Process Server 3.2.0

Deployment overview

From the identity server side, tasks can be aligned with a workflow and the real business process can be done in the BPEL engine. WSO2 Identity Server (WSO2 IS) supports any BPEL engine. In this use case we will be using WSO2 BPS.

The following is an overview of the setup. There is an identity server (WSO2 IS) that connects to a BPEL engine (WSO2 BPS) to perform the tasks. The user store should be shared across these servers.

Figure 01

Steps to configure the workflow feature

  1. Download WSO2 IS 5.1.0 and WSO2 BPS
  2. Since the IS and BPS need to run on the same machine, you need to change the running port of one of the servers. To do so open the file BPS_HOME/repository/conf/carbon.xml and change the <Offset> tag value to 1 (the default value is 0). The will run the BPS to on port 9444.
  3. Share the user stores. Since there is an embedded LDAP server in WSO2 IS, you need to configure the BPS to connect to the same LDAP server. Navigate to BPS_HOME/repository/conf/user-mgt.xml and uncomment the tag <!--UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">.
  4. Make sure to set the property value <Property name="ConnectionURL">ldap://localhost:10389</Property> correctly.
  5. Remove the existing user store configuration by commenting the <UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager"> tag.

Now the setup configuration is done.

Use case

Consider a company where new employees are added to the system by HR, post an approval process. For example, a senior HR manager has to approve new user additions. Once this is done, the user can login to the system and continue his work.

Configurations to implement the use case

The workflow will complete the user addition task once a user in a particular role approves the process.

Firstly, there should be a role created and a set of users assigned to it. These are the users that can approve the task. In this use case we will only allow users with the senior_hr_manager role to approve the user addition task.

  1. Create a senior_hr_manager role in WSO2 IS
  2. Give it login permission

    Figure 02

    Figure 03

  3. Create a user and add the senior_hr_manager role to him

    Figure 04

    Figure 05

    Now the workflow related configurations can be carried out since the server setup and the related users/roles have been created.

  4. Create a BPS profile. This is where you configure the identity server to connect to the BPS. You can have many BPSs configured in different profiles and use one of them when creating a workflow.

    To create a BPS profile click on Configure > BPS Profiles > Add. The window below will be displayed.

    Figure 06

    Following are the meanings of each of the above fields.

    Profile Name: A unique name to identify the profile

    BPS Host: The host URL of the BPS (e.g. https://localhost:9444)

    Username: The username that is used to authenticate the user at the BPS. The requests to the BPS will be sent as this user and they should have the permission to deploy and invoke BPELs and perform human tasks

    Password: The password of the user mentioned above

    Username to callback: The username that is to be authenticated at the IS when callback requests are made from the BPS. This user should have administrative permission

    Password of user to callback: The password of the above mentioned user

  5. Fill these fields as shown below.

    Profile Name: WSO2_BPS_1

    BPS Host: https://localhost:9444 (this will point to the already running WSO2 BPS)

    For BPS connection details and call back server connection details input admin, admin as the username and password.

    Figure 07

  6. Create a workflow with the BPS profile that we created earlier. Navigate to Main > Manage > Workflows > Add. You will land on the following page.

    Figure 08

  7. Fill the fields as shown below.

    Workflow Name: Senior_HR_Manager_Approval

    Workflow Description: One of the senior HR managers should approve the task

    Template: Simple Approval (there are only two templates in the WSO2 IS out of the box - Simple Approval and Deny Immediately)

    Figure 09

  8. Click next and enter the senior_hr_manager as the 'Role to Authorize the Request'

    Figure 10

  9. Click next
  10. Select the BPEL engine profile to be used. In this case there will be only one option to select since we created only one BPS profile. Also fill the 'Approval Request Subject' and 'Approval Request Body'. This will be included in the request sent to the senior HR manager role users.

    Figure 11

  11. Click finish to complete the task. Now you have successfully added a workflow to the system.
  12. Link this workflow with an identity server operation. To do so navigate to Main > Manage > Workflow Engagements > Add. The window below will be displayed.

    Figure 12

  13. Input a name for the engagement in the Engagement name field. By default, it supports only ‘User Store Operations’ as the Operation Category.
  14. Under that you have to select an operation where the workflow needs to be engaged. Operations such as 'Add User', 'Add Role', 'Delete User' and more are available. In this case we will select the 'Add User' operation.
  15. Under the 'Association details' section, you have to select the workflow that is to be engaged first. Since we only have one workflow, that will be displayed in the list. Select it.
  16. There are three other options that you can select while configuring when to apply the workflow engagement.

    Apply to all requests: The workflow will be triggered for all the requests of the selected operation.

    Apply if: Provides the ability to trigger the workflow only if a condition is satisfied (e.g. the workflow should be triggered only if the user is added to the primary user store when “Adding a User” but not for the secondary user store.). This section supports simple conditions. If the condition is complex where multiple conditions are evaluated with connectors (and/or), use the Advanced section.

    Advanced: Provide the support for advanced conditions. The condition needs to be given as an Xpath string.

    After configuring all the fields, it will look like the window below.

    Figure 13

Now that all the configurations are done, when you add a user it won’t be displayed under the users section immediately and the user won’t be able to login. The user will be enabled once the user addition task is approved by a user who has the role of senior_hr_manager.

Testing the workflow

To test the workflow, just login to the WSO2 IS with the admin user credentials. Create a user with the name bob. After you successfully create the user, it shouldn’t be displayed in the existing user list.

The dashboard for users with the senior_hr_manager role will display pending approvals. You can approve the pending tasks there after which the user should be able to behave the same way as a normal user.

Figure 14

Workflow extensions

The workflow comes with some advanced features such as

  • Multi-step approvals
  • User specific approvals
  • Multiple role based approvals

Currently only one role can be added in 'Role to authorize the request', but in advanced configurations one or more roles and users can be added.

Instead of a one step approval, there can be multiple steps to the approval flow. For example, a workflow with two step approval where in the first step 'Role to authorize the request' is hr_manager and in the second step 'Role to authorize the request' is senior_hr_manager. In this case , when a user is added to the system, only users with hr_manager role can initially see the pending approvals. After the users with this role approves the pending tasks, then the users with senior_hr_manager role can see the pending tasks. After both the users approve, the task is completed.


The workflow feature in WSO2 IS is very useful in the world of identity. With this new feature you can control the tasks you perform in the identity server to a higher degree.

About Author

  • Lasitha Wattaladeniya
  • Software Engineer
  • wso2