My whirlwind year continues. After returning from Australia last week, I’m turning around next week to present at three events in Europe: Microsoft SharePoint Connections in The Hague,  September 26-30; my SharePoint Administration MasterClass in Lisbon on October 1, and The Experts Conference in Dusseldorf October 4-7. Hope to see some of you there!! It will be a power-trip, for sure, as I’ll also be finishing up my work on a SharePoint 2010 book for Microsoft. No rest in SharePoint 2010 land!

During my work on the SharePoint training kit, which will be released later this year, I banged my head into the wall with an issue with claims-based authentication. Thanks to my friend Gary Lapointe, a SharePoint and PowerShell guru, I came to discover that an annoying little bug was my nemesis. So this week, let’s touch on a few take-aways about claims-based authentication, look at how to create a SharePoint Web application using Windows PowerShell, and along the way let’s bring the bug to light.

Claims-based authentication, or claims authentication for short, is new to SharePoint 2010. It’s amazing to me just how much terrible documentation there is about claims authentication in SharePoint on the Internet. A lot of people are very confused about claims authentication and how to describe it. But it doesn’t have to be hard to understand at all! We’ll go into the details about claims auth over coming weeks in this column.

My next frustration came from articles that purported to show you how to configure claims authentication in SharePoint. A lot of what you can find on the ‘net was written during SharePoint betas, during which claims auth itself was half-baked, so that’s forgivable if distracting.

But there are also a lot of articles out there that are theoretically up-to-date, but either are downright inaccurate or simply a hot mess because they have code samples that weren’t tested properly, and don’t work. If you want to get up to speed on claims authentication, start with one of the gurus— Spence Harbar  — then learn more, elsewhere, at your own risk.

And keep your eyes on our magazines in the next few months—we’ll get that article in there!

My third frustration is that, in reality, claims authentication is a “version 1.0” feature for SharePoint. Claims auth, in general, is a tried-and-true concept and I have no doubt that it will be “the next big thing” for identity (AD, AD FS). But its implementation in SharePoint is still version 1.0, and there are some rough spots.

Again, we’ll cover those in upcoming weeks but let me say, very clearly, that you need to test claims authentication for your application before converting your production app to claims auth. There are a lot of moving parts, with claims, SharePoint, authentication providers (like Kerberos and forms authentication), profiles, audiences, custom code and third-party solutions, and you need to make sure they all work for you.

If you’re upgrading to SP2010, there’s no “going back” once you convert an app to claims—you can’t convert back to Classic Mode authentication—so be sure you have a backup of your app!

Fourth, I ran into a bug that PowerShell exposed. So let’s address that one.

If you want to create a Web application that uses claims authentication using PowerShell, you must first create an object referencing your authentication provider (Windows, forms, or SAML token), then “pass” that object to the New-SPWebApplication cmdlet to create the Web application.

The following example shows the use of the New-SPAuthenticationProvider cmdlet to create a new Windows authentication provider:

$ap = New-SPAuthenticationProvider \\[-UseWindowsIntegratedAuthentication\\] \\[-DisableKerberos | DisableKerberos:$false\\] \\[-UseBasicAuthentication\\] \\[-AllowAnonymous\\]

Where:

• The -UseWindowsIntegratedAuthentication switch parameter specifies that the authentication provider will be Windows.

• The -DisableKerberos switch parameter, if specified, disables Kerberos authentication. The authentication provider uses NTLM only.

The -DisableKerberos:$false syntax enables authentication.

Here’s the bug: Note In the RTM version of SharePoint, there's a bug in the class that initializes DisableKerberos to true. Therefore, the switch parameter doesn't work as documented. You must use -DisableKerberos:$false to enable Kerberos. It's likely that in a future release, Microsoft will either correct the behavior so that Kerberos is enabled by default, and the documentation will be correct, or it will add a switch parameter that enables Kerberos.

• The -UseBasicAuthentication switch parameter, if specified, enables Basic authentication.

After you create the object representing the authentication provider, you pass the object as the -AuthenticationProvider parameter to the New-SPWebApplication cmdlet. The following example shows the use of the New-SPWebApplication cmdlet to create a new Web application:

New-SPWebApplication -Name <Name> -Port <Port> -HostHeader <HostHeader>
-AuthenticationProvider <AuthenticationProvider> \\[-AllowAnonymousAccess\\]
\\[-SecureSocketsLayer\\] -URL <URL> -ApplicationPool <ApplicationPool>
-ApplicationPoolAccount <ApplicationPoolAccount> -DatabaseName <DatabaseName>

Where:

• <Name> is the name of the new Web application.

• <Port> is the port on which the Web application will be created in IIS.

• <HostHeader> is the host header, in the format server.domain.com.

Note that the Get-Help documentation for the cmdlet states that the format for <HostHeader> is http://server.domain.com. The documentation is incorrect.

• <AuthenticationProvider> is an object representing an authentication provider.

Use the New-SPAuthenticationProvider to create an object representing an authentication provider, as described earlier.

• The -AllowAnonymousAccess switch parameter, if specified, enables anonymous authentication.

• The -SecureSocketsLayer parameter, if specified, enables SSL for the Web application.

You must also use IIS Manager to create the certificate in the server’s certificate store and bind the certificate to the IIS Web site.

• <URL> is the public URL for the Web application’s Default zone.

• <ApplicationPool> is the name of the application pool.

• <ApplicationPoolAccount> is the managed account that the application pool will use.

This parameter is required if you are specifying an <ApplicationPool> that does not already exist. Use the Get-SPManagedAccount cmdlet as shown in the example below. If the <ApplicationPool> already exists, do not include this parameter

• <DatabaseName> is the name for the first content database for the Web application.

For example, the following command creates a Web application with Claims Based Authentication. A Windows authentication provider is constructed that uses only NTLM—Kerberos is disabled—and passed as the authentication provider for the new Web application:

$ap = New-SPAuthenticationProvider –UseWindowsIntegratedAuthentication –DisableKerberos
New-SPWebApplication -Name "Contoso Partner Portal" -Port 443 -HostHeader "partners.contoso.com" –AuthenticationProvider $ap –SecureSocketsLayer -URL "https://partners.contoso.com:443" -ApplicationPool "SharePoint Extranet Applications" –ApplicationPoolAccount (Get-SPManagedAccount "CONTOSO\SP_WebApps") -DatabaseName "SharePoint_Content_Partners"