Introduction to OAuth

OAuth is a standard, simple, and secure authorization protocol that enables you to approve an application to act on your behalf without sharing your user name and password. It is an authentication standard that allows you to grant specific credentials for the sharing of resources from web, mobile and desktop applications. This enables you to share your specific private resources or data (i.e. lists, documents, contacts, etc.) that are stored on one site or application with another site or application.

For more information about OAuth, see KB002028: Outbound Authorization and OAuth in K2.

Why K2 uses OAuth

OAuth enables outbound data calls with claims-based users’ identity. This allows K2 to access line of business (LOB) resources, such as SharePoint, Google, Twitter, and Facebook, on behalf of the user.

OAuth is not outbound claims, and when using OAuth, K2 does not create or pass Security Assertion Markup Language (SAML) tokens via brokers.

Where K2 uses OAuth

K2 smartforms uses OAuth to create trust credentials that can then be shared across diverse systems. This allows you to securely access resources without needing to continually login to those systems.

OAuth is used in K2 for SharePoint as part of SharePoint's App model. In SharePoint 2013/2016, apps execute outside the context of SharePoint, and OAuth is used to allow K2 to perform actions on behalf of the SharePoint user. The app requests the level of permission it requires, and these can only be granted by someone with that permission level.

How K2 uses OAuth

OAuth uses a token system to manage sessions. There are two token types used, access tokens and refresh tokens.

Access Token

The K2 app uses the access token when first interacting with SharePoint resources and a token is not already cached. K2 stores the access token with the expiration value, and if the token has expired, or is about to expire in the next 60 seconds, then the refresh token is used to request a new access token (see below). In SharePoint 2013/2016, access tokens are good for 12 hours. Access tokens are used to create a client-side object model (CSOM) ClientContext that identifies the user and authorization level for the particular action.

Refresh Token

The K2 app uses the refresh token to request a new access token without prompting the user or an administrator to click Trust again. The K2 app updates the stored refresh token with every request. A refresh token is good for 6 months after creation.

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 in order for the user to authorize the creation of the access and refresh tokens. The app communicates with the K2 server and receives a No Token condition. It then initiates the Trust dialog between the K2 system, the SharePoint system, and the backend identity and authentication servers (Security Token Services and Active Directory, typically).

Image Data Flow

The K2 app (1) sends an authentication request through the broker layer (2) to the K2 server (3). The K2 server then interrogates the database (4) for an access token. If an access token is not stored for that user (5) then it returns the request (6) with the No Token condition (7). K2 smartforms then initiates (8) the trust dialog with SharePoint. If the user selects to Trust the K2 app (9), a trust request is then sent to the K2 server (10). The K2 server sends a trust request (11) to the STS (12), which authenticates the user using Active Directory and SharePoint (13-16), and returns an access token through the Trust site (17) to the K2 server (18). That access token is then stored in the database (19) and a valid token condition is then returned to K2 smartforms (20-22).

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:

Image Data Flow

The K2 app through K2 smartforms (1) sends an authentication request through the broker layer (2) to the K2 server (3). The K2 server then interrogates the database (4) for an access token. The access token that is stored in the K2 Database for that user (5) is returned through the broker (6) to SharePoint (7). SharePoint then uses the token to authenticate the action, and SharePoint data is then returned to K2 smartforms (8-9) and displayed in the K2 app.

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. This takes place from within the K2 server.

Image Data Flow

The K2 app through K2 smartforms (1) sends an authentication request through the broker layer (2) to the K2 server (3). The K2 server then interrogates the database (4) for an access token. The access token that is stored in the K2 Database for that user has expired so an Expired Token condition is returned to the K2 server(5). The K2 server initiates a Refresh Token request through the Trust site (6) to the STS (7). The STS issues a new Access Token (8) which is returned to the K2 server (9) and stored in the database (10). That is returned through the broker (11-12) to SharePoint (13). SharePoint then uses the token to authenticate the action, and SharePoint data is then returned to K2 smartforms (14-15) and displayed in the K2 app.

OAuth and Claims

OAuth is NOT a replacement for claims-based authentication; the OAuth token system is a way to provide access to a calling application for an already authenticated and authorized user. K2 users login via an Identity Provider (IdP)/Security Token Service (STS) which issues a Security Assertion Markup Language (SAML) token containing the user’s identity claim. That identity claim is used to uniquely identify that user in both SharePoint and K2.

While using OAuth, K2 relies on the configuration of a K2 user manager to provide authentication and user and group resolution for identity stores such as Azure Active Directory, SharePoint Site Collection Groups, Active Directory, SQL, LDAP or custom/in-house directory stores. K2 provides the ability for incoming claims-based authentication through configuration of mappings between claims-based identity providers and K2 user managers and more specifically the user’s identity claim.

On-Premises vs Online

The authentication path of the OAuth token system for K2 in the cloud is different than using K2 on-premises. The following diagram demonstrates the three-legged path between the K2 App, Azure AD and Microsoft 365/SharePoint Online vs the K2 app to SharePoint path used on a local system. This on-prem communication uses a high-trust, certificate-based communication path from the K2 server to the SharePoint server, which is sometimes referred to as server-to-server (S2S). This is one of the reasons why K2 needs to install a certificate for SharePoint on-premises integration.

The authentication path of the OAuth token system in a hybrid environment (online and on-premises) adds the three legged path between the K2 App, Azure AD, and the on-premises SharePoint server.

K2 for SharePoint Settings

The trust request for OAuth is presented when first adding the app to the SharePoint app catalog.

The K2 for SharePoint App must be added to the app catalog and the Registration Wizard run before it can be deployed and activated to site collections served by the app catalog.

The Registration Wizard creates the App Only (administrative) token that the K2 app uses to communicate securely with SharePoint. The Registration Wizard shows a list of items it is creating at the time of registration.

You can use the K2 Management site to modify the OAuth configuration, or to delete OAuth tokens. See OAuth in the K2 Five User Guide for more information.