With Claims-based Authentication (CBA) there are many moving pieces that must fit together correctly for a user's unique identity to flow from one system to another. Due to the complex nature of the inner workings of Authentication things can and do go wrong. This article will help you troubleshoot CBA issues with practical and theoretical advice along with best practice tips learned from real-world experience.

Table of Contents

Articles in this Series

Approaching Troubleshooting

More often than not, when something is not working correctly it means that the connections between the various systems has not been made correctly or that the information being passed through those connections does not match what the receiving end is expecting.

It's an absolute requirement to have a topology diagram that describes the various pieces of the puzzle. Without this overview you will not be able to troubleshoot your configuration or have anyone else help you troubleshoot it. The topology is the starting point of any Authentication project and should include all the necessary information like endpoints and thumbprints. Some configuration happens automatically for you when adding the K2 for SharePoint app to a SharePoint site because they are well-known endpoints and certificates, such as those from trust.k2.com and AD/Azure AD. However, if you have a custom STS or even a custom flow that is handled through an internal AD FS server, the configuration is manual.

Image

The reactionary method of plugging in various values to the various configuration columns may get you through little bumps in the road, but you will not have a good understanding of what the true identity flow is even if you get it working. This approach will only take you so far.

A better approach is to sit down with pen and paper (or Visio or your topology diagramming tool of choice) and map out your environment, gathering all of the required information first so that you have a good understanding of how you think it works. With this knowledge and pre-understanding, your efforts will be rewarded with less frustration. Use this approach when thinking about and implementing the guidance in this article.

For the purposes of this article, we'll use the Denallix 6.1 core and point out the various values you'll need to know for configuring an environment that has K2 (all components), SharePoint 2013 on-prem with two web apps: one for Windows and one for Claims (via an AD FS Trusted Provider and AD FS).

SharePoint 2013 and SharePoint 2016 are similar in design and underlying authentication, so any mention of SharePoint 2013 can be substituted with SharePoint 2016.

Image

What follows are the details of how all of the pieces fit together on the Denallix core and where to find the values that are configured.

Portal (Claims) Authentication Setup

In the SharePoint 2013 web app that is setup for claims-based authentication, the ADFS Trusted Provider is chosen (along with Windows) for authentication. The Trusted Provider configuration allows SharePoint to trust users coming from AD FS (in this case AD users, but they could be from any Identity Provider supported by AD FS).

Image

AD FS Relying Party Trusts

For K2 to trust the same users from AD FS that SharePoint does via the Trusted Provider mechanism, you must configure the Relying Party Trusts in AD FS Management for each K2 site as follows:

Image

Setting up the claim rule for each of the Relying Parties ensures that K2 has a way to map claims inside the token to a unique user value, such as UPN. This is contained within the Identity Claim. Inside the Identity Provider Claim is the value that K2 uses to know which claim is coming in and what security label to map the claim to.

Image

Before you can use these values you must create an Issuer entry in the Manage Issuers form.

Image

To get the thumbprint of your AD FS server signing certificate, go to AD FS Management and expand the Service node. Then click on Certificates and look for the primary Token-signing certificate (you may only see one – choose that one). Right-click the certificate and select View Certificate. On the Details tab select Thumbprint and copy the value.

Image

The thumbprint has spaces every third character. Eliminate these spaces and convert all alphabetical characters to uppercase. You can then use this thumbprint in the Manage Issuers form.

You can write a function in Excel to clean up the thumbprint. Paste the thumbprint into a blank workbook in cell A1. You'll need a new function as follows:

Function CleanThumbprint(thumbprint)

    CleanThumbprint = Replace(thumbprint, " ", "")

End Function

In Excel press Alt-F11, insert a new module in the workbook and paste in this function code. Press Alt-F11 to get back to Excel and in B1 type in the following function:

=UPPER(CleanThumbprint(A1))

Image

Then copy that value out of Excel to use in your Manage Issuers form.

Once you have the Issuer created with the Manage Issuers form, you can use the values from the AD FS claims rules (which you configured using AD FS Manager) to establish the trust, which is configured with the Manage Claims form. 

Image

Assume that all configuration values are case-sensitive as well as space-sensitive.

K2 Installation Issues

There are a few things that are helpful to know before you begin installing K2. This section describes these issues and what you need to do to address them. This applies only to K2 Five & K2 blackpearl customers.

Host Headers & Certificates

