How to Decrypt a SAML Response in Delphi Using TsbxSAMLReader

Introduction

When working with SAML (Security Assertion Markup Language) responses in Delphi, developers often face challenges due to limited documentation and scarce code examples. Recently, I encountered such difficulties while using nSoftware IPWorks and decided to share a concise code snippet to help others navigate this process.

Prerequisites

To run the provided Delphi code, ensure you have the following units from the nSoftware SecureBlackbox 2022 package:

sbxsamlreader
sbxcertificatemanager
sbxtypes

These units are essential for handling SAML responses and managing certificates within your Delphi application.

Step-by-Step Guide to Decrypting a SAML Response

1. Import Necessary Units

Begin by importing the required units from the SecureBlackbox package:

uses
  sbxsamlreader,
  sbxcertificatemanager,
  sbxtypes;

2. Implement the Decryption Method

Below is a Delphi procedure that demonstrates how to decrypt a SAML response using TsbxSAMLReader:

procedure SAMLTests.ReadSAML;
var
  vReader: TsbxSAMLReader;
  vCertificateManager: TsbxCertificateManager;
  vCertificate: sbxtypes.Tsbxcertificate;
  vAttribute: TsbxSAMLAttribute;
  I: Integer;
begin
  vCertificateManager := TsbxCertificateManager.Create(nil);
  vReader := TsbxSAMLReader.Create(nil);
  try
    // Import the PEM-formatted certificate and private key
    vCertificateManager.ImportFromFile('path_to_certificate.pem', '');
    vCertificateManager.ImportKeyFromFile('path_to_private_key.pem', '');
    
    // Assign the certificate for decryption
    vReader.DecryptionCertificate := vCertificateManager.Certificate;
    
    // Open and parse the SAML response XML
    vReader.Open(TFile.ReadAllText('path_to_saml_response.xml'));
    
    // Check if any assertions are present
    if vReader.AssertionCount > 0 then
    begin
      // Pin the first assertion for processing
      vReader.PinAssertion(0);
      
      // Iterate through the pinned assertion attributes
      for I := 0 to vReader.PinnedAssertionAttributes.Count - 1 do
      begin
        vAttribute := vReader.PinnedAssertionAttributes.Item[I];
        writeln(vAttribute.Name);
        writeln(vAttribute.Values);
      end;
    end;
  finally
    // Clean up resources
    vReader.Free;
    vCertificateManager.Free;
  end;
end;

3. Understanding the Code

Certificate Management: The code begins by creating instances of TsbxCertificateManager and TsbxSAMLReader. It imports the PEM-formatted certificate and private key, which are crucial for decrypting the SAML response. Ensure that the certificate used matches the one the SAML identity provider used to encrypt the response.
Opening the SAML Response: The Open method reads the SAML response from a local XML file (saml_response.xml). After parsing, it checks the AssertionCount to determine if any assertions are present.
Pinning and Accessing Attributes: The first assertion is pinned using PinAssertion(0). This allows access to the PinnedAssertionAttributes, enabling iteration through each attribute to retrieve its name and value.

Important Considerations

Certificate Consistency: For successful decryption, ensure that the PEM certificate and private key used in the code match those used by the SAML identity provider to encrypt the saml_response.xml.
Error Handling: While the provided code includes basic error handling through the try...finally block, consider implementing more robust error management to handle potential issues during file import or XML parsing.

Conclusion

Decrypting SAML responses in Delphi can be streamlined using the TsbxSAMLReader component from nSoftware IPWorks. By following the steps outlined above and ensuring proper certificate management, developers can efficiently handle encrypted SAML assertions within their applications. Sharing this snippet aims to bridge the documentation gap and assist fellow developers in implementing secure SAML authentication flows.