ADFS Product Support Blog

Office Integration with MOSS and ADFS

jimsim — Tue, 16 Jun 2009 20:39:00 GMT

Previously, Office Integration with SharePoint secured by forms based authentication was not possible. The new ability of the Office client applications in Office 2007 SP2 to perform a forms login helps to solve this problem. You will need to install this post SP2 fix to your client machines to gain this functionality. What is needed in conjunction with it, is means to send an authentication prompt to the Office client if the login cookie doesn’t exist or has expired. The Identity Management team at Microsoft, in conjunction with the Microsoft Office team, have developed an HttpModule for SharePoint that does just that. The HttpModule is available as a source code sample download from this blog.

You will need to compile the source to a DLL and then install it to the GAC on the SharePoint front end servers.

To compile you will need Microsoft Visual C# 2008 edition .

You can download Microsoft Visual C# 2008 Express edition from http://www.microsoft.com/express/download/#webInstall

a. Extract the code sample locally for example c:\Patch

b. Open Microsoft Visual C# 2008

c. From the menu options select File / Open Project and browse to the file c:\Patch\retail\AdfsHttpModule.sln

d. Next, select build from the menu options

e. When prompted for password type “password”

f. The default location of the built DLL c:\Patch\release\release\bin

To install the compiled DLL to the GAC use the GACUTIL application. GACUTIL can be obtained by installing the .NET Framework 2.0 SDK

The command to install it would be:

“GACUTIL /i adfsfba.dll”

Next - make the following changes to SharePoint:

1. Go to Central Administration, click the Application Management tab, and click the Authentication Providers link.

2. In the Web Applications drop–down list, select the Web application that contains a forms authentication zone, and then click the link for the zone that is configured to use forms authentication.

3. On the Settings page for the zone, select the Enable anonymous access check box, and then set Enable Client Integration? to Yes.

Note:

Selecting the Enable anonymous access check box does not, by itself, grant anonymous access to any content in the Web application. However, it is needed to enable the Office client applications to gather enough information about the site to display the logon window.

4. Edit the web.config file as follows on each front end Web server in the farm for the zone that is secured with ADFS:

a. Add the entry for the HttpModule code sample after the ADFS module. You should see an existing entry such as the following.

Xml

Copy Code

<add

name="Identity Federation Services Application Authentication Module"

type="System.Web.Security.SingleSignOn.WebSsoAuthenticationModule, System.Web.Security.SingleSignOn,

Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null"

b. Add the following entry immediately after the existing entry.

Xml

Copy Code

<add

name="ADFS Module for Office Forms Based Auth"

type="ADFSFBA.ADFSFBAHttpModule,ADFSFBA,Version=1.0.0.0,

Culture=neutral,PublicKeyToken=083ff59054782422,Custom=null"

c. Add the usettp element in the websso section, as follows.

Xml

Copy Code

…

…

</websso>

After you complete these steps, you can use the Office client in a nearly seamless, integrated experience with SharePoint Server. The authentication prompts for an ADFS-secured site can be further reduced by adding the site for the account logon service (FS-A) to the Local Intranet Zone in Internet Explorer.

ADFSDiag has been updated again!

jimsim — Thu, 11 Dec 2008 20:16:00 GMT

The updated tool can be found here. The attachment contains both 32 and 64 bit installers.

A cool new feature - Claim Flow Analysis has been added to this version. I'll write up a quick blog on how to use this feature soon.

Adding an ADFS Proxy Server

jimsim — Tue, 10 Jun 2008 19:05:00 GMT

I'm going on an hour trying to get the screen shots formatted correctly. Live Writer is making them too small. I'll just attach the word document to the end if you want to see the pictures better. I'm done messing around with this for now! If you know what I'm doing wrong - please send me a comment!

In this blog, I will discuss the steps needed to add an ADFS Proxy to your environment. I will also outline a couple of gotchas that I ran into along the way.

First, we will start with the certificates…We need an SSL certificate on the default web site that has a subject name which matches the Federation Server URL. Since I am adding a proxy on the Account side, I need a SSL certificate with adfsaccount.adatum.com

