Overview
This document demonstrates some key points with AD FS configuration, the problems we may face and how to do troubleshooting.
For complete information, please read the step-by-step guide here: http://technet.microsoft.com/en-us/library/dd378921%28WS.10%29.aspx
1. Service Roles & Certificates
|
|
Account AD FS (1) |
Resource AD FS (2) |
Resource App (3) |
|
Service Roles |
FS IIS |
FS IIS |
AD FS Web Agent IIS |
|
Self Certificate |
1.1 Token signing certificate for FS. 1.2 Authentication certificate for IIS |
2.1 Token signing certificate for FS. 2.2 Authentication certificate for IIS |
3.1 Authentication certificate for IIS |
|
Certificate needs to be Imported |
1.1 |
2.2 |
|
|
Trusted Root Certificate to be imported |
1.1 1.2 |
2.1 2.2 1.1 |
3.1 2.2 |
2. Time Zone
All the servers should be in the same time zone, and the time difference should be within 5 minutes
3. Email Suffix
When add a new account partner, make sure the email suffix is identical with your domain for Identity Claims “E-Mail” and “User Principal Name”
4. Change FS certificate
For some reasons, such as the certificate expires, you may need to change the certificate, then you can create new self-signed certificate in IIS, and replace the old one in AD FS, but please make sure to check your web.config file of the AD FS site, it usually locates at “\adfs\sts\web.config”, open it and make sure the certificate X509Thumbprint has been updated to the one you created.
Some key points needs to pay attention to:
- When update self token certificate, go to ADFS, right-click “Federation Service” (not “Trust Policy”), in the Properties, we can select and view certificate in Token-signing certificate, here we need to make sure ADFS has the permission to access the certificate private key (click view and it should show the certificate info and in the bottom it should show that “You have a private key that corresponds to this certificate”). When this finished, click apply or ok to save changes, this will change the adfs web.config file with the new certificate keys. If here we meet any error says don’t have permission to the event logs, remember to change to log folder and grant full control to the adfs application pool user (usually it is “Network Service”).
- When update none-self token certificate, only needs to write click the related Account partner and select properties, then update the certificate (no need the private key), old one can be deleted.
- Self-signed certificate is no need to be imported to mmc Trusted Root Certification Authorities, it has been done automatically.
- None-self certificate import, don’t need the private key, only a .cer is ok;
- When update or imported certificate, need to recycle IIS, otherwise it may redirect to error page.
5. Diagnostics & Troubleshooting
Open web.config, find the section <system.diagnostics>, change the WebSsoDebugLevel to 255, AD FS will log every event when processing request, log file locates at initializeData
6. Account partner AD FS configuration export & import
After you finished the resource partner configuration in account AD FS, you may want to configure the cooperating side in Resource AD FS, then Export & Import will help. Right click the resource partner you configured, and then select export, you will export the configuration information to a xml, then import the xml into Resource AD FS, you will finish the configuration, the certificate has been included in the XML.
7. Web.config transformation
Since we have some special settings in web.config for AD FS application, and it should be changed in different environment, we need to do web.config transformation when publish the application, the command line is as below:
msbuild D:\TFS\ETTfsApp\Englishtown\Team_LLS\Development\Source\LLS\AdfsAuthentication\AdfsAuthentication.UI\AdfsAuthentication.UI.csproj /v:diag /t:PipelinePreDeployCopyAllFilesToOneFolder /p:_PackageTempDir=D:\publish\adfs;Configuration=release;FilesToIncludeForPublish=OnlyFilesToRunTheApp;AutoParameterizationWebConfigConnectionStrings=false;ProjectConfigTransformFileName=web.uat.config /l:FileLogger,Microsoft.Build.Engine;logfile=D:\publish\BuildLog\MyLog.log
in TeamCity we also need to enable web.config transformation, change the settings as below:
msbuild.FilesToIncludeForPublish: OnlyFilesToRunTheApp
msbuild.publish.target: PipelinePreDeployCopyAllFilesToOneFolder
/p:_PackageTempDir=%drop.folder%/;Configuration=%msbuild.configuration%;FilesToIncludeForPublish=%msbuild.FilesToIncludeForPublish%;AutoParameterizationWebConfigConnectionStrings=false;ProjectConfigTransformFileName=web.%msbuild.transform.env%.config
8. End