Configuration

Overview

K2 allows for the use of incoming claims from SharePoint 2010 claims authentication enabled sites. K2 must be configured to register the SharePoint Security Token Service (STS) certificates and map the incoming claims that contain user and group information to the appropriate K2 User Manager. This section explains the configuration settings required and how to determine them.

The configurations are added as a <configuration><sourcecode.security.claims> section in the K2HostServer.config file. The physical path to this file is [Installation Directory]\Host Server\Bin\K2HostServer.config.

Example
The following example is for the fictitious Denallix.com SharePoint claims based site on a single server with user mappings configured for Windows (Active Directory), Forms (LDAP) and a Trusted Provider (AD FS for LDAP).

Copy
<sourcecode.security.claims> <!-- The combination of issuers and claimTypeMappings allows K2 to ensure incoming claims are valid and have not been tampered with --> <issuers> <!-- An entry for each certificate (signing or encrypting) for a trusted STS --> <issuer name="SharePoint Security Token Service" thumbprint="8BD27388714EC92EA0433BE660BA7698430CE4FF" /> <issuer name="SharePoint Security Token Service Encryption" thumbprint="54722E70106DF64E48DD2FF2AFC8BC4F8DE231B1" /> </issuers> <claimTypeMappings> <!--K2ADFS Security/Role Provider for Trusted Provider--> <claimTypeMapping securityLabel="K2ADFS"> <!-- Claim that represents the system issuing the identity and role claims to be mapped to the K2 security label--> <identityProviderClaim originalIssuer="SecurityTokenService" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/identityprovider" claimValue="trusted:ADFS LDAP" /> <!-- Claim that represents the user for the K2 security label--> <identityClaim originalIssuer="TrustedProvider:ADFS LDAP" claimType="http://schemas.k2.com/identity/claims/name" /> <!-- Claim that represents the groups for the K2 security label--> <roleClaim originalIssuer="TrustedProvider:ADFS LDAP" claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" /> </claimTypeMapping> <!--K2 Security/Role Provider for Windows Authentication--> <claimTypeMapping securityLabel="K2"> <!-- Claim that represents the system issuing the identity and role claims to be mapped to the K2 security label--> <identityProviderClaim originalIssuer="SecurityTokenService" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/identityprovider" claimValue="windows" /> <!-- Claim that represents the user for the K2 security label--> <identityClaim originalIssuer="Windows" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/userlogonname" /> <!-- Claim that represents the groups for the K2 security label--> <roleClaim originalIssuer="Windows" claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid" /> </claimTypeMapping> <!--K2FORMS Security/Role Provider for Forms Authentication--> <claimTypeMapping securityLabel="K2FORMS"> <!-- Claim that represents the system issuing the identity and role claims to be mapped to the K2 security label--> <identityProviderClaim originalIssuer="SecurityTokenService" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/identityprovider" claimValue="forms:LdapMembershipProvider" /> <!-- Claim that represents the user for the K2 security label--> <identityClaim originalIssuer="Forms:LdapMembershipProvider" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/userlogonname" /> <!-- Claim that represents the groups for the K2 security label--> <roleClaim originalIssuer="Forms:LdapRoleProvider" claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" /> </claimTypeMapping> </claimTypeMappings> </sourcecode.security.claims>

Copy

<sourcecode.security.claims>

<issuers>
    
    <issuer name="SharePoint Security Token Service" thumbprint="8BD27388714EC92EA0433BE660BA7698430CE4FF" />
    <issuer name="SharePoint Security Token Service Encryption" thumbprint="54722E70106DF64E48DD2FF2AFC8BC4F8DE231B1" />
</issuers>
<claimTypeMappings>
    
    <claimTypeMapping securityLabel="K2ADFS">
      
      <identityProviderClaim originalIssuer="SecurityTokenService" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/identityprovider" claimValue="trusted:ADFS LDAP" />
      
      <identityClaim originalIssuer="TrustedProvider:ADFS LDAP" claimType="http://schemas.k2.com/identity/claims/name" />
      
      <roleClaim originalIssuer="TrustedProvider:ADFS LDAP" claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
    </claimTypeMapping>
    
    <claimTypeMapping securityLabel="K2">
      
      <identityProviderClaim originalIssuer="SecurityTokenService" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/identityprovider" claimValue="windows" />
      
      <identityClaim originalIssuer="Windows" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/userlogonname" />
      
      <roleClaim originalIssuer="Windows" claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid" />
    </claimTypeMapping>
    
    <claimTypeMapping securityLabel="K2FORMS">
      
      <identityProviderClaim originalIssuer="SecurityTokenService" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/identityprovider" claimValue="forms:LdapMembershipProvider" />
      
      <identityClaim originalIssuer="Forms:LdapMembershipProvider" claimType="http://schemas.microsoft.com/sharepoint/2009/08/claims/userlogonname" />
      
      <roleClaim originalIssuer="Forms:LdapRoleProvider" claimType="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
    </claimTypeMapping>
</claimTypeMappings>
</sourcecode.security.claims>

Issuers

