Configure K2 SmartForms for AAD Authentication

My post “Configure K2 SmartForms for AAD Authentication” has been just recently published on AcloudA Blog. But in addition to that I’ve already managed to revisit exactly the same process to see how it works in K2 Five Public RC which is already available to K2 clients upon request.

This article assumes that you have K2 Five Public RC installed and configured in your environment with on-premise AD or K2 SQL authentication and we now just want to add an 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.

First part is fully covered in my previous article so I only going to go through K2 side configuration steps.

To begin configuration process, we need to open 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:

As you can see overall UI theme changed a bit in K2 Five from black to silver/gray and in New OAuth Resource form we now have two extra fields “Refresh Token Endpoint” and “Metadata Endpoint”. We now need to 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, i.e. they should look as follows:

Token Endpoint value:

https://login.microsoftonline.com/{AAD_DIRECTORY_ID}/oauth2/token

Authorization Endpoint URL value:

https://login.microsoftonline.com/{AAD_DIRECTORY_ID}/oauth2/authorize

We leave Use Host Server Authorization Endpoint checkbox unchecked, and two new fields unfilled and click on OK button (see screenshot below):

Our next step is to edit client_id resource parameter of newly created OAuth resource. For that make sure that your “AAD” resource is selected in resource list and select client_id from the lest of Resource Parameters below and click on Edit button 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 enter 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 are 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, for that navigate to Authentication > Claims > Issuers, click New and fill in New Claim Issuer form 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 Authentication > Claims > Claims and click New:

In the New Claim Mapping form, we then select label and issuer we created earlier and fill in the form. 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).

Next, 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 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. And here things are a bit different in K2 Five – you actually won’t be able to access anything until rights will be granted. Both K2 Management and K2 Workspace are now essentially SmartForms based forms and you going to get related error messages when you don’t have access to them:

As for designer it seems it is also locked for AAD user, which was not the case in K2 4.7:

It looks like even designer is locked out by default, but bad thing that error messages not too user friendly to say the least.

This nudges us to perform our final configuration step. As we don’t have K2 Management rights we need to go and grant them, right? No changes between 4.7 and K2 Five here, before we will be able to read AAD data we need to obtain and cache AAD OAuth token for K2 service account and until that we only going to get this error message:

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 (no changes here if we compare with K2 4.7):

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:

If we now trying to login to K2 sites using our AAD account prior to granting any rights both K2 Designer and K2 Workspace going to be available to him in default configuration (so Designer is still not locked out by default), but K2 Management is not accessible until you grant your user appropriate rights:

Of course, K2 Designer we see in K2 Five is completely different beast than it used to be, but discussing it is out of scope for this article, so I’ll just put only one screenshot of it below:

So, after repeating AAD integration configuration steps I can say that at least in K2 Five Public RC we don’t see any drastic changes when it comes to configuring AAD integration (though we can see couple of tiny changes but they don’t impact the overall process) – depending on your preference you can either refer to my old article to go through the entire process or use an old article only for AAD app set up part and this one for K2 configuration part.

Update 09.2018: Since this post has been written official K2 documentation has been updated to cover this scenario. Below you can find direct links to relevant section of K2 ICG:

Manually Configure K2 for Azure Active Directory (AAD) K2 4.7

Manually Configure K2 for Azure Active Directory (AAD) K2 5.0

Manually Configure K2 for Azure Active Directory (AAD) K2 5.1