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.

ADFS Claims Aware Virtual Lab - now online

jimsim — Sat, 21 Jul 2007 16:33:53 GMT

I recently worked with the folks that handle the virtual labs for Technet. We corrected the certificate issues and some other minor issues. You can access the lab here.

Event Overview:

After completing this lab, you will be better able to set-up a trust relationship among business partners. You will walk-through creating, populating, and transforming "claims" about users that are shared between security contexts. Additionally, you will turn federation claims into authorization decisions in a federated application and finally, you will integrate a claims-aware application.

This is a very cool way to get your hands on ADFS without having to setup 3 or 4 virtual machines.

Configuring SQL Reporting Services to use ADFS Authentication

jimsim — Tue, 08 May 2007 01:51:11 GMT

Special thanks to Rahul Shelar and Sachin Mundra from the ADFS and SQL teams for working with me on this latest issue. Without their help, I would still be banging my head against the wall. I learned quite a bit about SSRS along the way and also learned what the stupid checkbox in IIS really meant.

This document assumes SSRS is installed and working properly using Windows Integrated Authentication. SQL Reporting Services is installed on a R2 member server named SRS.Treyresearch.net and the SQL 2005 database server is located on another R2 member server named SQL.Treyersearch.net

The following is a screenshot of IIS Manager after initial installation and configuration of SSRS.

The App Pool Identity can be either Network Service (default) or a domain service account

Steps to configure the site for ADFS

1. Enter the FQDN and path to the federationserverservice.asmx page of the FS-R on the web sites node of IIS.

2. Enable the ADFS agent on the default web site

3. Add the token based application to ADFS.MSC on the resource federation server

4. On the Reports Virtual Directory, add the ADFS ISAPI extension (c:\windows\system32\ifsext.dll)

a. Properties of Reports Virtual Directory in IIS Manager
b. Configuration button on the Virtual Directory tab
c. Type in or browse to c:\windows\system32\ifsext.dll
d. deselect the checkbox labeled “Verify file exists”
e. Choose Insert

5. Verify the Directory Security Permissions are set to anonymous on the Reports Directory

6. Repeat steps 4 and 5 on the ReportServer Virtual Directory. When adding IFSEXT.DLL to the Application Wildcard Maps area – you must choose “Move Up” to ensure it is at the top of the list. The 2.0 Framework ISAPI is present on the ReportServer virtual directory, but not on Reports.

This means that the Reports directory will only have IFSEXT.DLL specified, but the ReportServer directory will have IFSEXT.DLL specified first, then ASPNET_ISAPI.DLL listed second. Again – it is crucial that the “Verify File Exists” checkbox is NOT selected.

7. Modify the RSWebApplication.config file located at c:\program files\Microsoft SQL Server\MSSQL.1\Reporting Services\ReportManager and modify/add the following lines

<ReportServerUrl>https://srs.treyresearch.net/ReportServer</ReportServerUrl>

<PassThroughCookie>_WebSsoAuth</PassThroughCookie>

<PassThroughCookie>_WebSsoAuth0</PassThroughCookie>

</PassThroughCookies>

</CustomAuthenticationUI>

The file should look like this:

More information on the RSWebApplication.config settings can be found here:

Configuring Report Manager to Pass Custom Authentication Cookies

http://msdn2.microsoft.com/en-us/library/ms345241.aspx

8. Since the ADFS Token based agent writes an Local impersonation NT Token, you cannot impersonate user credentials to access the SQL database residing on a different machine than SSRS

a. In SSRS Configuration Manager, go to the Database Setup section and specify an account to be used to contact the SQL database. You many use Windows Credentials or SQL Credentials here

9. Test accessing the ReportServer and Reports with ADFS enabled. You must use the FQDN in the address – i.e. https://srs.treyreserach.net/Reports or https://srs.treyresearch.net/ReportServer

a. http://srs/Reports will no longer work as it did under Windows Integrated Auth. You must use the URL specified on the ADFS Web Agent tab and in ADFS.MSC.

IFSEXT.DLL and the dialog box that is so very WRONG

jimsim — Fri, 27 Apr 2007 03:21:00 GMT

Ifsext.dll is the ADFS ISAPI used by the Token based Web Agent...We have seen issues before where we either need to add this manually or move it to the top of the list on the application config section of IIS.

Once you go the properties of a web site, the Virtual Directory tab has a button labeled Configuration.

The bottom section of the dialog has a box that is labeled Wildcard application maps (order of implementation). This is where you may need to insert the ifsext.dll file. When you do this - the box below is presented and you can browse to the needed file.

For ADFS - this file must be at the top of the list. Using the token based applications for SharePoint 2007 - this is a common "gotcha" - the ifsext.dll is below the Framework 2.0 ISAPI. After setting everything up - you get an "access denied" error message from the site even though you have the proper group SID according to the ADFS logs and you have added that group to SharePoint permissions. Once you move the ifsext.dll to the top - everything works as expected. I used to think that was a whipping - not anymore...

