Ctrlk

SSO Troubleshooting Guide

Diagnose and resolve common SSO login failures in PCD, including authorization errors, SAML attribute mapping mistakes, certificate issues, and login loops.

Overview

This guide helps you diagnose and resolve the most common SSO login failures in Private Cloud Director. Each section maps a symptom to its likely cause and provides the steps to fix it.

If you are not sure which symptom applies, start with the Diagnostic Checklist below.

Diagnostic Checklist

Work through this checklist from top to bottom. Stop at the first item that matches your situation.

  1. Can the user reach the IdP login page? If not, the issue is network or DNS — not SSO configuration.

  2. Does the user authenticate successfully at the IdP but land on an error page in PCD? Go to Authorization Errors.

  3. Is the user redirected back to the login page immediately after authenticating (login loop)? Go to Login Loops.

  4. Does the user land in PCD but see no tenants, no resources, or a blank dashboard? Go to Missing Tenants or Resources.

  5. Is the error related to an expired or invalid certificate? Go to Certificate and Metadata Issues.

  6. Are SAML attribute values missing or incorrect in PCD? Go to SAML Attribute Mapping Errors.

Authorization Errors: "Account Not Authorized"

Symptom

After authenticating at the IdP, the user sees an "Account not authorized" error or a denial containing identity:get_project in the PCD error page or browser console.

Cause

The SAML assertion was accepted, but the Identity Service could not find a valid role assignment for the user in any tenant. This typically means:

  • The user's IdP group does not match any SAML group mapping in PCD.

  • The SAML group mapping exists but has no tenants or roles assigned.

  • The group attribute value sent by the IdP does not match the value configured in the SAML group mapping.

Fix

  1. Log in to PCD as an administrator.

  2. Navigate to Settings > Enterprise SSO > SAML Groups.

  3. Open the SAML group that should apply to this user.

  4. Under Group Mapping, verify that the SAML Group Attribute name and SAML Group Values exactly match what the IdP sends. Values are case-sensitive.

  5. Under Tenants & Roles, confirm that at least one tenant and one role (Admin, Self-Service User, or ReadOnly) are assigned to the group.

  6. Ask the user to log out and log in again.

Tip: Verify what the IdP actually sends

Use your browser's developer tools (Network tab) to capture the SAML POST request during login. Decode the SAMLResponse field (it is base64-encoded) and inspect the AttributeStatement block. Compare the attribute names and values against what is configured in your SAML group mappings.

SAML Attribute Mapping Errors

Symptom

The user can log in but:

  • Their display name is missing or shows as an email address.

  • Role assignments do not apply correctly.

  • Group-based tenant access does not work.

Cause

The attribute map XML registered in PCD does not match the attribute names the IdP includes in the SAML assertion, or the SAML group mapping uses a different attribute key than what the IdP sends.

Fix

  1. Decode a live SAMLResponse to identify the exact attribute names the IdP sends (see the tip in Authorization Errors).

  2. Navigate to Settings > Enterprise SSO.

  3. Update the SSO Provider Attribute Map in XML field. Each <Attribute> element's name attribute must match the attribute name in the SAML assertion exactly. The id attribute is the internal alias used in the SAML group mapping.

Example: if the IdP sends http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress but your map has name="Email", the mapping will not work. Update the name to match the IdP's assertion.

  1. In SAML Groups, verify that the SAML Attribute Key for Email, First Name, and Last Name fields use the id values defined in the attribute map XML (not the name values).

  2. Select Save and ask the user to log out and log in again.

Certificate and Metadata Issues

Symptom

Login fails immediately after the IdP redirect with an error such as:

  • "SAML signature verification failed"

  • "Metadata could not be loaded"

  • "Invalid issuer"

Cause

  • The IdP's signing certificate has been rotated without updating the metadata in PCD.

  • The SAML Metadata URL is unreachable from the PCD management plane.

  • The Entity ID configured in PCD does not match the issuer in the SAML assertion.

Fix

  1. Refresh metadata: if you configured a SAML Metadata URL, verify that the URL is publicly reachable and that the certificate it returns is the current signing certificate in your IdP.

  2. Update the metadata manually: if your IdP does not publish a live metadata URL, download the current IdP metadata XML from your IdP's admin console and paste it into the SSO Provider Attribute Map in XML field, replacing the old content.

  3. Verify the Entity ID: navigate to Settings > Enterprise SSO and confirm that the Entity ID field exactly matches the entityID in your IdP's metadata. This value is case-sensitive.

  4. Check certificate expiry in your IdP: if the IdP signing certificate has expired, renew it and re-export the metadata.

Self-Hosted deployments only

If you host your own management plane, you can inspect the Shibboleth service provider logs for detailed signature verification errors:

SaaS customers should contact Platform9 Support for assistance with certificate verification errors.

Login Loops

Symptom

The user is redirected to the IdP, authenticates successfully, and is immediately redirected back to the PCD login page. This cycle repeats without the user landing in the product.

Cause

  • The Assertion Consumer Service (ACS) URL configured in the IdP does not match the URL that PCD expects.

  • The SAML response is being delivered to the wrong endpoint, so the Identity Service rejects it and the browser is redirected to log in again.

  • A cookie or session mismatch in the browser is holding stale state.

Fix

  1. Verify the ACS URL in your IdP. The correct ACS URL is:

    Replace <FQDN> with your deployment FQDN (without the region) and <DOMAIN_NAME> with your SSO domain name (for example, IDP1).

  2. Verify the SP Entity ID in your IdP. The correct entity ID is:

  3. Clear the browser session. Ask the user to clear cookies and cached data, then retry login in a private or incognito window.

  4. Check the RelayState. Some IdPs require a specific RelayState value. For PCD, the RelayState field should be left blank in the IdP application configuration.

Missing Tenants or Resources

Symptom

The user can log in but sees an empty dashboard, no tenants, or fewer resources than expected.

Cause

  • The SAML group mapping that controls tenant assignment is not matching the user's group membership in the IdP.

  • The user's role in the assigned tenant is ReadOnly, which limits visibility of certain resource types.

  • The user's IdP group value changed (for example, after a directory sync) and no longer matches the SAML group mapping.

Fix

  1. Follow the steps in Authorization Errors to verify the SAML group mapping and tenant/role assignment.

  2. If the user should have a specific role, confirm that the role assigned in the SAML group mapping matches the intended access level. See RBAC Roles and Permissions for the full permissions matrix.

  3. If the user is a ReadOnly user who cannot see expected resources, this is expected behavior. ReadOnly users have visibility restrictions on some resource types by design.

Next Steps

PreviousSet up DuoNextApplication Catalog

Last updated

Was this helpful?