SAMLReader Component
Properties Methods Events Configuration Settings Errors
The SAMLReader component offers SAML message processing functionality.
Syntax
TsbxSAMLReader
Remarks
SAMLReader provides means for processing of SAML protocol messages and extraction of their elements. Together with SAMLWriter it provides fine-grained access to the contents of SAML messages. You may consider using these classes if functionality offered by SAMLIdPServer and SAMLSPServer is too high a level for your usage scenario.
SAMLReader and SAMLWriter are independent of SAML server controls, and focus on scenarios that require lower-level access to SAML messaging.
SAMLReader can process the following types of SAML messages:
- AssertionIDRequest
- SubjectQuery
- AuthnQuery
- AttributeQuery
- AuthzDecisionQuery
- AuthnRequest
- ManageNameIDRequest
- LogoutRequest
- NameIDMappingRequest
- ArtifactResolve
- Response
Pass your SAML message to Open (or OpenStream) method. Upon processing, component will populate the elements of the message in the properties, such as InputType or Issuer. More complex elements, such as assertions, require pinning with PinAssertion method to be populated in the object properties.
The snippet below shows how to use SAMLReader to process a message of the AuthnRequest type created by the
matching SAMLReader example (or by any compatible SAML endpoint). The input SAML message has the following look:
<samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="53GhrzQ5f89fu214ANAR" Version="2.0" IssueInstant="2021-12-15T10:39:31Z" Destination="http://destination-url.com" IsPassive="false" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="https://assertion-consumer-url.com" AttributeConsumingServiceIndex="1" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"> <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://issuer-url.com</saml:Issuer> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/> <ds:Reference URI="#53GhrzQ5f89fu214ANAR"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><ds:DigestValue>+xhhgXtwYN0/r9h7WAwg=</ds:DigestValue> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue> jfYeIq/z8D1tJZYbVqDMoqKpdrfGMj8/zI7gbUsJbECAr00cN34md2QG0mo4cOx7pny+5 Tht7tUzqENHqcZdmlOcZc2JcJqokVxIcLEluFiWKlNjpexkXFQKzOC1peRfTZm8SQTqtP Cz8IknLUc6Scfml29PHmks1PxjJDteGb/+FggsZRTGZC3a05nvH3ayvHukPeHuHssx5dX nj0quT8salR6fdx6lAJo/AnDHzcfBNyxAMn+ebk5VOOgVD1L3PayvXib/maj8aVI2I5UT o4vmfybTWKzeS8DX9We7UV+4Xowwe647t1A912xLVub/e23A18Yf1V0PXC87kttTkA== </ds:SignatureValue> <ds:KeyInfo> <ds:X509Data><ds:X509Certificate> MIIEKDCCAxCgAwIBAgIFYA3A3gIwDQYJKoZIhvcNAQELBQAwfjELMAkGA1UEBhMCVVMxC zAJBgNVBAgTAk5DMRQwEgYDVQQHEwtDaGFwZWwgSGlsbDEiMCAGCSqGSIb3DQEJARMTc2 FsZXNAbnNvZnR3YXJlLmNvbTEoMCYGA1UEAxMfU2VjdXJlQmxhY2tib3ggRGVtbyBDZXJ 0aWZpY2F0ZTAeFw0xNzA5MDEwMDAwMDBaFw0yMjA5MDEwMDAwMDBaMH4xCzAJBgNVBAYT AlVTMQswCQYDVQQIEwJOQzEUMBIGA1UEBxMLQ2hhcGVsIEhpbGwxIjAgBgkqhkiG9w0BC QETE3NhbGVzQG5zb2Z0d2FyZS5jb20xKDAmBgNVBAMTH1NlY3VyZUJsYWNrYm94IERlbW 8gQ2VydGlmaWNhdGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCfAVIcq9o eoIbw56LsPjxWsX3YGkqasBQzgQymhfcDZeSvFKFis8iqArGLTUUWOaImO5t2UmjIa+4n YP39hb9Z1r0CMy53p83oYbbZZ7qMeji0pMAufJHqKCN8t2HNWf2HE8S9UOU7R/UHdrSAN JitBKV9lSG9f450yWoGNwt35ZCsOp0zqtCgvkEvteGsz01R5DDjOccs3QNu25K/Sf27KP CYabS6A1ehYNY/G32qoKNJhu3DN4bWje57gBWi9WSfQ3tZUOV5q2ozaNJA78Wl4fXC6RB CaBh0GOwXeyZoH13LJdn+lqlCSMz024ImG4yFQEENbWvE9Elku8RYTn73AgMBAAGjgaww gakwHwYDVR0jBBgwFoAUmt/L7GI1SH36Sp8EUBxTwuzSgqMwHQYDVR0OBBYEFJrfy+xiN Uh9+kqfBFAcU8Ls0oKjMA8GA1UdEwEB/wQFMAMBAf8wDwYDVR0PAQH/BAUDAwDuADBFBg NVHSUEPjA8BggrBgEFBQcDAQYIKwYBBQUHAwIGCCsGAQUFBwMDBggrBgEFBQcDBAYIKwY BBQUHAwgGCCsGAQUFBwMJMA0GCSqGSIb3DQEBCwUAA4IBAQBovHBbMsW/k/5iuLQQqsYS ng5X2iy1W+5BRb1hz0MGnHGLqJWy1ty5+bTo6g/zvT65dXIPIexLkInEenYSy75Lthr6a ewUcvwfl1TYXjWlMD5Nm5pM9As71+XsGSdYGXoKohbEzbT6RDByjwR+yxtatqko7e1Eg6 InNJRTRt7al/63FSPEgSCqOX6asDVDNZ83db0dOcoeaPEiDz3liE3+tYHtKXj5/qwTtYd aqBZxdJfuCKZveEFe1DO3/ayDvIvG9Eme+rEjntErF+Cw9a8ukesvDuT49cRE9oTs3O7f 6LUbhCv5zJN+dTFr75NSdWdp4yvn3nK3i2udeMnTWK0U </ds:X509Certificate></ds:X509Data> </ds:KeyInfo> </ds:Signature> <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"/> <saml:Conditions NotBefore="2021-12-15T10:39:31Z" NotOnOrAfter="2021-12-15T11:09:31Z"><saml:OneTimeUse/></saml:Conditions></samlp:AuthnRequest>Samlreader reader = new Samlreader();reader.ValidateSignatures = true;reader.Open(req);Log("SAML document loaded. The message is of the " + reader.InputTypeString + " type, and was issued by " + reader.Issuer + " at " + reader.IssueInstant + ".");if (reader.InputType == SamlreaderInputTypes.cstyAuthnRequest){ Log("AuthnRequest.ConsumerServiceURL: " + reader.AuthnRequest.AssertionConsumerServiceURL); Log("AuthnRequest.ProtocolBinding: " + reader.AuthnRequest.ProtocolBinding); Log("AuthnRequest.Conditions.NotBefore: " + reader.AuthnRequest.ConditionsNotBefore); Log("AuthnRequest.Conditions.NotAfter: " + reader.AuthnRequest.ConditionsNotOnOrAfter);}if (reader.Signed) { Log("The message was signed by " + reader.SigningCertificate.SubjectRDN); Log("Signature validity: " + reader.SignatureValidationResult.ToString());}Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
| Artifact | Provides access to SAML artifact object. |
| ArtifactResolveQuery | Returns the content of the ArtifactResolve query. |
| AssertionCount | Returns the number of assertions in the SAML message. |
| AssertionIDRequest | Provides access to parameters of AssertionIDRequest element of the message. |
| AttrQueryAttributes | Use this property to access the attribute query element of the message. |
| AuthnQuery | Use this property to access the AuthnQuery element of the SAML message. |
| AuthnRequest | Use this property to access the AuthnRequest element of the SAML message. |
| AuthnRequestConditions | Provides access to the AuthnRequest condition collection. |
| AuthnRequestScopingIDPList | Provides access to the AuthnRequest scoping IDP list. |
| AuthzDecisionQuery | Check this property to access the AuthzDecisionQuery element of the SAML message. |
| Binding | Returns the SAML message binding type. |
| BlockedCertificates | The certificates that must be rejected as trust anchors. |
| ChainValidationDetails | The details of a certificate chain validation outcome. |
| ChainValidationResult | The general outcome of a certificate chain validation routine. Use ChainValidationDetails to get information about the reasons that contributed to the validation result. |
| Consent | Returns the Consent parameter of the SAML message. |
| DecryptionCertificate | Specifies a decryption certificate. |
| Destination | Returns the Destination parameter of the SAML message. |
| ID | Returns the ID of the processed message. |
| IgnoreChainValidationErrors | Makes the component tolerant to chain validation errors. |
| InputType | Returns the type of the processed message. |
| InputTypeString | Returns the type of the processed message, as an original string. |
| InResponseTo | Returns the in-response-to parameter of the message. |
| IssueInstant | Returns the issue time of the message. |
| Issuer | Returns the issuer of the message. |
| KnownCertificates | Additional certificates for chain validation. |
| KnownCRLs | Additional CRLs for chain validation. |
| KnownOCSPs | Additional OCSP responses for chain validation. |
| LogoutRequest | Use this property to access the LogoutRequest element of the SAML message. |
| ManageNameIDRequest | Use this property to access the ManageNameIDRequest element of the SAML message. |
| NameIDMappingRequest | Use this property to access the NameIDMappingRequest element of the SAML message. |
| OfflineMode | Switches the component to the offline mode. |
| PinnedAssertionAttributes | Contains a list of attributes included in the pinned assertion. |
| PinnedAssertionConditions | Contains a list of conditions included in the pinned assertion. |
| PinnedAssertionInfo | Contains information about the pinned assertion. |
| PinnedAssertionIssuer | Returns the pinned assertion issuer. |
| PinnedAssertionStatements | Provides the details of statements included with the assertion. |
| PinnedAssertionSubjectConfirmations | Contains the details of subject confirmations included with the assertion. |
| PinnedAssertionSubjectID | Returns the pinned assertion subject. |
| POSTBinding | Provides access to the details of the POST binding. |
| Profile | Specifies a pre-defined profile to apply when creating the signature. |
| Proxy | The proxy server settings. |
| RedirectBinding | Provides the details of the Redirect binding. |
| RedirectBindingCertificate | Sets the certificate for validating the signature over the redirect binding. |
| Response | Use this property to access the details of the SAML response element. |
| SignatureValidationResult | Contains the signature validation result. |
| Signed | Returns true it the message is signed. |
| SigningCertificate | The certificate of the signature creator. |
| SocketSettings | Manages network connection settings. |
| SubjectConfirmations | Returns a list of subject confirmations from the SubjectQuery element. |
| SubjectID | Returns the subject of the message. |
| TLSSettings | Manages TLS layer settings. |
| TrustedCertificates | A list of trusted certificates for chain validation. |
| UseBinding | Enables or disables automated binding processing. |
| ValidateSignatures | Enables or disables automated signature validation. |
| ValidationLog | Contains the complete log of the certificate validation routine. |
| ValidationMoment | The time point at which chain validity is to be established. |
| Version | Returns SAML content version string. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
| CompareIDs | Compares two SAML IDs. |
| Config | Sets or retrieves a configuration setting. |
| GetIDProp | Extracts a specific property from a SAML ID. |
| Open | Opens a SAML entity. |
| OpenBytes | Opens a SAML entity. |
| OpenFile | Opens a SAML entity. |
| OpenStream | Opens a SAML entity contained in a stream. |
| PinAdviceAssertion | Pins advice assertion by propagating it in PinnedAssertionXXX properties. |
| PinAssertion | Pins assertion by propagating it in PinnedAssertionXXX properties. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
| Error | Fires to report an error condition. |
| Notification | This event notifies the application about an underlying control flow event. |
| SignatureFound | Signifies the start of signature validation. |
| SignatureValidated | Reports the signature validation result. |
Configuration Settings
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
| IgnoreSystemTrust | Whether trusted Windows Certificate Stores should be treated as trusted. |
| TolerateMinorChainIssues | Whether to tolerate minor chain issues. |
| UseMicrosoftCTL | Enables or disables automatic use of Microsoft online certificate trust list. |
| UseSystemCertificates | Enables or disables the use of the system certificates. |
| CheckKeyIntegrityBeforeUse | Enables or disable private key integrity check before use. |
| CookieCaching | Specifies whether a cookie cache should be used for HTTP(S) transports. |
| Cookies | Gets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only). |
| DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
| EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
| GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
| HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
| LogDestination | Specifies the debug log destination. |
| LogDetails | Specifies the debug log details to dump. |
| LogFile | Specifies the debug log filename. |
| LogFilters | Specifies the debug log filters. |
| LogFlushMode | Specifies the log flush mode. |
| LogLevel | Specifies the debug log level. |
| LogMaxEventCount | Specifies the maximum number of events to cache before further action is taken. |
| LogRotationMode | Specifies the log rotation mode. |
| MaxASN1BufferLength | Specifies the maximal allowed length for ASN.1 primitive tag data. |
| MaxASN1TreeDepth | Specifies the maximal depth for processed ASN.1 trees. |
| OCSPHashAlgorithm | Specifies the hash algorithm to be used to identify certificates in OCSP requests. |
| UseOwnDNSResolver | Specifies whether the client components should use own DNS resolver. |
| UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
| UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
| UseSystemRandom | Enables or disables the use of the OS PRNG. |