SAML certificates explained

Auth & identity

September 4, 2024

Author: Isaac Ejeh

Author: Edwin Lim

SAML certificates are digital certificates used within the SAML (Security Assertion Markup Language) protocol to establish trust and secure connections between identity providers (IdPs) and service providers (SPs).

These certificates are typically X.509 certificates which contain a public key, a digital signature from a trusted certificate authority (CA), and metadata about the certificate holder. Within SAML SSO (single sign-on) flows, they can be used to either sign, encrypt, or decrypt SAML messages (mostly responses and assertions).

In this article, you’ll learn about SAML certificates and how identity providers and service providers use them to maintain the integrity and authenticity of SAML messages. We’ll also explore the structure of SAML certificates to show you how signing certificates may differ from encryption certificates based on key usage. Finally, we’ll discuss some of the most common SAML certificate errors and provide best practices for dealing with these errors in both test and production environments.

The X.509 certificate standard

The X.509 certificate standard is a public key infrastructure (PKI) framework that defines the format, structure, and content of public key certificates used to verify the authenticity of digital identities over networks. It was first introduced by the International Telecommunication Union (ITU) in 1988 and has since become the most widely used standard for issuing digital certificates.

At its core, an X.509 certificate binds a public key with a specific identity that could belong to an organization or individual, and this binding must be verified by a trusted third party known as a certificate authority (CA). X.509 is used in SAML because the authentication flows between disparate SAML entities (IdPs and SPs) rely heavily on trust relationships, and X.509 certificates provide a standardized and secure way to establish and maintain these trust relationships.

How do SAML (X.509) certificates work?

There are two main types of SAML certificates—signing certificates and encryption certificates—and each type plays a unique role in securing the authentication and authorization data transmitted within SAML authentication flows. IdPs typically use signing certificates to sign the responses and assertions they send to SPs in order to certify their origin and integrity, while encryption certificates are used to encrypt sensitive elements within these assertions, ensuring that only the intended SPs can decrypt and access them.

Nested structure of a SAML certificate in XML format

What are SAML signing certificates, and how do they work?

When an SP sends a SAML authentication request (AuthnRequest) to an IdP via an SP-initiated SAML SSO flow, or when a user directly selects an SP via an IdP-initiated SAML SSO flow, the IdP typically responds by sending a digitally signed SAML response containing assertions about the user.

To sign these SAML responses and assertions, IdPs use signing certificates that contain a public and private key pair. The IdP uses the private key to create a digital signature by generating a cryptographic hash of the assertion’s content and then encrypting this hash. This digital signature is attached to the SAML response and/or assertion, and the corresponding public key (commonly referred to as the verification certificate) is embedded in the signing certificate and shared with the SP, so that it can verify the signature.

When an SP receives a SAML assertion, it uses the public key from the IdP's signing certificate to decrypt the signature and compares the resulting hash with a freshly computed hash of the received assertion. If the hashes match, it confirms to the SP that the assertion hasn’t been altered and is from a trusted IdP with which it has an existing relationship.

While signing certificates are commonly used by IdPs to sign responses and assertions, SPs can also use them to sign the authentication requests they send to IdPs. In such cases, the IdP will extract the SP’s public key from the SAML signing certificate to verify that the request originated from a legitimate SP and not an impersonator.

What are SAML encryption certificates, and how do they work?

When an IdP generates a SAML assertion that contains user attributes or other sensitive data, it often needs to encrypt this data to ensure that only the intended SP can access it. To perform this encryption, the IdP has to use the SP’s encryption certificate, which contains a public key and is provided in the SP’s metadata document.

The IdP typically uses this public key to encrypt sensitive portions of an assertion, such as the attribute and authorization statements. Once encrypted, this data can only be decrypted by the corresponding private key, which is securely held by the SP. This ensures that even if the assertion is intercepted during transmission, its sensitive elements will remain inaccessible to unauthorized parties.

Upon receiving the encrypted SAML assertion, the SP can then use its private key to decrypt the encoded elements, which may be necessary for making authentication and authorization decisions about the user.

While encryption certificates are primarily used by IdPs to encrypt SAML assertions, SPs may also use them to protect any sensitive data they send to IdPs. However, this is less common in standard SAML flows.

It's also important to note that in some SAML implementations, the same certificate may be used for both signing and encryption functions. However, the decision to use separate certificates or a single certificate for both purposes often depends on the specific security requirements and policies of the organizations implementing SAML.

Structure of SAML certificates

Both signing and encryption certificates follow the standard structure of X.509 certificates, even though they serve different functions within a SAML authentication flow. Here’s an example structure of a single SAML certificate that can be used for both signing and encryption due to its key usage extension:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1234567890 (0x499602d2)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=Example CA, O=Example Organization, C=US
        Validity
            Not Before: Jan  1 00:00:00 2023 GMT
            Not After : Jan  1 00:00:00 2024 GMT
        Subject: CN=example.com, O=Example Organization, C=US
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:af:1e:...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Key Usage: 
                Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment
            X509v3 Subject Alternative Name: 
                DNS:example.com
    Signature Algorithm: sha256WithRSAEncryption
         4d:88:...

