Troubleshoot "Invalid Custom Claims" SSO error

The "Invalid Custom Claims" error occurs when Housing.Cloud cannot find the user's full name in the SAML assertion returned by your identity provider. This happens when the custom attribute mapping doesn't match the actual attribute name in your SAML response.

To fix this, you'll capture a SAML assertion from a login attempt, decode it to find the correct attribute name, and update your custom mapping configuration.

Capture the SAML assertion

Ask the affected user to share their screen and walk them through capturing the raw SAML data:

1. Right-click anywhere on the login page and select Inspect or Developer Tools (wording varies by browser)
2. Navigate to the Network tab in the developer tools panel
3. Check the Preserve Log option to keep all network activity visible
4. Attempt to sign in using SSO
5. Locate the network call to /acs in the list of requests
6. Click the /acs entry and select Request Payload
7. Copy the entire payload value (a long base64-encoded string) and send it via email—it's too long for chat

Decode and locate the attribute

Use any base64 decoder tool to convert the payload into readable XML. The decoded result is your SAML assertion.

Look for the AttributeStatement section near the bottom of the XML. Identify which attribute contains the user's full name, then copy the Name value from that attribute element.

Example:

<samlp:Response  ID="_717340cf-5217-49c4-8b54-2630478d1954" Version="2.0" IssueInstant="2026-02-26T21:37:32Z"  Destination="https://auth.housing.cloud/auth/v1/sso/saml/acs"  Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"  InResponseTo="id-f0d2daa2f8d36b66af50059ff93a5cd169808a7a">
  <Issuer>{{your-institution}}</Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <Assertion ID="_12345" IssueInstant="2026-02-26T21:37:32Z" Version="2.0">
    <Issuer>{{your-institution}}</Issuer>
    <ds:Signature>...</ds:Signature>
    <Subject>
      <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">jane.doe@housing.cloud</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="id-..." NotOnOrAfter="2026-02-26T21:40:32Z" Recipient="https://auth.housing.cloud/auth/v1/sso/saml/acs" />
      </SubjectConfirmation>
    </Subject>
    <Conditions NotBefore="2026-02-26T21:37:27Z" NotOnOrAfter="2026-02-26T22:37:32Z">
      <AudienceRestriction>
        <Audience>https://auth.housing.cloud/auth/v1/sso/saml/metadata</Audience>
      </AudienceRestriction>
    </Conditions>
    <AuthnStatement AuthnInstant="2026-02-26T21:37:32Z" SessionIndex="_57364054-6cc6-4078-a957-b5aba66ebd8e" SessionNotOnOrAfter="2026-02-27T05:37:32Z">
      <AuthnContext>
        <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
      </AuthnContext>
    </AuthnStatement>
    <AttributeStatement>
      <Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" FriendlyName="email">
        <AttributeValue>jane.doe@housing.cloud</AttributeValue>
      </Attribute>
      <Attribute Name="sisId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" FriendlyName="sisId">
        <AttributeValue>123456789</AttributeValue>
      </Attribute>
      <Attribute Name="displayName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" FriendlyName="displayName">
        <AttributeValue>Jane Doe</AttributeValue>
      </Attribute>
    </AttributeStatement>
  </Assertion>
</samlp:Response>

In this example, the attribute containing the full name is displayName. Your identity provider may use a different name like fullName, cn, or name.

Update the custom mapping

Navigate to Setup > Authentication in the Housing.Cloud admin portal. Locate the Custom Mappings section and edit the configuration.

Replace the value for name_full.name with the attribute name you found in the SAML assertion. Using the example above, you would enter displayName.

Save your changes. The affected user should now be able to sign in successfully.