Welcome to the first in a series of articles that discuss how authentication and authorization work in K2. In this overview you'll discover how:

  • user identities flow into K2 and by what mechanisms, and how they are verified
  • users are authorized for resources internal to K2
  • users and the K2 server are authorized for resources external to K2
  • users, groups, and roles are managed by K2
  • trust.k2.com works and what role it serves
  • to troubleshoot authentication issues

Table of Contents

Articles in this Series

About Identity

We start the discussion with the concept of Identity. There's nothing fancy about an Identity -- it is simply a unique item belonging to a system. A single identity must be unique in that you can't have two of the same identities that refer to different items. For example, there can't be two email addresses of joe.bocardo@denallix.com -- this is a single, unique identity.

Secondly, each identity belongs to a system, in this case denallix.com, and the uniqueness is bound by that system. The identity of joe.bocardo@denallix.com and joe.bocardo@gmail.com may refer to the same person in the real world, but these are separate and unique identities according to all identity management systems.

Ultimately, identity comes down to a unique string that can be verified by one system against the system that stores the identity.

In technical parlance, the system that stores identities is called – wait for it – an Identity Store, and can be anything from Windows (Active Directory) to Google to Facebook to Salesforce. The sales counter of that store is called the Identity Provider, and that's where you as a customer can come and verify that someone's identity is stored there.

Authentication

Verifying that someone's identity is stored and managed by a system is called Authentication. From the Greek word authentikos, which means Principal, Genuine, authentication is the process of determining from the source that an identity is authentic.

There are several methods in which an identity can be authenticated. In the Windows world, the main identity mechanism used to be NTLM, which is based on a challenge/response mechanism that precludes the user's password from being sent over the wire. Instead, hashes (calculated numbers) are sent instead as tokens representing the user's information. Windows networks have turned from NTLM to Kerberos as the authentication mechanism of choice for large domains as it provides better security.

Kerberos is a protocol based on ticket exchange and mutual authentication, meaning both ends of the connection are authenticated to each other. The key is that there is a trusted third party facilitating the encryption of the communication between the two endpoints, such as when a notary public authenticates signatures on a contract and records the signing act in a separate logbook. Kerberos, along with Constrained Delegation, allows authentication on a Windows network to be highly secure and trusted, but, in the end, involves systems exchanging encrypted tickets which are then used to create session tokens for the two parties to exchange authorization information.

Claims-based Authentication (aka Claims-based Identity) is a common way for systems to exchange identity and authentication information across multiple systems. It simplifies this logic into envelopes called tokens that are issued by a corresponding issuer, also known as a Security Token Service (STS).

The strength of claims-based authorization is that what is inside the claim can be identities for any system, including Windows. As long as both systems know what to do with the identity inside the token, it's very similar to NTLM or Kerberos ticket/token exchange. The key difference is that the method of exchanging claims is not specific to a vendor and can be cross-platform, cross AD Domain (without trust), and from on-premises to cloud and back.

Remember that all of this authentication communication happens over secure and encrypted channels (mostly HTTPS), so the configuration of it can at times seem daunting. What you once got pre-configured out of the box with a Windows machine, where the internal guts of how user accounts and identity flowed when you made your machine part of a Windows domain, you now have to explicitly setup for communicating with other user identity stores on the internet, such as Facebook, Twitter, Azure AD and the like, which is where the power of claims really shines.

As you can see in the following diagram, the user authenticates with an issuer, the issuer gets information from one or more identity stores, sends a token back and the user sends that token to the claims-based application. What is not clear in this picture is that in many cases the claims-based application must trust the issuer, but that will be covered in more depth in the Claims-based Authentication article.

Image