A good checkpoint would be to simply visit https://adfsaccount.adatum.com and make sure you can get to the Under Construction page without any certificate errors. In order to do this, we need to make sure that the name adfsaccount.adatum.com resolves to the IP address of the Proxy machine instead of the FS-A server. My DNS server currently resolves adfsaccount.adatum.com to the IP address of the FS-A. So, the easiest way to do this in a lab environment like this is by using a host file entry.

My Proxy Server has an IP of 192.168.0.119 – so I can use the host file to bypass DNS resolution for this name. It is easy to comment out the entry and put it back so you can simulate an external client and internal client quickly.

Now that we have SSL setup properly and our client machine resolves the name to the IP of the proxy server, we are ready to request and install a Client Authentication Certificate in the local computer store.

In my first attempt and putting this blog together, I ran into some issues with the client auth certificate, so it may be good information for you to read that blog before going any further.

The client authentication certificate will be used by the Proxy server to authenticate with the Federation Server. We will install it into the local computer personal store, then export the public key and add it to the Trust Policy on the Federation Server.

Unlike the SSL certificate, we don’t need to worry about any specific name. We only care that the EKU has client authentication.

Below is a shot of my certificate server web page after doing “advanced certificate request” then “Create and submit a request to this CA”

In the name field, I just put something useful to identify the certificate quickly when I view my local computer store.

If you have a plain Standalone CA, your screen should look like this:

You can check the box to store the certificate in your local store and give it a name like ADFS Proxy Certificate. This will save you some extra steps that I had to go through.

On my CA, I have had to issue some certificates to some Vista and WS08 machines. In order to do this from a 2003 CA, you need to update the web enrollment pages. Instructions and the hotfix needed to do this are outlined in this KB article. In the article it states the following about computer enrollement:

Computer certificate enrollment
Administrative rights are required to request a computer certificate. In Windows Vista, Microsoft Internet Explorer does not use administrative rights to run. Therefore, the option to store a computer certificate in the computer store was removed from the Windows Server 2008 certificate enrollment pages.

Note the lack of the ability to install the certificate directly into the computer store. So I had to install it in the user store, then export with the private key, then import to the computer store. I had to check the “mark keys as exportable” checkbox before placing the request.

After approving the request on my CA, then going back to check on the status of a pending request, the only option is to “Install this certificate” and when you do this, it is placed in the user store.

From the user store, do an export with the private key

Then import to the local computer store and this will complete the Client Authentication Certificate request and your local computer store should look like this:

The next step is to install the ADFS Proxy component on this server.

Setup will prompt you to choose a Client Authentication Certificate.

After choosing Select – you will be displayed with a list of all certificates that have the Client EKU in the local computer store. In this setup, I only have one.

The next piece of information that setup will want is the FQDN of the Federation Server. We also should ensure that the Proxy Server resolves this name to the IP of the actual Federation Server. In most cases, this is accomplished with a host file entry. I will explain the name resolution portion of this more at the end of this blog.

The next item we need to do is export our Client Authentication Certificate (only the public key is needed) and copy it to the Federation Server.

Now we need to go to the Federation Server itself and launch ADFS.MSC. From the snap-in, go to properties of the Trust Policy and then go to the FSP Certificates tab. This is where we are going to add the exported client authentication certificate.

If you go back to the Proxy server and launch ADFS.MSC, you will notice there isn’t much to configure here and all the information needed should already be present.

Next, from the client machine that we have a host file entry on, we will enter the web application URL. Instead of being redirected to the FS-A when the client resolves adfsaccount.adatum.com it will go to the FS-A Proxy and we get a Forms Based Auth page like this:

This is the clientlogon.aspx page from the Proxy Server and the user is prompted for Username/Password each time they access an ADFS enabled application.

I’m going to try to cover a few items that often cause confusion with the Proxy component.

1. The server does not have to be domain joined. It can be and often is a standalone server in the perimeter network. A typical setup would be to have the Proxy in the DMZ and a firewall rule which allows communication over 443 between the Proxy and the Federation server only.

2. The matching certificate subject names on the Federation Server and the Federation Server Proxy also cause confusion. The reason for this is that the ADFS server can only have a single endpoint URL. The web servers and partner federation servers can only be configured with a single URL for federation services. In my example it is adfsaccount.adatum.com. My Federation Server has an IP address of 192.168.0.170 and my Federation Proxy Server has an IP address of 192.168.0.119 (normally this would be a public IP since it would be in the DMZ). My internal DNS server has an A record for adfsaccount.adatum.com à 192.168.0.170, but the internet DNS servers would have an A record for adfsaccount.adatum.com à 192.168.0.119

