Tag Archives: K2

Blast from the past: Configure K2 SmartForms for AAD Authentication (4.7)

DISCLAIMER: This is a post which used to be published on another web site, and as it is no longer available there just re-publishing it here again. It is an old write up from summer 2017, so a lot of things surely have changed since then.

In my previous article –  Azure AD instance set up basic walkthrough, I covered process of setting up of an Azure Active Directory (AAD) instance and also such basic things as subsequent AAD user creation, joining Windows 10 device to AAD and configuring logon to Windows 10 device using AAD account. 

In this blog post I decided to put this AAD instance to more serious/interesting use and configure K2 SmartForms for AAD authentication. When configured, such AAD integration allows AAD users to login to K2 SmartForms web sites (Runtime, Designer, Management) and enables K2 use AAD users as destination users in workflows’ client events or pull users details via Azure Active Directory Service broker and respective SmartObjects. 

When you use SharePoint Online with K2 you get your AAD authentication configured automagically (see, for example, this blogpost which run through the steps involved), and it really means that once you activated K2 App on your SharePoint online site – things gets configured automatically on K2 side. Simplicity of this integration emphasizes current product focus on clients which use SharePoint Online in their environments. 

Things are a little bit different when you do not have (or do not want to use) SharePoint Online in your environment, but still need AAD users to interact with K2. Good news – this is something you can do, bad news – current K2 documentation has not been updated to reflect AAD side UI and terminology changes and all in all it is quite lengthy manual configuration process. So vendor documentation is in place and you may follow it along but like I said current edition needs to be updated a bit, but no worries we will cover everything here, simplifying (when possible) steps involved and using modern Azure Portal UI. 

This article assumes that you have K2 4.7 installed and configured in your environment with on-premise AD or K2 SQL authentication and now just want to add AAD integration. 

Beyond installed and configured K2 blackpearl and K2 SmarForms our prerequisites are AAD subscription (this has been covered in my previous article) and SSL configuration of K2 web sites (as usual for test purposes you can get away with self-signed certificate, and this is also covered in K2 Installation and Configuration Guide). 

There are two big parts in setting up K2 and AAD integration: registering K2 SmartForms app in AAD and K2 side configuration of OAuth Resource and AAD label. 

Let’s start with registering K2 SmartForms app in AAD. In the real world you may not have access to AAD and somebody else will have to perform these steps for you. But, in any case, once app registered you will need certain values from registered K2 app which used to perform K2 side configuration. For the sake of convenience those will be written IN BOLD CAPITAL LETTERS and I suggest you create some table or text document which you can fill in as you go through AAD app set up part and then use it while performing K2 side configuration. 

Our first step is to log on to https://portalazure.com, select AAD domain and click on App registrations link under Manage

It will open App Registrations page where you need to click on “New application registration” button: 

This button starts Create app wizard where you are filling in application name, leaving application type on its default value of “Web app / API” and specifying Sign-on URL as shown below: 

Once app has been created you can see it in the list of your apps: 

If you click on it you can see your newly created app properties page: 

We now can further configure app and take a note of details we will later need to use on K2 side, for now from the Settings page copy and save your APPLICATION ID value. For additional properties and settings, use Settings pane on the right. For example, we can add customized logo for our app as shown below (that comes in handy if your list of registered apps is large, as logo helps you to find your app somewhat quicker in App Registrations list): 

While we still have app properties blade open we can adjust App ID URI replacing GUID which goes after K2 site part of URL and changing it to something less lengthy and easier to read for human. In my case I’ve changed it to “/identity/” (as you can see on the screenshot above). NOTE: This App ID URI must be unique within your AAD instance (UI won’t allow you to enter duplicate). Also on this page be sure to set Multi-tenanted option to Yes. 

Once again be sure to save APPLICATION ID into your app info table, and then click on Keys under API ACCESS section: 

There you need to type in description and select expiration time for the key, and click on Save to retrieve the key value: 

Once you click on Save, copy and save the key into table. Important warning: You will not be able to retrieve the key value once you leave this page so make sure you have it stored/copied: 