When installing K2 you need to be aware of the IIS applications that K2 installs, namely:

  • AutoDiscover: The AutoDiscover service that is used by different tools but mainly used by the K2 for SharePoint Registration Wizard when supplying a K2 URL.
  • Designer: The K2 Designer site where Forms, Views and SmartObjects can be designed.
  • K2Api: The API used by the K2 Mobile app to retrieve and action tasks.
  • K2Services: The web services that wrap the K2 workflow client, allowing you to call into the K2 server via WS, REST or WCF in order to work with tasks from a custom application. Also includes the Sync service which is used by the K2 Mobile app.
  • Runtime: The SmartForms Runtime site.
  • RuntimeServices: Deprecated services used for SharePoint 2010 integration.
  • SP15EventService: The service called by a SharePoint site when SharePoint list and library events fire, usually to start a workflow.
  • ViewFlow: The View Flow service that graphically displays the current state of a workflow instance.
  • Workspace: The K2 Workspace which includes the worklist, reports, SSO configuration and Management features.

A best practice recommendation is to use a pre-configured host header with a trusted root authority SSL certificate for all K2 sites.

On the Denallix core, you will find that there's a single IIS site that hosts all of these applications, and it's configured with a host header and SSL using a purchased wildcard certificate. This is a recommended best practice as it ensures that your bindings are setup and controlled by you (vs. the K2 installer) and the service can be called by SharePoint Online events (see the Certificates sidebar below for more information on using wildcard certificates).

Image

If you have Web Front Ends (WFEs) that host SmartForms sites, make sure that you copy the certificate to the machines hosting those sites as well.

When purchasing a certificate it is best to purchase a wildcard cert. These allow you to use the certificate for multiple sites/apps. You should be aware, however, that they can only be used for single-level subdomains. For more information see https://en.wikipedia.org/wiki/Wildcard_certificate

The SP15EventService receives events from SharePoint 2013/2016 and SharePoint Online when you've configured a workflow that starts with an event (List Item Added, Document Updated, etc.). If your SharePoint site is an on-premises site the service does not need to be configured with SSL and, if it is, does not need a root authority certificate. However, if you're integrating with SharePoint Online it MUST be configured with an SSL certificate from a root authority or SharePoint will not call the endpoint. 

Identity Provider Issues

When thinking about where your user information is coming from, in particular in a claims-based environment, you must split apart the Identity Store (aka Identity Provider/IdP) and the Secure Token Service (STS). The first one is where and how user information is stored. The second is the service that takes that information and wraps it in a format that K2 can consume, namely a claims token.

Image

There are many examples of this pair of technologies:

Identity Provider (IdP)

Secure Token Service (STS)

Azure AD

Access Control Service (ACS)

Active Directory

Active Directory Federation Services (ADFS)

LDAP

Active Directory Federation Services (ADFS)

Facebook/Google/Twitter

ACS/ Onepass/Okta

 

For custom identity stores and/or STSs, your pairings will look different. It is critical to understand exactly where the token is coming from and what it contains. For more information about exactly how K2 trusts IdPs and consumes tokens from STSs, see Claims-based Authentication in K2.

Once you have a clear idea of what these two are, draw them out. Many times you'll have multiple Relying Parties that need to do something with a token, K2 being just one of those relying parties. The key thing to remember is that you must map out specifically the trust that needs to be configured, how that trust is configured, and what piece of information is going to serve as the user's identity contained within the claim.

When configuring claims mappings in K2 it is critical that you match the case for all configuration values as they are cAsESenSitiVe. Always check and recheck that your values in K2 are 100% in line with your values in the source system or the trust flow will not work.

When using third party or custom providers, for K2 to consume the claims token and set the correct cookie, the headers on the token must be something that the Windows Identity Framework (WIF) can handle. If WIF cannot handle the token then K2 cannot handle it either.

SharePoint Issues

This section is meant to guide you in your configuration of and integration with SharePoint 2013 on-premises and SharePoint Online. There are many issues and corresponding best practices outlined here that may require you to do further reading and research. Use the links provided to help you work through the issues.

General Issues

You should always install the K2 for SharePoint app from the installation media. The K2 for SharePoint app in the SharePoint store can be used however it's a best practice to manually upload the correct app to the app catalog for the tenancy (for SharePoint Online) or to the app catalog associated with the web app containing the site collections needing K2 integration (for SharePoint on-prem).

