Identify issues in a SAML assertion

Use the instructions in this article to identify potential issues in your SAML assertion. You will first need to capture your assertion. Follow these instructions:  SAML Troubleshooting Step: Capture an Assertion.

Clean up your XML file (optional)

The XML assertion file can appear as a wall of text, making it difficult for you to find the elements you're looking for. 

Follow this process to make your XML file easier to read.
 

  1. Copy the text of the assertion and go to xmlprettyprint.com. Paste the copy into the text field and click the Pretty Print XML buttonIf xmlprettyprint.com returns a blank screen, try jsonformatter.org/xml-pretty-print. 
  2. Save the file. 

Verify the assertion isn't encrypted

Use Ctrl + F (Cmd + F on a Mac) to search your file for:

  • EncryptedAssertion
  • EncryptedData
  • CipherData

If any of these values are present, have the IdP Admin disable assertion encryption to generate a new, unencrypted assertion. Smartsheet support can attempt to decrypt the file, but it is faster to work with your in-house resources to generate a new assertion. 

Analyze the assertion

The assertion contains all the items detailed below. Validate each item appears as expected. 

Certificates

Certificates authenticate the information passed to Smartsheet. The login process will not complete if the certificates are not current or do not pass. 

Check the certificates in metadata. There can be multiple certificates and the Key Expiration date may not be accurate.

  1. Find the certificate in the assertion
    1. Open your assertion file. 
    2. Use Ctrl + F (Cmd + F on a Mac) to search for 509Certificate
    3. Copy all the data after the > and before the closing <

Check the certificate 

  1. Go to https://redkestrel.co.uk/products/decoder/
  2. Paste the certificate data into the text field and click the Decode button
  3. Verify that all fields are passing:

  1. Verify the certificate matches the certificate in your organization's metadata. Ask the IdP admin to export the metadata from their IdP to cross-reference the assertion information.

If the certificates don't pass the certificate check or pass the decoder, update your certificate or add the most recent metadata from the IdP into Smartsheet. 

Attribute Claims

The assertion contains a long list of claims or attributes. Smartsheet only requires two claims for authentication: the Persistent ID (also known as Name ID) claim and the Email Address claim. 

Smartsheet checks for two things: 

  • Is the claim set up correctly?
  • Is the correct information passed?

Make sure any claims are set up as shown in this Help Center article. 

Check the Persistent ID

Use Ctrl + F (Cmd + F for Mac) and search for "NameID" or "name=". 

When setting up SAML for the first time, users can set the NameID element for their Persistent ID claim. The formats below are accepted examples. 

  • urn:oasis:names:tc:SAML:1.1:nameid-­format:emailAddress
  • urn:oasis:names:tc:SAML:2.0:nameid­-format:email
  • urn:oasis:names:tc:SAML:2.0:nameid-­format:persistent
  • urn:oasis:names:tc:SAML:2.0:nameid-­format:unspecified
  • urn:oasis:names:tc:SAML:1.1:nameid­-format:unspecified
  • urn:oid:1.3.6.1.4.1.5923.1.1.1.10

Here's an example of a NameID Persistent ID attribute: 

<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">user@domaindotcom</saml:NameID>

The bold highlights the part of the claim to check. If you use NameID, it should match one of the examples above. 

The italic hightlghts the information the IdP passes Smartsheet to authenticate the user. For the Persistent/NameID, this doesn't have to be an email address on the desired Smartsheet account, but it often is. 

Another common choice is the IdP User ID for that person. If the italic section shown above is not the user's email, note this as a potential issue.  

When setting up SAML for the first time, users can also choose to not use the NameID element and instead just pass us a straightforward Persistent ID attribute. 

An accepted Persistent ID attribute could look like the example above (with one of those 6 accepted claims) or like the example below (with one of five accept claims): 

  • name="eduPersonPrincipalName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:basic"
  • name="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname""
  • name="persistent" nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-­format:persistent"
  • name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:uri"
  • name="eduPersonPrincipalName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:uri"

Here's an example of a Persistent ID attribute:
 

<saml:Attribute Name="eduPersonPrincipalName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"><saml:AttributeValue xsi:type="xs:string">user@domaindotcom</saml:AttributeValue></saml:Attribute>

The claim is formatted in bold. If this claim matches the accepted examples, this attribute is good to go. Check the italic text to ensure that an email address on the desired Smartsheet account is passed. If the italic section shown above is not the email, note this as a potential issue. 

Email Address Attribute

Use Ctrl + F (Cmd + F for Mac) and search for "emailaddress" or "nameFormat". 

The Email Address attribute must pass a verified email address on the Smartsheet account and won't accept NameID elements (like the Persistent attribute above). This attribute must match one of the claims below and pass the right email. 

  • name="email" name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress""
  • name="emailAddress",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:basic"
  • name="emailaddress",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:basic"
  • name="Email",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname­-format:basic"
  • name="saml_username",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:basic"
  • name="emailAddress",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:unspecified"
  • name="emailaddress",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:unspecified"
  • name="emailaddress",nameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress""
  • name="urn:oid:0.9.2342.19200300.100.1.3",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-­format:uri"
  • name="mail",nameFormat="urn:oasis:names:tc:SAML:2.0:attrname­-format:basic" 

Here's an example of how this appears in an assertion: 

<saml:Attribute name="emailaddress"nameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"><saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">;user@domaindotcom</saml:AttributeValue>

The claim is highlighted in green and blue. As long as this claim matches our accepted examples, this attribute is good to go. Check the purple text to ensure that an email address on the desired Smartsheet account is passed. 

If the italic section is not the right email, update the user's attribute in the IdP or add the other email as a confirmed alternate email address in Smartsheet. Check with your IdP Admin to determine the best path forward.

Review your findings

An assertion must meet the following requirements: 

  1. The certificate passes and matches the certificate in the org metadata
  2. The Persistent ID/NameID attribute matches one of the examples and passes an email address from the desired Smartsheet account.
    Note that sometimes this claim will pass another value and this can be okay. Confirm that the value being passed is intended. If there are no other issues, try passing a verified email (on the Smartsheet account) for that claim instead. 
  3. The Email Address attribute matches a claim example and is passing an email address from the desired Smartsheet account. 
Was this article helpful?
YesNo