If we think about this – if the client is internal to the network, it will point to internal DNS for name resolution and will resolve the name to the .170 address and never visit the Proxy Server. This will result in a single sign on experience as the client has already entered username/password to authenticate with a DC on the internal network.

If the client is at home or at a public place on the internet, they will be pointed to some ISP DNS server for name resolution. This will resolve the name to the .119 address and the user will get a Forms Based Authentication experience because we assume they have not authenticated with a DC on the internal network.

Thru the use of a host file on the client machine, we can simulate resolving the name to different IP addresses quickly. The client is pointed to internal DNS so it resolves the name to .170, but a host file entry with the adfsaccount.adatum.com to the .119 address will bypass DNS and simulate a different DNS server with the .119 for that name.

I hope this is clear and I’m not over explaining. Please feel free to comment to this post if it isn’t clear or if you have a better way to explain.

Interesting problem when adding an ADFS Proxy

jimsim — Wed, 04 Jun 2008 18:10:00 GMT

I am working on a blog post (step-by-step) for the Proxy component and I ran into a problem yesterday that ran me around pretty good. We have seen this issue or variations of it on some support cases recently, so I thought the actual problem itself would make a good post.

The problem is caused by permissions to the private key on the Client Authentication Certificate needed. In my initial attempt to setup and document the Proxy component, I made a request to my Standalone CA for a client authentication certificate. After approving the request, the only option from the certificate web page was to "install this certificate". Next, when I viewed the certificate snap-in on the proxy server, I noticed that the certificate was installed to the user store and not the computer store. I simply did a copy paste operation from user to computer. This appeared to work for me because when I double clicked the certificate, it looked fine. I saw the "You have a private key" on the general tab and I assumed all was well.

When I went to test - I received a failure. The first thing I did was run the ADFS Diagnostic tool. I ran it on the FS-A, then copied the file to the FS-A Proxy. I passed all tests and the tool was not finding the failure!

Here are the Event Log and Debug Logs from my FS-A and FS-A Proxy when I attempted to access the application with the Proxy in place:

From the FS-A

Event Viewer:

Event Type: Error

Event Source: ADFS Federation Service

Event Category: None

Event ID: 664

Date: 6/3/2008

Time: 5:13:09 PM

User: N/A

Computer: ADFSACCOUNT

Description:

The Federation Service failed a privileged Web method call because Secure Sockets Layer (SSL) client authentication information was not available.

This event can occur if the client does not provide a client certificate or if Internet Information Services (IIS) rejects the client's certificate because it does not chain to a trusted root certification authority in the Federation Service.

User Action

If this is a valid call from the Federation Service Proxy, ensure that the root of the Federation Service Proxy client certificate is trusted by the Federation Service.

Debug logs:

2008-06-03T22:13:09 [INFO] Processing HTTP POST: https://adfsaccount.adatum.com/adfs/fs/FederationServerService.asmx

2008-06-03T22:13:09 [VERBOSE] Received message that is not SignIn Request or Response.

2008-06-03T22:13:09 [ERROR] MethodInvocationCheck: Client cert is not present

2008-06-03T22:13:09 [EVENTLOG] Error ProxyWebMethodAccessDeniedNoCert ()

2008-06-03T22:13:09 [ERROR] MethodInvocationCheck: Denying access

From the FS-A Proxy

Event Viewer:

Event Type: Error

Event Source: ADFS

Event Category: None

Event ID: 605

Date: 6/3/2008

Time: 5:13:09 PM

User: N/A

Computer: FSA-PROXY

Description:

The Federation Service Proxy encountered an exception when it called a Federation Service Web method.

Federation Server URL: https://adfsaccount.adatum.com/adfs/fs/FederationServerService.asmx

Web method: GetProxyTrustConfiguration

Proxy certificate thumbprint: ECF1FE79E51231DF48098E1044233FCBDABF04CC

This may cause a user request to fail.

User Action

The exception details may give an indication of the precise problem.

Check network connectivity between the Federation Service Proxy and the Federation Service.

Ensure that the Federation Service is running.