SharePoint Common Consent allows a Tenant/Global Administrator to trust the K2 for SharePoint app once for the tenancy/app catalog, and then users are not prompted to trust the app. The account used the first time the app is registered is saved as the Admin OAuth token associated with the K2 Service account. This account needs permissions on all the site collections where K2 will be registered regardless of the user that runs the Registration Wizard thereafter. If you do not use a Tenant/Global Administrator's account you will receive an Access Denied error similar to the following:

Access denied. You do not have permission to perform this action or access this resource. Failed to initialize the Context:[SharePoint URL]

Certificate Issues

Be aware of SSL requirements and certificate update implications to keep K2 integration functioning as expected.

Remote Events

It is a best practice when using SharePoint Online (and technically the only configuration that works) to configure your K2 SP15EventService to use SSL with a root authority certificate. If SharePoint Online sees that the SSL connection to K2 is not verified by a trusted root authority certificate it will cancel the event call, meaning that K2 will not receive the event from SharePoint and the workflow will not fire.

Certificate Expiration

In the event that your STS certificate expires and you have to renew it, you must follow the guidance at Changes To Know About When Your SharePoint STS Token Signing Certificate Expires – the Impact to Your High Trust Applications (blog)

After following that guidance, take the following steps in K2:

  1. Remove the app from the site collection
  2. Delete all OAuth tokens using the Manage OAuth Tokens form in K2 Designer (System > Management > Security > Forms)
  3. Run the K2 AppDeployment.exe tool to fix the SPTrustedSecurityIssuer
  4. Add the app to the site collection
  5. Run the Registration Wizard

For non-SharePoint STS certificate errors, such as when a certificate for the SmartForms sites or other K2 sites expires, you must update the certificate in IIS. If it's a certificate that affects one of the claims issuers, such as the K2 self-signed certificate, you must update the claims issuer thumbprint that's associated with the certificate. To get the thumbprint of the new certificate, see How to: Retrieve the Thumbprint of a Certificate. Be sure to remove the spaces in the certificate before updating the thumbprint for the issuer.

App Catalog

You should not use the same app catalog for multiple SharePoint web apps. This can cause some potential permissions issues because the web apps will most likely have different permissions and may likely have different HTTP/HTTPS schemes. The best practice for these and other potential problems is to use a single app catalog per web app. This does, however, mean that you will upload the K2 for SharePoint app multiple times.

User Profile Service

The User Profile Service (UPS) in SharePoint must be configured and contain at least the users who will be using K2 integration, whether it's design time or runtime. SharePoint uses the UPS to validate OAuth tokens that are passed in, meaning that if the user information does not exist in the UPS then K2 cannot successfully use the user's OAuth token to query and update information in SharePoint.

Even if users can log in to SharePoint and can be issued an OAuth token, the UPS may not be configured correctly to validate those tokens.

To ensure that the User Profile Application (UPA) database, where UPS stores information, is populated correctly for a particular user, log in to SharePoint as the user in question and navigate to the following page: https:///_api/SP.UserProfiles.PeopleManager/GetMyProperties

This page returns all properties from the UPA database. The ones that must be populated for OAuth tokens to be validated are SPS-ClaimID, SPS-ClaimProviderID, SPS-ClaimProviderType, and SPS-UserPrincipalName.

Image

Image

Image

For information about using PowerShell to validate the UPA properties see Errors.

AD FS

When using AD FS as your user store and authentication mechanism, verify that your users are populated in the UPS. For more information about SharePoint UPS see Errors.

Distributed Cache

When using Distributed Cache there can be timeout issues and the cache may not be big enough to store all of the tokens. Fixing this is somewhat of a trial and error and you should not solely rely on the documentation of Distributed Cache.

Zones

If your web app has different zones, and each zone has a different URL, you can only use the K2 for SharePoint app from one of those zones. Because of this limitation, you should either A) not use zones or B) make sure that the users who need to design and/or run K2 forms are all in the same zone, and enable K2 for that zone with the associated URL.

To work around this issue, you may choose to employ host-named site collections for web apps that do not use host headers. Keep in mind that this does not point to the same content that zones allow you to do, but it may help you solve potential business scenarios. For an excellent blog on host-named site collection, see Kirk Evans' blog What Every SharePoint Admin Needs to Know About Host Named Site Collections.

Tools, Errors, and Tips

