Authentication and Authorization in K2

KB002026

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

• About Identity
• Authentication
• Authentication and K2
• Authentication Options for K2
• SharePoint and the App Model
• Authorization & OAuth
• User Managers
• Claims-based Authentication Flow with SharePoint
• OAuth Authorization Flow with SharePoint
• Appendix: Terminology and Definitions

Articles in this Series

• Authentication and Authorization in K2 (this article)
• Claims-based Authentication in K2
• Outbound Authorization an OAuth in K2
• About K2Trust
• Troubleshooting Claims-based Authentication Issues
• Understanding User Managers, Identity Providers, Claims, and Realms

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 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.

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:

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.

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:DENALLIXJOE 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.

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

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).

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.

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