Once you copied and saved the KEY VALUE to table you can navigate away from this blade. As you can see on the screenshot above Azure UI additionally warns you that you will not be able to retrieve the key value once you leave this blade so make sure you that you saved it.  

If you navigate away from this blade and return to it you will see that key value is hidden and there in no options to retrieve it: 

Now from the app properties page click on Settings, then on Reply URLs and add two additional reply URLs (make sure to adjust {YourK2Server} value as necessary, in my case K2 server name was “k2.zlatagroup.com”, for example). So https://{YourK2Server}/runtime should be already here and you need to add the following:  

Token Endpoint Reply URL – https://{YourK2Server}/identity/token/oauth/2 

Authorization Endpoint Reply URL – https://{YourK2Server}/identity/authorize/oauth/2 

After this your Reply URLs list should look as on the screenshot below, and you can click on Save: 

Let’s also make sure that we have required app permissions. For that we need to navigate to Required permissions and then add/edit Windows Azure Active Directory permissions: 

Here we need either grant (Add button) or make sure (click on “Windows Azure Active Directory” permissions entry) and ensure that the following permissions are granted for K2 app: 

As a final touch we need to configure our AAD App to allow us to log in against all our K2 sites by modifying the app manifest file. Click on edit app manifest button: 

Within manifest file locate “identifierUris” section and append it so that it lists all your K2 sites, as shown on the screenshot below:  

Now we need to click on Endpoints button from the App registrations blade list: 

It will open Endpoints information page, from which you need to copy and save the following items: Federation Metadata Document URL, the OAuth 2.0 Token Endpoint, and the OAuth 2.0 Authorization Endpoint URL (the GUID section of all these URLs is your Directory ID). 

After saving endpoints information we need to obtain and store the Certificate Thumbprint. For that we need to navigate to Federation Metadata Document URL of our AAD using web browser and once XML is loaded search for X509Certificate value (within the Signing container) and copy it: 

You just copy entire line between <X509Certificate> and </X509Certificate> tags. Next Open a browser and browse to the online SAML fingerprint tool, paste the copied X509Certificate value into the form and make sure the sha1 algorithm is selected, then click the Calculate Fingerprint

Save FINGERPRINT VALUE. This concludes AAD app configuration part. After completing it you supposed to have this data: 

  • APPLICATION ID. Referred as Client ID in old Azure UI/K2 documentation. You can get it from app properties blade in AAD. Used as Authorization, Token and Refresh value of client_id OAuth resource property in K2. 
  • KEY. Key value which must be copied from the App Keys page at the stage of key creation. Used in all values of client_secret OAuth resource property in K2. 
  • METADATA URL. Can be copied from App Registrations > Endpoints page. 
  • OAUTH AUTHORIZATION ENDPOINT. Can be copied from App Registration > Endpoints page. Used when adding New OAuth Resource in K2. 
  • TOKEN ISSUER ENDPOINT. Can be copied from App Registration > Endpoints page. Used when adding New OAuth Resource in K2. 
  • DIRECTORY ID. GUID part which can be found in abovementioned endpoint URLs, or in Azure Active Directory Properties. Used as token value of resource_id OAuth resource property in K2.  
  • FINGERPRINT VALUE. Can be generated with SAML fingerprint tool from <X509Certificate> value of your app federation metadata document. 

Now we are done with AAD side app switch over to K2 Management site. As our first step here, we need to Register an OAuth Resource in K2. To do that we navigate to Authentication > OAuth > Resources and click on New button: 

This will open New OAuth Resource window where you need to type in resource name, select Microsoft Online as a resource type and enter Authorization and Token Endpoint values we recorded during AAD app registration. We leave Use Host Server Authorization Endpoint checkbox unchecked and click on OK button (see screenshot below). 

Our next step is to edit client_id resource parameter, which you can select from the list of Resource Parameters and then click Edit as shown below: 

Once client_id edit dialog has been opened we just need to paste APPLICATION ID we saved during AAD app registration in all three fields of this box, i.e. we use it as a value for Authorization, Token and Refresh: 

We next need to edit number of other parameters in the same fashion. We edit api_version resource parameter entering “1.0” for all values: 

Next, we edit scope resource parameter entering reader as Authorization Value as shown below: 

