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.
- Inbound OAuth: this means 'incoming' integration where third-party systems need to interact with K2 APIs. Examples include custom applications that need to start workflows, retrieve and complete workflow tasks, or execute SmartObject methods via K2 APIs. In this scenario, the bearer token is verified and used by K2 to authorize the incoming request. These incoming tokens are not cached by K2. See Configure AAD and K2 Services for Inbound OAuth for information on how to set up and use inbound OAuth.
- Outbound OAuth: this means 'outgoing' integration where K2 needs to interact with other systems through SmartObjects, and the underlying Service Instance for the SmartObject is configured to use OAuth authentication. In this scenario, K2 acts on behalf of an AAD user using Refresh Tokens, issued by AAD (or some other identity provider) and cached by K2. Examples include when K2 needs to interact with a third-party service such as SharePoint, Exchange, and CRM and pass through the OAuth credentials of a connected user. This article describes outbound OAuth token flow.
Table of Contents
Articles in this Series
Outbound Identity from K2
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.
.png)
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:
- ServiceAccount: This is useful if you always want to use the K2 Service Account identity to connect to the LOB system rather than impersonating or using other credentials. For this option to work, the LOB system must be able to work with integrated authentication and add them to their security configuration since the credentials used to connect to the target system will be the Windows credentials of the K2 service account user. This option usually does not require Kerberos as there is only a single hop between K2 and the LOB.
- Impersonate: This option is used when you want K2 to connect to the LOB system using the credentials of the user that is currently connected to K2. In other words, when a user runs a SmartForm that requests data from some system, K2 will pass that user’s credentials to the target system, effectively impersonating that user. Behind the scenes, the K2 Service Account impersonates the current user on the thread and then connects to the LOB system. For this option to work, the underlying system should support Windows authentication since K2 will pass the Windows credentials of the currently-connected user to the target system. If Enforce Impersonation is checked, K2 must handle the impersonation via Kerberos. If ‘Enforce Impersonation’ is not checked and Kerberos fails, the backend attempts to handle the impersonation if properly configured to do so, otherwise, the SmartObject execution is retried as the K2 service account.
- SSO: Single Sign-On, meaning that an identity specific to the LOB system has been cached for the current user and should be used when connecting to the system. This option is similar to Impersonate, but the K2 Server looks up the SSO credentials based on the configured label (Security Provider when setting up credentials) and uses those credentials when connecting to the LOB system. This option is mostly used when the target system does not support integrated authentication or if users use a different username and password to connect to a target system.
- Static: A static account that you configure in the service instance. Useful when you have a single account that you use to connect to some data source, or when you are developing a solution and don't need to test the full user identity runtime configuration yet. This option requires you to provide a username and password and all interaction with the target system will occur in the context of this statically-defined user.
- OAuth: Uses an OAuth resource instance with all of the redirects and refreshes as configured. OAuth resource configuration must take place before you can use it as the authentication method for your instance. This option is used when the target system supports OAuth 2.0 and you want to enable K2 to pass OAuth credentials for the currently-connected user to the target system.
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.
What is OAuth?
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.
The original versions of the OAuth protocol, 1.0 and 1.1, work very differently than the current protocol, version 2.0. K2 only supports systems that handle OAuth 2.0 flows.
Does OAuth Replace or Require Claims in K2?
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.
The Benefits of OAuth
Let's take a brief look at some of the benefits of OAuth.
- OAuth is an open, simple, and secure protocol that enables users to approve an application to act on their behalf without sharing their user name and password.
- OAuth is decentralized, meaning there's not one entity or authority that certifies what an OAuth transaction looks like.
- OAuth enables users to share their private resources or data (contact list, documents, photos, videos and so on) that are stored on one web application with another web application.
- Users don't have to provide their credentials each time they want one app to do something in another app. Instead, they trust it once and from that point forward they don't have to think about it again. However, they can revoke the trust at any time.
Why does K2 use 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.
Token Flow Example: SharePoint
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.
Access Token
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.
Refresh Token
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.
Access and Refresh token expirations vary from system to system. Some systems may issue new access tokens with every call and some may not issue refresh tokens at all, it just depends on the system and how their authorization rules work.
Token Conditions
The following three conditions occur when using OAuth in K2.
- No Token: When there is no token present for the application, the OAuth Trust dialog is shown to the user for him to authorize the creation of the access and refresh tokens. The app communicates with the K2 server and receives the ‘No Token’ condition. It then initiates the Trust dialogue between the K2 server, the SharePoint system, and the backend identity and authentication servers.
.png)
(1) Sends an authentication request via a SmartForm
(2) The request travels through the broker layer
(3) And to the K2 server
(4) The K2 server looks in the database for an access token
(5) In the case where there is no access token
(6) It returns the request through the broker layer
(7) And returns a 'No Token' condition
(8) A Trust dialog prompt appears from SharePoint
(9) The trust request is sent to trust.k2.com
(10) trust.k2.com sends the request to the Identity endpoint
(11) The Identity endpoint forwards the request to the K2 server
(12) The K2 server verifies it the identity endpoint sends it back to trust.k2.com
(13) trust.k2.com sends it to the STS
(14) The STS sends the verification to the IdP
(15) The IdP sends the verification back to the STS
(16) The STS communicates with SharePoint to ensure the user trusted the K2 app
(17) SharePoint acknowledges the trust of the app
(18) The STS sends the validated token back to trust.k2.com
(19) trust.k2.com sends the token back to the Identity endpoint
(20) The Identity endpoint forwards the token to the K2 server
(21) The K2 server caches the token in the database
(22) The database operation returns successfully
(23) The K2 server passes the token back through the broker layer
(24) The token is used by the SmartForm
The trust.k2.com server depicted in these diagrams is only used when using SharePoint Online integration. If it's an on-premises server (in the case of K2 blackpearl or K2 Five) that K2 is integrated with, the communication between K2 and SharePoint happens via a high-trust, server-to-server (S2S) channel that is based on a certificate. During S2S communication the full claims token is passed to SharePoint from K2 for additional context. For more information about the role of K2Trust (trust.k2.com) see the About K2Trust article in this series.
- Valid Token: When the access and refresh tokens have been created, and the app calls for an OAuth token, the K2 server retrieves the token data from the database and uses it to perform the data functions between K2 and SharePoint, as shown below:
.png)
K2 performs the following steps:
(1) Sends an authentication request via a SmartForm
(2) The request travels through the broker layer
(3) And to the K2 server
(4) The K2 server looks in the database for an access token for that user
(5) The access token is found
(6) The token is returned to the broker layer
(7) The token is used by the broker to update or request data from SharePoint
(8) Data is returned from SharePoint to the broker
(9) Data is shown in the SmartForm
- Expired Token: When an access token is about to expire or has already expired, the refresh token is used to create a new access token.
.png)
K2 performs the following steps:
(1) Sends an authentication request via a SmartForm
(2) The request travels through the broker layer
(3) And to the K2 server
(4) The K2 server looks in the database for an access token
(5) In the case where the access token is expired
(6) The K2 server sends the request through trust.k2.com
(7) trust.k2.com requests an access token from the STS with the refresh token
(8) The STS sends back an access token to trust.k2.com
(9) trust.k2.com sends the token to the K2 server
(10) The K2 server caches the token in the database
(11) The database returns a success
(12) The K2 server passes the token back through the broker layer
(13) The token is used by the broker to update or query SharePoint for data
(14) Data is returned from SharePoint to the broker
(15) Data is shown in the SmartForm
On-premises vs. Online
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.
.png)
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.
The self-signed certificate is only used for signing communications with SharePoint on-premises. It is not used or intended for web traffic encryption.
Name: K2 OAuth High Trust
Certificate Store Location: Local Computer > Personal > Certificates
Signature hash algorithm: sha512
Public Key: RSA (2048 Bits)
Azure AD Token Expirations
The following information, except for App Only, is taken from http://www.cloudidentity.com/blog/2015/03/20/azure-ad-token-lifetime/
- Access tokens last 1 hour
- Refresh tokens last for 14 days, but
- If you use a refresh token within those 14 days, you will receive a new one with a new validity window shifted forward of another 14 days. You can repeat this for up to 90 days of total validity, then you’ll have to re-authenticate
- Refresh tokens can be invalidated at ANY time, for reasons independent from your app (e.g. user changes password). Hence you should NOT take a dependency on the above in your code – your logic should always assume that the refresh token can fail at any time
- Refresh tokens issues for guest MSA accounts last only 12 hours
- App Only tokens, which became available for SharePoint Online in 2017, allows a provider-hosted app, such as K2 for SharePoint, to be issued a token that can be continually refreshed without re-authentication. This means that you don't have to log in with your tenant admin account to refresh the token. K2 Five and K2 Cloud use App Only tokens, while K2 blackpearl continues to use an admin token.
- Note that with App Only tokens, the Modified By, App Created By, and App Modified By columns in SharePoint show the app information associated with the token, as in this image:
- Use the following table for reference about these columns and how App Only affects their values:
|
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
|
Common Consent
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.
.jpeg)
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.
Audiences
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.
The OAuth Resource Audience is a configurable value that is not directly tied to the Microsoft Common Consent Framework. At the publication time of this document, there are not any services other than Microsoft that would require this property to contain a value. As such, this new property is optional.
Resource Types and Resources
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