This example structure represents a decoded, human-readable format of an X.509 certificate—it's not the raw certificate data itself (which would be in binary or Base64 format).

Here’s an example of how this SAML certificate will typically look like when encoded in Base64 format:

Now, let’s explore the key elements that make up this X.509-based structure of a SAML certificate in more detail:

Version

This element specifies the version of the X.509 standard a certificate adheres to. This is highly important because the different versions of the X.509 standard define the features and functionalities that can be included in a certificate.

For example, most SAML certificates use version 3, which allows for the inclusion of additional data and functionalities via extensions. These extensions can be used to specify policies, constraints, or additional identity data, and they can be designated as critical or non-critical.

Serial number

The serial number element is a unique identifier assigned to each SAML certificate by the certificate authority (CA) that issued it. This number helps the CA to track and manage all issued certificates.

For example, if a certificate expires or is compromised, the CA uses this number to mark it as invalid. In essence, the serial number is used in certificate revocation lists (CRLs) and other status checks to ensure that compromised or expired certificates are properly handled and don’t remain active or in circulation.

Issuer

This specifies the name of the certificate authority (CA) that issued the SAML certificate. The issuer element is usually presented in the distinguished name (DN) format and includes additional details such as the organization name, unit, country, and more. Service providers use this element to verify that a certificate originates from a trusted CA, which is important for maintaining trust and security in SAML authentication flows.

Signature algorithm

This element specifies the cryptographic algorithm the certificate authority (CA) used to sign the SAML certificate. It details how the signature must have been generated, including the specific algorithm such as RSA or ECDSA, and the associated hash function like SHA-256. This information is essential for verifying that the certificate has been properly signed by a recognized algorithm that meets the required security standards for SAML authentication.

Validity period

This element defines the timeframe during which a SAML certificate is considered valid, specified by two dates—the “Not Before” and “Not After” date attributes. These dates ensure that the certificate can only be used within a specific period, preventing the use of inactive or expired certificates, which could otherwise compromise the security of a SAML authentication flow.

Subject

The subject element specifies the entity to which a SAML certificate is issued, typically an identity provider (IdP) or a service provider (SP). This element includes details such as the subject’s distinguished name (DN) or domain name, which helps identify the entity within SAML authentication flows. Additionally, the subject may include other identifiers like the organization name, organizational unit, or even an email address, depending on the certificate's intended use and the issuing authority’s policies.

Subject public key info

This element contains the public key associated with a SAML certificate and the algorithm used to generate it. The public key is a cryptographic key that serves two primary functions in SAML: for verifying digital signatures in the case of a signing certificate, or for encrypting sensitive data in the case of an encryption certificate. It’s part of a key pair, where the corresponding private key (held securely by the certificate owner) is used for signing or decryption, depending on the type of certificate.

Extensions

Extensions are additional fields in a SAML certificate that support extra information or functionality beyond the standard certificate attributes. Common extensions include key usage, which specifies how the key can be used (e.g., whether it’s for creating digital signatures or encrypting data), subject alternative names, which list additional identities for the subject, and extended key usage, which further defines the key's intended purposes (e.g., client or server authentication). These extensions make the certificate more flexible, ensuring it can meet specific requirements and constraints within various SAML SSO use cases.

Signature

The Signature element is the actual digital signature attached to the SAML assertion or response. It's created using the private key associated with the certificate and is a cryptographic hash of the assertion's content, which is then encrypted. This digital signature is used by the service provider (SP) to verify that a SAML response or assertion hasn't been tampered with and that it originates from a trusted identity provider (IdP). During verification, the SP typically uses the IdP's public key to decrypt this signature and compare it with a freshly computed hash of the received assertion.

Certificate authority (CA)-signed certificates vs self-signed certificates in SAML

Choosing between certificate authority (CA)-signed certificates and self-signed certificates is an important decision that defines the level of security and trust between SAML entities.

CA-signed certificates are issued and validated by a trusted third-party authority, making them the preferred choice for most production SAML environments. By relying on a CA, both the IdP and SP can be confident that a SAML certificate has been thoroughly vetted and is less likely to be involved with malicious activity.

On the other hand, self-signed certificates are generated and signed by the same entity that intends to use them, without requiring third-party verification. While they offer the same cryptographic capabilities as CA-signed certificates, they don’t provide the same level of trust because they lack external validation.

Self-signed certificates are typically used in development or tightly controlled production environments such as corporate intranet systems where functionality is the primary concern, rather than security. They allow developers to quickly establish SAML connections without needing an external CA.

