Skip to main content

Integrate OAuth 2.0 / OpenID Connect with Flowable Control

Target audience: Developer

Introduction

For all Flowable products (Work, Design, Control, etc.) Spring Boot Starter dependencies exist to customize them. One typical customization that is often required is to integrate Single-Sign On (SSO).

This How-To describes how you can use the Flowable Control Application with OAuth 2.0 / OpenID Connect. The principles shown here can be also used to do other security configurations.

note

This integration is also available out-of-the-box for the Flowable Control application provided by Flowable. The same properties explained here are also valid for the out-of-the-box application.

Additionally, this How-To is an example that is meant as an inspiration when met with similar requirements. Custom code isn't covered by standard Flowable Support.

Project Setup

To customize the Flowable Control application we first need to setup a project. This can be based on a start.spring.io project which can then be enhanced with the Flowable dependencies. Your project should include in addition to that a driver of a supported database.

Once you created the project you can add the Flowable Control dependency:

<dependency>
<groupId>com.flowable.control</groupId>
<artifactId>flowable-spring-boot-starter-control</artifactId>
<version>${com.flowable.control.version}</version>
</dependency>

You also need to add your database configuration to the application.properties as well as some required default properties:

flowable.control.app.security.encryption.credentials-i-v-spec=j8kd02hejA9lKmm6
flowable.control.app.security.encryption.credentials-secret-spec=9FGl73ngxcOoJvmL
flowable.control.app.cluster-config.name=Default Cluster
flowable.control.app.cluster-config.user-name=admin
flowable.control.app.cluster-config.password=test
flowable.control.app.cluster-config.server-address=http://localhost
flowable.control.app.cluster-config.port=8080
flowable.control.app.cluster-config.context-root=/

Once this is done, you can start the Spring Boot app, and you will have Flowable Control running with the context root /flowable-control on your defined port.

In the example above you can open localhost:8080/flowable-control/, and sign-in with the username admin and the password test.

It expects a running Flowable Work on port 8080 (as shown in the configuration properties).

Authenticating with OAuth 2.0 / OpenID Connect

Our Flowable Control application can now be enhanced with the security configuration of our choice.

In this tutorial we are integrating with an OAuth 2.0 server, which can be for example Keycloak, Okta, Azure AD etc.

Alternatively, but not covered in this tutorial, you can do a SAML integration similarly.

Azure SSO Setup

For this example integration we are going to use Azure SSO.

The first thing we need to do before starting with the Flowable Project setup is to make sure that we have an Azure Active Directory instance. If you don't have one then we suggest following the Create Azure Active Directory instance guide from Azure.

However, most likely you have one Azure Active Directory for your company. We will head to https://portal.azure.com/ and navigate to it. Next step is going to be to create our Application Registrations. The steps for that are explained here in the Azure documentation. Make sure that you store the generated key somewhere, we will need it for configuring our application.

note

Granting admin consent for your example might not be possible if you are using your main directory. However, this is not a problem for our configuration.

You can skip the last step (selecting implicit grant and hybrid flows), because we are not going to use the Azure AD Spring Boot Starters.

In addition to the steps explained above we need to add some more configurations in order to simplify our integration with Flowable:

  1. Go back to the "Authentication" section and change the "Redirect URIs" to "http://localhost:8080/login/oauth2/code/azure" Change Authentication Redirect URIs
note

You need to use the URI where Flowable Control is running. Make sure that this does not clash with Flowable Work

Required Dependencies

The first step of the configuration is to add the needed dependencies to our project to have OAuth 2.0 Spring modules:

<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-jose</artifactId>
</dependency>

The first dependency is the Spring OAuth 2.0 client itself, while the second one is for Javascript Object Signing and Encryption (jose), which allows parsing of a JWT token.

Configuration Properties

As a next step need to integrate with our OAuth 2.0 provider.

The configuration here is specific to the Azure SSO. However, the general structure is normally the same for all providers.

In the example below the following replacements are needed:

  • <name> - This can be any string you want. e.g. azure
  • <client-id> - The id of the client which we created at the beginning. This can be seen in the overview of the application.
  • <client-secret> - The secret of the client which we created at the beginning
  • <tenant-id> - The tenant id of the Azure AD. This can be seen in the overview of the application.
spring.security.oauth2.client.registration.<name>.client-id=<client-id>
spring.security.oauth2.client.registration.<name>.client-secret=<client-secret>
spring.security.oauth2.client.registration.<name>.scope=openid,profile,email
spring.security.oauth2.client.registration.<name>.authorization-grant-type=authorization_code
spring.security.oauth2.client.provider.<name>.issuer-uri=https://login.microsoftonline.com/<tenant-id>/v2.0
spring.security.oauth2.client.provider.<name>.user-name-attribute=email

