In the first article in this series, you got an overview of authentication and authorization as it relates to K2. This document focuses on Claims-Based authentication (CBA) in K2.

Claims-Based Authentication is a consistent approach for applications to get and verify identity information across multiple systems. Whether it's inside an enterprise organization, through a different provider, or on the internet, claims-based authentication can simplify and standardize authentication logic and flow across various systems.

Not every organization needs CBA – some companies may be built entirely on applications that use Integrated Windows Authentication and Kerberos, and many of the benefits inherent in CBA are present in Kerberos. However, as soon as these companies introduce non-Windows apps, they need to federate identity management with a partner or web property, or they need to introduce SharePoint 2013/2016 into their environment, they must start down the CBA path.

Once you start down the CBA path, you must train your internal infrastructure team to be able to understand, configure and support CBA. This requires specialized configuration and specific know-how to troubleshoot CBA-related issues.

Table of Contents

Articles in this Series

The Benefits of CBA

Configuring CBA can be challenging, similar to configuring Kerberos in an enterprise environment, so why would someone want to go down the CBA route? The benefits are clear when you consider the following facts:

    1. Single Sign-On (SSO) makes it easy for users to connect to multiple systems without having to remember different usernames and passwords. Claims enables SSO by basically being the Integrated Windows Authentication for the internet. There's still quite a ways to go before this becomes a reality, but claims is on its way of providing this utopian ideal for at least the well-known identity providers such as Google, Facebook, and Microsoft. CBA also offers single sign-out, which most people don't even think about.
    2. Claims-based architectures (that is the location of the identity provider and the applications that use the identities supplied by that provider) can be highly decentralized. This means your applications can be built and maintained by a group that has no direct relation to the group maintaining the identities, and in many cases, they aren't even employed by the same company.
    3. Having CBA also means that you can have multiple identity providers for a single application. Another term for this is federated, meaning that each provider's identities can flow through a single access point that transforms the various claims types into a single, standard format that can then be used for an application. There are many companies in this Identity As A Service (IDAAS) business today, such as Okta, Ping Identity, Auth0, SiteMinder, OnePass, and Microsoft (via its Azure Access Control Service). None of these types of identity clearing house services would be possible without CBA. If you have a need to use one of these services other than Azure, consider using K2 Consulting Services.
  1. Application developers can remove themselves from the identity storage and management business to focus on their applications. Leaving identity management to the big guys probably offer better privacy protection and identity theft prevention insofar as their core business is keeping and protecting user information.

Lastly, it removes the need to create duplicate identities for every application.

What's in a Claim?

The term claim simply means a statement that a user is making about themselves. They're claiming that they are over 18 years old or that they like the color red, for example. It's fairly open-ended what a user can claim, or more accurately, what a provider knows about its users and what statements it can make about them. Ultimately, however, it's up to the application, aka the Relying Party, the one requesting the claims from the provider, to tell the provider what claims it needs. For example, K2 (the relying party) might tell Azure Active Directory (the identity provider) that K2 requires claims describing the groups that the user belongs to.

It's important to understand from the outset that K2 consumes claims but does not issue them. In technical terms, K2 serves as a relying party and is not a provider of claims. This is familiar to you if you've configured K2 to operate in a Windows (Active Directory) environment. K2 knows about users from Active Directory and can pass along information about those users to other systems, but those users and information about them do not reside in K2.

With claims it's very similar with one key difference: K2 converts user information from claims-based to Windows-based identities and does not pass along the claim to other systems.

Getting into the Flow

Let's start by reviewing a typical claims flow which looks something like this illustration (if you read the overview document this diagram should look familiar).

In this example, imagine that a user has clicked on a link in a SharePoint 2013 site that takes them to the Create K2 Application page.

Step 1: The user clicks a K2 artifact in a SharePoint site, triggering a request for the token requirements
Step 2: The Relying Party (RP) which in this case is the K2 server sends back the token requirements
Step 3: The user is directed to the Security Token Service (STS) in order to request the appropriate token. At this step they may be prompted to supply their credentials
Step 4: The STS validates the user with the identity store which is bound to an Identity Provider (IdP)
Step 5: The store packages up the appropriate claims based on the request and what information it can supply, and sends them back to the STS
Step 6: The STS wraps the claims in a token, signs it with a certificate and sends it back to the user
Step 7: The user sends the token to the K2 sever
Step 8-10: K2 resolves the token using the Windows Identity Framework (WIF) and sends the claims inside to the application
Step 11: The data the user originally requested along with an authorization cookie (to store the encrypted claim) are sent back to the user to complete the operation

