When SharePoint 2010 was developed, Microsoft took extra care to include support for
a claims-based identity model. There are quite a few benefits to doing it this
way, one of which is that it simplifies managing identities across organizational
structures. So lets take a look at adding a Secure Token Service as an Authentication
Provider to SharePoint 2010.
First, Some Prerequisites
-
You have to use PowerShell for most of this. You wouldn’t/shouldn’t be adding
too many Providers to SharePoint all that often so there isn’t a GUI for this.
-
The claims that SharePoint will know about must be known during setup. This
isn’t that big a deal, but…
Telling SharePoint about the STS
Once you’ve collected all the information you need, open up PowerShell as an Administrator
and add the SharePoint snap-in on the server.
Add-PSSnapin Microsoft.SharePoint.PowerShell
Next we need to create the certificate and claim mapping objects:
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("d:\path\to\adfsCert.cer")
$claim1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
-IncomingClaimTypeDisplayName "Role" –SameAsIncoming
$claim2 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
-IncomingClaimTypeDisplayName "EmailAddress" –SameAsIncoming
There should be three lines. They will be word-wrapped.
The certificate is pretty straightforward. It is the public key of the STS.
The claims are also pretty straightforward. There are two claims: the roles
of the identity, and the email address of the identity. You can add as many
as the STS will support.
Next is to define the realm of the Relying Party; i.e. the SharePoint server.
$realm = "urn:" + $env:ComputerName + ":adfs"
By using a URN value you can mitigate future changes to addresses. This becomes
especially useful in an intranet/extranet scenario.
Then we define the sign-in URL for the STS. In this case, we are using ADFS:
$signinurl = https://[myAdfsServer.fullyqualified.domainname]/adfs/ls/
Mind the SSL.
And finally we put it all together:
New-SPTrustedIdentityTokenIssuer -Name "MyDomainADFS2" -Description "ADFS
2 Federated Server for MyDomain" -Realm $realm -ImportTrustCertificate $cert
-ClaimsMappings $claim1,$claim2 -SignInUrl $signinurl -IdentifierClaim $claim2.InputClaimType
This should be a single line, word wrapped. If you wanted to you could just
call New-SPTrustedIdentityTokenIssuer and then fill in the values one at
a time. This might be useful for debugging.
At this point SharePoint now knows about the STS but none of the sites are set up
to use it.
Authenticating SharePoint sites using the STS
For a good measure restart SharePoint/IIS. Go into SharePoint Administration
and create a new website and select Claims Based Authentication at the top:
Fill out the rest of the details and then when you get to Claims Authentication
Types select Trusted Identity Provider and then select your STS.
In this case it is my ADFS Server:
Save the site and you are done. Try navigating to the site and it should redirect
you to your STS. You can then manage users as you would normally with Active
Directory accounts.
Over the last few years Microsoft has made a push for all of it’s Server Solutions
to have the capability of being managed via PowerShell. Active Directory Federation
Services is no different.
When we installed ADFS for the first
time, the installer told us it needed PowerShell as a pre-requisite, so we get
some cmdlets available to us out of the box. Before we start playing around
with them though we need to register the cmdlets to our PowerShell session. We can
do with this command:
Add-PSSnapin Microsoft.Adfs.PowerShell
At this point we can now muck around with all of the available cmdlets. For
a full list of available
cmdlets for ADFS check out TechNet.
Let’s take a look at our ADFS Server Properties:
Get-AdfsProperties
AcceptableIdentifiers : {}
AddProxyAuthorizationRules : […snip…]
AutoCertificateRollover : True
CertificateCriticalThreshold : 2
CertificateDuration
: 365
CertificateGenerationThreshold : 20
CertificatePromotionThreshold : 5
CertificateRolloverInterval : 720
CertificateSharingContainer :
CertificateThresholdMultiplier : 1440
ClientCertRevocationCheck : None
ContactPerson
:
DisplayName
: WEB1.nexus.external.test
ExtendedProtectionTokenCheck : Allow
FederationPassiveAddress : /adfs/ls/
HostName
: WEB1.nexus.external.test
HttpPort
: 80
HttpsPort
: 443
Identifier
: http://web1.nexus.external.test/adfs/services/trust
InstalledLanguage
: en-US
LogLevel
: {Errors, Information, Verbose, Warnings}
MonitoringInterval
: 1440
NetTcpPort
: 1501
NtlmOnlySupportedClientAtProxy : False
OrganizationInfo
:
PreventTokenReplays
: True
ProxyTrustId
: 58cb3f40-0633-4d9e-b3c2-84f9bc8c2ce8
ProxyTrustTokenLifetime : 21600
ReplayCacheExpirationInterval : 60
SignedSamlRequestsRequired : False
SamlMessageDeliveryWindow : 5
SignSamlAuthnRequests : False
SsoLifetime
: 480
Nothing fancy there. What about updating?
get-help Set-AdfsProperties
Yep, we can do that:
NAME
Set-ADFSProperties
SYNOPSIS
Sets the properties of the Federation Service.
SYNTAX
[…snip…]
DETAILED DESCRIPTION
The Set-ADFSProperties cmdlet sets the global properties and configuration
of the Federation Service.
Updating settings isn’t all that exciting, so what about managing Relying Parties?
Add-ADFSRelyingPartyTrust
Get-ADFSRelyingPartyTrust
Remove-ADFSRelyingPartyTrust
Enable-ADFSRelyingPartyTrust
Disable-ADFSRelyingPartyTrust
Update-ADFSRelyingPartyTrust
You can also manage things like Certificates:
Add-ADFSCertificate
Remove-ADFSCertificate
Update-ADFSCertificate
There are many more things you can do from within PowerShell. Again, for the
full list check
out TechNet.
Being able to manage ADFS directly from PowerShell makes things a lot easier.
Not only for those who aren’t too keen on using MMC snap-ins, but also for the developers
to automate deployment for testing and development.