SAMLReader Component

Properties   Methods   Events   Config 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> 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 component with short descriptions. Click on the links for further details.

Method List

---

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

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.

Config Settings

---

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

Artifact Property (SAMLReader Component)

Provides access to SAML artifact object.

Syntax

property Artifact: TsbxSAMLArtifact read get_Artifact;

Remarks

Use this property to access the parameters of the Artifact object from the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLArtifact type for a complete list of fields.

ArtifactResolveQuery Property (SAMLReader Component)

Returns the content of the ArtifactResolve query.

Syntax

property ArtifactResolveQuery: String read get_ArtifactResolveQuery;

Default Value

''

Remarks

Check this property if InputType is set to cstyArtifactResolve to access the content of the ArtifactResolve query.

This property is read-only and not available at design time.

AssertionCount Property (SAMLReader Component)

Returns the number of assertions in the SAML message.

Syntax

property AssertionCount: Integer read get_AssertionCount;

Default Value

0

Remarks

Check this property to retrieve the number of assertions contained in the SAML message.

This property is read-only and not available at design time.

AssertionIDRequest Property (SAMLReader Component)

Provides access to parameters of AssertionIDRequest element of the message.

Syntax

property AssertionIDRequest: TsbxSAMLAssertionIDRequest read get_AssertionIDRequest;

Remarks

Use this property to access the parameters of AssertionIDRequest element. Check this property if InputType is returned as cstyAssertionIDRequest, which indicates that the message contains the relevant element.

This property is read-only and not available at design time.

Please refer to the SAMLAssertionIDRequest type for a complete list of fields.

AttrQueryAttributes Property (SAMLReader Component)

Use this property to access the attribute query element of the message.

Syntax

property AttrQueryAttributes: TsbxSAMLAttributeList read get_AttrQueryAttributes;

Remarks

Check this property if InputType is set to cstyAttributeQuery to access the attribute query element of the message.

This property is read-only and not available at design time.

Please refer to the SAMLAttribute type for a complete list of fields.

AuthnQuery Property (SAMLReader Component)

Use this property to access the AuthnQuery element of the SAML message.

Syntax

property AuthnQuery: TsbxSAMLAuthnQuery read get_AuthnQuery;

Remarks

Check this property if InputType is set to cstyAuthnQuery to access the parameters of the AuthnQuery element of the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLAuthnQuery type for a complete list of fields.

AuthnRequest Property (SAMLReader Component)

Use this property to access the AuthnRequest element of the SAML message.

Syntax

property AuthnRequest: TsbxSAMLAuthnRequest read get_AuthnRequest;

Remarks

Check this property if InputType is set to cstyAuthnRequest to access the AuthnRequest element of the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLAuthnRequest type for a complete list of fields.

AuthnRequestConditions Property (SAMLReader Component)

Provides access to the AuthnRequest condition collection.

Syntax

property AuthnRequestConditions: TsbxSAMLAssertionConditionList read get_AuthnRequestConditions;

Remarks

Use this property if InputType is set to cstyAuthnRequest to access the collection of AuthnRequest condition objects.

This property is read-only and not available at design time.

Please refer to the SAMLAssertionCondition type for a complete list of fields.

AuthnRequestScopingIDPList Property (SAMLReader Component)

Provides access to the AuthnRequest scoping IDP list.

Syntax

property AuthnRequestScopingIDPList: TsbxSAMLIDPEntryList read get_AuthnRequestScopingIDPList;

Remarks

Use this property if InputType is set to cstyAuthnRequest to access the scoping IDP list.

This property is read-only and not available at design time.

Please refer to the SAMLIDPEntry type for a complete list of fields.

AuthzDecisionQuery Property (SAMLReader Component)

Check this property to access the AuthzDecisionQuery element of the SAML message.

Syntax

property AuthzDecisionQuery: TsbxSAMLAuthzDecisionQuery read get_AuthzDecisionQuery;

Remarks

Use this property if InputType is set to cstyAuthzDecisionQuery to access the AuthzDecisionQuery element.

This property is read-only and not available at design time.

Please refer to the SAMLAuthzDecisionQuery type for a complete list of fields.