Image

To describe this process in a different way, the RP, in this case K2, redirects to the STS. The STS does the authentication with the IdP to make sure the user is who they say they are, and then returns a token. This token only contains the claims that the RP says it needed.

The K2 Server checks to make sure it trusts the issuer by validating the thumbprint it has configured for the issuer against that issuer's certificate used to sign the token. In a claims world the token is always signed by the IdP to make sure the token isn't tampered with. K2 then cracks the token to get the user information out in order to determine who the user is and what claims or statements they are making about themselves.

It's all about Trust

The handling of claims from an issuer (the STS) by an application involves an explicit trust of that issuer by the application. This is different than other authentication approaches where the trust is implicit.

Also keep in mind that claims are typically signed and encrypted, meaning that you as an application developer receiving the claim can be assured that it came from a trusted issuer.

Lastly, remember that Trust is one-directional. The application trusts the issuer, and not the other way around.

There are a lot of abbreviations here, so let's take a moment to review in plain language what some of these terms are:

Security Token

XML document describing a user that is sent during an access request, often called a SAML token but a SAML token is a type of Security Token

Claims Provider

Partner in a federation that creates security tokens for users

Relying Party

Partner in a federation that consumes security tokens for providing access to applications

Claims

Statements about users that are sent inside security tokens

Name Identity Issuer

String that uniquely identifies an issuer to a relying party

When K2 opens the security token it is looking for two claims that must be in the configured claims mappings:

  • The IdentityProviderClaim: This is how K2 maps a user to a configured K2 label. This must exactly match the values that K2 has stored for it and must also be a static value that is the same for every user associated with that IdP. An example ADFS IdP claim is:
Type = "http://schemas.k2.com/identity/claims/identityprovider", Value = "ADFS")
  • An IdentityClaim, such as the following:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

WIF also requires the Name claim (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) to be in the token, and most systems do this by default. Microsoft Online (SharePoint Online, Azure AD, etc) utilizes the UPN (User Principal Name, such as joe@company.onmicrosoft.com) as the unique identity for users within a tenant. That value is populated in the Name claim as well and K2 maps that claim as the Identity claim. For more information see http://www.cloudidentity.com/blog/2013/02/13/the-name-claim-sometimes-it-s-the-simple-things/

The Architecture of Claims

K2 uses Microsoft technologies for handling claims. Claims in the Microsoft platform consists of a few key pieces of technology, namely:

  • WS* Extensions, such as WS-Federation, WS-Security, WS-Trust and a couple of others, form the backbone of the claims-handling capabilities on the Microsoft platform. This platform allows other platforms, such as K2, to handle claims in a standard way by incorporating these technologies
Any claim provider that does not support WS-Federation cannot be used directly by K2.
  • Windows Identity Foundation (WIF) is the set of .NET classes for implementing claims-based identity in an application.
  • Security Assertion Markup Language (SAML) is an XML-based standard protocol for exchange security tokens. K2 supports SAML tokens versions 1.1 and 2.0.

There are two different SAMLs that you may hear about. Most often it's the format of the protocol for exchanging tokens, and these are called SAML tokens. There's also a SAML 2.0 protocol which is often referred to as SAML/p, SAML/P or SAML-P (where the 'p' stands for protocol). However, WIF does not support these protocols which also means that K2 does not support it. Microsoft has added this for Azure AD tenants but at the time of this writing K2 does not support this protocol.

  • Active Directory Federation Services (ADFS) enables enterprises to use single sign-on (SSO) to authenticate users to multiple applications. Just like the cloud version of AD is called Azure Active Directory (AAD), the cloud version of ADFS is called Azure Access Control Service (ACS). They are both Identity Federation Providers which, through claims, allow identities from multiple providers to be consumed in a standard way. Identity Federation Providers, in contrast to Identity Providers, federate the issuance of claims from other IdPs. The main use of these types of services is to translate a claim from an IdP into a different format that K2 can consume, such as from a SAML/P or other format into standard SAML, but they also act as a single claims issuer for multiple providers.

Image

Configuration and Mechanics

With this knowledge of claims let's take a detailed look at how K2 configures and uses claims, and what you might have to do manually. It's important to understand first what the built-in STSs are doing.

The K2 STSs - WindowsSTS and FormsSTS