In this section, you will find tools, common errors, and tips that will help you identify problems and solutions when troubleshooting claims-based authentication and OAuth authorization issues.

Tools

  • Fiddler: Fiddler or a different network tracing tool like Wireshark, and even the tracing supplied by some browser's development tools, will help you determine what the network traffic looks like between K2 and LOB systems. To capture K2 Server service traffic setup a proxy using the  following these steps:
        1. Stop K2 server
        2. Open "C:\Program Files (x86)\K2 blackpearl\Host Server\Bin\K2HostServer.exe.Config"
        3. Add the following to the section. 

These sample values are from the K2 Denallix Core's Fiddler configuration – you must change these values to reflect the values in your environment.

    http://127.0.0.1:9999" usesystemdefault="false" />

        1. Restart the K2 Server and look for traffic from the K2 server, such as it checking the Exchange autodiscover service periodically.
        2. Remove this configuration when needing to run K2 Server as a service without Fiddler running, otherwise the K2 Server will be unreachable. The alternative to doing this is to run the K2 Server in Console Mode.

Errors

This section lists some errors and solutions or work arounds to them.

401 Errors

Failed to initialize the Context: The remote server returned (401) Unauthorized

This error is commonly presented as the following:

'Failed to initialize the Context: URL: https://portal.denallix.com Username: Error Details: The remote server returned an error: (401) Unauthorized. Method: SharePointService.initializeContext'.

Notice the highlighted portion where it calls out username but does not list one. Since the K2 for SharePoint Registration Wizard runs in the context of the app itself (using the OAuth app-only token), the error means that there is no user context established. Typically the issue is related to the K2 OAuth High Trust certificate used in the 2-legged OAuth scenario for on-prem SharePoint servers.

Ensure that the certificate used in SharePoint is the same as on the K2 server. On the SharePoint server, use the PowerShell command Get-SPTrustedSecurityTokenIssuer. Then compare the certificate with the thumbprint configured on the K2 server.

You must check the certificate in the Local Computer certificate store on all of the SharePoint servers to make sure the thumbprint is correct.  There are two K2 OAuth High Trust Certs in the following three stores, and you must check all of them:

  • Personal
  • Intermediate Certification Authorities
  • Trusted Root Certification Authorities

404 Errors

HTTP 404 errors can take a variety of forms, but most of the time this occurs because of one of the following:

  1. Inability to resolve the App domain back to the correct location, e.g. the SharePoint WFE or corresponding load balancer.
  2. The inability of the destination IIS server to resolve the App Domain and provided host header to a SharePoint site that can process the traffic.

 

For item 1 you need to put a random number in front of the URL you are using for the app domain, such as 123.denallixapps.com, and try pinging it. If it resolves to the IP address in use for the WFE or WFE Farm, then it's working correctly. 

Then ensure there is an empty binding somewhere on the WFE. If your SharePoint farm makes use of host headers then the app domain traffic will have nowhere to go. For item 2 you must add another SharePoint web application with no host header in order for this traffic to get through.

For more information see the following:

https://samlman.wordpress.com/2015/03/01/planning-the-infrastructure-required-for-the-new-app-model-in-sharepoint-2013/

Blank Pages

On occasion, you may see blank page issues when browsing to a newly-added app or running the K2 for SharePoint Registration Wizard. To work around this problem do one or more of the following.

  1. Try to open the site from a different machine (in other words, open the site remotely)
  2. Try a different browser (Chrome or Firefox)
  3. Add all URLs to the intranet zone in Internet Options > Security > Local intranet:
  • K2 Application Sites  (SmartForms, Workspace  - ViewFlow and Identity applications)
  • SharePoint sites (*.sharepoint.com for SharePoint Online)
  • SharePoint app domain sites (*.[appdomain])
  • Microsoft authentication sites (*.microsoftonline.com and *.windows.net for SharePoint Online)
  • K2 authentication sites (*.k2.com for SharePoint Online)
  • Authentication Provider sites (ADFS endpoints etc.)
  1. Put the browser in debug mode and look for JavaScript errors

SharePoint User Profile Service

You may also find that different 401 issues can be solved by correct population and configuration of the User Profile Service (UPS).

The following K2 Help link provides steps for verifying that a SharePoint user profile service application is configured and running, and that profiles are present for all users.

http://help.k2.com/onlinehelp/k2forsharepoint/icg/current/default.htm#Install_Topics/Maintenance/Troubleshooting.htm

