This document enables users to troubleshoot issues or errors that might occur while configuring custom SSO access using the SSO wizard available in PDC.

• Introduction
  • Recording SAML traces
• Common configuration issues
  • Azure IdP wildchar in URL
  • PDC SP-Metadatafile does not contain X509 Certificate
  • SSO does not consider role attributes
  • Unable to process the SAML WebSSO request : Unable to derive operator from SAML assertion
  • Unable to process the SAML WebSSO request : Error authenticating user, contact administrator
  • Unable to process the SAML WebSSO request : Missing Relaystate information in IDP Response
  • Unable to process the SAML WebSSO request : Caught Exception while validating SAML2 Authentication response protocol : Error during certificate path validation: basic constraints check failed: this is not a CA certificate
  • Unable to derive attribute <attributename> from SAML assertion for operator establishment
  • PDC works incorrectly when you log out while using custom SSO

Introduction

You can configure Single Sign-On (SSO) login authentication for Pega Diagnostic Center (PDC). By using the wizard in PDC, you can configure an Identity Provider (IdP) to authenticate users in organizations while accessing PDC. PDC only supports SAML 2.0 identity providers.

For detailed processes, refer to the Configuring SSO login authentication in PDC SSO configuration guide.

Recording SAML traces

You might have to record Security Assertion Markup Language (SAML) traces to troubleshoot some of the issues in this support document. To record SAML traces, perform the following actions:

1. Install the SAML-tracer browser plugin for your Browser.
   For example, Google Chrome offers the following plugin: SAML-tracer
2. From the Extensions browser menu, open the SAML-tracer plugin dialog box.
3. In PDC, launch the login URL from the Custom SSO Configuration landing page.
4. In the SAML-tracer plugin dialog box, select the POST step with the AssertionConsumerService URL.
5. View or save the SAML trace by performing the following actions:
   • To view the SAML trace, navigate to the SAML tab.
   • To save the SAML trace, in the top menu, click the Export button, select a cookie-filter profile, and click Export.

Common configuration issues

Azure IdP wildchar in URL

Symptom

When using Azure as an IdP, you are unable to add URLs that contain an asterisk (*) during configuration.

Solution

1. Replace all asterisks (*) with %2A in all the Service Provider (SP) URLs in the configuration.
2. Create an incident support ticket. To resolve this issue, support engineers must perform some additional actions on your behalf.

PDC SP-Metadatafile does not contain X509 Certificate

Symptom

When trying to set up SSO in PDC, the error message PDC SP-Metadatafile does not contain X509 Certificate is displayed while attempting to sign a certificate.

Solution

The SSO wizard in PDC does not support certificate signing.

To enable x509 certificate signing, submit a Service Request for Custom PDC SSO Integration. This ensures that your service history notes that you have a custom SSO configuration.

The recommended approach is to send a certificate to Pega to use in the authentication service for request signing. The certificate will be uploaded to a new keystore. This gives you control over the certificate and allows Pega to make the necessary changes.

If you are unable to provide a certificate, contact Pega Support. A self-signed certificate will be created for you to use in the authentication service. Note that this certificate needs to be renewed before it expires.

SSO does not consider role attributes

Symptom

When logging in to PDC, the user is not assigned the correct role after configuring attribute names and values to assign User and Manager roles through the custom SSO wizard.

For more information about role mapping, refer to Configuring SSO login authentication in PDC.

Solution

1. On the Advanced configuration settings tab in the SSO wizard configuration screen, note the SAML attribute name and attribute values set for User, Manager, and Deny access roles.
2. Record the SAML trace during login. In the SAML trace log, verify the presence of the configured attribute name for the role under the AttributeStatement element. Then, perform one of the following actions:
   • If the attribute name is not present, ensure that you set it in your IdP.
   • If the attribute name is present, verify whether the attribute name and value match with the User, Manager, or Deny access fields configured in the wizard.
3. If all the configurations are correctly mapped, contact Pega Support and share the SAML trace for further investigation.

Unable to process the SAML WebSSO request : Unable to derive operator from SAML assertion