This will hook up Spring with our OAuth 2.0 provider, in a next step we need to configure that our OAuth 2.0 token is required. Therefore, we still require some Java code to customize our security configuration.

Security Configuration

Flowable offers an out of the box SecurityConfiguration which is used by default and can configure HTTP Basic or OAuth2 login for Flowable. In order to enable OAuth2 we need to set the following properties:

# Setting this will tell Flowable Control to use oauth2 for logging into it
flowable.control.app.security.type=oauth2

# The authorities from the OAuth2 token that should mark the user logging in as an admin user
flowable.control.app.security.oauth2.admin-authorities=
flowable.control.app.security.oauth2.authorities-attributes=roles
flowable.control.app.security.oauth2.tenant-attribute=
flowable.control.app.security.oauth2.privilege-role-authority-prefix=
flowable.control.app.security.oauth2.username-attribute=
flowable.control.app.roles.default-user-role=
flowable.control.app.roles.default-admin-role=

The flowable.control.app.security.oauth2.admin-authorities can be used to mark user logging in as an Admin user in Flowable Control. A user will also be marked as an Admin user in Flowable Control if it has the access-admin role given by the SSO Provider. Azure SSO can be configured in such a way that different users can get specific roles for a particular application.

note

flowable.control.app.security.oauth2.privilege-role-authority-prefix, flowable.control.app.security.oauth2.username-attribute, flowable.control.app.roles.default-user-role and flowable.control.app.roles.default-user-role will be further looked at later in this how-to.

In case you are not using an OpenID Connect OAuth2 SSO you can configure the attributes that contain the current user information.

flowable.control.app.security.oauth2.current-user.first-name-attribute=given_name
flowable.control.app.security.oauth2.current-user.last-name-attribute=family_name
flowable.control.app.security.oauth2.current-user.display-name-attribute=name
flowable.control.app.security.oauth2.current-user.email-attribute=email

We can now start the application and head to the Control endpoint. We will be greeted by the Azure SSO login. Once you sign in you will be redirected to the Flowable Control UI.

In the next section we are going ot explain how you can grant the user admin permissions.

Configuration Flowable Permissions

Currently Flowable distinguishes 2 types of users:

  • Admin
  • Non-Admin

Configure Admin Users

Control Admin users are allowed to add new Cluster Configurations, change Cluster Configurations, perform destructive operations (e.g. terminate a Process instance). In order to make a user an admin, first we are going to add the access-admin role in our Azure application.

The value of the role needs to be access-admin.

Once we have this role created we need to assign it to our user or even groups. To do this we need to go to the "Enterprise Applications" section of our Active Directory. Azure Enterprise Applications

Once we are there we will head to "All Applications" and search for the application we created at the beginning. We've named it "Flowable Azure SSO Demo".

Find Demo Application in Azure Active Directory

We now select the application and head to "Assign Users and Groups"

Assign Users and Groups

There we select and edit our user

Select User for Assignment

And assign the default user role to the user

Assign Role to User

Finally, after these steps we can head to our application, and we will see that the user now has Admin privileges, i.e. the user can edit the cluster configuration.

Configure User permissions

With the introduction of roles and privileges in Flowable Control the possibilities to grant access to users increased drastically. To grant privileges to users, the built-in SecurityConfiguration provides different solutions.

Granting Flowable Control roles

The flowable.control.app.security.privilege-role-authority-prefix can be used to map authorities to Flowable Control roles. To activate that mapping, we need to provide the prefix for role authorities.

flowable.control.app.security.privilege-role-authority-prefix=FLW-CONTROL-ROLE-

Create a role in Azure. Use the prefix FLW-CONTROL-ROLE- followed by the actual role name AccessProcess. Assign the Azure user to the Role FLW-CONTROL-ROLE-AccessProcess

Assign create Azure role

Create the Flowable Control role AccessProcess.

Control role

note

Check out the Control user guide for role management for a detailed guide.

Add the Access Process privilege to the role and close the dialog with a click on save Assign create Azure role

note

See the control privileges list for more details

Finally, you can log in with your Azure account and the user Control role

Assigning user to Flowable Control roles

You can assign the Azure user directly to roles in Flowable Control. Set the flowable.control.app.security.oauth2.username-attribute property and Flowable Control checks the assigned users for all existing roles. The defined privileges are applied accordingly.

Create a role in Flowable Control. In this example, we add the Delete Instance privilege.

Assign create Azure role

Assign the Azure user to the Control role

Assign create Azure role

note

Check out the Control user guide for role management for detailed information.

At last, one additional property is required.

flowable.control.app.security.oauth2.username-attribute=email

The email attribute is provided by Azure. We add the property flowable.control.app.security.username-attribute=email to tell Flowable Control the attribute, where to find the username, and match it with assigned Flowable Control roles.

note

The permissions are accumulated over all roles. Either provided by the username to role mapping or direct role assignment.