Common SAML certificate errors

There are several certificate-related issues that can disrupt SAML SSO flows and cause authentication errors. Knowing how to identify these certificate errors is the only way to troubleshoot and fix them in no time.

Here are some of the most frequent certificate errors you may experience, whether you’re working with SAML certificates in development or production:

1. Certificate mismatch: A certificate mismatch error typically occurs when the certificate presented by the sending entity, whether it’s an IdP or SP, doesn’t match the one expected by the intended recipient. This could happen if the IdP or SP updates its certificate but fails to update the corresponding metadata or notify the other party of the change.

2. Certificate revocation: When a sending party uses a certificate that has been revoked by the CA (usually due to compromise or key loss) without checking its status on Certificate Revocation Lists (CRLs) or the Online Certificate Status Protocol (OCSP), it will result in a revocation error.

3. Invalid certificate signature: This error occurs when the intended recipient is unable to verify the certificate’s digital signature with the associated public key. This might be due to a data mismatch, but could also indicate that the certificate was tampered with or corrupted during transmission, possibly signifying a security breach or an attempted man-in-the-middle attack.

4. Self-signed certificate rejection: This error occurs when a self-signed certificate is presented in a SAML environment configured to accept only CA-signed certificates. While self-signed certificates can be used in high-trust SAML scenarios, most systems will reject them by default for security reasons.

5. Incomplete certificate chain: This error occurs when a SAML recipient is unable to fully validate the certificate chain, which usually consists of the end-entity certificate, intermediate certificate, and root certificate. If any part of this chain is missing or incorrect, the recipient won't be able to trust the SAML message.

6. Incorrect key usage: As we’ve seen so far, version 3 SAML certificates have specific key usage extensions that define their intended purpose (e.g., digital signature, key encipherment). If a recipient attempts to use a certificate for a purpose not specified in its key usage extension, they will encounter this error.

7. Untrusted certificate authority: This error happens when a certificate is signed by a CA that isn’t trusted or recognized by the intended recipient. This could occur if the sending party uses certificates from lesser-known CAs or if the CA’s root certificate isn’t installed in the recipient’s trust store.

Best practices for managing SAML certificates

To effectively manage both encryption and signing SAML certificates in production, we’ve outlined the most common best practices for certificate holders and recipients:

1. Use separate certificates for signing and encryption

While it’s possible to use a single certificate for both signing and encryption in SAML, it's best to use separate certificates for these functions. This separation reduces the risk of a single point of failure and minimizes the potential impact if either of the certificates is compromised.

Also, using distinct certificates simplifies how you manage the lifecycle of each certificate and handle key rotation. If you need to make changes to one certificate (e.g., for signing), you can do so without affecting the other certificate meant for encryption.

2. Maintain accurate and up-to-date metadata

When updating or replacing certificates, it’s best practice to ensure the associated metadata is updated and correctly distributed to all relevant SAML entities, whether IdPs or SPs. Failing to update metadata files can lead to certificate mismatch errors, where entities attempt to validate a SAML message against an outdated or incorrect certificate.

3. Avoid using self-signed certificates in production

While self-signed certificates might be convenient for development or controlled environments, they’re generally not recommended for production. Self-signed certificates lack the external validation that CA-signed certificates provide, making them less secure.

4. Use trusted Certificate Authorities (CAs)

Only use certificates issued by reputable and well-established certificate authorities (CAs) that are trusted by your recipients (IdPs or SPs). Trusted CAs have undergone rigorous vetting and follow industry-standard security practices, which adds a layer of confidence in the validity and integrity of your certificates.

5. Use strong cryptographic algorithms and key lengths

Always ensure that the certificates you send or receive are issued by a CA that employs robust cryptographic algorithms (e.g., RSA with SHA-256) and adequate key lengths (at least 2048 bits for RSA). Avoid deprecated algorithms like SHA-1 or MD5, which are no longer secure and may lead to vulnerabilities in your SAML authentication flows.

6. Establish proper certificate lifecycle management

As a certificate holder, you should establish clear policies and procedures for managing your SAML certificates, including issuing, renewing, revoking, and replacing certificates. The only way to prevent unexpected authentication failures for SPs or any other recipient of SAML messages is for certificate holders to implement a proper certificate lifecycle management process.

Also, both sending and receiving parties should keep a detailed inventory of all certificates used within their SAML environment, including details such as the issuing CA, expiration dates, key usage, and the systems or applications where each certificate is deployed.

Getting started with Stytch SAML SSO

Ready to implement SAML SSO in your B2B SaaS app? Stytch has done all the heavy lifting for you.

We make it super easy for your engineering team to go live with SAML without worrying about all the certificate errors and best practices we just discussed. You can check our SAML SSO docs and sign up for a free developer account to get started.

For questions about our features or pricing, contact us at support@stytch.com or schedule a call with one of our Solutions Engineers.