K2 supports a one-to-many mapping between K2 and the certificates that the SharePoint STS uses to sign (SharePoint Security Token Service) and encrypt (SharePoint Security Token Service Encryption) the security tokens it issues. The default installation of SharePoint will generate and store individual certificates for both signing and encrypting on each server in the farm. The image highlights the values required for an <issuer> entry – the name and thumbprint for each individual signing and encrypting certificate for the STS.

Claim Type Mappings

K2 recommends a one-to-one mapping between a K2 User Manager (UM) and an incoming claim set Identity Provider (IP). Each <claimTypeMapping> will contain an entry for the Security Label of the associated K2 UM and three claim types to be mapped from the IP: Identity Provider, Identity and Role.

It is recommended that one K2 User Manager is mapped to a single Identity Provider. However, if more than one mapping is required, the runtime resolution of users is determined by the order they are registered in the <sourcecode.security.claims> configuration. Furthermore, it is recommended that the Windows Identity Provider, typically used for service accounts only, be the last one registered in the <sourcecode.security.claims> configuration.

The image below highlights the values required for a <claimTypeMapping>. The claimTypeMapping requires a unique K2 UM securityLabel to be configured. The identityProviderClaim requires an originalIssuer, claimType and claimTypeValue to be configured while the identityClaim and roleClaim require originalIssuer and claimType to be configured.

Legend

1 Identity Provider
2 Identity
3 Role

K2 requires the claimType for the identityClaim to match the claim mapping configured in SharePoint as the Identifier Claim. The K2 Server Configuration section provides automatic and manual approaches that aid in configuring the appropriate identity claim type mapping for K2.

K2 Server Configuration

The <sourcecode.security.claims> section must be manually added to the K2HostServer.config file. However, the method used to generate the configuration section values can be automatically generated or manual. Using the automatically generated approach is recommended.

Automatically Generated Approach

This option requires the use of PowerShell scripts available as a download for this topic that will interrogate a SharePoint 2010 claims configuration and automatically generate all the resulting <sourcecode.security.claims> configuration section for K2HostServer.config.

SharePoint Central Administration
Run these commands on the SharePoint Central Administration server or for single server farm configurations.

Download and extract the Get-ClaimTypeMappings.ps1 script
Start SharePoint 2010 Management Shell
Execute Get-ClaimTypeMappings.ps1 and provide the values requested at the prompts
1. For more information on the options available, execute:
  Get-Help .\Get-ClaimTypeMappings.ps1
2. NOTE: The script will stop executing if the SharePoint environment is not properly configured for K2 claims support. For more information, see Claims-based AuthenticationOpen the [Installation Directory]\Host Server\Bin\K2HostServer.config. file.
Add the resulting <sourcecode.security.claims> XML to the end of the <configuration> section
Save the file and restart the K2 blackpearl Server service

SharePoint Web Front Ends
Additionally, run these commands on the SharePoint web front ends for multi-server farm configurations.

Download and extract the Get-AdditionalIssuers.ps1
Start SharePoint 2010 Management Shell
Execute Get-AdditionalIssuers.ps1
Open the [Installation Directory]\Host Server\Bin\K2HostServer.config. file
Add the resulting <issuer> XML to the end of the <configuration><sourcecode.security.claims><issuers> section
Save the file and restart the K2 blackpearl Server service

Once the K2 Server has restarted an IISRESET will be required

Download: You can download the SourceCode.Security.Claims sample scripts by clicking here.

Manually Generated Approach

This option requires extensive knowledge of the SharePoint claims configuration and optionally the use of the community provided SourceCode.Samples.Claims.WebPart.

The image below highlights the values required in K2HostServer.config as returned by the SourceCode.Samples.Claims.WebPart.

Legend

1 Identity Provider
2 Identity
3 Role

Download and install the SourceCode.Samples.Claims.WebPart
Open the [Installation Directory]\Host Server\Bin\K2HostServer.config file
Add the example <sourcecode.security.claims> XML from this topic to the end of the <configuration> section

Update the values in the example with the values from your environment for

Issuers – certificate name and thumbprint for SharePoint Security Token Service and SharePoint Security Token Service Encryption certificates for all servers in the farm. These values can be determined by using the MMC Certificates Snap-in and navigating to the Local Computer\SharePoint\Certificates node or using the SharePoint 2010 Management Shell and executing the following PowerShell commands.

Copy
(Get-SPServiceApplication -Name SecurityTokenServiceApplication).SigningCertificateThumbprint (Get-SPServiceApplication -Name SecurityTokenServiceApplication).EncryptionCertificateThumbprint

Claim Type Mappings – identity provider claim, identity claim and role claim for each authentication provider associated with the web application. These values can be determined from the scripts used to configure SharePoint for claims authentication or the community provided web part.

Save the file and restart the K2 blackpearl Server service
Once the K2 Server has restarted an IISRESET will be required

Download: You can download the SourceCode.Sample.Claims.WebParts sample scripts by clicking here.

The SourceCode.Sample.Claims.WebPart is provided as an example only and is not supported.

Claims

Configuring the LDAP User Manager