In this third article in the Authentication and Authorization in K2 series, we discuss how authorization fits into the K2 platform. Although primarily focused on the OAuth technology, you'll also learn how non-OAuth authorization works as it is essential to understanding the full breadth of how the platform connects to other systems.
In the overview article, we mentioned that K2 is a hub that connects various systems in the enterprise and even outside the firewall to systems on the Internet. One of K2’s primary benefits is its ability to connect to other systems through the SmartObject architecture. Whether it's reading or writing data from various systems in workflows, forms, and reports, configuring K2 to connect to these systems is often a first-time exercise of learning how those other systems must be configured to share data with platforms such as K2.
Before you begin, review the terms "Inbound OAuth" and "Outbound OAuth" to determine what configuration is required for your needs. These terms refer to the direction that OAuth tokens are flowing, and the direction is described from the perspective of the K2 server.
There are multiple ways in which K2 SmartObject Service Instances can connect to other systems so that those other systems can authorize K2 to read and write data. You see these options when you configure a service instance.
Why is this important? Because service instances represent how you'll connect to other line of business (LOB) or external systems. They are instances of service brokers that are either built specifically for that system, such as SQL Server, or are brokers built based on a particular technology, such as WCF or REST. Regardless of the system or technology, the available outbound Authentication Modes (aka Authorization) are the same. Not every service broker supports all of the authentication types, so changing this might not have any effect. These modes are explained in the product documentation, but here's a brief summary of what these mean and why they're useful:
When you set up a service instance you must choose one of these modes, and if you choose OAuth you must also specify the resource and optionally the audience (more on this later).
When you specify OAuth as the mode, you must be sure that your broker supports OAuth. Also, newer out-of-the-box brokers that come with K2 support OAuth but some of the older ones do not.
From this point forward we will only be discussing OAuth. If you need further information about the other modes please see the product documentation, searchable on http://help.k2.com.
By definition, OAuth is an open standard for authorization. Being an open standard means it has become the default standard for authorizing one app to do something on a person's behalf in another app. An example of this would be your workout app tweeting an update of your latest run on your Twitter profile. When you first set up the permission (sometimes apps refer to it as a partnership), you authorize an application to do something on your behalf in another application. This something is usually called the scope of the authorization and can be anything from accessing your information to performing some action. An OAuth authorization, along with its scope, typically expires after a period of time and can be refreshed. The authorization can also be revoked at any time.
It is important to note that OAuth is not Claims-Based Authentication (CBA). While CBA and OAuth often work hand-in-hand because they are becoming de facto standards for authentication and authorization, they are not dependent on each other or share the same architecture.
Firstly, since they are doing different jobs, OAuth does not replace claims in the K2 platform. Your users still sign in via an IdP (with an STS), which then issues the SAML token containing the user's claim. This is authentication (sometimes abbreviated as auth-N). CBA is used to uniquely identify the user and to determine who belongs to what group and what K2 security label they are mapped to. In fact, whatever mechanism your users use to authenticate is just fine with OAuth; it can be Integrated Windows authentication that maps to the K2 label, so CBA is not a pre-requisite for OAuth to work.
OAuth provides an application with the ability to act on behalf of a user. This is authorization (sometimes abbreviated as auth-Z). Think about these as entirely separate functions unto themselves and you'll be ahead of most everyone else who struggles to understand auth-N and auth-Z as separate operations.
Let's take a brief look at some of the benefits of OAuth.
While OAuth is becoming more widely adopted by many companies, the main impetus behind K2 supporting OAuth in the platform is SharePoint 2013. The best way and only way to authorize a user or server to act on your behalf in SharePoint 2013/2016 is to use OAuth. Gone are the days where you could simply switch the context of the thread to another user. Switching the context of the thread still works in the SharePoint API but you must be running your code on the SharePoint server. But in this day and age of cloud computing, only a fraction of K2 actually runs on the SharePoint server. K2 does 99% of its work with SharePoint remotely through the client API and REST services, meaning that the call into SharePoint from K2 comes bearing an OAuth token instead of relying on any thread context impersonation.
Typically OAuth is used for personal authorizations, such as granting your photo app to post pictures to your Facebook page. SharePoint's OAuth implementation is different in a couple of ways. Namely, it uses OAuth for users just like any other app, but it also has the concept of an admin token that can be used to perform work on behalf of many users or an account that represents another system. That token is valid for 90 days. SharePoint Online also has the concept of Common Consent, which is discussed later in this document.
K2's OAuth support works for both types but it's important to know the difference between the two.
In earlier versions of SharePoint, namely 2010 and 2007, K2 must install bits on the SharePoint servers, does not rely on OAuth, and can do the thread context switching for user impersonation. However, that is older technology that, while maintained, is not the direction in which SharePoint is heading.
This section illustrates the initial flow and then the subsequent flow when the OAuth token is cached by the K2 server for use when K2 interacts with SharePoint. It also illustrates the difference in flow between SharePoint Online (Office 365) and SharePoint On-Premises (On-Prem) servers. The former uses a flow that is brokered by trust.k2.com, while the latter uses a high-trust, server-to-server certificate-based flow. K2 Appit also uses the online flow through trust.k2.com.
There are two types of OAuth tokens: Access tokens and Refresh tokens.
The K2 App uses the access token whenever it interacts with SharePoint resources. Access tokens are used to create remote context (i.e. a session) on the SharePoint server that identifies the user and authorization level for the particular action. K2 stores the access token with the expiration value. If the token has expired, or is about to expire in the next 60 seconds (this value is not configurable), then the refresh token is used to request a new access token. In SharePoint 2013, access tokens are valid for 1 hour.
K2 uses the refresh token to request a new access token without prompting the user to trust the app again. K2 updates the stored refresh token with every request. A refresh token for SharePoint 2013 expires in 14 days or when the user's password changes. The refresh token can be renewed within the 14 day period, and extended for up to 90 days. At any time after the 14 days without renewal, after the 90 days, or after the user changes their password, K2 for SharePoint must be trusted again.
The following three conditions occur when using OAuth in K2.
K2 performs the following steps:
K2 performs the following steps:
The authentication path of the OAuth token system for K2 connecting to SharePoint Online is different from using K2 connecting to SharePoint On-Premises. The following diagram demonstrates the three-legged path between the K2 App, Azure AD and SharePoint Online vs the K2 App to SharePoint on a local system.
For on-premises scenarios, K2 uses a self-signed certificate to establish trust between K2 and SharePoint. The certificate is used to sign the calls made to SharePoint APIs. K2 generates a unique self-signed certificate at installation. The private key is stored in the K2 database and the public key is hosted at https://[k2server]/autodiscover/api/metadatadocument. The App Deployment utility registers the public key with SharePoint which establishes the high-trust.
Name: K2 OAuth High Trust
Certificate Store Location: Local Computer > Personal > Certificates
Signature hash algorithm: sha512
Public Key: RSA (2048 Bits)
The following information, except for App Only, is taken from http://www.cloudidentity.com/blog/2015/03/20/azure-ad-token-lifetime/
SharePoint |
Account |
Created By |
Modified By |
App Created By |
App Modified By |
Online |
User Context |
{Logged in user} |
{Logged in user} |
K2 for Office 365 |
K2 for Office 365 |
Online |
App Only |
SharePoint App |
SharePoint App |
K2 for Office 365 |
K2 for Office 365 |
On-prem |
User Context |
{Logged in user} |
{Logged in user} |
K2 Five for SharePoint |
K2 Five for SharePoint |
On-prem |
App Only |
SharePoint App |
SharePoint App |
K2 Five for SharePoint |
K2 Five for SharePoint |
In 2014 Microsoft released something called Common Consent for its online properties. This framework allows an admin (a tenant admin to be exact) to install and initially trust an app. From that initial trust forward, user consent is automatically granted to the app. So there's one (common) trust consent for multiple users.
Common Consent allows K2 to reduce the number of Trust prompts that it may need to show when integrating K2 with other sites in a site collection or, more broadly, across the tenancy or farm. This represents the first in what is likely to be a trend to extend OAuth more into the enterprise arena from its personal, 1:1 beginnings.
Image from Authorization Code Grant Flow (https://msdn.microsoft.com/en-us/library/azure/dn645542.aspx)
A Common Consent token flow looks like the following:
(1) The client application makes the request for a resource. The user agent passes along this request to Azure AD.
(2) Azure AD verifies the user and passes back an authorization code to the client application
(3) The client application sends the auth code directly to AAD
(4) AAD passes back an access token
(5) The client application uses the access token to query the online resource (such as SharePoint, Exchange, Lync, etc.)
(6) The resource sends back the requested data
The importance of Common Consent here, and the flow, is that the trust has been promoted up to Azure AD instead of sitting at the SharePoint, Exchange or Lync level, so a common trust consent applies to all properties managed by Azure AD.
You may also see an OAuth Resource Audience option when you register a service instance with the UI or via the API. This additional configuration property is used in conjunction with the Common Consent Framework to allow K2 to retrieve access tokens for different services (aka, audiences). These services would be various online properties such as SharePoint, Exchange, AAD, and the like, and can be accessed using the same OAuth token. The boundary for these audiences is at the service instance level. In other words, your service instance is bound to a specific service audience.
A Resource Type is an OAuth configuration for a particular property, such as LinkedIn. A Resource is an instance of the Resource Type. Only Resources can be used to register a service instance. For more information about creating Resource Types and Resources, see KB001702 - How to configure OAuth in K2