For all values of client_secret enter KEY we saved during AAD app registration: 

We specify https://graph.windows.net for all values of resource parameter: 

For redirect_uri we enter https://{YourK2Server}/identity/token/oauth/2 as Authorization and Token value: 

For entity_id parameter we entering DIRECTORY ID of your AAD instance as a token value: 

After all these edits you Resource Parameters for AAD resource should look like this: 

We now ready to add AAD security label in K2 (you can use something other than “AAD” as label name). For this we need to execute this SQL script or use sample script from K2 Installation and Configuration guide adjusting values for @OAuthProviderName and @SecurityLabelName variables. Be sure to back up your K2 database as you supposed to do before any direct modification of K2 database (I hope this is already your habit? If not try to form it 😊). 

Once script has been executed, we need to restart K2 service to get this new label initialized/picked up by K2. 

Our next step is to add new claim issuer from K2 Management site, as shown below: 

You need to specify the following values there: 

For Issuer value you specify https://sts.windows.net/{DIRECTORY_ID}/, for URI value you specify https://login.windows.net/{DIRECTORY_ID}/wsfed. As a Thumbprint value you need to paste your FINGERPRINT VALUE. Pay attention to trailing slash in Issuer URL – do not omit it. 

Next step is configuration of the Claim Mappings in K2. Claim mappings are used to identify the incoming claims and map them to the appropriate K2 security label. To do that we navigate to Claims, click New, select label and issuer we created earlier and fill in the form as shown on the screenshot below. We need to type in User and Group token identifiers and fill in all values under Identity Provider along with Original Issuer and Claim Type values under Identity section (see screenshot below). 

Now we need to configure the Realms and Audience URIs linking them with new issuer. For that, we navigate to K2 Management > Authentication > Claims > Realms and for each and every realm enable our AAD issuer, by means of selecting realm entry, clicking Edit and checking newly created issuer in Linked Issuers list: 

Hooray! We can now navigate to our SmartForms URL and select our AAD and logon with AAD credentials: 

Once label is selected you are redireted to Microsoft login page (https://login.microsoft.online.com) where you need to type in your AAD credentials and click Sign in: 

What you going to see next obviously depends on which K2 site you were trying to access. If it was K2 Designer then it will be opened without further questions in the default configuration: 

But in case you try to open K2 Management you are going to get insufficient permissions message: 

Which nudges us to perform our final configuration step. As we don’t have K2 Management rights we need to go and grant them, right? But as soon as you attempt to do it you will see that at this stage you are unable to do it: 

Error message tells us that OAuth token requires authorization and comes from K2 URM Service. It means that we need to obtain OAuth token for K2 service account (URM Service runs in the context of this account). To do that perform the following steps: 

1) Run SmartObject Services Tester (“C:\Program Files (x86)\K2 blackpearl\Bin\SmartObject Service Tester.exe”) in the context of your K2 service account using standard Windows “Run as different user” option. 

2) Now the tricky part. Unfortunately, now, in K2 4.7 SmartObject Services Tester only allows you to perform authorization redirect only when you are creating new instance (this possibly will be addressed in upcoming K2 Five release). Thus, to get our K2 Service account token instead of touching URMService we will simply register new Azure Active Directory service instance (and you may want to have it anyway): 

In Add Service Instance dialog we just switching Authentication Mode to OAuth, selecting our OAuth Resource (“AAD”) and typing https://graph.windows.net as OAuth Resource Audience value. We do not touch any other settings leaving them on default values as illustrated below. 

Once you click on Next, you will get this message (once again this message appears only when you are adding new instance, not editing existing one!): 

Once you hit OK browser window will be opened where you need to type in your AAD credentials. Important: you need an AAD user with Global administrator directory role for this action, otherwise you are going to see the following error: 

If you remember one of the rights we granted to our app is “Read directory data” and as it is a directory wide access only global admin AAD user can grant consent to this right: 

Once you type in your AAD global admin user credentials you just need to confirm that we are granting permissions mentioned above to the app: 

Once you click on accept you should be redirected on your K2 Identity site (you may get Windows credentials prompt at this stage – type in your K2 service account credentials) and see “Authorization Successful” message: 