Ensure that the Federation Service Proxy client authentication certificate has been added to the list of proxy authentication certificates in the Federation Service trust policy.

Ensure that the Federation Service Proxy client authentication certificate chains to a root that is trusted by the Federation Service.

Ensure that the Federation Service Internet Information Services (IIS) Secure Sockets Layer (SSL) server certificate chains to a root that is trusted by the Federation Service Proxy.

Ensure that the Federation Service Uniform Resource Locator (URL) that is configured in the Federation Service Proxy web.config uses the name that is the subject of the Federation Service IIS SSL server certificate.

Additional Data

Exception details:

System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> Attempted to perform an unauthorized operation.

at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall)

at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters)

at System.Web.Security.SingleSignOn.FederationServerSoapProxy.GetProxyTrustConfiguration(VersionInformation proxyVersion, VersionInformation& fsVersion, ProxyInformation& proxyInformation, TrustConfigurationData[]& trustConfig)

at System.Web.Security.SingleSignOn.LSPersistentState.GetPolicy(VersionInformation& fsVersion, ProxyInformation& proxyInformation, TrustConfigurationData[]& data)

Debug logs:

2008-06-03T22:13:09 [VERBOSE] Processing HTTP GET: https://adfsaccount.adatum.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:treyresearch&wct=2008-06-03T22:13:09Z&wctx=https://adfsweb.treyresearch.net:8081/claimapp/\https://adfsweb.treyresearch.net:8081/claimapp/default.aspx

2008-06-03T22:13:09 [VERBOSE] Received SignIn Request.

2008-06-03T22:13:09 [ERROR] Exception from GetProxyTrustConfiguration: System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> Attempted to perform an unauthorized operation.

at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall)

at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters)

at System.Web.Security.SingleSignOn.LSPersistentState.GetPolicy(VersionInformation& fsVersion, ProxyInformation& proxyInformation, TrustConfigurationData[]& data)

2008-06-03T22:13:09 [EVENTLOG] Error ExceptionFromFedServer (https://adfsaccount.adatum.com/adfs/fs/FederationServerService.asmx, GetProxyTrustConfiguration, ECF1FE79E51231DF48098E1044233FCBDABF04CC, System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> Attempted to perform an unauthorized operation.

at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall)

at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters)

at System.Web.Security.SingleSignOn.LSPersistentState.GetPolicy(VersionInformation& fsVersion, ProxyInformation& proxyInformation, TrustConfigurationData[]& data))

As you can see, there is a problem with the client auth certificate somewhere. I did a fair amount of double checking my steps - but everything looked correct and seemed to be checking out. The doubt was starting to creep in - I started to wonder how much I knew about this stuff! Then I remembered an issue that came up a few weeks ago.

The diagnostic tool does check for the existence and proper permissions of the private key and will flag it - but it does so in the user context. ADFS is operating under the machine context. So when I look at the certificate or run some certutil commands against it - it all checks out because I'm in my user security context. If I launch a CMD prompt with AT scheduler and run the same commands or run the Diagnostic tool - I find the error. The local computer does not have permissions to the private key of the client authentication certificate.

I was able to re-issue the certificate and mark the private keys as exportable, then do an export/import operation from the user store to computer store and everything worked as expected.

Since Client Authentication certificates are commonly used for user operations vs. computer operations - it is easy to see how others could hit this very same problem. Hopefully the errors and debug log entries will make this blog post discoverable for others hitting this.

Using ADFS with Constrained Delegation

jimsim — Wed, 14 May 2008 01:08:00 GMT

With ADFS - the authentication token issued is good for the web server with the agent installed. It is a local RPC token and cannot go off the box. With some additional configuration, you can configure ADFS to go off the box and delegate with a kerbitized back-end. There are some caveats - namely, a shadow account must exist in the resource forest. If you are in a WebSSO scenario - then this isn't a big deal because the account is already there. If you are in a Federated WebSSO scenario, you will need to create accounts that have a matching UPN address.

Also, keep in mind that you will need to first do Protocol Transition, then Constrained Delegation.

Start with the ADFS step-by-step lab found here with Adatum (account) and Treyresearch (resource) setup as noted:

FS-A is running on a DC

FS-R is running on a DC

Web Server is running on a member server of the FS-R domain

The web application used for this test is attached – it simply enumerates the contents of ou=a,dc=treyresearch,dc=net.

