ADFSv2 and SharePoint Configuration Blogx - TechNet Blogs

wanderooswarrenΤεχνίτη Νοημοσύνη και Ρομποτική

21 Νοε 2013 (πριν από 3 χρόνια και 10 μήνες)

198 εμφανίσεις

In this post I’m going to do an end
-
to
-
end walk through on how to configure SharePoint 2010 and ADFS
v2 together to use SAML claims authentication. I’ll includes

steps and PowerShell scripts to demonstrate
and will try and bring all of the pieces together in one big posting.

First
a brief overview of the components involved and what we’re going to need to do. In this scenario
ADFS v2 is our Identity Provider, als
o known as an IP
-
STS (Security Token Service). We need to configure
ADFS with information about our Relying Party, or RP. In this case, SharePoint is our RP


it’s depending
on ADFS to do the authentication and provide the claims. From the SharePoint pe
rspective, we have to
configure it to trust the IP
-
STS that is sending us claims, and then we have to set up a web application
and site that’s going to consume those claims.

We’ll begin by creating the relying party in ADFS. Note that it really doesn’t ma
tter which order you do
these things in, but as a matter of practice

I generally configure ADFS first. So go to the server on which
ADFS is installed and open the AD FS 2.0 Management application.

Expand the Trust Relationships node
and click on the Relyi
ng Party Trusts node.


Click on the Add Relying Party Trust link in the right pane to start the Add Relying Party Trust wizard.


Click the Start button to continue.


Select the option to Enter data about the relying party manually, and then click the
Next button.


Enter a Display name and optionally a description for the relying party and then click the Next button.


Select the option to use the AD FS 2.0 profile and then click the Next button.


You can select a certificate to encrypt the SAML token

itself. This isn’t done frequently because ADFS
will require our connection to SharePoint be made over SSL, so the channel the token is sent over is
encrypted already. Click the Next button.


Check the box to
Enable support for the WS
-
Federation Passiv
e protocol
. For the protocol URL you need
to enter the

Url for the SharePoint web applictation’s root site, and include the “_trust” subdirectory. In
this example, the Url to my SharePoint web application is https://seo14, so the WS
-
Federation Passive
pr
otocol Url is https://seo14/_trust/. After entering your Url click the Next button.


For the relying party trust identifier you need to enter a realm that your web application will pass to
ADFS when users log into the web application. The realm is gener
ally created in the format of
urn:foo:bar. The realm is associated with a web application and is how ADFS can map the login request
that’s come in to the relying party trusts it has. When used with SharePoint, ADFS sees the realm
associated with the logi
n request, it looks that up to find the relying party trust, and then after it
authenticates the user it looks to that WS
-
Federation Passive protocol Url to know where to redirect the
user afterwards. So in this case, I’ve entered a realm of urn:seo:share
point. When I try navigating to my
SharePoint site at https://seo14 I’ll be redirected to ADFS and I’ll configure SharePoint to use the realm
urn:seo:sharepoint for that request. Once ADFS has authenticated me it will redirect me again to
https://seo14/_
trust/ because that’s the passive protocol Url for that relying party. Add whatever realm
you want to use here and make a note of it because you will need to enter it again when you configure
SharePoint. Then click the Next button.


In most cases you
will want all of your users to be able to use this relying party. We’ll assume that’s the
case for this scenario so just accept the default choice and click the Next button.


If you needed to make any other configuration changes at this time to the relyi
ng party trust you could
do it here. For this scenario we don’t need to so just click the Next button to continue.


We’re done configuring the relying party trust but we still need to create a claim rule to tell ADFS what
claims to send back to SharePoin
t. So leave the box checked to Open the Edit Claim Rules dialog and
click the Close button.


Now we are going to create a new rule, so click the Add Rule… button.


We are going to send LDAP attributes as claims because we are getting information from Ac
tive
Directory in this case, meaning we will authenticate at ADFS and ADFS is going to use the corporate
Active Directory to authenticate us and determine what our attributes are. So leave the default value
selected and click the Next button to continue.


Start out by typing in a Claim rule name; it can be whatever you want. Next, in the Attribute store drop
down select Active Directory. Next, for our scenario we want to send email address and the groups to
which the user belongs back to SharePoint. We

are going to use email address as the identifier for the
person, and we want all the groups a user belongs to sent over in the Role claim. To do the mapping,
select the attribute you want from the drop down on the left side, and then select the claim tha
t it will
be sent out as in the drop down in the right pane. In this case we want the E
-
Mail
-
Addresses attribute
from Active Directory to be sent out in the standard E
-
Mail Address claim. We want the groups to which
a user belongs to be sent out in the s
tandard Role claim. In this case I’ve selected Token
-
Groups


