> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.id.me/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server. # Best practices > SAML 2.0 best practices To efficiently and effectively integrate with ID.me it is recommended to use one of the Web Access Management Software Configurations listed above in the Resources section of this document. These configurations simplify the process of generating SP metadata and ingesting IdP metadata, whereas custom SAML implementations require you to manually apply the details above during integration planning and design. ## Matching When matching attributes in the ID.me payload to user data on your side, do not rely on a single attribute. Best practice would be to match multiple attributes such as SSN/ITIN, DOB and Last Name. Matching on SSN/ITIN as the first attribute to establish uniqueness, followed by Date of Birth, Last Name, and so on will increase assurance of uniqueness. With Last Name, issues can arise for hyphenated names or legal name changes. If First Name is leveraged, consideration should be taken to allow variations such as Thomas/Tom through the use of fuzzy logic. Upon subsequent logins from a user, the UUID from ID.me should be incorporated into the logic. Additionally, some attributes may have been updated. For example, last names may change due to marriage status or legal name changes. ## Storing user attributes Storing key attributes about the user is vital to a seamless digital identity verification experience. It is recommended to store the returned attributes in a separate table within your database with some relation to the user record. Remember, the ID.me provided UUID will remain constant for the life of that user's ID.me account. When extracting user attributes from JSON it is recommended that the handle_name be used to read the attributes. Relying on attribute order is susceptible to errors and issues as the platform and policies evolve. ## Using user attributes It is recommended that the user attributes be used to pre-fill information into any additional forms requested in the workflow in the same session to improve UX. Consider locking fields that are pre-filled with attribute data, where appropriate. For example, First Name, Last Name and Social Security Number be locked. A "Preferred Name" field can be leveraged to allow for nicknames. Care should be taken to handle unexpected payload changes such as the addition or removal of an attribute, change in attribute ordering, or an attribute containing an unexpected special character. ## Exception handling If the user denies the access request, or if the request is invalid, the client will be informed using the parameters in the following table, appended to the AssertionConsumerService: > **Important!** > > These codes all begin with `urn:oasis:names:tc:SAML:2.0:status:` > > *Example* > > `urn:oasis:names:tc:SAML:2.0:status:AuthnFailed` | Code | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AuthnFailed | The responding provider was unable to successfully authenticate the principal | | Requester | The request could not be performed due to an error on the part of the requester | | Responder | The request could not be performed due to an error on the part of the SAML responder or SAML authority | | VersionMismatch | The SAML responder could not process the request because the version of the request message was incorrect | | InvalidAttrNameOrValue | Unexpected or invalid content was encountered within an element | | InvalidNameIDPolicy | The responding provider cannot or will not support the requested name identifier policy | | NoAuthnContext | The specified authentication context requirements cannot be met by the responder | | NoAvailableIDP | Used by an intermediary to indicate that none of the supported identity provider elements in an can be resolved or that none of the supported identity providers are available | | NoPassive | Indicates the responding provider cannot authenticate the principal passively, as has been requested | | NoSupportedID | Used by an intermediary to indicate that none of the identity providers in an are supported by the intermediary | | PartialLogout | Used by a session authority to indicate to a session participant that it was not able to propagate logout to all other session participants | | ProxyCountExceeded | Indicates that a responding provider cannot authenticate the principal directly and is not permitted to proxy the request further | | RequestDenied | The SAML responder or SAML authority is able to process the request but has chosen not to respond. This status code MAY be used when there is concern about the security context of the request message or the sequence of request messages received from a particular requester. | | RequestUnsupported | The SAML responder or SAML authority does not support the request | | RequestVersionDeprecated | The SAML responder cannot process any requests with the protocol version specified in the request | | RequestVersionTooHigh | The SAML responder cannot process the request because the protocol version specified in the request message is a major upgrade from the highest protocol version supported by the responder | | RequestVersionTooLow | The SAML responder cannot process the request because the protocol version specified in the request message is too low | | ResourceNotRecognized | The resource value provided in the request message is invalid or unrecognized | | TooManyResponses | The response message would contain more elements than the SAML responder is able to return | | UnknownAttrProfile | An entity that has no knowledge of a particular attribute profile has been presented with an attribute drawn from that profile | | UnknownPrincipal | The responding provider does not recognize the principal specified or implied by the request | | UnsupportedBinding | The SAML responder cannot properly fulfill the request using the protocol binding specified in the request |