This means that K2 service account token has been created and cached on your K2 server and you can see it in K2 Management > Authentication > OAuth > Tokens: 

3) You can now get back to SmartObject Services Tester and click on Next, Add to finish creation of AAD Service Instance: 

We now completed all the configuration steps and can grant rights to AAD users and use them in all K2 user pickers: 

It is good time to switch over to our Windows10 machine where we enabled AAD logon (see my previous blogpost) and look how it works there. 

First, we can conveniently see our K2 app in Access Panel application in our web browser. Just open https://account.activedirectory.windowsazure.com in your browser and without any credentials prompts (remember we are logged on to Windows 10 device with AAD credentials) you can see this: 

At this point I had realized that I have published K2 runtime site here, which is of little use as entry point for users, but you can correct this and publish either K2 Designer or K2 Management here. But in any case, from this Windows 10 machine we can navigate to K2 Management or Designer sites after just selecting AAD label and without typing in any credentials. 

I should say that the way this integration looks now in K2 4.7 is a bit inconvenient and lengthy. There are a lot of manual steps where you can easily make small mistakes which prevent your entire set up from working correctly, but with some experience you can do it. I think we have these manual configuration steps just because there was much more focus on SharePoint online AAD integration from K2 side and little attention to AAD without SharePoint online integration scenario. But in case a lot of clients will be asking vendor to simplify and better support this AAD only integration scenario, this can be improved and simplified in response to that. 

In any case I think this article gives a very good example of using AAD as an authorization provider for K2. I hope it was informative and useful and in case you have any questions you may leave them in the comments section below. 

Removing K2 node from K2 farm

Just a quick note on removal of a node(s) from K2 servers farm. When you run K2 uninstall on one of the nodes, and obviously when you suddenly lose one of your nodes (server failure without ability to restore it), information about it still stored in K2 database and additional steps are required in that scenario.

To reiterate, just running K2 uninstall on the node does not remove references to the node from K2 database.

To clear that up there is a stored procedure Server.kClusterDown which removes references to the node you removing from all the relevant tables:

Server.ProcInst
Server.DestQueue
Server.Async
Server.IPCAsync
Server.ClusterMessage

It sets Running=0 for node you want to remove in Server.Server table, and then updates all references to the server ID of the server you want to delete with ID of server which you keep.

You run this stored procedure specifying IDs (note: IDs not sever names) from Server.Server table as a parameters:

@ServerID = NEW SERVERID / ID OF THE SERVER WHICH STAYS IN YOUR FARM
@ClusterServerID = OLD SERVERID / ID OF THE SERVER WHICH YOU REMOVE FROM YOUR FARM
@ServerDownTimeout = 0

As usual before attempting any direct modifications on K2 system database you should back it up beforehand.

Unable to run SharePoint 2019 installer when Office 365 is installed on the same machine

I recently spend some days having fun with good old on premise software and it really makes one appreciate infra as a code and provisioning everything in the cloud, fast. 🙂 The problem is that most of the vendors of on prem software have more focus on introducing their cloud offerings and do not want to invest heavily into improving their on-prem installers to accommodate for myriad of edge-cases even if you have support contract of some sort, and if you don’t, then you some times doomed to fight all sorts of obscure errors which can drive crazy any normal person, except for those who strive to convert oneself to a guru in a very narrow and obscure details of proprietary software combinations… Such type of expertise makes one shine on some rare occasions/in the specific niche but amount of efforts one has to spent learning how to fight small strange problems with obscure solution can be demotivating as it is normally all edge and isolated cases which eat up your time to discover solutions which are often not reusable. Well if in process of fighting those you have time and enough of supporting materials to get understanding of how it all works it is one story (good learning/reusable knowledge), but if you are in a get this thing provisioned ASAP mode then you probably revert to fix it by all means without time to think through why fix was needed and what is the best solution – that’s a bad use of precious time, but sometimes there are no other options. Cloud apps and services has their own share of little problems but really cloud really removes bulk of initial setup and provisioning issues – and if there are real problem with that then it is something that vendor will be willing to fix in the most of the cases. This is because to qualify for being cloud software supposed to offer you on-demand self-service provisioning capabilities which have to work with no human intervention beyond “I’m requesting XYZ” from the consumer side. Anyhow that was a bit of self reflection after setting up mix of software on a demo box which involved K2 5.4, SQL 2019, SharePoint 2019 with someone putting RPA software and Office 365 on the same box in parallel – amount of strange errors was higher than normal this time. So just a little blogpost to take a note of couple of problem/solution pairs in case I will run into this again or someone else will run into those.