The dialog that is wrong - so very very wrong, is the part that says “Verify that file exists”

What would you think this means? I can tell you that I thought it meant - verify the .dll file placed in here actually exist before you say OK.

Well – that is NOT what it means…

From the IIS Documentation:

Add/Edit Application Extension Mapping (for Wildcard Application Maps)

Executable

Type the name of the executable file (.exe or .dll). The executable file must be located on your Web server's local hard disk.

Browse

Click to locate your Web server's local hard disk for the ISAPI application.

Verify that file exists

Select Verify that file exists to instruct the Web server to verify the existence of the requested script file and to ensure that the requesting user has access permission for that script file. If the script does not exist or the user does not have permission, the appropriate warning message is returned to the browser and the script engine is not invoked. This option can be useful for scripts mapped to non-CGI executables, such as the Perl interpreter, that do not send a CGI response if the script is not accessible. Because the script must be opened twice, once by the server and once by the script engine, enabling this option can impact performance.

WOW! The fact is that if the file doesn’t exist in the location you specified – you will get an error either way.

I mentioned a future blog on SQL Reporting Services and that is still going to happen.

After just understanding this after several hours of troubleshooting by many different people - I felt I had to quickly write about it.

Having this box checked on the reportserver directory will make it so a report will never render if the toolbar is enabled. The request for /ReportServer/Reserved.ReportViewerWebControl.axd does not exist in the ReportServer directory.

Setting up an ADFS environment - Part 2

jimsim — Thu, 26 Apr 2007 03:51:00 GMT

This blog will build on my previous blog and walk you through the steps to getting your lab up and running.

Let’s start on the Account side and install the Federation Server Service. Select add/remove programs, windows components, details of Active Directory Federated Services, then check the Federation Server checkbox

Setup does a check to make sure SSL has been enabled on the web site, then it will prompt you to select a token signing certificate and select an Trust Policy or create a new one.

Instead of having setup create a self-signed token signing certificate (the default) – Choose “Select token-signing certificate” and hit the Select button

The select certificate dialog appears and displays the local computer personal certificate store. The Token signing certificate you downloaded and installed previously will be listed along with your SSL certificate for IIS. Choose the token signing certificate and complete the installation.

Repeat these steps on ADFSRESOURCE (the FS-R) and get it to same place.

Launch the ADFS snap-in (start/run/adfs.msc – or find it in the administrative tools folder). On both servers, we should now have the Federation Service installed and ready to begin the process of creating a Federation trust between the organizations.

I will start the configuration on the FS-A again and configure the information to reflect Adatum.

Right click on the Trust Policy node and choose properties. The general tab has two items of information which we will fill in to reflect “My Organization”

I recommend that you make all entries in lower case and keep the URI something short and meaningful.

Change the Federation Service URI to urn:federation:adatum

Change the Federation Service URL to https://adfsaccount.adatum.com/adfs/ls/

The display name tab can be changed if you wish. If you review the Verification Certificate tab, you will notice the same Token Signing Certificate you selected at setup is present. Each Federation Server will have a Token Signing certificate and this certificate will automatically be added to the list of verification certificates on the Trust Policy level.

Switch to the Resource side and perform the same steps on the FS-R. Populate it with the following information:

Change the Federation Service URI to urn:federation:treyresearch

Change the Federation Service URL to https://adfsresource.treyresearch.net/adfs/ls/

The next step is to configure an Account Store on the FS-A

On your FS-A, right click on the Account Stores node under My Organization and choose New – Account Store. This will launch the Add Account Store Wizard. This lab example will use an Active Directory Account Store (ADAM as an account store is worthy of a different blog)

There isn’t any configuration left to do here so just hit next and complete the wizard.

We are now ready to complete the federation trust by using the import/export feature. I recommend you use this feature as it will eliminate any typo’s or mismatches that are common to initial installations of ADFS.

Start on the FS-A and right click the Trust Policy Node – choose Export Policy from the menu. I’m going to put it in my c:\certs folder (I know it’s not a certificate – just trying to keep things organized) and name it something descriptive.

Notice the description of the Export Generic Partner Policy dialog – it tells you the following information is contained in the file:

Display Name, URL, URI, and Verification Certificate

It’s not a ton of information and it won’t help you import any claims you may configure (we will have to wait for the next version to get more options on import/export). But this does ensure the correct certificate is brought over and also URI and URL are usual suspects when initial setup doesn’t work. It really is a better way to go.

Repeat the export process on the FS-R and then copy each export file to the partner machine. The FS-A should have the “Treyresearch-FS-R export file.xml” and the FS-R should have the “Adatum-FS-A export file.xml” locally