The WindowsSTS and FormsSTS are both available out of the box and are provided for flexibility when integrating K2 with different IdPs. These STSs are a required configuration of K2 web sites (K2 Designer, K2 smartforms runtime and View Flow) when claims tokens are involved in authenticating users. This means that the authentication settings for the IIS site that hosts the main K2 sites is set to Forms and Anonymous Authentication by default.

Image

The WindowsSTS is a wrapper for a Windows token. It's similar to setting up AD FS that uses Active Directory for storage of user information but doesn't allow as much configuration as you get with AD FS Management. In addition, with the Windows STS there's an implicit trust of Windows tokens on the same domain so the amount of checking and verification is less than with AD FS. The key features of the Windows STS are as follows:

  • Automatic login of the current user that hits the STS, wraps it in a claim and returns it to the RP
  • Designed mainly for K2 sites to keep configuration at a minimum (K2 designer/SmartForms runtime/K2 View Flow)
  • If you have ADFS in your environment you don't need the Windows STS
    • As long as the RPs are in the same domain, with ADFS 3.0 you can have a single realm with multiple audiences instead of having multiple realms for a PowerShell do to this see Appendix B: PowerShell Script for AD FS Configuration. For more about realms and audiences see Realms and Audiences
    • This works on wildcards and the domain must match across all realms

The FormsSTS was initially created to do SQL login processing but it can be used for other scenarios. The manner in which the FormsSTS processes your login information is slightly different than the WindowsSTS because it must map your information to a particular IdP. Once it finds you, it associates you with that label and fully logs you in, caching your identity in the process. When configuring the claims mappings for the FormsSTS, you should only use the Security Label section if you want to force a mapping to a particular security label.

Image

You specify an original issuer of SecurityLabelClaim, give it a type of http://schemas.K2.com/identity/claims/{YourSecurityLabelName} and a value of your security label. In the above example replace CustomSecurityLabel with the security label that forces the mapping of this claim to a particular label.

Host Headers and the built-in STSs

When you want internal and external users connecting to the same site and you have site URLs such as k2intra.denallix.com and k2.denallix.com, you should map them to the same realm. Outside of SharePoint, based on the incoming URL, they are routed to the correct issuer (internal or external). Configuring them with the same realm means that your users won't see both issuers in the login dropdown which can cause some confusion.