Unqualified Names because it sends the group name out as a simple string


the name of the group.
You could send out the SID of the groups but that becomes more difficult to use when you are t
rying to
assign a Role claim to a SharePoint group. After you’ve finished configuring this rule as described here,
click the Finish button to complete the rule.


Click the OK button to complete the process of creating your relying party trust in ADFS.

From a
configuration standpoint in ADFS there’s nothing else we need to do. However there is one other thing
we need to get from it. ADFS uses a certificate to sign the tokens it sends out. This ensures the
consumer of the token that it has not been ta
mpered with since it was created. To configure SharePoint
we need a copy of this certificate because we’ll use it when configuring it to use ADFS as the IP
-
STS. To
get this token signing certificate from ADFS, expand the Service node and click on the Cer
tificates node.


There is a section there for Token
-
signing certificates. You may have one to many token
-
signing
certificates, but there will always be ONLY one Primary token signing certificate. Click on that
certificate, and then click on the View Cer
tificate link in the right pane.


In this particular case I chose to use the certificate I created for SSL on the ADFS web site. I’m not
suggesting that this is needed or even recommend; it’s just what I chose to do. Now that you are
viewing the certifi
cate, click on the Details tab at the top of the dialog.


Click on the Copy to File… button. That will start a wizard to save

a copy of the certificate to disk.


Click the Next button to continue.


You don’t need the private key, so accept the default
settings and click the Next button.


The default format is fine so click the Next button to continue.


Pick a location to save the certificate and click the Next button. Make sure you remember this location
because you will need to copy the certificate
from where you save it over to the SharePoint server.


All the information needed to copy the certificate locally has been captured now so click the Finish
button to complete the wizard and save the certificate to a local file. Copy this file to the Shar
ePoint
server and then we are finished with the ADFS server.

Switch over to the SharePoint server and we will begin configuring it. Before we start configuring
SharePoint I recommend that you create a new web application now. Create it to use claims
auth
entication, but select Integrated Windows authentication


NTLM for the Authentication Settings.
Make sure you configure the web application to use Port 443 and you select the radio button that says
Use Secure Sockets Layer (SSL). Once you’ve created yo
ur web application remember to go into the IIS
Manager and edit the bindings for the new virtual server so you can assign the appropriate SSL
certificate. These steps are outside the scope of this posting, but are well
-
documented in many places
around the

Internet. To recap, for our scenario then there is a web application I’ve created that uses
Port 443 and SSL and the Url for that web application is https://seo14.

The first thing I’m going to do on the SharePoint side is to add the token signing certif
icate I copied from
the ADFS server. Before I do that though, I need to look at the certificate. The token signing certificate
may have one or more parent certificates in its chain.
If it does, I need to add every certificate in that
chain to SharePoint
’s list of trusted root authorities. To figure that out, I’ll find the token signing
certificate I copied over from ADFS and double
-
click on it; that brings up the certificate properties
window. If you click on the Certification Path tab you can see if t
here are any other certificates in the
chain. In my scenario my token signing certificate DOES have a parent


it is the root certificate
authority certificate.


What I need to do now, is for each certificate in the chain above my token signing certifica
te, I need to
save a copy of each one locally. I can do that by clicking on the certificate, which enables the View
Certificate button in the dialog. If I click on that it will open a separate properties dialog for that
certificate. I can then follow th
e same process I described earlier to save a copy of the certificate to
disk: click on the Details tab, click on the Copy to File… button, then save the certificate locally as a .CER
file. In my case I did this and saved it to C:
\
adfsParent.cer. So now
on my SharePoint server I have two
certificates:



C:
\
adfs.cer, which is the token signing certificate I copied from my ADFS server



C:
\
adfsParent.cer, which is the parent certificate to my token signing certificate

Now that I have both of these certificate
s, I need to add them to my list of trusted root authorities. I’m
going to do that in PowerShell with this script:

$root = New
-
Object
System.Security.Cryptography.X509Certificates.X509Certificate2("C:
\
adfsParent
.cer")

New
-
SPTrustedRootAuthority

-
Name "Token Signing Cert Parent"
-
Certificate
$root

$cert = New
-
Object
System.Security.Cryptography.X509Certificates.X509Certificate2("C:
\
adfs.cer
")

New
-
SPTrustedRootAuthority
-
Name "Token Signing Cert"
-
Certificate $cert

After I execute those commands
in PowerShell the output looks something like this:


Next I’m going to create the claim mappings that SharePoint is going to use. If you recall from earlier in
this article I said that I was going to use email address and role claims in SharePoint. Here
’s the
PowerShell that I’ll use to create those mappings:

$map = New
-
SPClaimTypeMapping
-
IncomingClaimType
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
-
IncomingClaimTypeDisplayName "EmailAddress"
-
SameAsIncoming

$map2 = New
-
SPClaim
TypeMapping
-
IncomingClaimType
"http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
-
IncomingClaimTypeDisplayName "Role"
-
SameAsIncoming

Next I’m going to create a variable for the realm that I want SharePoint to use. For this scenario I said I
was going to use the realm urn:seo:sharepoint. Here’s the PowerShell to create my realm variable:

$realm = "urn:seo:sharepoint"

Now I’m ready to create my SPTrustedIdentityTokenIssuer. This is where I tie together all of the
configuration information so
SharePoint knows how to
connect and work with the IP
-
STS. I’ll show the
PowerShell here and then explain the important parts:

$ap = New
-
SPTrustedIdentityTokenIssuer
-
Name "SAML Provider"
-
Description
"SharePoint secured by SAML"
-
realm $realm
-
ImportTrust
Certificate $cert
-
ClaimsMappings $map,$map2
-
SignInUrl "https://
congen1.contoso.local
/
adfs/ls
"
-
IdentifierClaim
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

The “Name” attribute is what is going to show up in your web application
when you configure what
authentication provider it should use. The “realm” attribute is where we plug in the realm that we want
SharePoint to use with this trusted identity token issuer. The “ImportTrustCertificate” attribute is where
we pass it the toke
n signing certificate that we copied from the ADFS server. The “ClaimsMappings”
attribute is where we tell it what the claims are that we want this trusted identity token issuer to use.
The “SignInUrl” is
the Url that users should be redirected to in ord
er to authenticate with the IP
-
STS. In
this case we want users to authenticate
with the ADFS server using Windows integrated security, so we
send them to the /adfs/ls subdirectory. Finally, the “IdentifierClaim” attribute tells SharePoint which of
the cl
aims is going to be
thee

claim that is used to identify users. In this case we’re saying email address
is how you identify a person.

Once that last PowerShell command has executed, we have an SPTrustedIdentityTokenIssuer that can
be used with our SharePo
int web application. So now we’ll open up the browser and navigate to Central
Administration. Click on
the Manage Web Applications link, then click on the web application in the list
that’s going to use ADFS to authenticate, then click the Authentication
Providers button in the ribbon.

Click the link in the dialog that corresponds to the zone in which you are going to use ADFS to
authenticate. Scroll down to the Authentication Types section. You can now de
-
select NTLM, and you
should see a new provider
called “SAML Provider” in the list of trusted providers.


Check the box next to it and click the
Save

bu
tton to save your changes. Now you can go and create a
site collection for the web application. Again, describing that process step
-
by
-
step is not
in scope for
this posting, but there is one important thing to remember when you do this. When you add the Site
Collection Administrator, remember to enter the name in the format of your identity claim. For
example, in this scenario the identity claim is

email address. So when I added the Site Collection
Administrator the name I used was administrator@contoso.local, because that’s the email address of
the person I want to be the Site Collection Administrator.

Now I’m ready to try and go to my new site co
llection. I open up the browser and type in https://seo14
and hit enter. The first thing that happens is my redirected to the SignInUrl for the
SPTrustedIdentityTokenIssuer that’s associated with my web application. If you recall from the
PowerShell th
at was used to create the SPTrustedIdentityTokenIssuer, that Url is
https://congen1.contoso.local/adfs/ls
. So here’s what I see after typing the Url to my SharePoint site in
the browser:


You can see the Url in the browser window now points to my ADFS
server and you can see the graphic in
the background behind the login dialog is for the ADFS server.

You may also notice that I’m signing in
using my Windows credentials, i.e. domain
\
user. Remember I’m able to do this because I’m
authenticating on the AD
FS server, not on SharePoint. SharePoint is configured to use email address as
my identity, but what is going to happen is that I’ll authenticate over on ADFS, and then it will use the
claim rule we created to pull out my email address and groups and put
them into claims that will be sent
back to SharePoint. So then after I’ve authenticated I’m redirected back to SharePoint at
https://seo14/_trust/, as I configured in the relying party I set up in ADFS. At that point SharePoint will
complete the authenti
cation process on its side as it takes the claims it got in the SAML token and
converts it into an SPUser. Then I finally arrive at the home page for the site:


You’ll notice the login control in the upper right
-
hand part of the page is displaying my ide
ntity as email
address, since that is my identity claim.

That’s the complete end
-
to
-
end process with a little explanation on the side. You should be able to use
it to get your sites configured and running by following these instructions.