Verifying ADFS Computer Settings and Connectivity

  • Article

Applies To: Windows Server 2003 R2

Before you begin troubleshooting, you must isolate the location of the problem by performing preliminary tests to verify that your federation servers, Web servers, and client computers are communicating and that Active Directory Federation Services (ADFS) is set up and running properly.

Verifying Settings to Locate the Point of Failure

ADFS components are deployed among several servers, each of which requires settings that affect various server-server and client-server interactions. The best way to effectively troubleshoot and solve a problem is to find the exact location of failure between ADFS components.

To help you better understand how to locate the point of failure, the following sample scenario is provided.

Sample Scenario

Using this sample diagram of a client requesting access to an ADFS-protected application in a Federated Web with Single Sign-on (SSO) scenario, you can easily distinguish how ADFS servers enumerate connections. This information is meant to assist you in determining which connection point might be causing the failure. If you are already familiar with the location of the failure in your environment, skip to the section where you suspect the failure is occurring. By testing for success at each step, you can better determine where the problem lies.

For more details and instructions for implementing this sample Federated Web SSO scenario, see the ADFS Step-by-Step Guide (https://go.microsoft.com/fwlink/?linkid=63445).

Web SSO Scenario

Note

To improve user experience, always obtain Secure Sockets Layer (SSL) certificates for any external (Internet-facing) computers from a well-known third-party certification authority (CA). Because well-known third-party CAs are already trusted by the client browser, the user does not receive prompts that the browser does not trust the root CA certificate.

Verification Steps to Locate the Point of Failure

Each topic below corresponds to a number in the preceding diagram and provides information and step-by-step procedures to help eliminate the error that is causing the failure.

1. Verify Connectivity and Initial Request from the Client

2. Verify Web Server Redirection to the Resource Federation Server

3. Verify Home Realm Discovery

4. Verify Client Authentication in the Account Domain

5. Verify Account Server Redirection to the Resource Federation Server

6. Verify Resource Server Redirection to the Web Server

1. Verify Connectivity and Initial Request from the Client

In this step, you verify that the ADFS client can reach the Web site on the Web server before the client has received any previous token.

When you enter the uniform resource locator (URL) of the Web application in the client browser for the first time, the client sends an initial GET request to the ADFS Web server. The ADFS Web server does not allow the client access to the requested page at this point because the client does not have an authentication token to present to the Web server at that point. If the ADFS client fails to receive access to the page, you get an error and the URL in the browser indicates the point of failure. Common errors might be Domain Name System (DNS) failures and 401 access denied errors.

Make sure you have good connectivity and name resolution between the account and resource domains. Clients coming from the Internet should be able to locate domain controllers.

Domain controllers, federation servers, Web servers, and clients need to be able to locate each other by a fully qualified domain name (FQDN). Ping by IP address and FQDN, and use Nslookup.exe to test DNS connectivity. In addition, to make sure that all the necessary ports are open, you can download PortqryUI.exe from the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=64729

Use the following tests to verify connectivity from the client:

If DNS resolution appears to be the connectivity problem, see Troubleshooting Domain Name System (https://go.microsoft.com/fwlink/?LinkId=62177). You should also check the Web server to verify that the ASP.NET v2.0.50727 extension is set to Allowed using the Internet Information Services (IIS) Manager snap-in. The typical symptom that occurs when this extension is set to Prohibited is a Page cannot be displayed error in the browser.

2. Verify Web Server Redirection to the Resource Federation Server

In this step, verify that the redirect of the ADFS client to the resource federation server is occurring properly and that the client can reach the Federation Service endpoint URL.

Note

The Federation Service URL is used by clients to access a server in the resource Federation Service. This URL has the form https://FullyQualifiedDomainName/adfs/ls/

The ADFS Web server issues a standard HTTP 302 REDIRECT to the client, which directs the client to the resource federation server. This redirect occurs to the resource federation server because the ADFS Web server knows about only its own federation server and requires that incoming ADFS tokens are signed by its federation server. The ADFS client is able to communicate with the resource federation server because it trusts the CA that issues the SSL server certificate for the resource federation server. As in Step 1 (Verify Connectivity and Initial Request from the Client), if the client fails to contact the resource federation server, an error appears and the URL on the browser indicates the point of failure. Common errors are DNS failures and 401 access denied. In this case, use the tests that are described in step 1.

Important

If the Federation Service endpoint URL value has recently been modified in the Windows NT token–based Web agent, clients may experience logon problems to Windows NT token–based applications that are located on the Web server within one hour from the time when the URL value was changed. After the one hour has passed, clients should be able to log on to the Windows NT token–based applications without problems. To avoid this one-hour delay, you can run iisreset from a command line immediately after the URL value changes.

3. Verify Home Realm Discovery

In this step, verify that the default page is displayed in the browser and the proper home realm of the client is available in the list.

When the ADFS client first requests a resource, the resource federation server has no information about the realm of the client. The resource federation server responds to the ADFS client with an HTTP 200, which provides the Client Realm Discovery page, where the user selects the home realm from a list. The list values are populated from the display name property in the account Federation Service trust policy. This value is known to the resource Federation Service through the account partner node properties.

The client realm discovery page fails to appear

If the client realm discovery page fails to appear, do the following on the client computer:

  1. Delete all cookies from the client browser to remove the persistent home realm cookie, if present.

  2. Try again to connect to the Web site. The Web server attempts to redirect to the resource federation server.

Administrative credentials

To complete this procedure, you must be a member of the Users group on the local computer.

To delete all cookies in Internet Explorer

  1. In Internet Explorer, on the Tools menu, click Internet Options.

  2. On the General tab, click Delete Cookies.

  3. In the Delete Cookies dialog box, click OK.

  4. In the Internet Options dialog box, click OK.

Deleting cookies does not solve the problem

If the ADFS client still fails to receive access to the realm discovery page, the problem is with the resource Federation Service because this redirection is the final step before the client is sent to the account Federation Service.

In this case, do the following:

  1. Look at the URL in the Web browser of the client to determine whether the failure is occurring on the Web server or on the resource federation server.

  2. If the URL still shows the Web server address and nothing further, you can assume that the issue is on the Web server. In this case, go to the next step.

  3. Look at the Application log on the Web server to see what errors are logged. Review the User Action section of the event and take proper troubleshooting steps according to any errors. If these steps do not solve the problem, go to the next step.

  4. Use the following procedure to confirm that the Web server can communicate with the Federation Service on the resource federation server.

    Administrative credentials

    To complete this procedure, you must be a member of the Administrators group on the local computer.

    To check the Federation Service URL

    1. On the ADFS Web server, open Internet Information Services (IIS) Manager, right-click Web Sites, and then click Properties.

    2. On the ADFS Web Agent tab, copy the Federation Service URL.

    3. Paste the URL into the browser address line, and then press Enter.

If the URL resolves properly, a Federation Service Web page appears that lists supported operations for the service.

Note

You might be prompted for a client authentication certificate, which is standard behavior.

The Federation Service URL does not resolve

If the URL does not resolve, assuming you have verified name resolution and connectivity, the error is most likely a typing error in the Federation Service URL on the Web server. Use the following procedure to check for potential typing errors for the Windows NT token-based Web agent.

To check the Federation Service URL of the Windows NT token-based Web agent

  1. On the ADFS Web server, open Internet Information Services (IIS) Manager, right-click Web Sites, and then click Properties.

  2. On the ADFS Web Agent tab, check that the URL specified in the Federation Service URL field is typed correctly.

Use the following procedure to check for potential typing errors in the web.config file that is associated with the claims-aware application.

To check the Federation Service URL in the web.config file

  1. Using Notepad, edit the web.config file associated with your claims-aware application.

  2. Find the Federation Service URL value in the web.config file by locating the <fs>FederationServiceURLValue</fs> entry. Check that the value and format specified in FederationServiceURLValue is typed correctly. An example of the Federation Service URL located in the web.config file used in the ADFS Step-by-Step guide is <fs>https://adfsresource.treyresearch.net/adfs/fs/federationserverservice.asmx</fs>.

Confirm that Web service extensions are configured properly

Confirm that ASP.NET v2.0.50727 (for claims-aware applications) and/or the ADFS Web Component Extension (for Windows NT token-based applications) are set to Allowed in the Internet Information Services (IIS) Manager snap-in on the ADFS Web server.

When the ADFS client successfully reaches the home realm discovery page and selects its domain, the ADFS client submits a POST back to the resource federation server that includes the home realm. In response, the resource federation server issues a 302 redirect to the ADFS client so that the client can be authenticated for its domain and receive the appropriate claims from the account federation server.

4. Verify Client Authentication in the Account Domain

If the address in the ADFS client browser indicates failure of client redirection from the resource federation server back to the account federation server, the client cannot be authenticated by a domain controller in the account forest. In this case, check the following:

  • The value of the Federation Service endpoint URL that is configured on the account partner node in the resource Federation Service trust policy is the same value as the Federation Service endpoint URL that is configured on the Trust Policy node in the account Federation Service. These values must match.

  • Whether or not the user account is configured to use the Smart card is required for interactive logon option in the account properties. If this option is enabled for a user account that is attempting to access an ADFS-enabled Web application, authentication to that application will not be successful.

Disable Java Scripting

JavaScript is used to automatically redirect the client to various points, including posting tokens. When JavaScript is disabled, the automatic redirect will be prevented and a submit button will be displayed instead. This button allows the client to walk through each step more easily as part of troubleshooting the configuration.

Administrative credentials

To complete this procedure, you must be a member of the Users group on the local computer.

To disable JavaScript in Internet Explorer

  1. Open Internet Explorer.

  2. On the Tools menu, click Internet Options.

  3. On the Security tab, click Custom Level.

  4. Scroll to the Scripting category.

  5. Under Active scripting, click Disable, and then click OK twice.

Check the Federation Service endpoint URL

Use the following procedures to check the value of the Federation Service endpoint URL on the Trust Policy node in the account Federation Service against the value on the account partner node in the resource Federation Service.

Administrative credentials

To complete these procedures, you must be a member of the Administrators group on the local computer.

To check the Federation Service endpoint URL in the account Federation Service

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. Double-click Federation Service, right-click the Trust Policy node, and then click Properties.

  3. On the General tab, check the value in the Federation Service endpoint URL box. If you need to change the value, select the domain portion of the URL, replace the selected text with the new URL, and then click OK.

Use the following procedure to check the Federation Service endpoint URL on the account partner node in the resource Federation Service.

To check the Federation Service endpoint URL in the resource Federation Service

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. Double-click Federation Service, double-click Trust Policy, double-click Partner Organizations, and then double-click Account Partners if you are logged on to the resource federation server, or Resource Partners if you are logged on to the account federation server.

  3. Right-click the account or resource partner whose Federation Service endpoint URL has changed, and then click Properties.

  4. On the General tab, check the value in the Federation Service endpoint URL box. If you need to change the value, select the domain portion of the URL, replace the selected text with the new URL, and then click OK.

5. Verify Account Server Redirection to the Resource Federation Server

After the client is authenticated and the account federation server receives authorization information from the domain controller, the account federation server builds the SAML token with the claims for the user, writes the cookie to the ADFS client. The account federation server then issues a POST REDIRECT with the SAML token and the redirect URL of the resource federation server. The account federation server signs the SAML token with its token-signing certificate. The resource federation server must have been configured with a verification certificate from the account federation server. The verification certificate contains the public key portion of the token-signing certificate of the account federation server. The resource federation server requires this certificate to verify that the account federation server sent the token.

If the verification certificate from the account federation server is not installed on the resource federation server, token validation fails. Use the following procedure to check for the existence of the verification certificate on the resource federation server.

View the current verification certificate

The verification certificate is invalid

If the verification certificate is present but has expired, follow the steps to roll over the verification certificate.

Rolling Over a Token-signing Certificate

The verification certificate is missing

If the verification certificate is not present, use the following procedure to first export the public portion of the token-signing certificate on the account federation server, and then you will need to import it into the certificate store on the resource federation server.

Export the public key portion of a token-signing certificate

6. Verify Resource Server Redirection to the Web Server

After receiving the token from the account federation server, the following events occur:

  1. Resource federation server maps the incoming claims in the token to the appropriate claims for the ADFS Web server, and then issues a token for the ADFS Web server.

  2. The resource federation server writes the cookie to the ADFS client and provides the token for the ADFS Web server to the client, along with the URL for the ADFS Web server. This information is provided to the client in the form of a POST REDIRECT.

  3. The resource federation server signs the token with its own token-signing certificate. The ADFS Web server uses the public key to verify that the token is signed by the resource federation server. The ADFS Web obtains the public key by making a call to the resource federation server. By using this public key, the ADFS Web server can verify that the token is signed by the resource federation server. The ADFS Web server then allows the appropriate access to the client.

If redirection to the ADFS Web server fails, the page fails to appear. Causes for failure can include:

  • The application URL in the trust policy does not match the return URL specified in the ADFS Web Agent tab on the Web server hosting the application.

  • The endpoint URL is incorrect for a federation server or federation server proxy

The application URL does not match the return URL

If the page fails to appear with an error such as “Server Error in ‘/adfs’ Application,” use the following procedures to check that the application URL in the properties of the application node on the resource federation server matches the return URL in the ADFS Web Agent tab on the application Web site.

  1. Set the return URL for a Windows NT token-based application

  2. Set the return URL for a claims-aware application

  3. Set the application URL for an application

You can also check the security and application logs in Event Viewer on the resource federation server and ADFS Web server for warnings and errors that provide problem-specific information.

The endpoint URL is incorrect for a federation server proxy

If a federation server proxy is in place in a perimeter network in the adatum.com domain, both the resource federation server in Treyresearch.net and the account federation server in Adatum.com must be configured with the location of the federation server proxy.

If you use a federation server proxy in the account domain, check the endpoint URL on both the account partner node and resource partner node on the respective federation servers. If the URL does not point to the federation server proxy, change its value. Use the procedure "To change the Federation Service endpoint URL" in the following procedure:

Change the Federation Service endpoint URL

The client authentication certificate for the federation server proxy is not configured

You must ensure that an SSL certificate and a client authentication certificate is installed on each server that is running the federation server proxy component. The public key portion of the client authentication certificate must be present on the account federation server and the resource federation server. If you have more than one federation server proxy, the same SSL and client authentication certificate can be shared among all federation server proxies. Alternately, you can obtain a separate SSL and client authentication certificate for each federation server proxy, export each certificate to a file, and import all of them to the Federation Service trust policy.

Note

When certificates are shared among servers in the same role, you export both the public and private portions of the certificates.

In the account Federation Service, if the client is internal, the client goes directly to the account federation server and the steps, as illustrated in the sample Federated Web SSO diagram, occur. If the client requests access remotely from the Internet, the client is redirected to the federation server proxy.

Use the following information and procedures for configuring the client authentication certificate and installing its public key on the federation servers.

Managing Client Authentication Certificates

See Also

Concepts

Configuring ADFS Servers for Troubleshooting