SecureBlackbox 2020 macOS Edition

Questions / Feedback?

SAMLReader Module

Properties   Methods   Events   Configuration Settings   Errors  

The SAMLReader component offers SAML message processing functionality.

Syntax

nsoftware.SecureBlackbox.Samlreader

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, class 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>
You can process this message and access its properties with the following code:
  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 module with short descriptions. Click on the links for further details.

ArtifactProvides access to SAML artifact object.
ArtifactResolveQueryReturns the content of the ArtifactResolve query.
AssertionCountReturns the number of assertions in the SAML message.
AssertionIDRequestProvides access to parameters of AssertionIDRequest element of the message.
AttrQueryAttributesUse this property to access the attribute query element of the message.
AuthnQueryUse this property to access the AuthnQuery element of the SAML message.
AuthnRequestUse this property to access the AuthnRequest element of the SAML message.
AuthnRequestConditionsProvides access to the AuthnRequest condition collection.
AuthnRequestScopingIDPListProvides access to the AuthnRequest scoping IDP list.
AuthzDecisionQueryCheck this property to access the AuthzDecisionQuery element of the SAML message.
BindingReturns the SAML message binding type.
BlockedCertificatesThe certificates that must be rejected as trust anchors.
ChainValidationDetailsThe details of a certificate chain validation outcome.
ChainValidationResultThe general outcome of a certificate chain validation routine. Use ChainValidationDetails to get information about the reasons that contributed to the validation result.
ConsentReturns the Consent parameter of the SAML message.
DecryptionCertificateSpecifies a decryption certificate.
DestinationReturns the Destination parameter of the SAML message.
IDReturns the ID of the processed message.
IgnoreChainValidationErrorsMakes the component tolerant to chain validation errors.
InputTypeReturns the type of the processed message.
InputTypeStringReturns the type of the processed message, as an original string.
InResponseToReturns the in-response-to parameter of the message.
IssueInstantReturns the issue time of the message.
IssuerReturns the issuer of the message.
KnownCertificatesAdditional certificates for chain validation.
KnownCRLsAdditional CRLs for chain validation.
KnownOCSPsAdditional OCSP responses for chain validation.
LogoutRequestUse this property to access the LogoutRequest element of the SAML message.
ManageNameIDRequestUse this property to access the ManageNameIDRequest element of the SAML message.
NameIDMappingRequestUse this property to access the NameIDMappingRequest element of the SAML message.
OfflineModeSwitches the component to the offline mode.
PinnedAssertionAttributesContains a list of attributes included in the pinned assertion.
PinnedAssertionConditionsContains a list of conditions included in the pinned assertion.
PinnedAssertionInfoContains information about the pinned assertion.
PinnedAssertionIssuerReturns the pinned assertion issuer.
PinnedAssertionStatementsProvides the details of statements included with the assertion.
PinnedAssertionSubjectConfirmationsContains the details of subject confirmations included with the assertion.
PinnedAssertionSubjectIDReturns the pinned assertion subject.
POSTBindingProvides access to the details of the POST binding.
ProfileSpecifies a pre-defined profile to apply when creating the signature.
ProxyThe proxy server settings.
RedirectBindingProvides the details of the Redirect binding.
RedirectBindingCertificateSets the certificate for validating the signature over the redirect binding.
ResponseUse this property to access the details of the SAML response element.
SignatureValidationResultContains the signature validation result.
SignedReturns true it the message is signed.
SigningCertificateThe certificate of the signature creator.
SocketSettingsManages network connection settings.
SubjectConfirmationsReturns a list of subject confirmations from the SubjectQuery element.
SubjectIDReturns the subject of the message.
TLSSettingsManages TLS layer settings.
TrustedCertificatesA list of trusted certificates for chain validation.
UseBindingEnables or disables automated binding processing.
ValidateSignaturesEnables or disables automated signature validation.
ValidationLogContains the complete log of the certificate validation routine.
ValidationMomentThe time point at which chain validity is to be established.
VersionReturns SAML content version string.

Method List


The following is the full list of the methods of the module with short descriptions. Click on the links for further details.

CompareIDsCompares two SAML IDs.
ConfigSets or retrieves a configuration setting.
GetIDPropExtracts a specific property from a SAML ID.
OpenOpens a SAML entity.
OpenBytesOpens a SAML entity.
OpenFileOpens a SAML entity.
PinAdviceAssertionPins advice assertion by propagating it in PinnedAssertionXXX properties.
PinAssertionPins assertion by propagating it in PinnedAssertionXXX properties.

Event List


The following is the full list of the events fired by the module with short descriptions. Click on the links for further details.

ErrorFires to report an error condition.
NotificationThis event notifies the application about an underlying control flow event.
SignatureFoundSignifies the start of signature validation.
SignatureValidatedReports the signature validation result.

Configuration Settings


The following is a list of configuration settings for the module with short descriptions. Click on the links for further details.

IgnoreSystemTrustWhether trusted Windows Certificate Stores should be treated as trusted.
TolerateMinorChainIssuesWhether to tolerate minor chain issues.
UseMicrosoftCTLEnables or disables automatic use of Microsoft online certificate trust list.
UseSystemCertificatesEnables or disables the use of the system certificates.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client components should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 macOS Edition - Version 20.0 [Build 8165]