Note: This documentation gets updated only when necessary, as the product is in sustained mode. For product updates see the Release Notes.

Multi-Authentication Providers

Multi-Auth is the ability for users to authenticate to a single SmartForms site using different authentication methods.

In most Microsoft-centric organizations Windows Authentication is used as the default authentication provider because it works seamlessly with Active Directory and does not require users to enter login details when accessing the site. The credentials used to log in to Windows are able to be passed to the site through Internet Explorer.

In some organizations Active Directory is not used so a different security provider is registered with K2 which points to a different service for authenticating users. In this case the users will need to provide a username and password to log in to the SmartForms site.

It is becoming increasingly common, however, for organizations to require a mixture of authentication schemes. It might be a scenario where Vendors or Partner organizations need access to internal resources or a scenario where a merger has brought in users from a different directory service. Whatever the case may be these organizations require an easy way to allow all their users access to the same resources.

Multi-Auth in K2 has added the ability for the user accessing the site to indicate how they would like to authenticate. The site then knows how to properly switch between authentication schemes depending upon the user’s selection.

One side effect to Multi-Auth is that Integrated Windows Authentication users, who are not used to any kind of intermediate step between clicking a link and seeing a form, will now occasionally need to select their authentication mode. Authentication is cached by the browser so they will not need to make their choice each time, but if the credentials are removed from the cache they will need to make the selection again.

How does Multi-Auth Work?

The following K2 sites now support Multi-Auth.

K2 smartforms Runtime
K2 smartforms Designer
View Flow

To enable Multi-Auth, some changes were made to how these sites work as well as how the K2 server handles authentication.

Claims Authentication

All authentication between SmartForms sites and K2 is done using Claims Authentication. You can read more about claims authentication here. The basic concept is that when a user authenticates against a particular provider, that provider can issue a set of standardized claims which tells others systems who the user is and what system authenticated them. Claims configured to provide more information about a person can also be issued, but for our purposes only the Identity Provider, and Security Label claims are used.

Not all Identity Providers issue claims based security tokens today. Most notably is Active Directory which issues Windows Authentication tokens. To solve this problem K2 has provided a Security Token Service (STS) that converts Windows tokens into claims, known as the K2 Windows STS. Similarly, since Forms Authentication also does not issue claims a K2 Forms STS has also been provided. Systems like Active Directory Federation Services (AD FS) and Azure Active Directory (AAD) issue claims through their own STSs.

Once a claims based security token comes into the K2 Server from SmartForms, the K2 Server checks a list of known Claim Issuers to see if there is a match. If there is no match an exception is raised. If there is a match in the Issuer list, the security token is “cracked” so that the claims can be read. K2 checks a list of claims that have been registered with the Issuer to determine who the user is. Once the identity of the user has been found the K2 security label that is mapped to the Issuer is added to the identity and the user is authenticated to K2.

Realms

Claims Authentication takes care of authenticating the user once the user has a security token issued from an STS. Getting the user to the right STS is all about Realms. A Realm is an identifier for a site. K2 uses a URI based identifier which is the URL of the site. Other systems might use other formats such as URN.

Each SmartForms site is configured to map to a Realm. The list of Realms to choose from is configured in K2. When the SmartForms site loads it checks with the K2 Server to understand what Issuer configurations are mapped to the Realm of the SmartForms site. If there is more than one Issuer mapped to the Realm, then the SmartForms site is in Multi-Auth mode and will present a page to the user for them to select which Issuer to use to log in. However, if there is already a security token cached in the user’s browser, the security token is sent through so that the user can be authenticated automatically without having to select an Issuer. Also, if there is only one Issuer configured for the Realm, then no login method selection is necessary and the user will be directed to the log in screen.

When the user selects an Issuer, or there is only one Issuer for the Realm, the URI that is stored with the Issuer configuration is used to route the user to the appropriate STS for log in. In the case of K2 Windows STS, which uses Windows Authentication, the log in happens without any user interaction. In the case of other STSs like AAD, AD FS and K2 Forms STS a login screen will be presented. The user enters valid credentials and a Security Token is attached to the redirect back to SmartForms and Claims Authentication takes over.

Below is a diagram that explains the relationship between Realms, Issuers, and Security Labels.

When Windows STS authentication or Forms STS authentication is enabled, it is important to frequently save work that has been done in the K2 Designer as work might be lost when the same session is left open for 8 hours or longer.