> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/identity-and-multi-tenancy/enterprise-sso/sso-troubleshooting.md).

# SSO Troubleshooting Guide

## Overview

This guide helps you diagnose and resolve the most common SSO login failures in <code class="expression">space.vars.product\_name</code>. 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](#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 <code class="expression">space.vars.product\_acronym</code>? Go to [Authorization Errors](#authorization-errors-account-not-authorized).
3. Is the user redirected back to the login page immediately after authenticating (login loop)? Go to [Login Loops](#login-loops).
4. Does the user land in <code class="expression">space.vars.product\_acronym</code> but see no tenants, no resources, or a blank dashboard? Go to [Missing Tenants or Resources](#missing-tenants-or-resources).
5. Is the error related to an expired or invalid certificate? Go to [Certificate and Metadata Issues](#certificate-and-metadata-issues).
6. Are SAML attribute values missing or incorrect in <code class="expression">space.vars.product\_acronym</code>? Go to [SAML Attribute Mapping Errors](#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 <code class="expression">space.vars.product\_acronym</code> 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 <code class="expression">space.vars.product\_acronym</code>.
* 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 <code class="expression">space.vars.product\_acronym</code> 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.

{% hint style="info" %}
**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.
{% endhint %}

***

## 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 <code class="expression">space.vars.product\_acronym</code> 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](#authorization-errors-account-not-authorized)).
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.

4. 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).
5. 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 <code class="expression">space.vars.product\_acronym</code>.
* The SAML Metadata URL is unreachable from the <code class="expression">space.vars.product\_acronym</code> management plane.
* The **Entity ID** configured in <code class="expression">space.vars.product\_acronym</code> 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.

{% hint style="info" %}
**Self-Hosted deployments only**

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

```bash
kubectl logs -n platform9 -l app=shibboleth --tail=100
```

SaaS customers should contact Platform9 Support for assistance with certificate verification errors.
{% endhint %}

***

## Login Loops

### Symptom

The user is redirected to the IdP, authenticates successfully, and is immediately redirected back to the <code class="expression">space.vars.product\_acronym</code> 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 <code class="expression">space.vars.product\_acronym</code> 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:

   ```
   https://<FQDN>/sso/<DOMAIN_NAME>/Shibboleth.sso/SAML2/POST
   ```

   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:

   ```
   https://<FQDN>/keystone
   ```
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 <code class="expression">space.vars.product\_acronym</code>, 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](#authorization-errors-account-not-authorized) 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](/private-cloud-director/identity-and-multi-tenancy/rbac-roles-and-permissions.md) 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

* For per-IdP setup instructions, see the guides under [Enterprise SSO](/private-cloud-director/identity-and-multi-tenancy/enterprise-sso.md).
* For role and permission details, see [RBAC Roles and Permissions](/private-cloud-director/identity-and-multi-tenancy/rbac-roles-and-permissions.md).
* For application credential issues when using SSO, see [Application Credentials](/private-cloud-director/identity-and-multi-tenancy/application-credentials.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/identity-and-multi-tenancy/enterprise-sso/sso-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.