Troubleshooting Your SAML Setup

This section includes information that might help you troubleshoot issues with your SAML single sign-on setup.

Table of Contents

URL-unsafe characters in URL

The Community Manager domain name is used in the Service Provider metadata URL. The domain name must have URL-safe characters or must use escape characters.

If the domain name includes characters that are not URL-safe, it might not work correctly.

I can log in to the Identity Provider but not to the Community Manager developer portal

If you can access the Identity Provider login screen, and login is successful, but you have not been successfully logged in to the Community Manager developer portal, it could be due to one of a number of issues.

In the Policy Manager SAML Web Browser SSO domain, check the following:

  • In the Identity Provider configuration, make sure the configured X.509 certificate for signature verification is still being used by the IdP to sign the assertions.
  • If the IdP is encrypting the SAML response, make sure the IdP is using the certificate that is configured for Service Provider on the Manage PKI Keys page.
  • In the Identity Mapping section, check to see that the user identifier location is configured correctly.
  • For HTTP-Artifact binding, check the following:
    • If the IdP uses the HTTP-Artifact binding of the Service Provider to send the artifact reference, make sure the correct authentication options have been selected on the SAML Identity Provider Configuration page.
    • if the IdP Artifact Resolution Service is on HTTPS, make sure there are no SSL handshake errors. If there are errors, import the CA certificate of the IdP server certificate into the Policy Manager trust store. In Policy Manager: Console > Configure > Security > Certificates > Trusted CA Certificates tab.
  • Check if the IdP uses a valid Name-ID format to communicate the subject inside the SAML response. If needed, check the allowed Name-ID formats in the Service Provider Configuration section.

I set up everything but I don't see the IdP login screen

  • In the Policy Manager SAML Web Browser SSO domain, do the following:
  • Check if the Authentication URL configured on the SAML Identity Provider Configuration page is valid.
  • Make sure the certificate that is configured on the Manage PKI Keys page is still used at the IdP for verifying the signatures on incoming AuthNRequests from this Service Provider.
  • If this issue is with end-user login in OAuth Provider, make sure the SSO login URL of this OAuth Provider is registered at the IdP as a valid Assertion Consumer Service URL with the correct binding format.
  • Check if the SAML Service Provider domain is initialized without any errors.

How can I change the IdP login screen from main page to popup or vice versa?

When enabling a domain for login in Community Manager, you can choose whether the login page is displayed as the main page or as a popup.

Log in as a Site Admin, go to More > Admin > Logins, and then, in the Mode column, choose Popup or Main.

For more information, refer to What login page integration modes are supported? (Site Admin help).

I can complete an end-to-end case but my Community Manager developer portal screens looks different from the IdP login screen

The Community Manager user interface look and feel is controlled by the styles defined in the custom.less file, which is uploaded by the Site Admin. Default styles are provided with installation, and the Site Admin can customize as needed.

If the Identity Provider login screen is customizable, you'll find this defined somewhere in the IdP account settings. For example, in PingFederate it's managed with an HTML adapter.

Some customers like to have a similar look and feel for all UI elements a user might see in the course of their platform experience; others prefer that the external login screen has a different look and feel, which conveys to the user that the login screen is external to the platform.

If you want a similar look and feel for both, you'll need to customize the Community Manager user interface, the Identity Provider login screen, or both.

I am doing the SP setup in PingFederate, but when I import the metadata.xml file I get the message "Invalid signature on metadata file." What do I do?

This message means that the signature is being validated and has been found to be invalid. If this occurs, check the following:

  • In Policy Manager, in the Service Provider configuration, make sure that the Sign Metadata checkbox is checked.
  • In the next tab, Manage PKI Keys, check the certificate details that are displayed.
  • In Policy Manager, make sure the CA is set up (Configure > Security > Certificates > Certificate Authority) and export the certificate.
  • Then, in PingFederate, go to Trusted CAs and import the certificate.

I configured the OAuth provider and configured SAML Web Browser SSO domain for the resource owner domain, but could not log in

When you set up the domain in Policy Manager, generate the metadata XML file, and import the metadata file to your Identity Provider, the file includes information about the endpoints you've configured.

When you add a new OAuth provider domain in Community Manager, a new endpoint is added to the metadata XML file. However, in order for this to work, you must add the information about the new URL to the Service Provider account with your Identity Provider. If this step is not done, the new URL will not work.

For more information, and instructions, refer to Adding a New OAuth Provider Domain: Manual IdP Configuration.

The metadata file doesn't have the login URL for my Community Manager installation

When you create the identity system in Policy Manager, you must make sure you access the metadata.xml file by using the metadata URL of the container where the features are installed that are using the SAML Web Browser SSO feature. For example:

  • If this domain is supporting Community Manager login, use the container that has the Community Manager feature installed.
  • If the OAuth Provider is using this domain for end-user authentication, use the container that has the OAuth Provider feature installed.

If there is no container with all the features that use the domain installed, get the metadata XML from one of the containers and add the other SSO URLs manually to it before registering the Service Provider with the Identity Provider.

If you provide the wrong metadata.xml file to the Identity Provider, the feature will not work.

For example, for login, you should see the login URL for your instance of the platform listed in one of the AssertionConsumerService nodes in the metadata.xml file, as shown below (variables for base URL shown in curly brackets).

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
Location="{http(s)}://{hostname}:{port}//api/login/ssoLogin" index="7"/>

For an OAuth Provider Domain, the entry in the AssertionConsumerService node would look something like the below.

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
Location="{http(s)}://{hostname}:{port}/oauth/auz/grants/provider/authcomplete" index="8"/>