On the account side (FS-A) , expand and right click and choose new – resource partner. The Add Resource Partners wizard appears. The first page gives the option to import a Parnter interoperability policy file

On the next page – choose Federated Web SSO

Notice how you have two options – Federated Web SSO and Federated Web SSO with Forest Trust. There are three scenarios you can setup ADFS in. Federated Web SSO, Federated Web SSO, and Web SSO. The WebSSO scenario would only involve a single company – therefore, you would never add a partner in this scenario.

Next – select UPN as the identity claim you wish to send (these can be changed later – for now, just choose UPN)

Let’s pass all UPN suffixes unchanged to the partner (again, we can change this later)

Keep the default to enable this partner and finish the wizard. Your account side ADFS snap-in should look like this:

Now – we will visit the Resource side (FS-R) and import the account partner with the file we copied over earlier.

Right click the Account Partner node under Partner Organizations and choose New – this will launch the Add Account Partner Wizard. Browse to the export file on when prompted.

Again – choose Federated Web SSO as the scenario

On the Accepted UPN suffix tab – we will enter adatum.com and choose add

Choose next, enable the application, and complete the wizard. Your ADFS snap-in on the Resource side should look like this:

At this stage we have the Federation Trust established between the two organizations. Our next task is to configure an application on the resource side and “federate it” to users on the account side.

I know I said that I would do this in two steps – but this document has been just sitting here for quite some time - Part 3 (later) will wrap it up with the application installation/configuration.

The federation trust between partners is now established – the rest is fairly easy.

The reason I’m stopping here and posting this – is mainly to clear the way for a new project (which is almost fully understood!)

I will get the steps needed to setup/configure SQL Reporting Services and use ADFS on the SSRS site. We have been heads down on this for a while now – and today we finally made some real progress!

Since my lab environment is already setup – I can get some screen shots and show you all the places to go to install/configure this.

Setting up an ADFS lab environment - Part 1

jimsim — Mon, 26 Feb 2007 16:54:00 GMT

In this blog, I’ll go though the PKI portion of setting up Trey Research and Adatum. While you can do this a number of different ways – I always setup and use a Standalone CA instead of generating self-signed certificates.

In my opinion, setting up a new CA (or making an existing lab box a CA) is faster in the long run than using self signed certificates. Also, it offers a better user experience for testing. Self signed certificates should NEVER be used for production systems.

Often, people will start with self signed, then change to CA issued certs and then generate a huge mess in the ADFS snap-in and in the certificate stores. When you get into this mess, you will find yourself looking through the thumbprint of different certificates to find the right one. If you lab setup will eventually be turned into your production environment, then do yourself a favor and setup the certificates the right way from the start.

I’ll start with the initial lab setup and end this blog at the completion of the certificate portion of the setup. Then do a part 2 blog that completes the FS setup with a sample application (the blog application) and a couple claims.

I know Nick’s step by step get’s you to the same place, but I think the PKI differences along with the order of steps I take you through are worthy enough to blog about and will help people get a good test environment up and running in short order. Performing the steps in my order makes the setup more logical to me - guess that's why it's "my order"

One last note on this...I've worked with a number of customers who had trouble setting up the step by step and getting it to work. In almost all cases - the problem was that they deviated from the guide. Sometimes - not doing something as it says in the step-by-step guide (or changing it around) matters, sometimes not.

I will try to stop at certain checkpoints and explain what we have done and why we did it.

Here’s my method (using Virtual Machines):

1. Build a R2 Enterprise Virtual Machine and install IIS, ASP, .NET 2.0 Framework. Put the support tools and resource kit on it… BGINFO that puts the IP / Machine name info on your wallpaper is handy as well. Another suggestion would be to install TextPad or some other file editor that can look at .xml files and display debug log files better than notepad. Get that server just how you like it – then run sysprep on it and copy the .vhd file off to use as the base image for the rest of your setup.

2. Create two single dc forests - name them what you like, but as I've said in the past, my lab walkthoughs will always use Adatum and TreyResearch. You may choose to set things up with Account.com and Resource.com – whatever works for you. Here are full machine names for the machines we will be installing certificates – if you have different names – you can map them to mine for the rest of the guide.

a. Adfsaccount.adatum.com - Domain controller and Federation Server for Adatum.com (FS-A)

b. Adfsresource.treyresearch.net - Domain controller and Federation Server for Treyresearch.net (FS-R)

c. Adfsweb.treyresearch.net - Web server in the Treyresearch forest. (WS)

d. Adfsclient.adatum.com - XP client in Adatum - used to test the user experience

3. Install and join an XP client to the Adatum forest

4. Install (or add the service to an existing machine) a stand-alone certificate authority. You can name it something creative like "StandaloneCA" - doesn't really matter

5. Configure DNS forwarders so both all machines can resolve adatum.com and treyresearch.net machine names

