Saml API Security

SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). In API contexts, SAML is typically used for single sign-on (SSO) where a user authenticates once with an IdP and gains access to multiple API services without re-authenticating.

The SAML flow in APIs follows a predictable pattern:

• Authentication Request: The user attempts to access an API endpoint and is redirected to the IdP for authentication
• Assertion Generation: The IdP verifies credentials and generates a SAML assertion containing user identity, attributes, and authorization decisions
• Token Exchange: The client receives a SAML token (often in a browser redirect) and exchanges it for an API access token
• API Access: The client uses the access token to call protected API endpoints
• Validation: The API validates the SAML assertion's digital signature and claims before granting access

The security properties that make SAML attractive for APIs include:

• Digital Signatures: SAML assertions are cryptographically signed by the IdP, preventing tampering
• XML Encryption: Sensitive assertion data can be encrypted to protect confidentiality
• Single Logout: SAML supports terminating sessions across all connected services
• Attribute-Based Access Control: Fine-grained permissions can be encoded in SAML attributes

However, these security properties only work when implemented correctly. Common pitfalls include signature verification bypass, XML external entity (XXE) attacks, and improper audience restriction validation.

Developers frequently make critical errors when implementing SAML for APIs. Here are the most dangerous misconfigurations:

Signature Verification Bypass: Some implementations skip XML signature validation entirely, allowing attackers to forge SAML assertions. Others validate signatures but don't verify the certificate chain or check for revoked certificates.

XML External Entity (XXE) Vulnerabilities: SAML processors that don't disable external entity resolution can be exploited to read arbitrary files, perform SSRF attacks, or cause denial of service through XML bombs.

Audience Restriction Bypass: SAML assertions include an audience restriction element specifying which service providers should accept them. Failing to validate this allows assertions intended for one service to be reused against another.

Clock Skew Issues: SAML assertions have validity periods. Implementations that don't properly handle clock skew between IdP and SP can either reject valid assertions or accept expired ones.

Insecure Metadata Handling: SAML metadata files contain public keys and configuration. Serving these over HTTP instead of HTTPS, or failing to validate metadata signatures, enables man-in-the-middle attacks.

Missing Multi-Factor Authentication Checks: Some APIs assume the IdP has enforced MFA but don't verify this in the SAML attributes, creating a gap between authentication strength and authorization decisions.

Assertion Replay Attacks: Without proper replay protection (tracking assertion IDs and timestamps), attackers can capture valid SAML assertions and reuse them to gain unauthorized access.

Securing SAML implementations requires attention to multiple layers. Here are concrete steps to harden your SAML-based API authentication:

XML Parser Configuration: Configure your XML parser to disable external entity resolution, DTDs, and external schema references. Use secure parser options like libxml2's XML_PARSE_NOENT flag set to false.

// Example: secure XML parser configuration
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
factory.setFeature("http://xml.org/sax/features/external-general-entities", false);
factory.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
factory.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);

Signature Validation: Always validate XML signatures using the IdP's public key. Verify the certificate chain, check revocation status via OCSP or CRL, and ensure the signature covers all relevant assertion elements.

Audience and Recipient Validation: Verify that the SAML assertion's audience restriction matches your service provider entity ID. Check that the recipient attribute matches your assertion consumer service URL.

Time Validation with Clock Skew: Implement time validation with configurable clock skew (typically 5 minutes). Reject assertions with not-before timestamps in the future or not-on-or-after timestamps in the past.

Replay Protection: Maintain a cache of consumed assertion IDs with their expiration times. Reject assertions with IDs that have already been processed. Use a sliding window or Bloom filter for high-volume systems.

Secure Metadata Exchange: Always serve SAML metadata over HTTPS with valid certificates. Sign your metadata files and verify signatures when consuming partner metadata. Implement metadata refresh with validation.

Attribute-Based Access Control: Don't just validate authentication status. Check SAML attributes for MFA status, user roles, and authorization decisions. Implement defense in depth by verifying claims server-side rather than trusting client assertions.

Monitoring and Alerting: Log SAML authentication failures with sufficient context for investigation. Monitor for patterns like repeated failed validations, unusual assertion replay attempts, or clock skew anomalies.

Testing with middleBrick: middleBrick's SAML security checks can identify common misconfigurations like missing signature validation, XXE vulnerabilities, and improper audience restriction handling. The scanner tests your SAML endpoints against the 12 security categories, providing a risk score and actionable findings to guide your hardening efforts.