Default admin and default non-admin roles

If no roles are granted, Flowable Control built-in SecurityConfiguration provides a fallback mechanism.

  • For admin users, the default Admin role grants access to all Flowable Control features
  • For non-admin users the default role grants all available access permissions

You can use flowable.control.app.roles.default-admin-role and flowable.control.app.roles.default-user-role to set the default roles that apply to users when no role is assigned.

flowable.control.app.roles.default-user-role=CustomDefaultUserRole
note

These default fallback roles are virtual and cannot be changed. You must create your own roles and set the properties to modify the fallback mechanism.

Create a new default role for the non-admin user. The default non-admin user role does not match our requirements. So we add a new role and grant more privileges, but also remove some Access Privileges

Set Acces Privileges

In addition, we want the non-admin user to be able to modify instances and instance-related data

Set Access Privileges

The user has access to several admin features and limited Access Privileges

Set Acces Privileges

note

Communicating between Flowable Work and Flowable Control is still with basic auth. Flowable Control is able to communicate with Flowable Work using OAuth2 as well. More about that in the next section.

OAuth2 Authentication between Flowable Control and Flowable Work/Engage

Flowable Control supports 3 types of authentication with Flowable Work / Engage out of the box:

  • Basic Auth
  • OAuth2 (client credentials)
  • OAuth2 (current user token)

Based on how your application is configured you will have the available authentication options in the Cluster / Endpoint configuration.

Cluster / Endpoint authentication options

OAuth2 client credentials

Using OAuth2 client credentials is similar to using Basic Auth, it is similar in such a way that a service account is used to communicate with Flowable Work / Engage. For the next section to work we assume that you have read the Integrate Azure SSO with Flowable Work How-To. While working through the How-To please ensure that the property flowable.security.oauth2.resourceserver.jwt.principal-claim-name is not set. Otherwise, the application token coming from Flowable Control won't be accepted by Flowable Work / Engage since it does not contain a preferred_username.

Before we continue configuring Flowable Control we need to do some configurations in our Azure portal.

First we need to make sure that we have a role for making a user / application an Admin. We will head to the Application App Roles and add a role with value GROUP_flowableAdministrator

Create Admin Role for Work

Once we have this role, we now need to assign it to our registered application. To do that we need to head to our application in the "Enterprise Applications". There we need to go to permissions and click on the "Grand admin consent for <Organization>". Note, that you need to have the right permissions to be able to do this consent.

Azure Add Permission

Azure Grant Admin Consent

Once we have this setup we need to configure Flowable Control. The configuration here is specific to the Azure SSO. However, the general structure is normally the same for all providers.

In the example below the following replacements are needed:

  • <name> - This can be any string you want. e.g. admin
  • <provider-id> - This is optional in order to link it to an already existing OAuth2 Client provider
  • <client-id> - The id of the client which we created at the beginning. This can be seen in the overview of the application.
  • <client-secret> - The secret of the client which we created at the beginning
  • <work-client-id> - The id of the client which was created for the Flowable Work Integration. This can be seen in the overview of the application.

spring.security.oauth2.client.registration.<name>.provider=<provider-id>
spring.security.oauth2.client.registration.<name>.client-id=<client-id>
spring.security.oauth2.client.registration.<name>.client-secret=<client-secret>
spring.security.oauth2.client.registration.<name>.scope=<work-client-id>/.default
spring.security.oauth2.client.registration.<name>.authorization-grant-type=client_credentials

# This part is optional. The provider-id above can be the same as the one set for login.
#spring.security.oauth2.client.provider.<provider-id>.issuer-uri=https://login.microsoftonline.com/<tenant-id>/v2.0
#spring.security.oauth2.client.provider.<provider-id>.user-name-attribute=email

To finalize the configuration we need to head to our cluster configuration and configure the authentication type.

Control change authentication type

Note, that the "OAuth2 Client Registration ID" should match the client registration name configured in the properties

Once this is setup you should be able to communicate between Flowable Control and Flowable Work.

note

In case the communication is not working you might be affected by your Access Token is being rejected due to invalid issuer. In order to fix that follow the answer on this question

OAuth2 Current User ID Token

In case you want to use the same ID Token between Flowable Control and Flowable work you will have to adapt the "Redirect URIs" of your Flowable Work configuration to also include the Flowable Control URI. This integration will only work if you are also using OAuth2 to login to Flowable Control.

info

For Flowable Control to work correctly, the user logging in to Control should also have admin rights in Flowable Work. Otherwise, Flowable Control might not work as expected.

Conclusion

The Flowable products are extendable through the default Spring Boot (starter) approach. You can customize security of your application specific to the need of your environment in a really powerful way.

Integrations to standard identity providers are working easily as everything is based on the Spring Security framework.

Additionally, the security between different Flowable applications can be configured easily.