Share via

Forefront UAG Troubleshooting: Federation Metadata Retrieval Errors

  • Article

Forefront Unified Access Gateway (UAG) performs a number of tests and checks when you retrieve the federation metadata from the Active Directory Federation Services (AD FS) 2.0 server. This topic describes how to troubleshoot any errors you may receive when retrieving the federation metadata.

Cannot retrieve federation metadata

There are several problems that may occur that prevent Forefront UAG from retrieving the federation metadata. Several problems are related to attempting to retrieve the federation metadata from the wrong location, or after typing the wrong path, directory, or file name for the federation metadata file. These error messages are:

  • Cannot retrieve federation metadata. The path <path_name> is not valid.
  • Cannot retrieve federation metadata. The directory <directory_name> could not be found.
  • Cannot retrieve federation metadata. The file <file_name> could not be found.
  • Cannot retrieve federation metadata. You don't have permission to access <file_location>.
  • Cannot retrieve federation metadata. The file name cannot contain any of the following characters: \ / : * ?  < > |

If you receive one of these errors when you retrieve the federation metadata from a file location, you must ensure that the full file path is correct and that the file is on the Forefront UAG server and not on a network location. You must also have read access to the folder containing the federation metadata file. An example path is "C:\Metadata\FederationMetadata.xml".

Cannot retrieve federation metadata. Try to retrieve it using a web browser and troubleshoot any errors that you receive, and then try again using Forefront UAG.

An unknown error occurred when Forefront UAG attempted to retrieve the federation metadata. In this case, we recommended that you try to retrieve the federation metadata using a web browser by typing the URL of the federation metadata into your web browser.

If the web browser is unable to retrieve the federation metadata, it will provide more detailed information about the possible problems retrieving the metadata than is available in Forefront UAG. You can troubleshoot the errors that you receive from the web browser and then return to Forefront UAG and attempt to retrieve the metadata.

Cannot retrieve federation metadata. There is a problem with the federation metadata file. For assistance, contact your AD FS administrator.

An unknown error occurred when Forefront UAG attempted to retrieve the federation metadata. In this case, we recommended that you re-copy the metadata file to a local directory and then try to retrieve the federation metadata again. If you receive the same error, try to retrieve the federation metadata using a web browser. The web browser can provide more detailed information about the possible problems retrieving the metadata than is available in Forefront UAG. You can troubleshoot the errors that you receive from the web browser and then return to Forefront UAG and attempt to retrieve the metadata.

The Federation Service does not contain a WS-Federation passive endpoint. For assistance, contact your AD FS administrator.

The Federation Service is the logical instance of AD FS 2.0, and servers on which you have installed AD FS 2.0 are part of the Federation Service. Forefront UAG supports Federation Services that contain one WS-Federation passive endpoint. The WS-Federation passive endpoint is defined in the AD FS 2.0 Management console in AD FS 2.0\Service\Endpoints with type SAML 2.0/WS-Federation and must be enabled. If the Federation Service is misconfigured, it may not define a WS-Federation passive endpoint. Make sure that the Federation Service is configured with only one WS-Federation passive endpoint.

The Federation Service does not contain any WS-Federation endpoints. For assistance, contact your AD FS administrator.

The Federation Service is the logical instance of AD FS 2.0, and servers on which you have installed AD FS 2.0 are part of the Federation Service. Forefront UAG supports Federation Services that contain one WS-Federation passive endpoint. The WS-Federation passive endpoint is defined in the AD FS 2.0 Management console in AD FS 2.0\Service\Endpoints with type SAML 2.0/WS-Federation and must be enabled. If the Federation Service is misconfigured, it may not define a WS-Federation passive endpoint. Make sure that the Federation Service is configured with only one WS-Federation passive endpoint.

The Federation Service contains more than one WS-Federation passive endpoint. Forefront UAG supports one WS-Federation passive endpoint. For assistance, contact your AD FS administrator.

The Federation Service is the logical instance of AD FS 2.0, and servers on which you have installed AD FS 2.0 are part of the Federation Service. Forefront UAG supports Federation Services that contain one WS-Federation passive endpoint. The WS-Federation passive endpoint is defined in the AD FS 2.0 Management console in AD FS 2.0\Service\Endpoints with type SAML 2.0/WS-Federation and must be enabled. If the Federation Service is misconfigured, it may not define a WS-Federation passive endpoint. Make sure that the Federation Service is configured with only one WS-Federation passive endpoint.

The federation metadata does not define any claim types. Forefront UAG requires at least one claim type. For assistance, contact your AD FS administrator.

The federation metadata file is automatically generated on the AD FS 2.0 server and contains configuration information that facilitates the proper configuration of claims provider trusts and relying party trusts; including the claims that are provided by the AD FS 2.0 server. Forefront UAG requires at least one claim type to be defined in the federation metadata to be used to identify the lead user; that is, the user who initiated the session, for claims-based authorization, or single sign-on when using Kerberos constrained delegation. The AD FS 2.0 server must also be configured to send the required claim to Forefront UAG. Make sure that at least one claim type is provided by the AD FS 2.0 server.

You can enable and disable claim types that appear in the federation metadata in the AD FS 2.0 Management console in AD FS 2.0\Service\Claim Descriptions. You can configure claim rules that define the claims that the AD FS 2.0 server sends to the Forefront UAG relying party in AD FS 2.0\Trust Relationships\Relying Party Trusts.

The federation metadata does not contain information about the token signing certificate. Forefront UAG cannot use federation metadata without this information. For assistance, contact your AD FS administrator.

The federation metadata file is automatically generated on the AD FS 2.0 server and contains configuration information that facilitates the proper configuration of claims provider trusts and relying party trusts; including information about the token signing certificate. Forefront UAG requires that the federation metadata contains information about the token signing certificate so that Forefront UAG can validate the certificate. Make sure that the relevant information is included in the federation metadata. You can check the validity of the token signing certificate in the AD FS 2.0 Management console in AD FS 2.0\Service\Certificates.

The federation metadata URL must begin with https.

When you retrieve the federation metadata from a URL, the URL that you enter must begin with https because AD FS 2.0 requires that the metadata is transferred only over a secure connection.

The federation metadata is not signed and Forefront UAG cannot verify the identity of the issuer.

When you retrieve the federation metadata, Forefront UAG checks that the federation metadata is signed with a token signing certificate. If the federation metadata is not signed, Forefront UAG cannot verify the identity of the issuer of the metadata and cannot use the metadata file. Make sure that the federation metadata is signed. You can check the token signing certificate in the AD FS 2.0 Management console in AD FS 2.0\Service\Certificates.

The federation metadata is signed, but the Forefront UAG server does not trust the certificate.

When you retrieve the federation metadata, Forefront UAG checks that the AD FS 2.0 Token-signing certificate used to sign the federation metadata is valid. If you see this error, you should check the certificate chain of trust, whether the certificate has expired, or if the certificate is not yet valid. You may also need to export the Token-signing certificate from the AD FS 2.0\Service\Certificates pane in the AD FS 2.0 Management console and import it into the Trusted Root Certification Authority certificates store on your Forefront UAG server.

The federation metadata is signed with an unsupported certificate type. Forefront UAG supports only X509 certificates.

The federation metadata is signed with a token signing certificate. By default, the AD FS 2.0 server uses a self-signed certificate that is suitable for testing purposes. If you use a trusted certification authority to provide the token signing certificate, you must make sure that you use an X509 certificate. Contact your AD FS administrator to make sure that the federation metadata is signed with an X509 certificate. You can check the token signing certificate in the AD FS 2.0 Management console in AD FS 2.0\Service\Certificates.