Introduction to OAuth
What is OAuth
OAuth is a standard, simple, and secure authorization protocol that enables users to approve an application to act on their behalf without sharing their user name and password. It is an authentication standard that allows users to grant specific credentials for the sharing of resources from web, mobile and desktop applications. This enables users to share their specific private resources or data (i.e. lists, documents, etc.) that are stored on one site/application with another site/application.
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 a user to securely access resources without needing to continually login to those systems.
OAuth is used in K2 for SharePoint as part of the ‘App’ Model. In SharePoint 2007 and 2010 the K2 integration had to be installed on the SharePoint server. In SharePoint 2013, Apps are able to run outside of SharePoint, and OAuth is used to allow the K2 App 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 will use the access token whenever it interacts with SharePoint resources. 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 (this value is configurable), then the refresh token is used to request a new access token (see below). In SharePoint 2013, 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 will use the refresh token to request a new access token without prompting the user to “Trust It” again. The K2 App will update 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 dialogue will be presented in order for the user to authorize the creation of the access and refresh tokens. The app communicates with the K2 Host Server and receives the ‘No Token’ condition. It then initiates the Trust dialogue between the K2 system, the SharePoint system, and the backend identity and authentication servers (Security Token Services and Active Directory).
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. 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 dialogue 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 Host 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 Host 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 simply a way to provide access to a calling application for an already authenticated and authorized user. K2 users still login via an identity provider / Security Token Service (STS) which will issue 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 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 to using K2 on-premises. The following diagram demonstrates the three-legged path between the K2 App, Azure AD and Office 365/SharePoint Online vs the K2 App to SharePoint path used on a local system.
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 site. Note: The K2 for SharePoint App must be added to each site in SharePoint. Once trusted, the K2 for SharePoint App Registration Wizard presents a configuration screen to create the OAuth Resource.
The Registration Wizard creates the tokens that the K2 App will use to communicate securely with SharePoint. The Registration Wizard will then report back on the creation of these settings.
Use the K2 smartforms Authentication Management Settings page to modify the OAuth configuration or to delete OAuth tokens. See K2 smartforms Authentication Management Settings for more information.