This guide enables constrained delegation without TCB on an AppPool identity. Many admins are concerned about any accounts with TCB enabled, so this should allow for better security practices with ADFS. This Whitepaper discusses the requirements and TCB user right in fairly good detail: http://technet2.microsoft.com/WindowsServer/en/Library/c312ba01-318f-46ca-990e-a597f3c294eb1033.mspx?mfr=true

The steps necessary to demo the functionality are detailed below.

Create a shadow user for adatum\adamcar in the treyresearch forest
- You must first add a upn suffix of adatum.com using domain.msc - the shadow account uses the adatum upn suffix address
Create two domain service accounts in the Treyresearch.net domain –
- One called webservice (for the web app pool identity)
- The other called ifs_account (for the adfs web agent)
On the local security policy of the web server – add these user rights to ifs_account:
- Act as part of the operating system
- Logon as a Service
- Generate Security Audit Events
On the local security policy of the web server – add these user rights to webservice:
- Logon as a Service
- Generate Security Audit Event
- NOTE: The App pool identity does not have TCB in this setup
Add both domain service accounts to the Web Server machine's local IIS_WPG group
Make sure both domain service accounts have write access to c:\windows\temp and c:\windows\microsoft.net\framework\v2.0.50727\temporary asp.net files
Change the Application Pool Identity for Web application to the webservice domain service account
Change the ADFS Web Agent service to run under the ifs_account
On the resource DC open the Users and Computers snapin, and on the delegation tab of both domain service accounts specify
- Trust user for specified services only
- Use any authentication protocol
- Add the domain controller’s LDAP service record.
Add the Web application code from here to the web server and enable the ADFS NT-Token based Web Agent
In ADFS.MSC on the FS-R, add a new token application – only enable the UPN claim.
In ADFS.MSC on the FS-R, go to the A. Datum account partner properties and on the resource accounts tab choose Resource accounts exist for some users (prefer resource accounts)
Create an OU and remove authenticated users from the security, add the adamcar shadow account and grant permissions. Enable object access auditing on the OU.

From an XP client in the Adatum forest logged on as Adamcar@adatum.com - launch a browser and open https://adfsweb.treyresarch.net/ou/default.aspx

The page writes out the identity of treyresearch\adamcar, then simply press the button and the contents of ou=a,dc=treyresearch,dc=net are displayed in the text box.

The DC’s security log should show the following:

Event Type: Success Audit

Event Source: Security

Event Category: Logon/Logoff

Event ID: 540

Date: 5/2/2008

Time: 11:44:14 AM

User: TREYRESEARCH\adamcar

Computer: ADFSRESOURCE

Description:

Successful Network Logon:

User Name: adamcar@adatum.com

Domain: TREYRESEARCH.NET

Logon ID: (0x0,0x5791A)

Logon Type: 3

Logon Process: Kerberos

Authentication Package: Kerberos

Workstation Name:

Logon GUID: {f825dc83-9f3c-feea-5c82-663d6ca646f8}

Caller User Name: -

Caller Domain: -

Caller Logon ID: -

Caller Process ID: -

Transited Services:

WEBSERVICE@TREYRESEARCH.NET

Source Network Address: 192.168.0.121

Source Port: 1150

Event Type: Success Audit

Event Source: Security

Event Category: Directory Service Access

Event ID: 566

Date: 5/2/2008

Time: 11:44:14 AM

User: TREYRESEARCH\adamcar

Computer: ADFSRESOURCE

Description:

Object Operation:

Object Server: DS

Operation Type: Object Access

Object Type: organizationalUnit

Object Name: OU=a,DC=treyresearch,DC=net

Handle ID: -

Primary User Name: ADFSRESOURCE$

Primary Domain: TREYRESEARCH

Primary Logon ID: (0x0,0x3E7)

Client User Name: adamcar@adatum.com

Client Domain:

Client Logon ID: (0x0,0x5791A)

Accesses: List Contents

Properties:

List Contents

organizationalUnit

Additional Info:

Additional Info2:

Access Mask: 0x4

Script to configure SharePoint to use ADFS authentication

jimsim — Thu, 01 Nov 2007 23:02:00 GMT

More great tools by the ADFS team...

