Identify issues in a SAML assertion

Prerequisites

First, you’ll need to capture the assertion. Learn how.

Step 1: Clean up your XML file (optional)

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

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

Step 2: Verify the assertion isn't encrypted

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

• EncryptedAssertion
• EncryptedData
• CipherData

If 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 working with your in-house resources is faster to generate a new assertion. 

Step 3: 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 won’t be completed if the certificates are outdated or don’t pass.
• Check the certificates in the metadata. Multiple certificates may exist, and the Key Expiration date may not be accurate.

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 select the Decode button.
3. Verify that all fields are passing.

4. 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 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 italics highlight the information the IdP passes to Smartsheet to authenticate the user. For the Persistent/name ID, 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 italicized section above doesn’t include the user's email, note this as a potential issue.  

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

An accepted Persistent ID attribute could look like the example above (with one of those six accepted claims) or like the example below (with one of five accepted 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. This attribute is good to go if this claim matches the accepted examples. Check the italic text to ensure an email address on the desired Smartsheet account is passed. If the italic section 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. It must also 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 an email address on the desired Smartsheet account is passed. 

If the email in the italic section is not the right one, 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.

   Sometimes, this claim will pass another value, which can be fine. 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 passes an email address from the desired Smartsheet account.