Archives

Archives / 2014 / June
  • How to check the version of AppFabric 1.1 aka the Distributed Cache

    Tags: AppFabric, SharePoint 2013

    Introduction

    The other day I posted about the patching procedure for the SharePoint 2013 Distributed Cache (Microsoft AppFabric 1.1) and on that post I got a great comment from Riccardo:

    Hi Wictor, is it possible to discover the patch level of the Distributed Cache without looking at control panel? Powershell?

    That is a great question Riccardo! But the answer is not that simple…

    Check the version using Installed Updates

    The easiest way to manually check what version of AppFabric you are using, or rather which CU that is applied to AppFabric 1.1, is to use the Program and Features tool in Windows Server and then click on View installed updates.

    Installed AppFabric updates

    As you can see in the screenshot above, they all have the same version 1.1.2106.32 and that is also the version you get when you query the registry with this:

    Get-ItemProperty HKLM:\SOFTWARE\Microsoft\AppFabric\V1.0\ -Name ProductVersion | select ProductVersion

    That version number is the version number of Microsoft AppFabric 1.1 and it doesn’t change when you are applying Cumulative Updates.

    Check the Distributed Cache version using PowerShell

    If you want to automate checking the patch level of the Distributed Cache then the only way I’ve found (if someone has a better way, please enlighten me) is to actually check the version of one specific file, the Microsoft.ApplicationServer.Caching.Configuration.dll file. This is one of the few files that is updated in all the current CU’s (1-5), but I cannot guarantee that it will be updated in future version. The check is is done using the following PowerShell script (remove the line breaks and paste as a single line):

    (Get-ItemProperty "C:\Program Files\AppFabric 1.1 for Windows Server\
    PowershellModules\DistributedCacheConfiguration
    \Microsoft.ApplicationServer.Caching.Configuration.dll" -Name VersionInfo)
    .VersionInfo.ProductVersion

    This script will give you different version numbers depending on your AppFabric 1.1 CU level as follows:

    CU level Product Version
    CU1 1.0.4639.0
    CU2 1.0.4644.0
    CU3 1.0.4652.2
    CU4 1.0.4653.2
    CU5 1.0.4655.2

    If this method is valid for future CU’s then please remind me to update this table.

    Summary

    So Riccardo, there you have the best answer I can give you. It is not an optimal solution but it works…

  • How to patch the Distributed Cache in SharePoint 2013

    Tags: SharePoint 2013, AppFabric

    Introduction

    In SharePoint 2013 the Distributed Cache plays a very important role, it is a key component for performance and caching. An incorrectly configured or managed Distributed Cache will cause issues, with your farm. I’ve even seen blogs recommending turning it off, most likely due to that they don’t manage the cache properly and get into a situation where it causes even worse performance problems. One of the good things with the Distributed Cache is that is not a SharePoint service, it is a standalone service called AppFabric 1.1 for Windows Server. Initially the guidance from Microsoft was that the Distributed Cache (DC) would be patched together with SharePoint and we should keep our hands off it. But that has over the time changed and allowed us to take advantage of the fixes and improvements that the AppFabric team does to the service. So, it is our responsibility to patch the Distributed Cache. But how do we do it?

    [Update 2014-07-16] Here's a link to the official statement that AppFabric/DC is independently updated from SharePoint: KB2843251

    Proper patch instruction

    First of all there are currently five released Cumulative Updates (CU) for AppFabric 1.1, CU1 to CU5. An AppFabric Cumulative Update is exactly the same as a CU for SharePoint, it contains all previous CUs. So if you install CU5 you also get CU1 to CU4 installed. The important thing with this is that you as an administrator should not just read the latest CU Knowledge base article, but also the previous ones (you will see one reason in a minute).

    Let’s assume that we have a SharePoint farm with more than one servers running the Distributed Cache service instance. To patch these we need to download the AppFabric CU that we would like to use. I’d recommend using the latest (CU5) right now and I’ve not yet seen any issues with it, only positive effects. If you are using Windows Server 2012 you definitely should go with at least CU4.

    Here’s a link to the different CU’s and their KB article respectively

    In this case let’s apply CU5.

    The first thing before patching that is really important to do is to properly shut down the Distributed Service instance. The reason that you would like to do this is that some items in the Distributed Cache is only living in the cache and is not backed to a persistent storage, such as some items in the SharePoint Newsfeed. If you do not properly shut down the service instance you will loose that data. Fortunately we have a great PowerShell cmdlet that does this job for us. The process here is that you need to patch one machine at a time according to these steps:

    1. Shut down the service instance on one machine
    2. Patch AppFabric 1.1
    3. Post-patch operations
    4. Start the service instance
    5. Restart from 1 on the next machine

    Do not do servers in parallel unless you have a massive amount of servers and can handle that extra load/redundancy!

    Step (1) is done in PowerShell using one of the built-in SharePoint cmdlets:

    asnp *sharepoint*
    Stop-SPDistributedCacheServiceInstance -Graceful

    This command will gracefully shut down the service instance on the local machine. A graceful shutdown means that all the cache items will be distributed to the other service instances in the cache cluster. Make sure that you have enough overhead to do this. This is yet another example of my “3 is the new 2” rule is important. When you patch one server you don’t want just one extra machine! Once the service instance is stopped, I normally wait a couple of extra minutes to make sure that all the cached items has properly propagated to the other servers.

    Then it is time to apply the actual AppFabric patch, step (2). Run the patch executable and follow the instructions. It’s basically a next, next, finish procedure.

    Step (3). When the patch is applied you should have read through the KB articles, and if you are applying CU3 or later you should have seen that in order to improve performance you need to modify the Distributed Cache configuration file. The CU3 KB article mentions a new feature added to the AppFabric service that takes advantage of the non-blocking background garbage collection feature in .NET 4.5, which is important for machines with large amounts of RAM – and that is exactly the description of a SharePoint server. So modify the DistributedCacheService.exe.config file as below to enable the background garbage collection:

    <configuration>
      ...
      <appSettings>
        <add key="backgroundGC" value="true"/>
      </appSettings>
    </configuration>

    The final thing we need to do on the machine is to start the service instance again, step (4). The AppFabric Windows Service will be disabled when it is shut down and you should NOT try to start that one manually, you must use the following PowerShell (or corresponding action in Central Administration if you’re a n00b).

    $instance = Get-SPServiceInstance | ? {$_.TypeName -eq "Distributed Cache" -and $_.Server.Name -eq $env:computername}
    $instance.Provision()

    This PowerShell snippet will get the Distributed Cache service instance on the machine where it is executed and provision it and start the AppFabric Windows Service.

    Once this is done and you are ready to move on to the next machine, step (5), give it a couple of extra minutes so that the newly patched (and empty) cache service instance has time to catch up.

    Not patching properly…

    A very common issue is that in order to apply the patch you just run the patch executable. Two things will happen when you do this. First of all the service will be shut down, but not gracefully and you will loose data. Secondly it will not start the service instance properly or at all. The patch contains a script that waits for the service to come online, but since this is not a normal AppFabric cache, it’s controlled by SharePoint, so this script will wait forever until the service comes up. If this happens all you have to do is kill the script window and start the service properly as shown above (warning: this is not a recommendation and there might be side effects)

    Summary

    I hope this short post cleared up some confusion on how to patch the Distributed Cache service in SharePoint 2013 and gave you an example on how to do this in a production environment without loosing any data. Of course, you should always test the procedure in a test/staging environment. Cache on!

  • Using SharePoint 2013 with Thinktecture IdentityServer 2

    Tags: SharePoint 2013, Claims

    Introduction

    SharePoint 2013 (and earlier versions) allows you to use alternative authentication “sources” than Windows. We can part from the different options with Windows login, use Forms Based Authentication (FBA) or use a federated/trusted identity provider. Forms based authentication is a good approach if you don’t want to manage your users in Active Directory or if you don’t want to use Windows Login. The downside with FBA is that you must manually do some web.config modifications, there isn’t any UI for managing the users (yes, I know you can use LDAP or just download something from the tubez, but you get my point). Using a federated approach is more interesting, that allows you to get the identity management and authentication away from your SharePoint farm (and this is a really good thing, SharePoint admins are generally not identity management people!). A trusted identity provider is a service such as Active Directory Federation Services (AD FS), Microsoft Azure Access Control Services (ACS) or any other SAML 1.1 compatible Identity Provider (IdP).

    I generally don’t like using FBA, due to the issues above. In this post I will show you how to do forms based authentication without using FBA, but instead using a trusted identity provider called Thinktecture IdentityServer 2. IdentityServer 2 is an awesome implementation of an identity provider and supports a plethora of standards. And it comes as open source, with a web based UI, is very configurable and is just one of the best options for you when you need to set up your SharePoint with users not in Active Directory.

    Thinktecture IdentityServer 2

    Without describing the Thinktecture IdentityServer 2 in my own words I think the official overview says enough:

    IdentityServer is a light-weight security token service built using .NET 4.5, ASP.NET MVC4, WCF and Web API. It has out-of-the-box support for user management using the ASP.NET membership and roles provider, but provides extensibility points to integrate arbitrary user databases. Futhermore almost any aspect of token issuance and data management can be customized using a plugin model.

    The really cool thing with it is that it supports SAML 1.1 and can be used as a SharePoint 2013 (or 2010) trusted identity provider with a few lines of PowerShell. Secondly if you already has SharePoint hooked up to AD FS (or another similar service) you can add IdentityServer 2 as Claims Provider Trust.

    Installing IdentityServer 2

    The first thing we should do is to get our hands on IdentityServer 2 and set it up in our environment. You have two options; either make a github clone if you need to modify the source (https://github.com/thinktecture/Thinktecture.IdentityServer.v2) or download it directly (http://thinktecture.github.io/Thinktecture.IdentityServer.v2/downloads/). In this post I assume you don’t want to do any development and do it the lazy way and just downloads it. Ok, the official link above will only give you a 404 when you click on the download link at the moment, so use this page instead to download the .zip file for version 2.2: https://github.com/thinktecture/Thinktecture.IdentityServer.v2/releases/v2.2.0.

    Now create a folder called IdSrv (or whatever you prefer) on one of your local disks, for instance d:\IdSrv\, and extract the ZIP file there. Next we need to create an IIS Web Site that uses this directory. Before proceeding with that we need to create a web server certificate – remember, always use certificates for these kind of services! You could use a self signed, but as always if you can use a domain/real CA that is preferred. Also you might need to set up a DNS entry, which is what I will use (idsrv.contoso.com). Once you have the certificate and hostname then you can proceed to the IIS configuring.

    We’ll create a new IIS site pointing at the folder we unpacked IdentityServer to. We also need to specify the binding to use https and select our certificate, image on the left below. When we click OK this will create a new application pool for us in IIS, for that application pool we need to switch the identity to use a domain account or if we’re doing a single server install use the Network Service, image on the right below.

    New IIS web site and bindings Change the app pool identity

    Since we now told IdentityServer to run as Network Service we also need to modify the folder permissions of the App_Data catalog and give the Network Service Modify permissions on that catalog. The App_Data catalog is where IdentityServer by default stores its database.

    Once we have done this we can browse to the binding specified in IIS and start using IdentityServer 2.

    Since this is a fresh installation and IdentityServer has no database we will be presented by a configuration screen. On that screen you should enter a site name, you must specify the Issuer URI (which uniquely identifies this issuer) as well as choose a signing certificate (this could be the one you created for the web site or a different one). Then you also need to specify an administrator username and password.

    Before you click save you must make sure that the account running the application pool (Network Service in this sample) has permissions to read the private key of the certificate that you use as signing certificate.

    Configuring IdentityServer

    Once you have done that you are all set to go!

    Users and roles

    To create users and roles you log in as the administrator and go to the administration menu and select users and/or roles. If you want to extend the user profile with more properties you need to modify the profile.config file under /Configuration in the IdentityServer folder. For this sample I add an additional property called “Title”, which I will use in a bit.

    Before proceeding create at least one user and add that user to the “IdentityServerUsers” role, that is by default the role that is needed to use IdentityServer for authentication federation.

    Final identity server tweaks

    Ok, now have an awesome identity system up and running. We need to tweak a few things in IdentityServer before doing the SharePoint stuff. We need to add a Relying Party (RP) to IdentityServer, and the Relying Party in this case is SharePoint. As the administrator in IdentityServer choose to add a new Relying Party. This RP needs a display name, a realm and a redirect URL. The display name is whatever you prefer, the realm must be a URI and the Redirect URL should be you SharePoint site with “/_trust/” appended, like in the screenshot below.

    Relying party in IdentityServer

    Another tweak we need to do is to tell identity server to use SAML 1.1 instead of SAML 2.0, since SharePoint does not support SAML 2.0. That is done under General Configuration of IdentityServer and the “Default WS* Token” property should be set to “urn:oasis:names:tc:SAML:1.0:assertion”.

    SNAGHTML10f558c

    Adding IdentityServer 2 as a trusted identity provider

    Now it is time to head on over to SharePoint and fire up a PowerShell prompt! The first thing we will do is to define a couple of properties:

    ## PROPERTIES
    $realm = "uri:identityserver:sp03"
    $signinurl = "https://idsrv.contoso.com/issue/wsfed"
    $description ="Provide description here"
    $url = "https://rootsite.sp03.contoso.com"
    $metadataurl = "https://idsrv.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml"

    The realm must be the same realm that we configured in IdentityServer for the Relying Party. The signinurl can be found on the home page > application integration in IdentityServer and it’s the URL called WS-federation. Description is just some description that you provide and url is the URL to the Web Application where you want to add this identity provider. Finally metadataurl is the WS-federation metadata end-point for identity server and that URL can be found on the same page as where we located the sign in URL.

    We’ll use this WS-federation metadata end-point to do some discovery from the SharePoint side:

    ## LOAD FEDERATION METADATA
    $fedmd = Invoke-WebRequest -Uri $metadataurl
    $fedmdXml = New-Object Xml
    $fedmdXml.LoadXml($fedmd.Content)
    $base64 = $fedmdXml.EntityDescriptor.RoleDescriptor.KeyDescriptor.KeyInfo.X509Data.X509Certificate
    $base64| Out-File -FilePath temp.cer -Append:$false
    $cert = Get-PfxCertificate -FilePath temp.cer
    Remove-Item temp.cer
    

    By invoking the end-point we can retrieve the signing certificate, and other metadata. We grab that certificate and temporary stores it as a .cer file before loading it up in a certificate variable which will be used to install it in SharePoint.

    ## ADD TRUST IN SP
    asnp *sh*
    $name = $fedmdXml.EntityDescriptor.RoleDescriptor.GetAttribute("ServiceDescription")
    New-SPTrustedRootAuthority -Name $name -Certificate $cert | Out-Null
    

    We use the certificate variable to create a trust in SharePoint, together with the name of the service, retrieved from the metadata endpoint.

    Next up is to create some claims mappings and the trusted identity token issuer in SharePoint.

    ## CREATE TRUSTED IDENTITY TOKEN ISSUER
    $map1 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" `
        -IncomingClaimTypeDisplayName "Email" –SameAsIncoming 
    $map2 = New-SPClaimTypeMapping "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" `
        -IncomingClaimTypeDisplayName "Role" -SameAsIncoming 
    $map3 = New-SPClaimTypeMapping "http://identityserver.thinktecture.com/claims/profileclaims/title" `
        -IncomingClaimTypeDisplayName "Title" -SameAsIncoming 
    $tit = New-SPTrustedIdentityTokenIssuer -Name $name -Description $description -Realm $realm `
        -ImportTrustCertificate $cert -ClaimsMappings $map1,$map2,$map3 -SignInUrl $signinurl `
        -IdentifierClaim $map1.InputClaimType
    

    We create three claims mappings in this case; the first one is the e-mail claim, the second one is a role claim and the third one is our custom claim using the user property Title we created. We can get the claims identifiers from the XML in the metadata endpoint. We’ll use the first claim, e-mail, as our identity claim when we finally create the trusted identity token issuer also passing in the realm and sign-in URL.

    Once this is done all we need to do is update our Web Application(s) to use this new identity provider. This can be done in the UI in Central Administration per Web Application or using PowerShell like this:

    ## UPDATE WEB APPLICATION WITH NEW IDP
    $wa = Get-SPWebApplication $url
    $ap = Get-SPAuthenticationProvider -WebApplication $wa -Zone Default
    if($ap.Count -eq 1) {
        $aps = New-Object System.Collections.ArrayList
        $aps.Add($ap) | Out-Null
    } 
    else {
        $aps = $ap
    }
    $ap = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $name
    $aps.Add($ap) | Out-Null
    Set-SPWebApplication -AuthenticationProvider $aps -Zone Default -Identity $wa
    

    First we retrieve the current authentication providers for the web application, then we create a new one from our just recently created trusted identity token issuer and then we add them all (as an array) to the web application.

    That’s it! Time for a test ride…

    Browse to a site on the web application where you enabled the IdentityServer authentication. You should be presented with the awesome standard SharePoint login selector page. In the drop down you will see two options; Windows Authentication and our IdentityServer option:

    Some sweet UI

    Select to log in using IdentityServer. This will take you to the log in page of identity server, where you present your credentials. If you log in using that user you created in identity server you will after a successful login see an access denied page from SharePoint. That’s because that user doesn’t have permissions yet.

    It is now we can take advantage of that we added the role or title claims. Open up a new browser and log in using Windows Authentication and give permissions to either a role or a title. Unfortunately the default claims people picker in SharePoint is a bit stupid when it comes to working with claims. You need to write the name of the group or title and then pick the correct claim. Hover the cursor over the alternatives to see which identity provider and which claim is which one. In this case we see three (our three different claims).

    Default Claims People Picker

    Once you have given permissions to a role, title or directly to the e-mail of the user, you should be able to log in properly and see the site.

    Summary

    In this post I’ve shown you how to use Thinktecture IdentityServer 2 as an identity provider to SharePoint 2013. IdentityServer is a great alternative to using FBA when you need a custom user and role store and it’s way easier and more manageable to set up, no fiddling with web.configs or installing full trust code you download from the interwebs in your SharePoint farm. Enjoy!

About Wictor...

Wictor Wilén is the Nordic Digital Workplace Lead working at Avanade. Wictor has achieved the Microsoft Certified Architect (MCA) - SharePoint 2010, Microsoft Certified Solutions Master (MCSM) - SharePoint  and Microsoft Certified Master (MCM) - SharePoint 2010 certifications. He has also been awarded Microsoft Most Valuable Professional (MVP) for seven consecutive years.

And a word from our sponsors...