Problems with the web.config files are one of the more common issues we see with ADFS/MOSS cases in PSS. Now there is a script with will make the modifications for you.

It is located on the SharePoint team blog and can be accessed here.

ADFS Diagnostic Tool

jimsim — Thu, 01 Nov 2007 22:44:00 GMT

A huge thanks to the ADFS test team for developing such a great tool.

Here is a quick "how to"

The tool is very simple to use and provides a graphical UI. In order to perform distributed diagnosis, i.e. diagnose failures based on the configuration of multiple machines in the scenario, it’s necessary to copy the out file generated by the tool each time it’s run and use it as an input/output file when running the tool on the next machine.

For example, to debug a scenario with an FS at the account role (FS-A), an FS at the resource role (FS-R) and a Web Server (WS), first run the tool on the FS-A selecting a new file, say adfsdiag.out. After the tool is run, this file will now contain configuration information relative to the FS-A. Copy the file to the FS-R machine and run the tool there, this time selecting the existing adfsdiag.out file. The tool will detect it already contains information relative to other roles and will execute extra configuration checks, for example, a claim flow check that verifies the outgoing claims sent by the FS-A match the incoming claims expected by the FS-R. After this second run, adfsdiag.out will contain information relative to both the FS-A and FS-R. Finally, copy the out file to the WS machine and run the tool again following the same steps. When running the tool for a role for which there’s already information present in the selected file, the old data for that role will be overwritten with the new information, making it possible to fix errors on a machine and re-run the tool without having to start the whole process all over again. There’s no “right order” to run the tool, all of them should give the same output, except for some certificate checks that will only be executed at the WS in case the information from the FS-R is available beforehand

Please give this tool a try and provide any feedback to this blog.

Enabling debug logging for Claims Aware Applications

jimsim — Fri, 10 Aug 2007 22:16:00 GMT

Place the following in your applications web.config file. Place this after the </system.net> section of the file.

<system.diagnostics>

</switches>

</listeners>

</trace>

</system.diagnostics>

Update on configuring MOSS as a claims aware application

jimsim — Tue, 31 Jul 2007 04:11:00 GMT

======================================================================================

UPDATE:

I'm not going to remove this blog or the original blog on the web.config entries - but I do want to make note that these web.config files should not be modified directly anymore. Please use the SetupSharePointADFS.vbs file to configure the MOSS applications for the SSO Provider. The script eliminates the possiblility of typo's, etc from these config files. I have used the script many times and it works great. If you open the help file included and go to the end - scenario 2 covers is the syntax you will use if you follow my other blog posts.

======================================================================================

It's been a few months since I posted the steps for configuring the WebSSO provider in MOSS. Recently, we have seen a spike in cases involving this configuration. In almost all of these cases, the problem has been with the web.config files. I'm going to try to highlight a couple of key points when setting this configuration up. I've also made some minor changes to the original post to eliminate some confusion.

First item - there are three web.config files you will edit, the central admin file, the intranet file which uses Windows Integrated Authentication, and the extranet site web.config. You will make the same changes to the central admin and intranet files. I'm going to put the section needed here. I recommend a copy/paste operation to notepad, change the fs-server to your actual server name, indent it how you like it, then modify the actual web.config files by copy/paste from your notepad file to the web.config file.

In the intranet and the central admin web.config files add this section directly below the <authentication mode> section

</providers>
</membership>
<roleManager enabled="true" defaultProvider="AspNetWindowsTokenRoleProvider">
<providers>
<remove name="AspNetSqlRoleProvider" /> <add name="SingleSignOnRoleProvider2" type="System.Web.Security.SingleSignOn.SingleSignOnRoleProvider2, System.Web.Security.SingleSignOn.PartialTrust, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" fs="https://fs-server/adfs/fs/federationserverservice.asmx" />
</providers>
</roleManager>

Now - on to the web.config file for the extranet. Add these entries:

Add the following entry within the <configSections> node

Add the following entry to the <httpModules> node

The ADFS authentication module should always be specified after the sharepoint SPRequest module in the in the <httpModules> section of the web.config file. It is safest to add it as the last entry in that section.

Add the following entry to the directly after the <authentication mode> node