6. Install SSL certificates on the default web site of the FS-A, FS-R, and WS

7. Install the Certificate Authority CA chain in the Trusted Root store of FS-A, FS-R, WS, and the XP client

8. Install a Token Signing certificate on the FS-A and FS-R in the local computer store of your FS/DC machines

Let's get started...

At this point, you should have the forests established, name resolution configured, and the domain controllers/federation servers and the Web Server should already have IIS/Framework 2.0 installed.

The first order of business is to install a SSL certificate on the default web site of all of the servers. I like to create a directory called c:\certs on each machine while setting things up. There will be certificate request files, certificate files, then export of certificates copied to other machines, etc. by the time we are all done.

It's easier/cleaner than tossing random cert files on your desktop or the root of the c: drive.

SSL Certificates

Start by adding an SSL certificate to the default web site of each machine. Launch the IIS Certificate wizard by going to Properties of Default Web Site - Directory Security tab - Server Certificate

When going through the IIS Certificate wizard – pay attention to the Common Name page. It defaults to just your computer name and we need to change this to the FQDN of the computer.

Change it to reflect the FQDN

When you have finished the wizard, save the request file in the c:\certs folder

Next step is to launch a browser from this machine and go to http://certicate-authority-name/certsrv to access the certificate services web page. Choose Request a Certificate, then Advanced Certificate Request

Choose “Submit a request by using a base-64…”

Next – paste the contents of the certreq.txt file you created when running though the Server Certificate Wizard in IIS.

Once completed, go to your CA machine and issue the pending request from the Certificate Authority snap-in tool

Back at server where you are installing the SSL certificate - from the main page on the certsrv website, you can choose “View the status of a pending certificate request”

Download the certnew.cer file and save it to your c:\certs folder as certnew-ssl.cer so you can keep track of what this certificate is for.

We are now ready to go back to IIS and install the certificate. If you go to properties - directory security tab - server certificate - you will get this dialog

Complete the wizard by selecting the certnew-ssl.cer file you obtained in the previous step.

Install the CA Certificate Chain

After installing a SSL certificate on the Default Web Site, the next step will be to install the CA certificate in the Trusted Root Store of the local machine.

From the main certsrv page, choose “Download a CA certificate, certificate chain, or CRL”

Select “Download CA certificate chain” towards the bottom and save the file to your c:\certs folder.

NOTE: If you choose “Install this CA certificate chain” link at the top of this page – it will install to the local users trusted root store which isn’t what we want – we need this in the local computer trusted root store.

Launch a MMC and add the certificates snap-in – choose local computer.

Right click certificates folder under Trusted Root – all tasks – import. Then browse to the chain file you downloaded in the previous step. After doing this, you should see your CA listed in this folder.

At this point, we have installed a SSL Server Authentication Certificate on the default web site and installed the CA chain in the local computer Trusted Root store. These steps should be repeated on the other Federation Server, the Web Server, and your XP client

Install the Token Signing Certificate

The next step will be installing a certificate to the local computer store which will be used for the ADFS Token Signing certificate. The token signing certificate can be any type (there is no EKU requirement for the TS certificate) and we don’t have to worry about the “issued to” name like we did with the SSL certificate.

From the main certsrv web page choose Request a certificate – advanced certificate request – create and submit a request to this CA