SSL-Offloading, where your decryption of SSL traffic happens on a different server, may result in 404 errors. This means that your reverse proxy has not been setup correctly for the K2 sites. Although the KB article is specific to F5 load balancers, the same issues apply to any SSL offloading scenario. See Configuring SSL-Offloading with F5 load balancers and K2 (http://help.k2.com/kb001679) for more information.

How SharePoint and K2 Work Together

While this discussion focuses on SharePoint, the principles discussed here apply to any LOB system that uses claims.

When you add the K2 for SharePoint app to a SharePoint site, you have to walk through the registration wizard in order to configure the app with a K2 server. Automatic configuration is supported when your users are coming from AD or AAD (in the case of a SharePoint Online/Office 365 instance). If you have Forms-based users or users from a Trusted provider you must manually configure K2 to trust those issuers.

On the second page of the registration wizard you see something like the following:

Image

You can see under the Claims section of this page that there are two different labels setup for this SharePoint Online instance, one for the K2 Windows STS issuer and one for the K2 Trust for Azure AD issuer. These issuers can be configured automatically for K2 because they are well-known and do not change. (The OAuth configuration is covered in the Outbound Authorization and OAuth in K2 article).

Active Directory and Azure Active Directory issuers are configured automatically, but if SharePoint is setup to use a Forms-based or Trusted provider, these must be configured manually. Whatever issuers you've setup in SharePoint, K2 must also be a RP for the issuer of those claims. Some configuration is automatic and some is manual.

You may be wondering why, with SharePoint, K2 can't just crack the claim and get the user information out of it. It's because the only RP for SharePoint's STS is SharePoint itself, which, in turn, means that for SharePoint, any app that needs user information from the claim must be an independent RP for the original issuer, hence the additional configuration. You'll see in the following forms that SharePoint doesn't appear, only Windows and Azure authentication values. This is because SharePoint is just a consumer (RP) of the claims and not the issuer. The handoff goes from SharePoint to the App Domain (more on that later), and then finally to K2. Each of these entities must be configured to trust the same issuer (or multiple issuers), and K2, based on the NII (NamedIdentityIssuer) value in the claim, figures out which issuer and claims mapping it's supposed to use for that value coming through.

Why does K2 for SharePoint need more configuration than other SharePoint apps?
You may be asking yourself, "why don't all SharePoint apps require this?" That's a good question. Although SharePoint passes an OAuth token to any and all apps to use for calling back into SharePoint from the app, K2, for the most part, doesn't use this OAuth token. This is due to the fact that K2 has its own web app (in fact, multiple apps) and must authenticate the user for its own purposes. There are instances that K2 operates within the app context and could use the OAuth token that it gets from SharePoint, but it must be its own RP for the IdPs configured in SharePoint, and establish those trust relationships, for scenarios that go beyond SharePoint.

In the K2 Management, you have access to forms that allow you to configure claims and OAuth, under Authentication > Claims where you can manage issuers and claims mappings.

Manage Issuers: Configuration information about each issuer that the K2 server trusts.

Image

Manage Claims: Configuration information about how issuers map to K2 security labels and what types of claims are used from the token.

Image

There's one more, Manage Site Realms, which is covered in the Realms and Audiences section.

Configuring a Claims Issuer

When you need to manually configure a claims issuer, it's extremely important to know what all of your values need to be before you attempt to configure it. Also remember that these settings are case-sensitive. Any errant values can cause strange errors if everything isn't exactly right, so make sure you have the correct values on hand before you start.

Troubleshooting Claims

When you think you have your claims configuration right but you're getting 401s, 404s and other numbered errors, it's time to look more closely at your configuration. This will be covered in greater detail in the troubleshooting article that is part of this series, but always keep in mind that claims configuration is all about matching a string. If the string can't be matched, or it's simply not ever getting through, your identity flows aren't going to work. Here are a few quick tips but also look at the troubleshooting article in this series:

  1. Try using 3rd party network monitoring tools such as Fiddler, WireShark or the browser's built-in tracing for seeing every network transmission.
  2. Look at the token value in the host server log file. This is written at the time the token is cracked when debug logging is turned on (for more information about turning this on see http://help.k2.com/kb000298). 
  3. Look in the database to see if the token has been cached. All validated tokens are cached in the HostServer.SecurityCredentialCache table in the ClaimsTokenXml column.
  4. If you see a WIF error 101 the issuer and the thumbprint do not match, which most likely means you're logging in from the wrong tenancy.

Make sure you get your thumbprint using PowerShell instead of copying it from MMC. For more information on how to do that see http://blogs.technet.com/b/tune_in_to_windows_intune/archive/2013/12/10/get-certificate-thumbprint-using-powershell.aspx

It's also helpful to have an accurate network topology diagram to share with your team and perhaps a K2 support representative so that everyone knows what the layout is, who needs to trust whom and with what certificate, and what the key IdPs, RPs and FPs (Federation Providers) are playing in the authentication flow.

Let's take a look at the typical values for a Windows AD claim configuration. Values in curly brackets – {} – are placeholders.

IdP

Active Directory

Issuer

WindowSTS

Name Identity Issuer

urn:office:idp:activedirectory

IdentityClaim

Original Issuer: AD Authority
Type: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

IdentityProviderClaim

Original Issuer: WindowsSTS
Type: http://schemas.microsoft.com/identity/claims/identityprovider
Value: WindowsSTS

User Token Identifier

i:0#.w

Group Token Identifier

c:0+.w

 

Azure Authentication

Type

IdP

Azure Active Directory

Issuer

K2 Trust for Azure AD

Name Identity Issuer

urn:federation:microsoftonline@{TenantGUID}

IdentityClaim

Original Issuer: https://sts.windows.net/{TenantGUID}/
Type: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

IdentityProviderClaim

Original Issuer: https://sts.windows.net/{TenantGUID}/
Type: http://schemas.microsoft.com/identity/claims/tenantid
Value: {TenantGUID}

User Token Identifier

i:0#.f|membership

Group Token Identifier

c:0-.f|rolemanager

Note a few differences in the above automatic configurations. The first one, Windows Authentication, can have static values for the Identity and Identity Provider claims as these are all on-premises values. For Azure AD, which is used for all identity for SharePoint Online sites, the tenant GUID is used in both the original issuer and the claim value to assure that there is a unique STS address for every SharePoint Online instance.

Note also the differences to the User and Group token identifiers. These are the values that typically come before the first or second pipe characters in the fully-qualified name in SharePoint. Whereas once you saw denallix\joe you'll now see i:0#.w|denallix\joe. That preface has some interesting meanings, mainly if it is an identity (i) or some other claim (c), the colon and 0 are always there, the 4th character in this case the hash or pound (#) means that it's a SharePoint logon name, and the last character means that it's a Windows-based (w) or a forms-based (f) identity. You'll find this last character is a (t) when a Trusted provider is configured. This is how claims manages users from multiple providers, and K2 uses these prefaces as a shortcut to determine what type of resolution to do. For a full list of all the various characters allowed in each position browse to https://msdn.microsoft.com/en-us/library/dn792518%28v=office.12%29.aspx

Configuring a Forms-based or Trusted Provider

You’ve read this far and you want to know what steps are required to configure your Trusted Provider to allow users from this identity store to be recognized by K2.

First off, you must have all of your values. Do you have the following information?

  • Issuer Name & Description
  • URI (typically you'll use the K2 FBA STS -- https://{K2 Site}/Identity/sts/Forms/wsfed – because this is the STS that will handle FBA and Trusted Providers)
  • The issuer's Thumbprint
  • The Original Issuer
  • The Identity Provider Claim, Type & Value
  • The Identity Claim & Type
  • The Realm and Audience

If you're using a custom STS and IdP, you must ensure that SAML tokens are issued in the 1.1 or 2.0 format and routed to K2 using the WS-Fed protocol.

Once you have all of these values, browse to the SmartForms in the K2 Designer and run the Manage Issuers form, clicking New to register a new Issuer. Check the Use For Login option if you want your users to be presented with the name of this issuer that they can choose when logging in to the K2 smartforms site, as in the following page:

Image

This page is only displayed if you have more than one issuer to be used for logging in. If you want to hide this page but still need multiple issuers, see Bypass Login Page when Accessing SmartForms.

You don't have to check the Use For Login checkbox for the label to be enabled from the claims flow-through from SharePoint, just if you want your users to be able to explicitly log in to the K2 Designer site. What this means is that if you have users that will only see forms and views inside a SharePoint site, you do not need to set the Use For Login option for that issuer (and K2 will still be able to get their information as long as the claims are setup properly). The beauty of this is that if you only have one group of users, say your internal users, who need direct access to the K2 Designer site, set only that issuer to Use For Login and the K2 Designer site won't even show the Select Login Method page.

The values in the next image are examples only and your values will be different.

Image

Once you have the issuer configured then you have to map the claims by using the Manage Claims form (below it has the title Edit Claim Type Mapping). Now remember, the only things you have to really worry about here is the Identity Provider Claim and the Identity Claim. However, you have to decide here what K2 label you're going to use for this issuer. For more information about registering a custom label, see http://help.k2.com/KB000186.

Image

Whatever you decide here for the label will prepend that value to users from this Identity Provider. You should have a single IdP mapped to a single label. You can have multiple claim type mappings using a single label, however for this to work in K2 the user manager must be able to resolve back to the IdPs. K2 will automatically configure claims like this for SharePoint 2013/2016, but this must be manually configured for other IdPs. For more information about dual authorization configuration in K2 see Multi-Authentication Providers.

When you have multiple claims mappings associated with a single label, you must use the Claim Type Info setting to let K2 know which claims mappings contain SharePoint users. This setting was introduced with the SharePoint 2010 integration when a Windows account was necessary for the K2 service account to connect to SharePoint. The Claims Type Info setting is used in this scenario for telling K2 not to use the mappings associated with the Windows claims mapping when resolving users in groups because the other mapping (AD FS or some other IdP) contained the user information.

In SharePoint this setting is used in the same capacity. Even though K2 trusts the issuers (STSs) directly, and there will typically be a single claim mapping per label, if the Claim Type Info setting is not true then users associated with that IdP will not be resolved from SharePoint groups. The recommendations for mappings associated with SharePoint are:

  • Have a single label per claim type mapping and always check the Claim Type Info setting
  • If you need to do multiple mappings per label, check the Claim Type Info setting for those claims mappings that contain SharePoint users
  • If you have multiple mappings and there are multiple SharePoint claim mappings, check each one

SharePoint group resolution happens when using the Synchronize Groups functionality from the K2 for SharePoint Settings page, when work is assigned to a SharePoint group during a client event, and when group resolution happens from the K2 server based on its configuration. If you wanted to test the resolution of groups use the following methods from the UMGroup SmartObject in the SmartObject Services Tester tool or K2 Management.

Image

The changes to the Claim Type Info setting may not happen automatically, so if you are testing this with the UM SmartObjects, refresh the cache and restart the K2 server after making a change to the Claim Type Info setting.


To refresh the user cache see Refresh the User Manager Cache. If you're working with SharePoint Online / Azure AD, the caching mechanism is different. See How Identities are Handled in K2 Cloud.

As with Claim Type Info, the User Token Identifier and the Group Token Identifier are only used when handling claims tokens from SharePoint.

Image

Realms and Audiences

There's one more form that is important to understand when you configure your claims in K2, and that is the Manage Site Realms form.

Image

A Realm is simply a key value that tells the STS what claims to put in the token. You may see realm URIs in the format of urn:sharepoint.denallix.com or something that looks more like a regular URL, such as https://k2.denallix.com/Designer/. It doesn't matter what format it's in as long as it's unique and has some claims associated with it.

Home Realm is reserved for future functionality and should not be used. If a value is configured for Home Realm it will not be used.

If you need to force a specific realm to be used when logging into the K2 Designer or to the SmartForms runtime site, you must edit the web.config file, changing the federatedAuthencation section to automatically login users with a specific IdP. 

You can see these same realms in the AD FS Management tool. They are called Identifiers here because they identify the calling application.

Image

You should create separate relying party trusts for each of the K2 web applications that may need to crack a claim and verify an identity, namely:

The K2 Designer (/Designer/), the SmartForms Runtime (/Runtime/) and View Flow (/ViewFlow). These web applications all understand and are configured out-of-the-box for claims authentication, and as such need to be configured as RPs in your STS (whether that's in ADFS or someplace else).

The Audience portion of the Realm is simply one or more URLs that are tied to a particular realm but that represent the same service. In most cases, you'll have a 1:1 mapping between your Realms and your Audiences, but you may have many URLs that are all tied to a single realm. If you access your SmartForms runtime site by both https://k2.denallix.com/runtime and https://dlx:81/runtime, for example, they must both be configured as audiences for your /Runtime/ realm.

What Does K2 do when it Cracks a Claim?

When a claim is presented to K2, the first thing it does is to crack it to figure out the UPN, for example i:0#.w|denallix\joe. Then it looks for the Identity claim and the Identity Provider claim. From these pieces of information K2 is able to determine that this identity is:

  1. An individual user
  2. A Windows-based user
  3. Should be mapped to the K2 security label (based on the original claims configuration)
  4. Has a domain of Denallix and an account name of Joe

For a full list of what these codes mean see SharePoint 2013: Claims Encoding (http://social.technet.microsoft.com/wiki/contents/articles/13921.sharepoint-2013-claims-encoding-also-valuable-for-sharepoint-2010.aspx

K2 also stores the tokens for valid users after it cracks them. If you ever had a need to look at the token you can use the SecurityManager API. The method is GetClaimsTokenXml(Guid credentialID).

Also, if you need to get the credential ID you can use GetCredentialID(string fqUserName).

At this point K2 knows everything it needs to handle this user internal to K2 and to, if necessary, impersonate the user to backend systems. SharePoint 2013 is different than most backend systems as 99% of the communication from K2 to SharePoint and back happens via the SharePoint 2013 service broker. This broker uses the SharePoint Client namespace (CSOM) and REST to communicate remotely with SharePoint, and it's configured to use OAuth as the impersonation method. More on what that means can be found in the Outbound Authorization and OAuth in K2 article that is part of this series.

Converting Claims Users to Windows Identities
Like SharePoint uses the WIF-installed Claims to Windows Token service to convert users from a non-Windows claim (SAML, X.509) to a Windows claim, K2 installs and uses a similar service called the K2 Claims to Windows Token Service.

This service is used in exactly the same manner to convert non-Windows claims to a Windows claim in order to handle internal communication and impersonation with backend systems, and can only be called from the App Pool account associated with K2 sites.

 

This service is installed on all SmartForms servers and needs to run with an account that has the Act as part of the Operating System policy right. It is NOT used by the WindowsSTS. For more information about this service see Delegation Settings to enable K2 Windows Token Service to impersonate using Kerberos

Show Me the Cookies

But before the claim is actually cracked, a Federated Authentication (FedAuth) cookie must be set in the browser session. You may or may not know that there are two ways in which Federated Authentication (aka claims-based authentication) can happen: Active and Passive. Active authentication is SOAP-based and Passive authentication is browser-based. Both are supported by WIF and K2 uses Passive authentication in the form of browser session cookies, aka FedAuth cookies.

Here is yet another diagram depicting the claims-based authentication flow, this time with an indication on when the cookie is written and some more details to complete the picture.

Passive federated authentication, and its corresponding reliance on cookies, is why K2 integration with SharePoint (and any other claims-based authentication integration) requires the use of cookies.

Let's take a look at a claims flow that has a little more detail.

Step 1: The user browses to the RP application.
Step 2: They are redirected to the IdP to be authenticated.
Step 3: If the user has not yet been authenticated by the IdP, the STS may present a challenge or redirect him to a login page to collect credentials.
Step 4: The user supplies his credentials.
Step 5: The user is authenticated by the STS.
Step 6: At this point, the STS issues a security token according to the sign-in request, and the sign-in response containing the token is posted to the RP via browser redirect.
Step 7: The RP processes the security token and authorizes access based on the claims it carries.
Step 8: If successfully authorized, the user is presented with the page he originally requested and a session cookie is returned.

Image

In this generic sample, the Web Site (RP) is SharePoint. K2 in this case would be another RP that sits alongside SharePoint, which SharePoint redirects to in an Inline Frame (IFrame) using the App Domain.

This communication loop can be traced using Fiddler or WireShark, and you can see the cookie contents in this case as well (read on for an illustration of this). When a cookie expires the user must perform the full loop again but when the cookie is valid the user is not challenged again for their credentials.

You've Been Framed

It's important to think about how SharePoint shows content from another domain, i.e. how does a K2 form appear inside SharePoint? It looks like a seamless operation when you've integrated K2 forms and views with a SharePoint list, but those forms and views are actually coming from the K2 server, not the SharePoint server. And this happens via IFrames with some help from the App Domain.

Let's say K2 is integrated with the Announcements list and SmartForms are used to replace the regular SharePoint forms. This means that when you click New, Edit or View you'll see a K2 form instead of a SharePoint form. How does this actually work though, because the form is coming from K2 not SharePoint?

When the K2 for SharePoint app is installed, it installs a couple of pages that are simply hosts for content originating outside of SharePoint and served by the K2 server. In this case the page that hosts the new form is called NewForm.aspx and lives in the K2Pages library. Its targetUrl property is set to the URL of the form created when the list was appified (when the list was integrated with K2). The URL also has a source property that points back to the list so when you click Save on the form it knows where to redirect.

The page itself is a blank page that loads the targetUrl value into an IFrame. There are a few other items in the K2Pages library, namely DispForm (the Display Form), EditForm, K2SharePointUserTaskForm and a couple of jquery files. These files along with the images and the app itself comprise the K2 for SharePoint app, which is why it's only a few hundred KB in size. Everything else that you see in SharePoint comes from the K2 server itself via IFrames.

There are some IdPs that do not allow you to IFrame without first logging in to them in a dedicated, non-framed window. The response header that these providers put on their login page is called X-Frame-Options:DENY. This can be altered to allow for SAMEORIGIN or an ALLOW-FROM uri, but the easiest way around this is to open the target in a new, dedicated window, login (or select the appropriate provider) and then refresh the original page.

This behavior can be seen with the K2 Worklist App Part when the AD FS login page has this option set.

Image

Image

The SharePoint App Domain

So that explains the IFrame, now let's briefly discuss the App Domain. Rather, it should be called the App URL because that's what you configure in SharePoint Central Administration. As you can see in the next page, SharePoint allows you to configure what your App URLs are going to look like. You set the domain and the prefix, and then SharePoint fills in the random number that is the App ID.

Image

This is where you get URLs that look like the following when you click on the K2 Application button.

Image

The full URL is as follows (without all the URL encoding so it's easier to read):

https://app-93832cf268b523.denallix.com/K2forSharePoint2/Pages/Application.aspx?formUrl=/Runtime/Form/K2 for SharePoint?SPSiteURL=https://portal.denallix.com&SPListId={C324795C-61CB-40FB-A9B7-85FB730A090A}&Source=https://portal.denallix.com/Lists/Announcements/AllItems.aspx

You can see the app domain is app-93832cf268b523.denallix.com. SharePoint assigns that number -- 93832cf268b523 – so that is your App ID. This allows SharePoint provide per-app security and to host content from another domain because it is pre-trusted with a wildcard certificate. The following diagram is from the MSDN article Configure an environment for apps for SharePoint (SharePoint 2013):

Image

The SharePoint App infrastructure is built on the idea of IFrames and App Domains, and as such, Microsoft came up with this architecture not only to avoid having users prompted by credentials each time they loaded an app, but to allow for security tokens to flow from SharePoint to apps via passive federated authentication (aka claims cookies). But that also requires that K2 (and any provider-hosted app) directly trusts the one or more IdPs configured in SharePoint.

Lastly, let's illustrate what a FedAuth cookie looks like using Fiddler to trace this interaction. The scenario here is that we have a document library on https://portal.denallix.com and we click on the K2 Application icon in the toolbar. You will see in the lines just above the highlighted line that there are a bunch of portal.denallix.com calls, a few of which are the appredirect.aspx (those lines in that gross yellow/green). Then the security token can be seen once it gets set on k2.denallix.com. Notice the FedAuth= line, that's the value of the cookie that contains the claims token. K2 cannot open that token unless it has the issuer's thumbprint, but it does because this is a Windows-based on-prem SharePoint site that was setup automatically with K2 during the K2 for SharePoint Registration.

Image

You'll also see the same thing from the two K2 STSs. In the following trace the Designer redirects to the STS, the STS validates the user, and then sends the token back to the Designer site in the form of the FedAuth cookie. You can see both the cookie and the referrer URL below.

Image

Conclusion

You've seen why and how CBA works, and some of the mechanics of the token flow. This gives you a better understanding of your K2 environment and can help you setup and troubleshoot your environments.

Appendix: PowerShell Script for AD FS Configuration

The following PowerShell script allows you to add an AD FS label for mapping claims.

   Write-Output "Configuring K2ADFS Label and Claims - Started"

    # ADFS Configuration

    Invoke-Sqlcmd -InputFile "C:\Resources\Configuration\K2\K2 User Managers\K2 LDAP User Manager (Trusted - Setup).sql" -ServerInstance . -Database K2

    Invoke-Sqlcmd -InputFile "C:\Resources\Configuration\K2\K2 Claims Config - ADFS.sql" -ServerInstance . -Database K2

    Write-Output "Configuring K2ADFS Label and Claims - Finished`n"

   

    Write-Output "Configuring ADFS Relying Parties - Started"

    function AddADFSRelyingParty([string]$name, [string]$realm)

    {

        # remove if exists

        $rp = Get-ADFSRelyingPartyTrust -Name $name

        if ($rp)

        {

        Write-Verbose "Removing Relying Party Trust: $realm"

        Remove-ADFSRelyingPartyTrust -TargetName $name

        }

 

        Write-Verbose "Adding Relying Party Trust: $realm"

        Write-Verbose "Add-ADFSRelyingPartyTrust -Name $name -Identifier $realm -WSFedEndpoint $realm"

        Add-ADFSRelyingPartyTrust -Name $name -Identifier $realm -WSFedEndpoint $realm

 

        # get the RP to add Transform and Authz rules.

        $rp = Get-ADFSRelyingPartyTrust -Name $name

 

        # transform Rules

        $rules = @'

        @RuleName = "Identity Provider Claim"

        => issue(Type = "http://schemas.k2.com/identity/claims/identityprovider", Value = "ADFS");

                                      

        @RuleTemplate = "LdapClaims"

        @RuleName = "Identity Claims"

        c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]

        => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",

        "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"), query = ";userPrincipalName,userPrincipalName,tokenGroups;{0}", param = c.Value);

'@

 

        Write-Verbose "Adding Claim Rules"

        Set-ADFSRelyingPartyTrust –TargetName $name -IssuanceTransformRules $rules

 

        # Authorization Rules

        $authRules = '=> issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "true");'

        Write-Verbose "Adding Issuance Authorization Rules: $authRules"

        $rSet = New-ADFSClaimRuleSet –ClaimRule $authRules

        Set-ADFSRelyingPartyTrust –TargetName $name –IssuanceAuthorizationRules $rSet.ClaimRulesString

    }

 

    AddADFSRelyingParty "SmartForms Designer" "https://k2.denallix.com/Designer/"

    AddADFSRelyingParty "SmartForms Runtime" "https://k2.denallix.com/Runtime/"

    AddADFSRelyingParty "SmartForms ViewFlow" "https://k2.denallix.com/ViewFlow/"

    Write-Output "Configuring ADFS Relying Parties - Finished`n"