<membership defaultProvider="SingleSignOnMembershipProvider2">
<providers>
<add name="SingleSignOnMembershipProvider2" type="System.Web.Security.SingleSignOn.SingleSignOnMembershipProvider2, System.Web.Security.SingleSignOn.PartialTrust, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" fs="https://fs-server/adfs/fs/federationserverservice.asmx" />
</providers>
</membership>
<roleManager enabled="true" defaultProvider="SingleSignOnRoleProvider2">
<providers>
<add name="SingleSignOnRoleProvider2" type="System.Web.Security.SingleSignOn.SingleSignOnRoleProvider2, System.Web.Security.SingleSignOn.PartialTrust, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" fs="https://fs-server/adfs/fs/federationserverservice.asmx" />
</providers>
</roleManager>
<websso>
<authenticationrequired />
<auditlevel>55</auditlevel>
<urls>
<returnurl>https://your_application</returnurl>
</urls>
<fs>https://fs-server/adfs/fs/federationserverservice.asmx</fs>
<isSharePoint />
</websso>

I've tried to clean up the trailing spaces and line it up with the technet documentation for my friends down in Houston ;)

Last - the latest issue we have seen is that we couldn't add a user by their UPN address to the SharePoint site. It turned out that an account store was not present on the FS-R. Here is the explanation on why this matters.

<snip>

The people picker will look up a user based on the email name(note: not the UPN) by successively calling ADFS MembershipProvider methods. During invitation time, the ADFS membership provider will call web method GetTrustedRealmUri() to FS and return the appropriate results.

If the input names are of valid email syntax, in either of the following 3 cases, the people picker can successfully resolve the user (which means the GetTrustedRealmUri() web method will return TRUE):

1. The user’s email suffix is accepted from one of the Federation trust partners.

2. There is a Windows Trust setup in the Policy with the account partner and is set to accept all domain suffixes.

3. There are account stores configured in the Trust Policy.

</snip>

ADFS Certificates - SSL, Token Signing, and Client Authentication Certs

jimsim — Tue, 24 Jul 2007 01:11:00 GMT

We are seeing quite a few support calls relating to certificate problems. Many of these are due to a misunderstanding of how the various certificates are used.

ADFS/PKI issues are often very difficult to diagnose for the following reason – a lack of logging telling you what the problem is.

For example – if the SSL certificate on your Web Server is incorrect or has a problem like missing a private key. The user experience will be a page can’t be displayed error and absolutely nothing will be logged in the event viewer, security log, or adfs debug logs.

There are several variations of this – but if you aren’t getting *anything* in the logs – start looking at your certificates! More times than not – it is the SSL certificate and you aren’t even getting to ADFS which is why there aren’t any error messages to work with.

Other sub-items that come to mind on this topic are:

1. Using Certutil to verify the certificates in question

2. What type of certificate should I use? 3^rd Party, an internal CA, or a combination of the two.

In addition to this blog, you should also review the TechNet documentation on Understanding Certificates starting here. Between the two, I hope it makes it clear what goes where.

Also, it may be helpful to revisit my blog on the PKI portion of setting up a lab. That is located here.

ADFS Certificates for Federation Servers

SSL Certificate

The SSL certificates must be trusted by the client machine which accesses the web sites. Since the client machine (in a Federated WebSSO scenario) will visit the WS, then the FS-R, then the FS-A, the client must trust all three SSL certificates. For this reason, it may make sense to use a 3^rd party certificate for the SSL certificate.

A SSL certificate is in place to encrypt the session between client and the server. These certificates are not specific to ADFS, but rather specific to IIS.

The Subject Name of the SSL certificate must match the names used in the ADFS configuration. For example, if you specify a federation server endpoint URL as https://adfsresource.treyresearch.net/adfs/ls/ - then the subject name on the SSL certificate for that server must be “adfsresource.treyresearch.net” This is a very important item and a common misconfiguration. The name can be anything – it just needs to match. If you choose to setup ADFS for use on the intranet only and you want to use only the host name, then the endpoint URL would be https://adfsresource/adfs/ls/ and the Subject Name on the certificate should be “adfsresource”

The same Subject Name rules also apply to the web sites protected by ADFS. The name on the certificate should match the name clients will use to access the ADFS protected web site.

Token Signing Certificate