To dig in and verify that the properties needed are populated in the UPS, you can run and view the output of the following PowerShell script:

#export UPS

$siteUrl = https://[SharePointSiteURL]

$outputFile = "c:\splogs\sharepoint_user_profiles2.csv"

Add-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue

$serviceContext = Get-SPServiceContext -Site $siteUrl

$profileManager = New-Object Microsoft.Office.Server.UserProfiles.UserProfileManager($serviceContext);

$profiles = $profileManager.GetEnumerator()

$fields = @(

            "SID",

            "ADGuid",

            "AccountName",

            "SPS-UserPrincipalName",

            "DstinguishedName",

            "Domain",

            "ResourceSID",

            "SID",

            "FirstName",

            "LastName",

            "PreferredName",

            "UserName",

            "SPS-SipAddress",

            "SPS-ClaimID",

            "SPS-ClaimProviderID",

            "SPS-ClaimProviderType"

                       )

 $collection = @()

 foreach ($profile in $profiles) {

   $user = "" | select $fields

   foreach ($field in $fields) {

     if($profile[$field].Property.IsMultivalued) {

       $user.$field = $profile[$field] -join "|"

     } else {

       $user.$field = $profile[$field].Value

     }

   }

   $collection += $user

}

 

$collection | Export-Csv $outputFile -NoTypeInformation

$collection |  Out-GridView

Change the [SharePointSiteURL] and output location before running.

If you're using AD FS or Forms or other non-AD user accounts the following PowerShell script can be used to verify if a valid user profile can be found for a specific user:

Set-ExecutionPolicy Unrestricted

Add-PSSnapin microsoft.sharepoint.powershell -ErrorAction:SilentlyContinue;

$user = Read-Host 'Find Account'

#Load SharePoint User Profile assemblies

#[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint")

#[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.Office.Server.UserProfiles")

 

#Get Context

$serviceContext = Get-SPServiceContext -Site "https:// [SharePointSiteURL]"

 

#Instantiate User Profile Manager

$userProfileConfigManager = New-Object Microsoft.Office.Server.UserProfiles.UserProfileManager($serviceContext);

 

#Get All User Profiles

$profiles = $user.GetEnumerator();

 

#Loop through all user profiles and display account information

foreach($profile in $profiles)