One of the errors I got was this one – “We’re sorry, Microsoft Office installer encountered a problem because you have these Click-to-Run installer based Office programs installed on your computer”:

This error basically blocks SharePoint 2019 or SharePoint 2019 installer – you can’t nor install nor repair, so for the first time I did removed Office 365 to do a SharePoint 2019 repair, but later on with eager RPA developer putting Office 365 installation back in no time I decided to search a way to avoid removing Office 365 to run SharePoint 2019 language pack installer. To remove this blocking warning you need to locate your Office installation registry subkey, which for x64 bit can be found under the following path:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\O365BusinessRetail – en-us]

Final part/subkey may vary depending on exact Office version you have, and x86 installation entries can be found under HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ subkey. So once you located right registry subkey you will need to add RED_DWORD parameter with name SystemComponent and value of 1 (see screenshot below).

Adding SystemComponent parameter

That should suppress blocking warning and it worked for me in my test environment. Surely MSFT introduced this blocking warning for a reason and you are free to investigate when it is better to avoid removing that warning and seek other ways of solving this. I would in my case it was TEST/DEV environment where developer need an office right on the server which IMO should be avoided in any type of PROD deployment, so this fix was OK for my scenario.

In addition to the above mentioned error, at the final stages of SharePoint 2019 apps environment set up I run into the problem where all was seemingly configured correctly but K2 for SharePoint app page was giving me 404 or other connectivity errors (depending on bindings configuration), to get to that stage I made use of my old blogost and this script (it seems some of the required service apps can only be added with PowerShell), but somehow in my previous write ups I’ve missed or did not mentioned requirement of putting a wildcard into host value of IIS site created for a web app which hosts app catalog. I was sure that it can work with require SNI and a host name (vaguely remembering that it should not be possible :)), especially after looking at another environment where it indeed works that way, but after resolving this problem by switching to * host and no SNI binding, I realized that other environment had SharePoint Routing Web Application which was responsible for magic of making it all work. My only problem is that I did setup that environment either and now not even remember this part of config.

K2 5.4 How to opt out from Setup Manager’s “Recover” state

In recent versions of K2 installer team introduced a feature which blocks installation in case of critical failure leaving you no choice but address the issue and perform repair. It basically blocks all the other options leaving you with Recover as an only available option as shown below:

K2 Setup Manager Recover mode

This option is here for a reason and unless you 100% sure that you need to exit out of this mode you should analyze error and perform repair, if necessary involving vendor support. But in case of throw away test box or initial installation you may want to unblock all the other option, let’s say to perform removal and start from scratch. To do that you just need to delete contents of the Setup State folder (default location is “C:\Program Files\K2\Setup\State”) which in this case will contain json files with the state of failed installation. Those files contain sections like “ComponentActions”, “FailedTarget”, “CompletedTargets”, but to the best of my knowledge support will ask you for installer trace to investigate any type of installer failures.

Like I said in case you understand what you are doing and need to exit out of “Recover” mode you can just use folder clear up approach explained above.

K2 5.4 Setup Manager – unable to change K2 Service Account

Although my keep steep drop in amount of K2 posts from my side with more than high probability in the future, I’m keep jotting little things for now. The other day I was a bit perplexed by K2 Platform Classic setup manager which blocked me from adjusting K2 service account like that:

K2 5.4 Setup Manager – Can’t change Service Account

What it actually does is forcing you to use currently logged in user. And addressing why part it happens when you have developer license – in that case setup manager forces you to use currently logged in user as a “service” account (remember that Developer license requires you to run your K2 service in a window within interactive user session). Just though it may be useful to write this down and share.