On the Federation Servers – you also need a token signing certificate. This certificate can be any X.509 certificate, the intended purpose or EKU doesn’t matter. The “issued to” name doesn’t matter. Any X.509 certificate will do. When you install the Federation Server role – setup will prompt you to pick a token signing certificate OR let setup create a self signed certificate for you.

Self Signed Certificates are OK for a lab – but should not be used in production deployments.

If you choose to select a token signing certificate in the setup portion, you will be presented with a list of all certificates present in the local machine personal certificate store. Whichever option you choose, the setup program will place an export of the token signing certificate in the list of verification certificates for the same machine. A verification certificate is simply an export (less the private key) of the token signing certificate. Each Federation Server must have a verification certificate for its own token signing certificate. If you change the token signing certificate later – the adfs.msc program will display a message telling you that the new verification certificate will be added to the list of verification certificates.

It seems a little strange that a Federation Server needs to verify its own token signing certificate, but that is the way it works…

A token signing certificate is used to “sign the ADFS authentication token” - this is the token that contains a users claims and is used to make authorization decisions at the website. The verification token is used to “verify” the token was sent by the federated partner and that it has not been tampered with.

In a Federated WebSSO scenario where you have an Account Partner and a Resource Partner, the Account Partner’s verification certificate must be present on the Resource Partners trust policy file. This certificate (by default) must be trusted, must be able to chain to the root, and must be able to access the certificate revocation list.

IMPORTANT NOTE:

Using the SSL certificate for the token signing certificate will work – but this should not be the configuration you use in production. This is considered bad key hygiene. The SSL certificate for the web site serves one purpose – the token signing certificate serves an entirely different purpose. This is the most misunderstood item we see.

Here is a screenshot from my Federation Server – notice how the SSL certificate is “issued to” adfsresource.treyresearch.net and the Token Signing certificate I use has a friendly name in the Issued To

ADFS Certificates for Federation Server Proxies

SSL Certificate

As with the other Federation Server roles, the FS-P web site will need a SSL certificate. The Subject Name must match the Federation Server endpoint URL specified on the Federation Server. If you have your endpoint URL as https://adfsresource.treyresearch.net/adfs/ls/ - the SSL certificate for the federation server itself should have a Subject Name of adfsresource.treyresearch.net and the Federation Server Proxy SSL certificate should also have a Subject Name of adfsresource.treyresearch.net. Even if the machine name is adfsproxy.treyresearch.net – the URL the client will hit is adfsresource.treyresearch.net. Whether or not the client is redirected to the IP address of adfsresource or adfsproxy depends on how the client resolves that name via DNS.

A typical name resolution setup for a Proxy scenario would be to have client machines on the internal LAN resolve adfsresource to the actual IP address of adfsresource.

Client machines on the internet (or outside of your internal LAN) resolve the name adfsresource.treyresearch.net to the IP address of adfsproxy.treyresearch.net. It is important to remember that you won’t specify the name adfsproxy.treyresearch.net anywhere in your setup. The website on this server should have a certificate issued to the name adfsresource.treyresearch.net.

The adfsproxy.treresearch.net server should be configured to resolve the name adfsresource.treyresearch.net to the actual IP address of adfsresource.treyresearch.net (this machine should be the only server in the DMZ/Internet) that knows adfsresource by its real IP. This is commonly accomplished by using a host file on adfsproxy.

With the scenario setup like this – the internal LAN clients will enjoy a single sign on experience when visiting an ADFS resource (not be prompted for credentials). Users external to the LAN will be presented with a forms based authentication page asking for username/password.

This is typically a desired configuration because the internet user probably hasn’t authenticated with his or her home domain.

Client Authentication Certificate

I like to explain the client authenticate certificate as “It is sort of like the token signing certificate, but for ADFS proxy servers” – while this isn’t really the case, it is a different certificate than what is used for SSL on the website. This certificate must have “client authentication” as an intended purpose. When you install the Federation Proxy component, when you choose your client authentication certificate, you will be presented with a list of certificates that have an EKU of “Client Authentication.” If you don’t have any in the local machine personal store, the list will be empty.

The client authentication certificate and its private key reside on the ADFS Proxy Server, but a copy of this certificate with only the public key resides on the Federation Server. This is why I try to explain it as “think of it like the proxies TS certificate” - it is different in many ways. Most importantly, it isn’t used to sign any tokens. But again – this is a completely different certificate than the one used for SSL on the server.