{

    if ($profile.AccountName.Contains($user))

    {

        Write-Host "AccountName:" $profile.get_Item("AccountName");

        Write-Host "SPS-UserPrincipalName:" $profile.get_Item("SPS-UserPrincipalName");

        Write-Host "SPS-ClaimProviderType:" $profile.get_Item("SPS-ClaimProviderType");

        Write-Host "SPS-ClaimID:" $profile.get_Item("SPS-ClaimID");

        Write-Host "SPS-ClaimProviderID:" $profile.get_Item("SPS-ClaimProviderID");

        Write-Host "UserName:" $profile.get_Item("UserName");

        Write-Host "WorkEmail:" $profile.get_Item("WorkEmail");

    }

Change the [SharePointSiteURL] with the value of your SharePoint site. Note that the input value for Find Account is case sensitive.

In addition to the above error, you may run into a 401 error where users that are added via an AD group to an on-prem SharePoint 2013 group are not resolved. See KB001627 – Known Issue when using OAuth with On-Premises SharePoint Farms. To resolve this problem, add an audience in UPS for the AD group so that SharePoint can properly resolve the AD group membership.

SharePoint Logging

If you need definitive proof that something is wrong with the UPS you can turn on advanced logging in SharePoint.

You can do this from Central Administration or from PowerShell for central admin follow this

https://sharepointv15.wordpress.com/2012/07/23/setting-up-sharepoint-2013-logging/

For PowerShell you can see what they are currently set to:

Get-SPLogLevel

Change the log location (to put it someplace easy to remember):

Set-SPDiagnosticConfig -LogLocation D:\DiagnosticLogs

The syntax is as follows:

Set-SPLogLevel -TraceSeverity {None | Unexpected | Monitorable | Medium | High | Verbose | VerboseEx} -EventSeverity {None | Information | Warning | Error | Critical | Verbose} [-Identity ] –Verbose

Set-SPLogLevel -TraceServerity verbosex

A sample of this is:

Set-SPLogLevel -identity 'SharePoint Server:User Profile' -EventSeverity Verbose -TraceSeverity Verbose

 

Then run:

Clear-SPLogLevel

 

It is easier to work with the ULS log when issuing a New-SPLogFile command before and after reproducing the error. This creates a new log file and limits the amount of data in the file.

If you run a SharePoint farm with many WFE you will need to run a merge command to collect all the logs across the farm. Something like the following:

Merge-SPLogFile –Path c:\temp\mergedlog.log" –Overwrite -StartTime "07/09/2017 12:00" -EndTime "07/09/2017 12:59"

Replace the dates and times as appropriate.

Certificate Errors

There may come a point where the SharePoint STS certificate expires. This can have a drastic effect on all apps that use high-trust communications between SharePoint on-prem and the app server, such as K2. For more information see https://samlman.wordpress.com/2015/03/02/changes-to-know-about-when-your-sharepoint-sts-token-signing-certificate-expires-the-impact-to-your-high-trust-applications/comment-page-1/

 

The error you receive is similar to the following:

The remote server returned an error: (401) Unauthorized.Failed to initialize the Context: URL: https://portal.denallix.com Username: Error Details: Method: SharePointService.initializeContext x-ms-diagnostics : 3000003;reason="Invalid audience Uri '00000003-0000-0ff1-ce00-000000000000/portal.denallix.com@5c89ac77-e67f-4752-8edc-9714ba9f45d0'.";category="invalid_client" SPRequestGuid : d8f61b9d-24ac-005d-6a17-f6536ea07698

The GUID value in bold is the old SharePoint authentication realm.

To correct this you must take the following steps:

  1. Remove the app from the site collection
  2. Delete all OAuth tokens using the Manage OAuth Tokens form in K2 Designer (System > Management > Security > Forms)
  3. Run K2 AppDeployment.exe to fix the SPTrustedSecurityIssuer
  4. Add the app to the site collection
  5. Run the Registration Wizard

For non-SharePoint STS certificate errors, such as when a certificate for the SmartForms sites or other K2 sites expires, you must update the certificate in IIS. If it's a certificate that will affect one of the claims issuers, such as the K2 self-signed certificate, you must update the claims issuer thumbprint that's associated with the certificate.

To get the thumbprint of the new certificate, see How to: Retrieve the Thumbprint of a Certificate - MSDN. Be sure to remove the spaces in the certificate before updating the thumbprint for the issuer.

AAD Authentication Problems

In some instances, even after you establish trust between K2 & AAD using a Global/Tenant Administrator account, other people cannot authenticate with AAD to access K2 sites or K2 Mobile. You can manually reconfigure the K2 admin consent process by substituting your client ID and redirect URL in the following Microsoft Online URLs:

  1. https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fgraph.windows.net&client_id={YOURCLIENTID}&prompt=admin_consent&redirect_uri={YOURREDIRECTURI}
  2. https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fgraph.windows.net&client_id={YOURCLIENTID}&prompt=admin_consent&redirect_uri=https%3A%2F%2F{YOURREDIRECTURI} %2Fidentity%2Fauthorize%2Foauth%2F2
  3. https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fgraph.windows.net&client_id={YOURCLIENTID}&prompt=admin_consent&redirect_uri=https%3A%2F%2F{YOURREDIRECTURI}%2Fidentity%2Ftoken%2Foauth%2F2
  4. https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fgraph.windows.net&client_id={YOURCLIENTID}&prompt=admin_consent&redirect_uri={YOURREDIRECTURI}

Tips

Presented here are a series of tips that may make your configuration and troubleshooting easier.

Tip 1: Console Mode

Run the K2 Server in Console Mode to see the immediate output of the claim when it's opened (cracked). You can view this in the K2 server logs but it's easier to see it when it comes through in real time. You can also see OAuth tokens and errors come through in real time.

Tip 1 Scenario

K2 has been configured to use both the K2 Windows STS and AD FS for authentication.  Logging into to Designer using the K2 Windows STS is successful but logging in using the AD FS issuer fails with the following error:

Image

The SAML token was verified successfully, but a return type mapping could not be found. Please ensure that you have configured the K2 server as specified in K2 Help: Installation and Configuration > Configuration > SharePoint > Claims-based Authentication.

To troubleshoot this, extract the ArrayOfClaimsCollectionData XML from the K2 server console or log file and compare it with Claim Type Mapping for ADFS that is configured in K2.

To see the K2 Claim Type Mapping configuration, login to the K2 Designer using the K2 Windows STS and run the Manage Claims form (All Items > System > Management > Security > Forms).  (If you do not see the System category you need to click the Show: (All) link at the bottom left-hand corner of the K2 Designer and check the System Objects checkbox.) 

Click on the security label in question, in this case K2ADFS, and click the Edit button. Now compare the Identity Provider and Identity claims configured in K2 with the claims in the ArrayOfClaimsCollectionData from the K2 Server log file:

Image

In this case you see that the Identity Provider claim configured in K2 is included in the claim set sent to K2 as seen below, however, the Identity claim configured in K2 for ADFS is emailaddress which is not included in the ArrayOfClaimsCollectionData.  As seen in the ArrayOfClaimsCollectionData output below, there is an Identity claim for upn and name but not for emailaddress:

Image

To resolve the issue, using the Manage Claims form to update the Identity claim in K2 to use upn as the Identity Claim Type instead of emailaddress.  If you have configured the LDAP User Manager for the AD FS label based on the Identity claim being emailaddress, it may require further configuration changes.

Tip 2: SSL

Use SSL everywhere – for SharePoint, for K2, for LOB systems. Mixing SSL and non-SSL sites can make it extraordinarily difficult to get systems talking to each other properly. If you use HTTP, SharePoint must be configured to allow metadata exchange over a non-secure connection. This is not recommended and should only be configured in non-production environments. The PowerShell to configure this is as follows:

# Disable HTTPS requirement

$stsc = Get-SPSecurityTokenServiceConfig

$stsc.AllowMetadataOverHttp = $true

$stsc.AllowOAuthOverHttp= $true

$stsc.Update()

Tip 3: Large Organizations and the SharePoint UPS

When you have a lot of users in Active Directory, do not use AD Sync for the SharePoint User Profile Service (UPS). Instead, perform a selective import for the UPS to save on storage and complexity, only syncing users who will be using K2 and other items that require the UPS.

Tip 4: Avoid Multiple Zones & URLs in SharePoint

When possible, avoid multiple zones and URLs in SharePoint. Your configuration of SharePoint and K2 is much more straightforward if you do not have multiple zones and URLs for a single SharePoint web app. If you must use Alternate Access Mapping, see Known Issue: SharePoint Alternate Access Mappings may not work without Additional Configuration

Tip 5: Use AD FS 3.0

If you have the option, use AD FS 3.0 instead of an earlier version as it supports wildcard relying parties, meaning you can have a single entry for all K2-based sites (Designer, SmartForms runtime and View Flow) instead of separate entries for each web property. This assumes that your K2 sites are in the same main domain.

Tip 6: Using K2 STSs for SSO across two Farms

When using K2 in the DMZ, such as for a SmartForms runtime site, you should try to make that server a member of the main domain inside the firewall as identities will be able to flow properly from the DMZ server to the K2 server.

Along with this, you can point the site in the DMZ server to use the internal Windows and Forms STS that ship with K2. You can also use this tip to use a single STS for different farms. For example, let's say you have k2dev.skappit.local and k2.skappit.local (no 'dev' in the name).

The red box shows the current farm – k2dev.skappit.local – while the green oval shows a Fiddler trace that confirms it’s hitting the STS in the other farm – k2.skappit.local.

Image

On k2dev.skappit.local the Issuers must be changed (URI and thumbprint):

Image

On k2.skappit.local the realms must be updated to include the k2dev URLs:

Image

Tip 7: K2 Worklist is Empty in K2 Mobile

If you encounter a situation where the K2 Worklist is empty in the K2 Mobile app, and you have a DMZ scenario where your SmartForms runtime site is running on a DMZ server that is part of the main domain, you may have to setup delegation in IIS to flow the identity through to the K2 server so that it can resolve the user and render worklist items.

Take a look at Troubleshooting the K2 Mobile Apps for iOS and Windows Phone (K2 WebAPI) for more information on the scenario.

To correct this situation, try the following approach:

Go into the Configuration Editor in IIS on the K2Api application and set useAppPoolCredentials to True under the system.webServer > security > authentication > windowsAuthentication section after adding Negotiate as a provider for Windows Authentication.

Image

In Active Directory, configure constrained delegation for the identity of the application pool so that it can delegate credentials to the K2 Server:

Image

Once you do this, you should be able to get worklist items in K2 Mobile without further issue. You do not have to reconfigure K2 to use Kerberos instead of Windows (NTLM) for PTA.