Binding Property (SAMLReader Component)

Returns the SAML message binding type.

Syntax

property Binding: TsbxSAMLBindingTypes read get_Binding;

TsbxSAMLBindingTypes = (
  csbtNone,
  csbtSOAP,
  csbtPAOS,
  csbtRedirect,
  csbtPOST,
  csbtArtifact
);

Default Value

csbtNone

Remarks

Check this property to obtain the message binding type.

This property is read-only.

BlockedCertificates Property (SAMLReader Component)

The certificates that must be rejected as trust anchors.

Syntax

property BlockedCertificates: TsbxCertificateList read get_BlockedCertificates write set_BlockedCertificates;

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ChainValidationDetails Property (SAMLReader Component)

The details of a certificate chain validation outcome.

Syntax

property ChainValidationDetails: Integer read get_ChainValidationDetails;

Default Value

0

Remarks

Use the value(s) returned by this property to identify the reasons that contributed to the overall validation result.

Returns a bit mask of the following options:

This property is read-only and not available at design time.

ChainValidationResult Property (SAMLReader Component)

The general outcome of a certificate chain validation routine. Use ChainValidationDetails to get information about the reasons that contributed to the validation result.

Syntax

property ChainValidationResult: TsbxChainValidities read get_ChainValidationResult;

TsbxChainValidities = (
  cvtValid,
  cvtValidButUntrusted,
  cvtInvalid,
  cvtCantBeEstablished
);

Default Value

cvtValid

Remarks

Available options:

Use the ValidationLog property to access the detailed validation log.

This property is read-only and not available at design time.

Consent Property (SAMLReader Component)

Returns the Consent parameter of the SAML message.

Syntax

property Consent: String read get_Consent;

Default Value

''

Remarks

Check this property to access the value of the Consent parameter of the processed SAML message.

This property is read-only and not available at design time.

DecryptionCertificate Property (SAMLReader Component)

Specifies a decryption certificate.

Syntax

property DecryptionCertificate: TsbxCertificate read get_DecryptionCertificate write set_DecryptionCertificate;

Remarks

Use this property to pass a certificate that should be used to decrypt the encrypted SAML message. The certificate must contain an associated private key.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Destination Property (SAMLReader Component)

Returns the Destination parameter of the SAML message.

Syntax

property Destination: String read get_Destination;

Default Value

''

Remarks

Check this property to access the Destination parameter of the SAML message.

This property is read-only and not available at design time.