Image from An Introduction to Claims (https://msdn.microsoft.com/en-us/library/ff359101.aspx)

Authentication and K2

You may be saying to yourself, "this is all fine and dandy, but how does this relate to K2?"

K2, like most platforms built on Windows, required and essentially assumed an Active Directory (AD) to retrieve the identity from. User authentication happened under the scenes and as long as you had a valid user you could do things like impersonate and act on the user's behalf. Then when Windows switched to Kerberos as the more secure, default mechanism, K2 administrators had to understand and configure a lot more trusts and constrained delegations than they were used to. To alleviate some of this, K2 introduced Pass-Through Authentication (PTA) which was used in cases where Kerberos wasn't entirely necessary or was simply overkill, and got K2 administrators out of the business of configuring their environments for Kerberos.

K2 as a Hub

K2, in many aspects, becomes the hub of line of business (LOB) data flowing in, out and around an enterprise's network. As a 3rd party system that integrates with Microsoft and non-Microsoft platforms, problems that go otherwise unnoticed become apparent in a network when K2 is installed. As such, K2 is sometimes thought of as the problem child of some particular LOB system when, in reality, it's the first time a customer has tried to integrate with that LOB system, and problems with the configuration are exposed. Kerberos is a classic example of this, but it can come in the form of any LOB system that must work with K2 in some aspect to automate business processes. The key thing is to understand the authentication, authorization and network/domain structure that must be in place for the LOB system to share its information with K2, and carefully mimic your production environment in order to catch configuration issues early.

Beyond Kerberos, the internet and widely-used sites and applications, such as Facebook, Twitter and the like, forced the Windows world and platforms built on Windows to work with those other systems across standard internet ports of 80 and 443 (aka HTTP and HTTPS). This, along with the drive to put Office in the cloud, resulted in Microsoft introducing authentication mechanisms in its products that could interoperate with other providers on the internet.

Authentication Options for K2

Out of the box K2 has always included the ability to install and work with a user source other than AD, which was and still is SQL Server. K2 users don't have to belong in AD as long as you point K2 to user information stored in SQL. SQLUM (for SQL User Manager) is the security label associated with users from a SQL identity store, just like K2 is the label associated with AD users.

K2 also supports other user managers, including custom, so technically K2 can understand user information from any identity store.

When SharePoint 2010 introduced claims-based authentication they left Windows-based authentication in as a Classic option. This allowed companies who were not ready to jump into claims an easy out for upgrading to SharePoint 2010. It also empowered those companies who had the need for identity stores to integrate those into their SharePoint environment, namely through the Forms-Based Authentication (FBA) and the Trusted Identity provider (Trusted) options. The main benefit to this was that they could easily configure multiple identity providers on the same web application, which in SharePoint 2007 required the use of multiple zones and web app extensions.

With SharePoint 2013 the classic mode is gone (well, technically you can get it back but it requires some PowerShell commands). So even if your network runs Windows/NTLM, your tickets from SharePoint 2013 are Windows identities wrapped in a claims token, and this is the default mechanism for how SharePoint 2013 handles identities. Claims tokens from SharePoint are sent in specially-formatted XML called SAML. So when referring to a claims token from SharePoint or K2, they are SAML tokens. Other formats are out there but not supported by SharePoint or K2.

What this means is that any system that needs to do something with users coming from SharePoint must at least be able open (sometimes referred to as crack or resolve) the claims token to figure out who the user is, and more importantly, where they're coming from. K2 introduced the claims-cracking logic for SharePoint 2010 integration while maintaining the standard NTLM-based authentication for those users staying in classic mode.

SharePoint and the App Model

With the integration of K2 and SharePoint 2013, K2 introduced an entirely new model of integration with SharePoint based on the SharePoint App Model. (Microsoft renamed apps to add-ins, but we'll continue to call them apps and the app model.)

The app model uses app domains and inline frames (iframes) to allow content from an entirely different server and domain to appear within the standard SharePoint UI, negating the need for 3rd-party assemblies to be installed on the SharePoint server. (If you remember the old BPOS initiative you'll understand why removing this need was deemed important, especially for the cloud).

Up until this point, K2 required components (WSP solutions) to be installed on every SharePoint server in the farm. While this required extra installation and configuration time, it also meant that the K2 logic and assemblies were part and parcel of the SharePoint domain and could pass user context and data to the K2 server as necessary without the need to independently verify the SharePoint user.

With the App model, this independent verification of users by K2 required additional configuration in terms of directly trusting the source of the SharePoint users, which meant that K2 had to be a relying party just like SharePoint to whatever authentication scheme was configured for the SharePoint web app. With SharePoint 2010, even a web app with claims configured didn't require this direct trust because the K2 components were installed directly in SharePoint. Yes, the SharePoint 2010 claim had to be cracked, but that was the only configuration that was needed because K2 always had a direct Windows-based connection back to the SharePoint server (as you recall this was a requirement of SharePoint 2010 integration, much like the SharePoint Search Crawler had).

For SharePoint 2013 and it's younger sibling, SharePoint 2016, the way the K2 server calls back into SharePoint is via the SharePoint 2013 SmartObject Service Broker, and this broker is configured to use OAuth. So remember, it's claims coming into K2 to handle the inbound identity (with a direct trust from K2 to the identity store), and OAuth going from K2 back to the SharePoint server as the outbound identity.

Authorization & OAuth

Authorization is easy to understand – it's what you are allowed to do. Are you authorized to drive a car, access the building at night, and raise a family? What it comes down to is there's an authority that allows or denies you access to some resource or activity. For electronic systems, it's usually access to a web site, a mapped network location or the Pyxis pain meds dispenser.

In a Windows authentication/authorization flow, your identity is passed to another Windows server that controls access to the resource either by user or group or a combination of the two. If you are on the list that has access, and you have a valid claims token that says you are the same person who is on that list, you're allowed access to the resource. Similar to the reason why Windows tokens don’t work outside of a Windows network for authentication, they also don't work well outside of the network for authorization, so a new protocol is necessary, not only for Windows but for other properties to talk to each other on behalf of their users as well – enter OAuth.

OAuth, according to its Wikipedia entry, is an Open standard to AUTHorization. Started in 2006 and broadly being adopted a few years later, OAuth fills the need for authorization across multiple, disparate web applications. The open portion of the description seems to mean that providers are free to deviate from any standard that some other guy came up. From Microsoft to Facebook to LinkedIn to Twitter, you won't find two OAuth token flows that are the same, but the basic idea is this: Ask the user for his or her permission to do something on their behalf. The something depends on the LOB you're connecting to, for example, an app on your smartphone that wants to tweet to the world the fact that you just set your personal best in your first half marathon. When you first setup the link between the app and Twitter you get a prompt to trust the app to have access to tweet on your behalf.

For K2, SharePoint 2013 was the impetus to build OAuth token handling into the platform, and it can be used to connect to most any other system that requires OAuth (more information can be found in the Outbound Authorization and OAuth in K2 article with a link to how to setup your own resource). In K2, integration with anything external to K2 usually happens via a SmartObject service instance, and you configure your Authentication Mode to be OAuth as in the following illustration:

Image

If K2 does not have a token cached for the system in question, in this case SharePoint, a redirect happens on service instance configuration that allows you to type in your credentials for that system and grant K2 some level of access to your information in that system. Once that system authenticates you, it gives the K2 server an authorization token that the K2 server can use to retrieve items from that system as you, without you needing to log in again.

Internal Authorization

This OAuth discussion – and the article in this series -- is focused primarily on authorization on systems external to K2. For authorization for K2-managed things, like workflows, tasks, SmartObjects and the like, there is UI in Workspace's Management Console and the K2 Management site that allows a K2 administrator to authorize users to particular resources or activities. 

When you delegate someone in your company to have access to your tasks, or you redirect a task to someone else, under the scenes you're authorizing them to have access to your tasks.

User Managers

The last key piece of overview information to bring it altogether is a quick discussion on how K2 keeps track of users. K2 uses something called a User Manager that is comprised of a few things – a security label (such as K2, SQLUM or LDAP), a security provider (the authentication mechanism configuration), an authentication provider (how does the user login), and a role provider (the mechanism for determining what groups/roles the user belongs to, which is technically not required). The end result of all of those things is a string such as K2:DENALLIX\JOE called a Fully-Qualified Name (FQN). An FQN, when valid, means that K2 has authenticated and can authorize that user represented by that string for some resource. It also means that K2 can cache an OAuth token for that FQN if and when they need to go outside of the K2 domain to a system that supports OAuth. Lastly, K2 supports a number of identity stores out of the box, and each has an associated security label. This security label along with the user name and any other information required by the security provider (such as domain) is what makes a user unique in K2 (the FQN). Groups also have FQNs.

As a comparison, SharePoint maps the authorized user from an underlying information store, in this case a claims-based Active Directory, to a SharePoint-specific user name, represented in the image below as Account.

Image

Similarly, K2 maps the authorized user from the underlying information store to a K2 fully qualified name user in the format of [Security Label]:[Domain\Username], represented as a K2 field part in the image below.

Image

Claims-based Authentication Flow with SharePoint

The following flow illustrates what happens when a user in SharePoint 2013 or 2016 clicks an item that requires a K2 resource to show something in an iframe (more on this later).

Image

Modified image from Claims based Access and Windows Azure (http://www.codemastersinternational.com/Blogs/Adnan-Boz/2011/2/6/claims-based-access-and-windows-azure)

OAuth Authorization Flow with SharePoint

The following flow illustrates what happens when the K2 server needs to do something on the SharePoint server, such as upload a document, create a list item or change a user's permissions.

Image

For more information about this flow of requests, responses and tokens, see Outbound Authorization and OAuth in K2 that is part of this series.

Appendix: Terminology and Definitions

Term

Definition

Identity Store

The location where identities are stored, such as AD, LDAP, SQL, etc.

Identity Provider (IdP)

A Web service that handles requests for trusted identity claims and issues SAML tokens. An identity provider uses a database called an identity store to store and manage identities and their associated attributes.

Claim

A statement that one subject makes about itself or another subject. For example, the statement can be about a name, identity, key, group, privilege, or capability. Claims have a provider that issues them, and they are given one or more values.  This data about users is sent inside secure SAML tokens.

Claim rule

A rule that is written in the claim rule language of the provider that defines how to generate, transform, pass through, or filter claims.

SAML Token

SAML is an XML-based open standard data format for exchanging authentication and authorization data between systems. SAML tokens are XML representations of claims.

Secure Token Store (STS)

A Web service that issues security tokens. SharePoint implements a STS to authorize activities within the application from multiple authentication providers

Relying Party (RP)

 

An application that consumes claims to make authentication and authorization decisions.  For example, the K2 server receives claims that determine if the user can access K2 data.

Azure Active Directory (AAD)

The cloud-based identity store from Microsoft.

Federation Provider (FP)

An authentication broker that acts as an intermediary between a relying party and one or more identity providers.

Account Control Service (ACS)

The cloud-based federation provider from Microsoft that provides protocol transition and claims mappings from multiple identity providers.

Single Sign-On (SSO)

Provides credential management so that users do not have to remember different credentials for different systems, and allows systems to trust one another. Federation Providers like ADFS and ACS provider SSO capabilities.

Windows Identity Framework (WIF)

Framework from Microsoft for building identity-aware applications, with tools for building claims-aware and federation capable applications.

AppOnly

A term used by Microsoft to describe the type of client credentials being granted.

Kerberos

The Kerberos protocol defines how clients interact with a network authentication service. Clients obtain tickets from the Kerberos Key Distribution Center (KDC), and they present these tickets to servers when connections are established. Kerberos tickets represent the client's network credentials.

Pass-Through Authentication

An alternative to Kerberos or a backup for when Kerberos fails to handle a connection to the K2 server.

OAuth

An open standard to authorize access to a resource based on a user trusting another system.

Token

Any defined network communication package that contains identification information. Can also be considered a ticket.

Trust

The action of granting another system access to your information on a particular system. What you grant access to depends on the type of request made and the available categories of information and actions.