Custom authentication example

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Security definition > Work Portal Security > Work Portal Authentication > Advanced authentication > Custom Authentication >

Custom authentication example


Bizagi Work Portal supports multiple types of authentication.

By default, Bizagi projects will use a local authentication (having Bizagi store the users and their encrypted passwords).

Among other types of authentications, you may rely on integrated options such as Windows and LDAP authentication or use a combination of 2 authentication types in specific scenarios where both corporate users and external users will be working on processes.

For more information about Authentication options in Bizagi, refer to Authentication.


For sophisticated scenarios where the above options do not apply to your authentication system, you may use Custom authentication either by itself, or combined alongside with Bizagi's local authentication to handle both corporate and external users separately.




In this section we illustrate how to configure custom authentication by providing a step-by-step example.


What you need to do

In order to use Custom Authentication, follow these steps:


1. Create your component

Write your own code inside of a component (a class library) which will provide the function that authenticates against your own authentication system.

Note that this component can connect to any type of system that serving as your users repository (i.e, in a database, files, in the cloud and accessed through web services, etc).


2. Create your users in Bizagi

Make sure that the users that will be logging in to Bizagi, are previously created (or imported) in Bizagi.

This is a requisite for Bizagi to consider if a particular user is allowed in the Work Portal and so that you can also consider the number of licensed users by your Work Portal.

Creating users in Bizagi considers that each user will have its own username, domain, and further basic information, and it will belong to an organization defined in Bizagi.

Passwords are not needed since these will not be stored in Bizagi when authenticating against an external system.


3. Configure custom authentication in Bizagi

Set the use of custom authentication either by itself or combined alongside Bizagi's local authentication.

To configure custom authentication you will also need to:

Specify in Bizagi the namespace and class of your component.

Specify in Bizagi, the class library (assembly's physical name) that contains the above class.

Include that assembly in the Work Portal and any additional settings (e.g, web.config changes when your authentication is done through web services).



We will illustrate how to use custom authentication, in a scenario where our authentication system is actually a proprietary application which provides authentication through web services.

Therefore, we will configure in Bizagi that all users authenticate against this system.


For this example, a dummy web service is provided and accessed at:





Follow these steps to work out the example described above.


1. Create your component

Use Visual Studio to code a component which implements the functions described at Custom Authentication, which are:

bool authenticate(...), void logOff(...), bool changePassword(...), bool changePassword(...).

Make sure you create and build this project as a class library and make sure it runs targeted to the .NET 4.0 framework:




To invoke our authentication system's web service, we include a service reference to the service's URL:




We name this service reference as MyAuthenticationService as shown below:





Note that our service URL includes the wsdl file, and we can note this is a WCF service (.svc):




Then we include in our Class1.cs, the implementation for our authentication function which is bool authenticate(...) which invokes the service interpreted by the MyAuthenticationService reference:




Make sure you build this project without errors and that you produce a class library as output:




You may download the above implementation as a Visual Studio .sln solution here.

From the above project, we will need to capture and remember the following information for further configuration steps in Bizagi:

The class library physical assembly is CustomAuthenticationComponent.dll.

The class implementing these functions is called Class1.

The namespace of this class is CustomAuthenticationComponent.

The service model configuration, which is automatically included in the config (to be able to consume the WCF service) is:




2. Create your users in Bizagi

Before starting to use custom authentication, make sure your create (or import) in your Bizagi Work Portal, any users that will be logging into it.

Recall that this is a requisite for Bizagi to consider if a particular user is allowed in the Work Portal and so that you can also consider the number of licensed users by your Work Portal.


Create your users through the admin menu in the Work Portal:




Make sure you specify a unique username, and the user's domain.

Inputting passwords is not needed since these will not be stored in Bizagi when authenticating against an external system.


If you wish to test the sample code and dummy authentication system we have provided in this example, make sure you at least create one of the existing users in our authentication system database (such as ken0 or terri0 as shown below).

Notice that our dummy authentication system just takes the initial part of e-mails and disregards the @adventure-works part.




3. Configure custom authentication in Bizagi

Configure in your Bizagi project, the use of custom authentication.

To do this in Bizagi Studio, go into the Expert View and locate the Security module.


Click on the Authentication option found under the Security item, and select Custom authentication from the drop-down list in the panel to the right:




Click Update.

You will get a confirmation message and notice that 2 additional parameters appear under Authentication.


Configure Custom authentication class by entering the name of our namespace followed by the name of the class (CustomAuthenticationComponent.Class1):




Click Update.

Configure Custom authentication component by entering the name of the physical assembly (CustomAuthenticationComponent.dll):




Click Update.

Finally, take the physical CustomAuthenticationComponent.dll assembly and place it in your Work Portal's bin folder (by default at C:\Bizagi\Projects\[your_project]\WebApplication\bin\):





1. When your component invokes a WCF service, it is necessary that you edit Bizagi's web.config file in order to include the service model's definition of that service (include the binding and the endpoint).

To do this, copy the elements inside of <system.serviceModel> from the app.config produced in our Visual Studio project:


  <basicHttpBinding><binding name="BasicHttpBinding_MyService" /></basicHttpBinding>



  <endpoint address=""

  binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_MyService"

  contract="MyAuthenticationService.MyService" name="BasicHttpBinding_MyService" />


And paste them into the web.config file of your project (by default, at C:\Bizagi\Projects\[your_project]\WebApplication\).

This should go into the <system.serviceModel> definition, making the file finally look like the below:




2. After configuring custom authentication in Bizagi, you may need to perform an IISReset on your IIS services.


And that's it.

At this point, we have set the use of custom authentication in Bizagi.



To test and verify the custom authentication logging in the example above, launch the Work Portal and login by inputting the username of one of the users you created in step # 2.

For a successful login, the dummy authentication system just validates that you input that same username in as the password.


For example, for the Ken0 username, use Ken0 as a password:





1. Keep in mind that whenever your perform a deployment to a test or production environment, you will need to make sure that you place the physical .dll assembly in your Work Portal's bin folder as well, for that target environment.


2. Whenever you upgrade your project to a newer Bizagi version, make sure you also consider the physical CustomAuthenticationComponent.dll assembly.

Meaning, that after the upgrade, you will need to make sure it is place in your Work Portal's bin folder.

Recall that before a version upgrade, Bizagi creates an automatic backup of your bin folder (alongside other backups such as the database). Therefore, you may find the physical .dll assembly in that backup folder.