FIPSMode Property (SAMLReader Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

ID Property (SAMLReader Component)

Returns the ID of the processed message.

Syntax

property ID: String read get_ID;

Default Value

''

Remarks

Use this property to get the SAML ID value of the message.

This property is read-only and not available at design time.

IgnoreChainValidationErrors Property (SAMLReader Component)

Makes the component tolerant to chain validation errors.

Syntax

property IgnoreChainValidationErrors: Boolean read get_IgnoreChainValidationErrors write set_IgnoreChainValidationErrors;

Default Value

false

Remarks

If this property is set to True, any errors emerging during certificate chain validation will be ignored. This setting may be handy if the purpose of validation is the creation of an LTV signature, and the validation is performed in an environment that doesn't trust the signer's certificate chain.

InputType Property (SAMLReader Component)

Returns the type of the processed message.

Syntax

property InputType: TsbxSAMLContentTypes read get_InputType;

TsbxSAMLContentTypes = (
  cstyNone,
  cstyAssertionIDRequest,
  cstySubjectQuery,
  cstyAuthnQuery,
  cstyAttributeQuery,
  cstyAuthzDecisionQuery,
  cstyAuthnRequest,
  cstyManageNameIDRequest,
  cstyLogoutRequest,
  cstyNameIDMappingRequest,
  cstyArtifactResolve,
  cstyResponse
);

Default Value

cstyNone

Remarks

Check this property on the early stage of message processing to find out the type of the data contained in the SAML message.

This property is read-only and not available at design time.

InputTypeString Property (SAMLReader Component)

Returns the type of the processed message, as an original string.

Syntax

property InputTypeString: String read get_InputTypeString;

Default Value

''

Remarks

Check this property to find out the content type of the data stored in the processed message. This returns a string originally included in the SAML message, which may be helpful when processing non-standard types.

Known SAML content types are:

• AssertionIDRequest
• SubjectQuery
• AuthnQuery
• AttributeQuery
• AuthzDecisionQuery
• AuthnRequest
• ManageNameIDRequest
• NameIDMappingRequest
• LogoutRequest
• ArtifactResolve
• Response
• LogoutResponse
• ArtifactResponse
• NameIDMappingResponse

This property is read-only and not available at design time.

InResponseTo Property (SAMLReader Component)

Returns the in-response-to parameter of the message.

Syntax

property InResponseTo: String read get_InResponseTo;

Default Value

''

Remarks

Check this property to obtain the In-Response-To parameter of the SAML message.

This property is read-only and not available at design time.

IssueInstant Property (SAMLReader Component)

Returns the issue time of the message.

Syntax

property IssueInstant: String read get_IssueInstant;

Default Value

''

Remarks

Check this property to obtain the issuing time of the SAML message.

This property is read-only and not available at design time.

Issuer Property (SAMLReader Component)

Returns the issuer of the message.

Syntax

property Issuer: String read get_Issuer;

Default Value

''

Remarks

Check this property to obtain the SAML ID of the issuer of the processed message.

This property is read-only and not available at design time.

KnownCertificates Property (SAMLReader Component)

Additional certificates for chain validation.

Syntax

property KnownCertificates: TsbxCertificateList read get_KnownCertificates write set_KnownCertificates;

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

KnownCRLs Property (SAMLReader Component)

Additional CRLs for chain validation.

Syntax

property KnownCRLs: TsbxCRLList read get_KnownCRLs write set_KnownCRLs;

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the CRL type for a complete list of fields.

KnownOCSPs Property (SAMLReader Component)

Additional OCSP responses for chain validation.

Syntax

property KnownOCSPs: TsbxOCSPResponseList read get_KnownOCSPs write set_KnownOCSPs;

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

LogoutRequest Property (SAMLReader Component)

Use this property to access the LogoutRequest element of the SAML message.

Syntax

property LogoutRequest: TsbxSAMLLogoutRequest read get_LogoutRequest;

Remarks

Check this property if InputType is set to cstyLogoutRequest to access the LogoutRequest element of the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLLogoutRequest type for a complete list of fields.

ManageNameIDRequest Property (SAMLReader Component)

Use this property to access the ManageNameIDRequest element of the SAML message.

Syntax

property ManageNameIDRequest: TsbxSAMLManageNameIDRequest read get_ManageNameIDRequest;

Remarks

Check this property if InputType is set to cstyManageNameIDRequest to access the ManageNameIDRequest element of the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLManageNameIDRequest type for a complete list of fields.

NameIDMappingRequest Property (SAMLReader Component)

Use this property to access the NameIDMappingRequest element of the SAML message.

Syntax

property NameIDMappingRequest: TsbxSAMLNameIDMappingRequest read get_NameIDMappingRequest;

Remarks

Use this property if InputType is set to cstyNameIDMappingRequest to access the details of the NameIDMappingRequest element of the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLNameIDMappingRequest type for a complete list of fields.

OfflineMode Property (SAMLReader Component)

Switches the component to offline mode.

Syntax

property OfflineMode: Boolean read get_OfflineMode write set_OfflineMode;

Default Value

false

Remarks

When working in offline mode, the component restricts itself from using any online revocation information sources, such as CRL or OCSP responders.

Offline mode may be useful if there is a need to verify the completeness of the validation information included within the signature or provided via KnownCertificates, KnownCRLs, and other related properties.

PinnedAssertionAttributes Property (SAMLReader Component)

Contains a list of attributes included in the pinned assertion.

Syntax

property PinnedAssertionAttributes: TsbxSAMLAttributeList read get_PinnedAssertionAttributes;

Remarks

Use this property to access the list of attributes included in the pinned assertion. Pin an assertion using PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

Please refer to the SAMLAttribute type for a complete list of fields.

PinnedAssertionConditions Property (SAMLReader Component)

Contains a list of conditions included in the pinned assertion.

Syntax

property PinnedAssertionConditions: TsbxSAMLAssertionConditionList read get_PinnedAssertionConditions;

Remarks

Use this property to access the list of conditions included in the pinned assertion. Pin an assertion using PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

Please refer to the SAMLAssertionCondition type for a complete list of fields.

PinnedAssertionInfo Property (SAMLReader Component)

Contains information about the pinned assertion.

Syntax

property PinnedAssertionInfo: TsbxSAMLAssertionInfo read get_PinnedAssertionInfo;

Remarks

Check this property to access the details of the assertion pinned with PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

Please refer to the SAMLAssertionInfo type for a complete list of fields.

PinnedAssertionIssuer Property (SAMLReader Component)

Returns the pinned assertion issuer.

Syntax

property PinnedAssertionIssuer: String read get_PinnedAssertionIssuer;

Default Value

''

Remarks

Check this property to access the SAML ID of the issuer of the assertion previously pinned with PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

PinnedAssertionStatements Property (SAMLReader Component)

Provides the details of statements included with the assertion.

Syntax

property PinnedAssertionStatements: TsbxSAMLAssertionStatementList read get_PinnedAssertionStatements;

Remarks

Use this property to access the statements included in the assertion previously pinned with PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

Please refer to the SAMLAssertionStatement type for a complete list of fields.

PinnedAssertionSubjectConfirmations Property (SAMLReader Component)

Contains the details of subject confirmations included with the assertion.

Syntax

property PinnedAssertionSubjectConfirmations: TsbxSAMLSubjectConfirmationList read get_PinnedAssertionSubjectConfirmations;

Remarks

Check this property to access the subject confirmations included in the assertion previously pinned with PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

Please refer to the SAMLSubjectConfirmation type for a complete list of fields.

PinnedAssertionSubjectID Property (SAMLReader Component)

Returns the pinned assertion subject.

Syntax

property PinnedAssertionSubjectID: String read get_PinnedAssertionSubjectID;

Default Value

''

Remarks

Check this property to access the SAML ID of the subject of the assertion previously pinned with PinAssertion or PinAdviceAssertion method.

This property is read-only and not available at design time.

POSTBinding Property (SAMLReader Component)

Provides access to the details of the POST binding.

Syntax

property POSTBinding: TsbxSAMLPOSTBinding read get_POSTBinding;

Remarks

Check this property to access the details of the POST binding. Use Binding property to obtain the type of binding used in the SAML message.

This property is read-only and not available at design time.

Please refer to the SAMLPOSTBinding type for a complete list of fields.

Profile Property (SAMLReader Component)

Specifies a pre-defined profile to apply when creating the signature.

Syntax

property Profile: String read get_Profile write set_Profile;

Default Value

''

Remarks

Advanced signatures come in many variants, which are often defined by parties that needs to process them or by local standards. SecureBlackbox profiles are sets of pre-defined configurations which correspond to particular signature variants. By specifying a profile, you are pre-configuring the component to make it produce the signature that matches the configuration corresponding to that profile.

Proxy Property (SAMLReader Component)

The proxy server settings.

Syntax

property Proxy: TsbxProxySettings read get_Proxy;

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Please refer to the ProxySettings type for a complete list of fields.

RedirectBinding Property (SAMLReader Component)

Provides the details of the Redirect binding.

Syntax

property RedirectBinding: TsbxSAMLRedirectBinding read get_RedirectBinding;

Remarks

Use this property to get the details of the redirect binding. Check the binding type using the Binding property.

This property is read-only and not available at design time.

Please refer to the SAMLRedirectBinding type for a complete list of fields.

RedirectBindingCertificate Property (SAMLReader Component)

Sets the certificate for validating the signature over the redirect binding.

Syntax

property RedirectBindingCertificate: TsbxCertificate read get_RedirectBindingCertificate write set_RedirectBindingCertificate;

Remarks

Use this property to provide the certificate to be used for validating the redirect binding signature.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Response Property (SAMLReader Component)

Use this property to access the details of the SAML response element.

Syntax

property Response: TsbxSAMLResponse read get_Response;

Remarks

Check this property if InputType is set to cstyResponse to access the details of the SAML response element.

This property is read-only and not available at design time.

Please refer to the SAMLResponse type for a complete list of fields.

SignatureValidationResult Property (SAMLReader Component)

Contains the signature validation result.

Syntax

property SignatureValidationResult: TsbxXMLSignatureValidities read get_SignatureValidationResult;

TsbxXMLSignatureValidities = (
  xsvValid,
  xsvUnknown,
  xsvCorrupted,
  xsvSignerNotFound,
  xsvFailure,
  xsvReferenceCorrupted
);

Default Value

xsvValid

Remarks

Use this property to check the result of the most recent XML signature validation.

This property is read-only and not available at design time.

Signed Property (SAMLReader Component)

Returns true it the message is signed.

Syntax

property Signed: Boolean read get_Signed;

Default Value

false

Remarks

Check this property to find out whether the SAML entity is signed.

This property is read-only and not available at design time.

SigningCertificate Property (SAMLReader Component)

The certificate of the signature creator.

Syntax

property SigningCertificate: TsbxCertificate read get_SigningCertificate;

Remarks

Use this property to access the certificate that was used to create the signature.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

SocketSettings Property (SAMLReader Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

SubjectConfirmations Property (SAMLReader Component)

Returns a list of subject confirmations from the SubjectQuery element.

Syntax

property SubjectConfirmations: TsbxSAMLSubjectConfirmationList read get_SubjectConfirmations;

Remarks

Check this property when processing a SubjectQuery message (InputType set to cstySubjectQuery) to access the list of subject confirmations.

This property is read-only and not available at design time.

Please refer to the SAMLSubjectConfirmation type for a complete list of fields.

SubjectID Property (SAMLReader Component)

Returns the subject of the message.

Syntax

property SubjectID: String read get_SubjectID;

Default Value

''

Remarks

Check this property to obtain the SAML ID of the message subject.

This property is read-only and not available at design time.

TLSSettings Property (SAMLReader Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

TrustedCertificates Property (SAMLReader Component)

A list of trusted certificates for chain validation.

Syntax

property TrustedCertificates: TsbxCertificateList read get_TrustedCertificates write set_TrustedCertificates;

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

UseBinding Property (SAMLReader Component)

Enables or disables automated binding processing.

Syntax

property UseBinding: Boolean read get_UseBinding write set_UseBinding;

Default Value

false

Remarks

This property controls whether component should process any known bindings it encounters in the message automatically. If using this property, check Binding property to establish the type of the binding processed, and POSTBinding and RedirectBinding to access the properties of specific binding types.

This property is not available at design time.

ValidateSignatures Property (SAMLReader Component)

Enables or disables automated signature validation.

Syntax

property ValidateSignatures: Boolean read get_ValidateSignatures write set_ValidateSignatures;

Default Value

true

Remarks

Use this property to enable or disable automated signature validation by the component.

This property is not available at design time.

ValidationLog Property (SAMLReader Component)

Contains the complete log of the certificate validation routine.

Syntax

property ValidationLog: String read get_ValidationLog;

Default Value

''

Remarks

Use this property to access the chain validation log produced by the component. The log can be very useful when investigating issues with chain validation, as it contains a step-by-step trace of the entire validation procedure.

This property is read-only and not available at design time.

ValidationMoment Property (SAMLReader Component)

The time point at which chain validity is to be established.

Syntax

property ValidationMoment: String read get_ValidationMoment write set_ValidationMoment;

Default Value

''

Remarks

Use this property to specify the moment in time at which chain validity should be established. The time is in UTC. Leave the setting empty to stick to the current moment.

The validity of the same chain may differ depending on the time point chosen due to temporal changes in subchain validities and revocation statuses.

Version Property (SAMLReader Component)

Returns SAML content version string.

Syntax

property Version: String read get_Version;

Default Value

''

Remarks

Check this property to read the SAML content version string, such as "2.0".

This property is read-only and not available at design time.

CompareIDs Method (SAMLReader Component)

Compares two SAML IDs.

Syntax

function CompareIDs(ID1: String; ID2: String): Boolean;

Remarks

Use this utility function to easily compare two SAML IDs.

Config Method (SAMLReader Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (SAMLReader Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

GetIDProp Method (SAMLReader Component)

Extracts a specific property from a SAML ID.

Syntax

function GetIDProp(ID: String; PropName: String): String;

Remarks

Use this method to recover a single ID property from a SAML ID.

PropName supports the following properties:

• Format
• NameQualifier
• IDType
• SPNameQualifier
• SPProvidedID
• Value

Open Method (SAMLReader Component)

Opens a SAML entity.

Syntax

procedure Open(Input: String);

Remarks

Use this method to process a SAML entity contained in a string.

OpenBytes Method (SAMLReader Component)

Opens a SAML entity.

Syntax

procedure OpenBytes(InputBytes: TBytes);

Remarks

Use this method to process a SAML entity stored as a byte array.

OpenFile Method (SAMLReader Component)

Opens a SAML entity.

Syntax

procedure OpenFile(InputFile: String);

Remarks

Use this method to process a SAML entity contained in a file.

OpenStream Method (SAMLReader Component)

Opens a SAML entity contained in a stream.

Syntax

procedure OpenStream(InStrm: TStream);

Remarks

Use this method to process a SAML entity contained in a stream.

PinAdviceAssertion Method (SAMLReader Component)

Pins advice assertion by propagating it in PinnedAssertionXXX properties.

Syntax

procedure PinAdviceAssertion(AssertionIndex: Integer; AdviceAssertionIndex: Integer);

Remarks

Call this method to pin the advice assertion specified by AssertionIndex by publishing it in the selection of PinnedAssertionXXX properties, such as PinnedAssertionInfo. Use AdviceAssertionIndex to specify the advice assertion index.

PinAssertion Method (SAMLReader Component)

Pins assertion by propagating it in PinnedAssertionXXX properties.

Syntax

procedure PinAssertion(AssertionIndex: Integer);

Remarks

Use this method to pin a SAML assertion specified by its AssertionIndex in the selection of PinnedAssertionXXX properties, such as PinnedAssertionInfo.

Check AssertionCount to obtain the number of assertions in the message.

Error Event (SAMLReader Component)

Fires to report an error condition.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

Subscribe to this event to be notified about any error conditions occurring during the component's work. ErrorCode and Description provide the details of the error.

Notification Event (SAMLReader Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

SignatureFound Event (SAMLReader Component)

Signifies the start of signature validation.

Syntax

type TSignatureFoundEvent = procedure (
  Sender: TObject;
  const IssuerRDN: String;
  SerialNumber: TBytes;
  SubjectKeyID: TBytes;
  CertFound: Boolean;
  var ValidateSignature: Boolean;
  var ValidateChain: Boolean
) of Object;

property OnSignatureFound: TSignatureFoundEvent read FOnSignatureFound write FOnSignatureFound;

Remarks

This event tells the application that signature validation is about to start, and provides the details about the signer's certificate via its IssuerRDN, SerialNumber, and SubjectKeyID parameters. It fires for every signature located in the verified document or message.

The CertFound parameter is set to True if the component has found the needed certificate in one of the known locations, and to False otherwise, in which case you must provide it manually via the KnownCertificates property.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. Separate validation results are reported for each, with the SignatureValidationResult and ChainValidationResult properties respectively.

Use the ValidateSignature and ValidateChain parameters to tell the verifier which stages to include in the validation.

SignatureValidated Event (SAMLReader Component)

Reports the signature validation result.

Syntax

type TSignatureValidatedEvent = procedure (
  Sender: TObject;
  const IssuerRDN: String;
  SerialNumber: TBytes;
  SubjectKeyID: TBytes;
  ValidationResult: Integer
) of Object;

property OnSignatureValidated: TSignatureValidatedEvent read FOnSignatureValidated write FOnSignatureValidated;

Remarks

This event is fired when the complete XML signature validation process is finished. IssuerRDN returns the name of the signature issuer, SerialNumber identifies the signing certificate, SubjectKeyID contains the key identifier (SecureBlackbox uses SHA-1 hash algorithm output as key identifiers). Finally, ValidationResult specifies whether signature is valid or not:

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

>

constructor Create();

Creates an empty CRL object.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

>

constructor Create();

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

>

constructor Create();

Creates a new ProxySettings object.

SAMLArtifact Type

Represents a SAML Artifact entity.

Remarks

This type is a container for a SAML Artifact entity. A SAML artifact consists of a TypeCode, an EndpointIndex, and a RemainingArtifact, which contains the body of the artifact and varies depending on the TypeCode.

Fields

Constructors

>

constructor Create();

Creates a new SAMLArtifact object.

SAMLAssertionCondition Type

Represents a SAML assertion Condition parameter.

Remarks

This type is a container for a single Condition parameter of a SAML assertion.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAssertionCondition object.

SAMLAssertionIDRequest Type

Represents a SAML AssertionIDRequest object.

Remarks

This type is a container for a SAML AssertionIDRequest element. This element is used to request assertions by their IDs.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAssertionIDRequest object.

SAMLAssertionInfo Type

Contains information about a SAML assertion.

Remarks

Use this type to get general information about a SAML assertion.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAssertionInfo object.

SAMLAssertionStatement Type

Represents an assertion statement.

Remarks

This type is a container for an assertion statement.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAssertionStatement object.

SAMLAttribute Type

A container for the SAML attribute object.

Remarks

This type is a container for the SAML attribute object.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAttribute object.

SAMLAuthnQuery Type

A container for AuthnQuery element.

Remarks

This type is a container for SAML AuthnQuery element, which represents an authentication event query.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAuthnQuery object.

SAMLAuthnRequest Type

Represents a SAML AuthnRequest object.

Remarks

This type represents a SAML AuthnRequest object. An AuthnRequest is sent by a principal to the identity provider when it needs to request an assertion containing an authentication statement.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAuthnRequest object.

SAMLAuthzDecisionQuery Type

Represents SAML AuthzDecisionQuery element.

Remarks

This type is a container for SAML AuthzDecisionQuery type.

Fields

Constructors

>

constructor Create();

Creates a new SAMLAuthzDecisionQuery object.

SAMLIDPEntry Type

Represents a single identity provider information.

Remarks

This type is a container of single identity provider-specific details.

Fields

Constructors

>

constructor Create();

Creates a new SAMLIDPEntry object.

SAMLLogoutRequest Type

Represents SAML LogoutRequest element.

Remarks

This type is a container for SAML LogoutRequest element.

Fields

Constructors

>

constructor Create();

Creates a new SAMLLogoutRequest object.

SAMLManageNameIDRequest Type

Represents a SAML ManageNameIDRequest element.

Remarks

This type is a container for ManageNameIDRequest element.

Fields

Constructors

>

constructor Create();

Creates a new SAMLManageNameIDRequest object.

SAMLNameIDMappingRequest Type

Represents SAML NameIDMappingRequest element.

Remarks

This type is a container for NameIDMappingRequest element.

Fields

Constructors

>

constructor Create();

Creates a new SAMLNameIDMappingRequest object.

SAMLPOSTBinding Type

Contains the details of the POST binding.

Remarks

This type provides access to properties of POST binding.

Fields

Constructors

>

constructor Create();

Creates a new SAMLPOSTBinding object.

SAMLRedirectBinding Type

Contains parameters of SAML Redirect binding.

Remarks

This type is a container for properties of SAML Redirect binding mechanism.

Fields

Constructors

>

constructor Create();

Creates a new SAMLRedirectBinding object.

SAMLResponse Type

Represents a SAML response.

Remarks

This is a container for SAML response parameters.

Fields

Constructors

>

constructor Create();

Creates a new SAMLResponse object.

SAMLSubjectConfirmation Type

Represents SAML SubjectConfirmation element.

Remarks

This type is a container for SAML SubjectConfirmating element.

Fields

Constructors

>

constructor Create();

Creates a new SAMLSubjectConfirmation object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

>

constructor Create();

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

>

constructor Create();

Creates a new TLSSettings object.

Config Settings (SAMLReader Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

SAMLReader Config Settings

Base Config Settings

Trappable Errors (SAMLReader Component)