Symptom

The system displays the error message Unable to process the SAML WebSSO request : Unable to derive operator from SAML assertion while the user is attempting to log in.
When you authenticate a new user, the system automatically creates a new operator. However, sometimes the required operators are missing.

Solution

DiagnosticCloudManager is a model operator that allows you to create new operators through custom SSO. Ensure that the DiagnosticCloudManager operator is present in PDC by performing the following actions:

1. In PDC, navigate to System Administration and select Manage Operators.
2. Verify if the DiagnosticCloudManager operator is present in the list of operators.
3. If the operator is not present, contact Pega Support.

Unable to process the SAML WebSSO request : Error authenticating user, contact administrator

Symptom

PDC administrators create local user IDs using email addresses as operator IDs. These users then attempt to access PDC through community integration, which also uses email addresses as operator IDs, but are unable to log in. PDC follows standard Pega authentication practices and automatically creates an operator ID when logging in through SSO. However, if the local ID already exists, it cannot be recreated. When platform authentication is enabled and Use external authentication is disabled, SAML SSO fails.

For more information about external authentication, refer to Defining security information for an operator.

Solution

To resolve this issue, perform either of the following actions:

• Update the record to set the Use external authentication flag
• Delete the operator record so that a replacement record is generated and saved during SSO

To enable external authentication, ensure that you have the Manager role, or ask a user with the Manager role to perform the following actions:

1. Log in to PDC with your password.
2. Navigate to System Administration and select Manage Operators.
3. Select the operator and click Next.
4. Select the Enable external authentication (SSO) checkbox.
5. Click Finish, then Close to return to the main screen.

Unable to process the SAML WebSSO request : Missing Relaystate information in IDP Response

Symptom

The systems displays the error message Unable to process the SAML WebSSO request : Missing Relaystate information in IDP Response while attempting to log in through IdP.

Solution

Ensure that the default relay state parameter is set to the login URL that was shared with you in the custom SSO configuration landing page. This ensures that the relay state information is included in the IdP response.

If you do not know how to set the default relay state parameter, or if you are unable to do it, use an SP-initiated login through your IdP.

Unable to process the SAML WebSSO request : Caught Exception while validating SAML2 Authentication response protocol : Error during certificate path validation: basic constraints check failed: this is not a CA certificate

Symptom

The system displays the error message Unable to process the SAML WebSSO request : Caught Exception while validating SAML2 Authentication response protocol : Error during certificate path validation: basic constraints check failed: this is not a CA certificate when the IdP sign-on certificate has expired.

Sometimes two sign-on certificate details might be present in the IdP metadata. When the IdP changes the certificates, it first publishes the new certificate in parallel with the old certificate in the metadata. When the IdP switches over to use the new certificate, all SPs must load the new certificate, or the signature validation fails.

Solution

Reupload the IdP metadata with the correct certificate details.

Unable to derive attribute <attributename> from SAML assertion for operator establishment

Symptom

The system displays the error message Unable to derive attribute <attributename> from SAML assertion for operator establishment during an attempt to log in by using custom SSO. This might occur if operator identification is unsuccessful. Identifying the operator is necessary to determine the name of the operator.

Solution

1. In the custom SSO wizard, verify whether the Operator identification is configured based on NameID or a specific Attribute.
2. Record the SAML trace during login.
3. Check whether the NameID or the specific Attribute is utilized for identification in the SAML trace and perform one of the following actions:
   • If operator identification is configured based on NameID, verify if the NameID attribute is present and holds a value in the SAML response. If it is not present, make the necessary adjustments in your IdP.
   • If operator identification is configured based on a specific attribute, verify if that attribute is present and holds a value in the SAML response. If it is not present, make the necessary adjustments in your IdP.

PDC works incorrectly when you log out while using custom SSO

Symptom

Upon logging out, the screen is blank, and no activity is recorded in the SAML-tracer.

Solution

1. In the custom SSO wizard, navigate to the Identity Provider (IdP) information tab.
2. From the TLS/SSL truststore drop-down menu, select the truststore from the list.