I change the type of certificate needed to Code Signing Certificate (but the type doesn't really matter). Select the checkbox to “store in the local computer store” to save a step later. Everything else can be left at the default.

Also – give this certificate a descriptive name in the friendly name field – we will want to differentiate this cert from our SSL cert at a glance.

Complete the request, then issue the pending request from the from the CA the same way we did for the SSL certificate, then take the browser back to “check the status of a pending request”

Now you can install this certificate to your local machine store by selecting “Install this certificate”

The FS-A and FS-R local computer computer store should look something like this

Remember – you will need 5 certificates in this setup example – 3 SSL certificates (adfsweb, adfsaccount, and adfsresource) and 2 token signing certificates (adfsaccount and adfsresource) installed in the local computer store. The Certificate CA Chain should be installed on every machine (client, FS, and WS) in the lab environment.

If you give some attention to detail on these steps - the rest of the setup will be much easier and you will get things working much faster at initial setup.

This completes the PKI portion and we are now ready to start the ADFS installation and configure the federation servers. I'll finish the part 2 blog that covers the remainder of the setup soon.

MS Virtual Lab - A PKI troubleshooting exercise

jimsim — Sun, 25 Feb 2007 19:11:00 GMT

I was going through some old items and came across this link for an on-line ADFS lab. I decided to run through the lab (takes about an hour). There are problems with it. The title of this blog tells you what these problems are.

I can tell it's an old lab, the manual tells you to enter the federation server url like:

https://adfsserver.treyresearch.com/adfs/ls/clientlogon.aspx - specifying the clientlogon.aspx file was how things were done up until beta 3 of R2 if I remember correctly.

You can get it working (just look around and get creative with the certs)

If you want some practice working with certificates used in ADFS - then you should check it out.

I submitted feedback and will try to locate who controls this content - but it will most likely be up there and in this condition for a while.

The online lab is a cool idea - too bad this is the only one I can find (and it's broken)

The NT Token Cache

jimsim — Sat, 24 Feb 2007 23:20:00 GMT

The NT Token cache on the web server – Maybe you didn’t know this even existed…

Consider this scenario:

You are setting up ADFS in a federated scenario with SharePoint configured as a token based application.

The initial setup has miscellaneous configuration errors that you correct along the way. You test again and find some more configuration issues further down the line. Each time you correct something – you try to get to the web site with your client machine and your test account. Each time – you are getting closer and closer.

Sound familiar?

You finally make it to the SharePoint page and you are happy…No errors from the Federation Servers and things went as expected. Maybe not 100% the way you expected – but you just need to make some minor changes with the SharePoint permissions, then you are ready to test out some different claims and other items you have on your list.

OK – careful right here. Something happened under the hood here – and it’s important!

Let’s talk about what just happened when you finally made it to SharePoint error free. The ADFS token based web agent wrote a NT token on the web server and this user (identified by their identity claim) will find and use this same token on subsequent requests to applications on this box for the next 60 minutes.

See where you can run into trouble during initial setup and testing? Let's continue with this example…

Let's assume that when you first accessed the site (successfully) – you had a UPN identity claim and Group Claim A (which mapped to Windows Group A). The agent wrote a token with the SID of Windows Group A on the web server. You then realize you need to test Group Claim B which is associated with Windows Group B. You take all the correct steps necessary – add him to a different group on the account side, log off/log on, test again.

Hmmm – you are still getting the permissions associated with Group Claim/Windows Group A. You start checking your configuration - looking at logs – you see the Group claim B getting passed as it should from the FS-A to the FS-R – but when the user gets to the Web Server – you don’t have the permissions you associated with group claim B.

Now the doubt starts to creep in…Just when you thought you had the hang of this claim thing ;)

You check/double/triple check your configuration – maybe you configure group claim C – same thing! What changed you ask yourself? Trying a different user on the account side probably never occurred to you (I know it never does to me when I’m in this place).

Hopefully you read this (and remember about the NT Token Cache) before you spin your wheels too long with a scenario as I described here. The example I gave above is not the only way you can get in trouble here – It’s just one of the ways.

If you enable debug logging on the web server, you will see a message indicating that a cache entry has been found

When you are in the lab and are going to be making changes, testing, then more changes, and more testing – You may want to consider reducing the CacheEntryLifetime to the minimum (1 minute) from the default (60 minutes). To do this – add the following registry values to the web server at this location:

HKLM\System\CCS\Control\LSA\WebSSO\Parameters

CacheEntryLifetime – dword – 60 decimal

CacheScavengeInterval – dword – 60 decimal

Reboot the server for these changes to take effect.

Now – you can continue your testing without hitting this type of problem. Keep in mind – this is for lab environments only. I have no idea what this would do to a busy production web server from a performance standpoint.

A complete list of all the cache settings is located here

This blog certainly raises some questions (for me anyway) - when I tried to test things to verify and provide more detailed information, I got into a major rat hole…

I’ll follow up with more detailed information like:

How the debug logs look – how to verify this is what you are hitting
Shadow account existence – and the account partner “ resource account” setting

I think more detailed items on the subject are needed here. I’m going to put this out for now and build on it later.

Understanding Organizational Group Claims

jimsim — Thu, 22 Feb 2007 17:19:28 GMT

I created a list of topics last night that I think will be useful to put up here…Going in any kind of order will be too tough for me (lazy) and I’m afraid it would slow down my blog production. Please let me know if you would like to see something specific. Otherwise, I’ll just try to keep putting stuff up in random order.

If you aren’t familiar with Claims in ADFS – I’d suggest this short read on TechNet before going any further. As you will find with most of my blogs – it will be helpful to get Nick’s step-by-step up and running so you can follow along.

In this doc, I’ll go through the steps to create an Organizational Group Claim and map it from the Account Partner to the Resource Partner and then send it to an application.

While this information may not be useful/interesting for everyone, I find myself going through it with several people I talk to about ADFS. Most people have it down about 90% of the way – but aren’t super crisp on all the steps and why you take them. I’ll follow this up with a more in-depth blog which discusses all three claim types with some real world examples of how things should be setup. Custom claims and how you use them is just one item that could certainly use some further explanation. I didn’t understand claims 100% myself for a very long time (maybe I still don’t – but I think I can fake it now).

There isn’t a right or wrong way with the order in which you do this (other than the Organizational Claim must be created first on both sides), so I’ll just tell you my way.

The steps I take are as follows:

Start on the Account Partner

1. Create Organizational Group Claim on the Account Side

2. Right click the account store and do a new Group Claim Extraction

3. Right click the resource partner and do a new Outgoing Group Claim Mapping

Next – go to the Resource Partner

1. Create an Organizational Group Claim and associate it with a Windows Security Group on the resource group tab

2. Right click the account partner and choose New Incoming Group Claim Mapping

3. Highlight the application in which you want to receive this claim and choose enable

There are a couple things to help you remember this –

1. You need to visit/configure the claim in three places on each side

2. The above order is very similar to how the claim flows when a user access an app

A very common error I see is associating the claim with a Windows Group on the account side by using the resource group tab (like you do on the resource side). This is not correct – it won’t prevent it from working, but it is an unnecessary step. On the account side – the claim is associated to the Windows group via the group claim extraction (step 2) method. Since it’s the account side (no application) – we don’t need to associate the Group Claim to a Windows Group – we only need to extract the claim from the account store (another way to say this – we need to figure out which users get this claim)

Let’s go through everything from start to finish and hopefully it will become clear.

1. Create Organizational Group Claim on the Account Side

Notice the Resource Group tab doesn’t have anything configured

2. Do a new group claim extraction from your account store. This is where you are saying – if you are a member of this Windows Group – I want you to have this Group Claim

3. Map the group claim by doing a new outgoing group claim mapping on the resource partner. The outgoing group claim name must match EXACTLY when we complete the steps on the resource partner. Personally, I use all lower case and hyphens to help minimize errors here. Also, think about what you name the mapping – you wouldn’t want to call this “example-outgoing-mapping” because that wouldn’t make sense when you type that name in on the resource side. On the resource side – it will be an incoming group claim mapping. This is just a tip to help keep things manageable – any name will work so long as they match on both sides.

That’s it for the account side – now we go to the resource federation server to configure the rest of the claim mapping.

1. Create an Organizational Group Claim – it is important to note that this claim name doesn’t have to match the Group Claim name which we configured for the Account side. In fact – the name will be different in most cases. The name here should be something logical for the resource side administrator – imagine 200 or 300 group claims – you want the display name to mean something to you.

Now – go to the resource group tab and associate a Windows Group to this claim. This is where you say – if a user comes to my application with this group claim – I want to associate it with this Windows Group. Typically, this group is empty. The Windows Group SID will be written to the web server (for token based apps) and the application will think that it’s a regular user with this group membership accessing it.

2. Remember, you must have at least one Identity claim – then you can have one or more group or custom claims here. The one identity claim is the only rule that can’t be broken. Notice how all my claims show up when I highlight Blog Application – but only UPN identity claim and Resource Example Group claim are highlighted (enabled)

3. Create the incoming group claim mapping from the account partner. Remember – we need to have an exact match on the claim mapping name.

That’s it! We’ve completed setting up a group claim mapping for a federated WebSSO scenario.

Installing MOSS as a claims aware application in ADFS

jimsim — Wed, 14 Feb 2007 23:22:00 GMT

Hi, this is Jim Simonet from the Enterprise Platform Support team and Steve Peschka from the SharePoint Ranger team. In this blog we’re going to talk about how to configure Active Directory Federated Services (ADFS) with SharePoint 2007. We have actually been working on this document for a few weeks now. The TechNet team has leveraged this document and will be publishing their content very soon. There are a few screen shots in this doc that couldn’t make it into the Technet document, also the format and order of steps will be slightly different.

Prior to beginning this blog, you should read a couple of related materials. They contain content that is too verbose to include here, but that will be valuable in helping you understand the concepts presented here.

Information about configuring the authentication provider in MOSS is here.

This install guide is built with server names from the Adatum-Trey Research step-by-step guide for setting up ADFS in a small lab environment. In this example a new server named Trey-MOSS was joined to the Treyresearch forest instead of using ADFSWEB as described in the step-by-step document. You will need to follow the steps in this step-by-step guide to configure your ADFS infrastructure. SharePoint 2007 is a claims-aware application though, so you don’t need to implement all of the steps for building NT token agent applications. The new server, Trey-MOSS will need to be Windows Server 2003 R2 (STD or ENT) and will need to have the Claims Aware Web Agent installed.

In addition, before you start you need to download and install a hotfix for ADFS. Without this hotfix, the information below will not work. You can find information about this hotfix at http://support.microsoft.com/kb/920764/en-us.

The steps in this blog will help you configure MOSS with the WebSSO provider. It is setup in a typical Extranet scenario that Steve discusses in his blog.

The site will exist in two zones – the default zone and an extranet zone. The same content will be in both, but the intranet zone will use the Windows Authentication Provider and the Extranet zone will use the WebSSO provider.

Install MOSS and successfully complete the Configuration Wizard
Launch Sharepoint Central Admin Site
From Application Management – choose Create or Extend Web Application,
Choose Create a new web application. This is how the initial web application that uses Windows authentication will be created.
Complete the steps in the page by extending the existing IIS web site on port 80.
Choose Create or Extend Web Application again, this time choose Extend an existing Web Application
Choose the web application you previously created using Windows authentication to extend
Add a host header – this is the DNS name by which the site will be known to users in the Extranet (extranet.treyresearch.net)
Change the zone to Extranet
Select the radio button that says “Use Secure Sockets Layer (SSL)”, and change the port number to 443. ADFS will only work with a site that is configured to use SSL.
Remove the “:443” text from the end of the “Load Balanced URL” edit box. IIS will automatically use port 443 since you specified the port number above.
Complete the rest of the steps in the page and finish extending the web application

If you look at the Alternate Access Mappings (AAM) page it should look something like this:

Add an SSL certificate to the Extranet Web Site in IIS. Make sure this SSL certificate is issued to extranet.treyresearch.net – this is the name which will be used by the clients when accessing the sites. Here is an example of how the certificate looks:

At this point – you should have a web site extended to the Extranet zone, a SSL certificate installed, and the AAM should show both the default Windows authentication site URL and Extranet zone SSL site URL.

Working with Groups

In SharePoint rights are typically provisioned using groups – Active Directory groups are added to SharePoint Site Groups. Those site groups have a set of permissions associated with them, so your membership in a given Active Directory and Site Group determines what rights you have within a site.

When you use ADFS as a role provider in SharePoint, the process needs to change. The reason for that is because there isn’t a way for the WebSSO provider to directly resolve an Active Directory group – instead it resolves membership through something in ADFS called Organizational Claims. You will need to do some work to create a set of Organizational Claims in ADFS that map to the SharePoint Site Groups into which you want to add users; you can then associate multiple Active Directory groups with an ADFS Organizational Claim on the account partner. The key take away here is – when you add permissions on SharePoint, you will add and associate Group Claims with the SharePoint Roles – not Windows Security Groups. This is very important to keep in mind as you go through the rest of the document.

Here is the process in ADFS for creating the new Organizational Claims and associating the account side Active Directory Groups with them:

In the Adatum Forest (Account Forest)

Create a Windows Group called Trey MOSS Readers
Create a Windows Group called Trey MOSS Contributors
Add Alansh to the MOSS readers group and Adamcar to the contributors group
Launch ADFS.MSC
Create an Organizational Group Claim called Trey MOSS Readers
Create an Organizational Group Claim called Trey MOSS Contributors
Right click the Active Directory account store and choose New Group Claim Extraction
1. Choose the Trey MOSS Readers Group Claim and associate it with the Trey MOSS Readers Windows Group
2. Do another group claim extraction and associate the Contributor claim with the Contributor Group
Right click the Trey Research Resource Partner and create the outgoing claim mappings
1. Choose the Trey MOSS Reader claim and map to outgoing claim adatum-trey-readers
2. Choose the Trey MOSS Contributor claim and map to outgoing claim adatum-trey-contributors

NOTE: The claim mapping names in step 8 must be agreed upon between the organizations and must match exactly.

On the Trey Research side – launch ADFS.MSC

Create an Organizational Group Claim called Adatum MOSS Readers
Create an Organizational Group Claim called Adatum MOSS Contributors
Create incoming group mappings for your claims
1. Right click the Adatum account partner and choose Incoming Group Claim Mapping
2. Choose Adatum MOSS Readers and map it to incoming claim name adatum-trey-readers
3. Choose Adatum MOSS Contributors and map it to incoming claim name adatum-trey-contributors
Enable the claims for the MOSS application
1. Click on the MOSS application – right click and choose enable on both the Reader and Contributor claims

Now we are ready to modify SharePoint so that we will be able to add the Claims to the Extranet site that has been extended

Change the web.config on the Central admin site and web.config on the Sharepoint 80 (Windows Authentication site)

In both web.config files add this section directly below the <authentication mode> section

<membership>
<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="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>

Change fs-server to reflect your resource Federation Server (i.e. adfsresource.treyresearch.net) and take note of the membership provider and role provider names because you will need to add these exact names on the Central Admin Page.

This change is necessary so that the web sites can resolve users and groups using the WebSSO/ADFS provider. One of the reasons you may do this is to be able to configure Policies for the web application for different ADFS users and groups, or for users that are authenticating with Windows to be able to provision permissions for ADFS users. One thing to note in the example above, since both of these sites using Windows authentication, they always use Windows authentication for the role provider -- that’s why the AspNetWindowsTokenRoleProvider is set as the default role provider.

Configure the Authentication provider for the extranet web application to use WebSSO.

Open your browser and navigate to the Central Administration site, click on Application Management and then on Authentication Providers. Make sure that you are working on the web application for which you wish to enable WebSSO.

You should see a list of two zones that are mapped for this web application; both should say Windows. Click on the link that says Windows for the web application in the Extranet zone and do the following:

In the Authentication Type section, click on the Web Single Sign On radio button. The page will post back and expose two new edit boxes.
In the Membership provider name edit box, type in the name of your web application’s Membership provider for the current zone. That is the name attribute value that was highlighted in the Membership element (SingleSignOnMembershipProvider2)
In the Role manager name edit box, type in the name of your web application’s Role provider. That is the value that was highlighted in the name attribute value of the roleManager element (SingleSignOnRoleProvider2)
Click the Save button.

Modify the web.config file for the Extranet site:

Add the following entry within the <configSections> node

<sectionGroup name="system.web">
<section name="websso" type="System.Web.Security.SingleSignOn.WebSsoConfigurationHandler, System.Web.Security.SingleSignOn, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null" />
</sectionGroup>

Add the following entry to the <httpModules> node

<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" />

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>

Change the fs-server to your resource Federation Server (i.e. adfsresource.treyresearch.net) and change your_application to reflect your application. Your application is going to be the MOSS URL that Federated Users will access. In this example, we will change this to https://extranet.treyresearch.net

Modify the Windows authentication web site so ADFS users can be granted rights to the site collection

There are two ways in which you can grant rights to ADFS users into the SharePoint site; one is by using a Policy. In this case, we are not going to use that method for a couple of reasons:

Granting rights by policy is a very coarse operation. It would allow the user (or group) to have the same set of rights in every web site, in every site collection, in the entire web application. It should be used very judiciously, and in this particular scenario we can grant access to ADFS users without resorting to this method

Once the site(s) are in use, in an extranet scenario it is quite likely that the internal users will be responsible for granting access to sites and content. For that to happen, one of two things needs to happen – either those users need to be given an ADFS login name or they need to be able to select ADFS users and Organizational Claims (analogous to Active Directory groups) from the Windows site. Obviously, it makes the most sense for the Windows users to continue to be able to use their existing credentials, rather than provision a new identity for Windows users – that would essentially defeat the purpose of supporting Windows authentication users.

This is also an opportunity to explore one of the neat features about SharePoint related to security. As you extend web applications with different providers, you can configure one or all of them to be able to find user and groups from providers you are using. So in this scenario, we are going to configure our site that uses Windows authentication, and let users of that site be able to select other Windows users, Windows groups, and ADFS Organizational Claims all from one site.

In order to do that, the Windows site has to “know” about the other providers it can use. The way to do that is to edit the web.config file for the Windows site. Those are the steps already completed and covered above in the section titled Change the web.config on the Central admin site and web.config on the Sharepoint 80 (Windows Authentication site).

Now you can add ADFS Claims to SharePoint site groups so that federated users have access to the site. Start by navigating to the Windows authentication site as an account that has administrative rights in there. Click on Site Settings, People and Groups. You will see a list of the SharePoint site groups.

Remember at the beginning of this document – you created a couple of Organizational Group Claims on Treyresearch

<snip>

On the Trey Research side – launch ADFS.MSC

Create an Organizational Group Claim called Adatum MOSS Readers
Create an Organizational Group Claim called Adatum MOSS Contributors

</snip>

You can click on any of the Sharepoint groups, and then click on the Add button. Use the People Picker to type in the name of any ADFS Organization Group Claims that you want to add to the group and click the OK button. Those ADFS users will now be able to access the site via the external https URL. The People Picker will not do wildcard searches for the claims – so type the claim in here exactly as you typed it in while creating the claim in ADFS.

Browse to the https://extranet.treyresearch.net web site as an ADFS user you added to a SharePoint Site Group in the previous section. You should be able to authenticate to and see the site.

One gotcha that came up from the review process...If you install SharePoint with a domain service account running the Application Pool, this domain service account must be granted the “generate security audit” user right for ADFS to function properly.

Introduction

jimsim — Mon, 12 Feb 2007 07:58:00 GMT

Hello,

My name is Jim Simonet and I work with the Microsoft PSS Directory Services Group. I work with a small team within Directory Services that supports the majority of ADFS issues at Microsoft. I'm creating this blog space to post about lessons learned in PSS regarding ADFS. I have many ideas in my head on useful content here and have a few items in the works right now.

Sharepoint 2007 seems to be a popular topic right now and I hope to put some useful content out soon which will help you configure Sharepoint 2007/MOSS as a claims aware application with ADFS.

Additionally, I'd like to use this space to document common misconfigurations I see with ADFS...

I hope that you will find this space helpful and provide feedback on ideas to blog about in the future.

Thanks,
Jim