SAML Component

Properties   Methods   Events   Config Settings   Errors  

The SAML component is used to obtain security tokens and assertions.

Syntax

TipaSAML

Remarks

The SAML component provides an easy-to-use interface to obtain security tokens and assertions. The component can also be used to parse assertions and inspect the claims within.

The component has built in support for working with Microsoft SharePoint Online and Microsoft Dynamics CRM Online. This support means only a minimum of information needs to be supplied to the component.

Microsoft SharePoint Online and Dynamics CRM Online

To begin working with SharePoint Online or Dynamics CRM Online first set the AuthMode to the appropriate value. The component will automatically populate several properties to known values. Set the User, Password, ApplicationURN properties and call GetSecurityToken. For instance:

component.AuthMode = SAMLAuthModes.amDynamicsCRM; //dynamic crm component.User = "user@mycrm.onmicrosoft.com"; component.Password = "password"; component.ApplicationURN = "urn:crmapac:dynamics.com"; component.GetSecurityToken(); After calling GetSecurityToken the SecurityTokenXML property will be populated.

ADFS and Others

When working with ADFS or another Security Token Service (STS) the GetAssertion method may be used to obtain an assertion. To begin set AuthMode to either amADFS or amCustom. Then set LocalSTS, User, Password, and ApplicationURN. For instance:

component.AuthMode = SAMLAuthModes.amADFS; component.User = "administrator"; component.Password = "admin"; component.LocalSTS = "https://adfs.contoso.com"; component.ApplicationURN = "https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/"; component.GetAssertion(); If the assertion is signed the component will use the certificate specified in SignerCert to verify the signature. If SignerCert is not set the component will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• AssertionId
• AssertionIssueInstant
• AssertionIssuer
• AssertionNotBefore
• AssertionNotOnOrAfter
• AssertionSubject
• AssertionVersion
• AssertionXML
• Claim* properties

Parsing an Assertion

The component may also be used to parse an existing assertion without contacting a STS. To parse an existing assertion call ParseAssertion with the assertion XML. If the assertion is signed the component will use the certificate specified in SignerCert to verify the signature. If SignerCert is not set the component will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• AssertionId
• AssertionIssueInstant
• AssertionIssuer
• AssertionNotBefore
• AssertionNotOnOrAfter
• AssertionSubject
• AssertionVersion
• AssertionXML
• Claim* properties

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.

ApplicationURN Property (SAML Component)

The application's Uniform Resource Name (URN).

Syntax

property ApplicationURN: String read get_ApplicationURN write set_ApplicationURN;

Default Value

''

Remarks

This property specifies the application's Uniform Resource Name (URN). This must be set before calling GetAssertion or GetSecurityToken.

When AuthMode is set to amDynamicsCRM the value specified here depends on the location of the account. Valid values are:

When AuthMode is set to camSharePointOnline this value is typically the URL to your site. For instance: "https://mycrm.sharepoint.com".

This property is not available at design time.

AssertionId Property (SAML Component)

The assertion id.

Syntax

property AssertionId: String read get_AssertionId;

Default Value

''

Remarks

This property hold the id of the assertion.

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

AssertionIssueInstant Property (SAML Component)

The time in UTC that the assertion was issued.

Syntax

property AssertionIssueInstant: String read get_AssertionIssueInstant;

Default Value

''

Remarks

This property holds the time that the assertion was issued.

This is in the standard xsd:dateTime format "YYYY-MM-DDThh:mm:ss". The date is specified in UTC.

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

AssertionIssuer Property (SAML Component)

The assertion issuer.

Syntax

property AssertionIssuer: String read get_AssertionIssuer;

Default Value

''

Remarks

This property holds the issuer of the assertion.

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

AssertionNotBefore Property (SAML Component)

The date on which the assertion becomes valid.

Syntax

property AssertionNotBefore: String read get_AssertionNotBefore;

Default Value

''

Remarks

This property specifies the earliest time instant at which the assertion is valid.

This is in the standard xsd:dateTime format "YYYY-MM-DDThh:mm:ss". The date is specified in UTC.

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

AssertionNotOnOrAfter Property (SAML Component)

The time at which the assertion expires.

Syntax

property AssertionNotOnOrAfter: String read get_AssertionNotOnOrAfter;

Default Value

''

Remarks

This property specifies the time instant at which the assertion has expired.

This is in the standard xsd:dateTime format "YYYY-MM-DDThh:mm:ss". The date is specified in UTC.

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

AssertionSubject Property (SAML Component)

The subject of the assertion.

Syntax

property AssertionSubject: String read get_AssertionSubject;

Default Value

''

Remarks

This property holds the subject of the assertion.

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

AssertionVersion Property (SAML Component)

The version of the assertion.

Syntax

property AssertionVersion: TipaTAssertionVersions read get_AssertionVersion write set_AssertionVersion;

TipaTAssertionVersions = (
  svSAMLv11,
  svSAMLv20
);

Default Value

svSAMLv11

Remarks

This property specifies the version of the assertion. This may be set before calling GetAssertion. This will be populated after calling ParseAssertion. Possible values are:

This property is not available at design time.

AssertionXML Property (SAML Component)

The assertion XML.

Syntax

property AssertionXML: String read get_AssertionXML;

Default Value

''

Remarks

This property holds the returned assertion. This is populated after calling GetAssertion.

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

AuthMode Property (SAML Component)

The authentication mode.

Syntax

property AuthMode: TipaTAuthModes read get_AuthMode write set_AuthMode;

TipaTAuthModes = (
  camSharePointOnline,
  camDynamicsCRM,
  camADFS,
  camCustom
);

Default Value

camSharePointOnline

Remarks

This property specifies the authentication mode. Possible values are:

When this property is set the component is initialized based on common settings for the selected mode.

Setting this property to 2 (camADFS) or 3 (camCustom) will clear the values in FederationURN, and FederationSTS. There is no functional difference between 2 (camADFS) and 3 (camCustom), they operate identically.

Setting this property to 0 (camSharePointOnline) or 1 (camDynamicsCRM) will populate FederationURN, and FederationSTS with known valid values for FederationURN, and FederationSTS.

The table below shows which properties are set depending on the value of this property.

The value 3 (camCustom) may be used with any STS as long as WS-TRUST is supported.

This property is not available at design time.

CertEncoded Property (SAML Component)

This is the certificate (PEM/base64 encoded).

Syntax

property CertEncoded: String read get_CertEncoded write set_CertEncoded;
property CertEncodedB: TBytes read get_CertEncodedB write set_CertEncodedB;

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

This property is not available at design time.

CertStore Property (SAML Component)

This is the name of the certificate store for the client certificate.

Syntax

property CertStore: String read get_CertStore write set_CertStore;
property CertStoreB: TBytes read get_CertStoreB write set_CertStoreB;

Default Value

'MY'

Remarks

This is the name of the certificate store for the client certificate.

The StoreType property denotes the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject property to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

This property is not available at design time.

CertStorePassword Property (SAML Component)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

property CertStorePassword: String read get_CertStorePassword write set_CertStorePassword;

Default Value

''

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is not available at design time.

CertStoreType Property (SAML Component)

This is the type of certificate store for this certificate.

Syntax

property CertStoreType: TipaCertStoreTypes read get_CertStoreType write set_CertStoreType;

TipaCertStoreTypes = (
  cstUser,
  cstMachine,
  cstPFXFile,
  cstPFXBlob,
  cstJKSFile,
  cstJKSBlob,
  cstPEMKeyFile,
  cstPEMKeyBlob,
  cstPublicKeyFile,
  cstPublicKeyBlob,
  cstSSHPublicKeyBlob,
  cstP7BFile,
  cstP7BBlob,
  cstSSHPublicKeyFile,
  cstPPKFile,
  cstPPKBlob,
  cstXMLFile,
  cstXMLBlob,
  cstJWKFile,
  cstJWKBlob,
  cstSecurityKey,
  cstBCFKSFile,
  cstBCFKSBlob,
  cstPKCS11,
  cstAuto
);

Default Value

cstUser

Remarks

This is the type of certificate store for this certificate.

The component supports both public and private keys in a variety of formats. When the cstAuto value is used the component will automatically determine the type. This property can take one of the following values:

This property is not available at design time.

CertSubject Property (SAML Component)

This is the subject of the certificate used for client authentication.

Syntax

property CertSubject: String read get_CertSubject write set_CertSubject;

Default Value

''

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are displayed below.

If a field value contains a comma it must be quoted.

This property is not available at design time.

Claims Property (SAML Component)

A collection of claims.

Syntax

property Claims: TipaClaimList read get_Claims;

Remarks

This property is a collection of claims parsed from the assertion. This is populated after calling GetAssertion or ParseAssertion.

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

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

FederationSTS Property (SAML Component)

The URL of the federation Security Token Service (STS).

Syntax

property FederationSTS: String read get_FederationSTS write set_FederationSTS;

Default Value

''

Remarks

This property specifies the URL of the federation Security Token Service (STS). When AuthMode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) this property is automatically populated.

This property is not available at design time.

FederationURN Property (SAML Component)

The federation Uniform Resource Name (URN).

Syntax

property FederationURN: String read get_FederationURN write set_FederationURN;

Default Value

''

Remarks

This property specifies the federation Uniform Resource Name (URN). This property is automatically populated when AuthMode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM).

This property is not available at design time.

LocalSTS Property (SAML Component)

The local Security Token Service (STS).

Syntax

property LocalSTS: String read get_LocalSTS write set_LocalSTS;

Default Value

''

Remarks

This property specifies the URL of the local Security Token Service(STS).

When AuthMode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) if this is not specified, then the component will attempt to determine this value automatically by querying the UserRealm.

When AuthMode is set to 2 (camADFS) or 3 (camCustom) this property is required.

This property is not available at design time.

Password Property (SAML Component)

The user's password.

Syntax

property Password: String read get_Password write set_Password;

Default Value

''

Remarks

This property specifies the user's password. This must be set before calling GetAssertion or GetSecurityToken.

This property is not available at design time.

Proxy Property (SAML Component)

This property includes a set of properties related to proxy access.

Syntax

property Proxy: TipaProxy read get_Proxy write set_Proxy;

Remarks

This property contains fields describing the proxy through which the component will attempt to connect.

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

SecurityTokenXML Property (SAML Component)

The security token XML.

Syntax

property SecurityTokenXML: String read get_SecurityTokenXML;

Default Value

''

Remarks

This property holds the security token. This is populated after calling GetSecurityToken.

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

SignerCertEncoded Property (SAML Component)

This is the certificate (PEM/base64 encoded).

Syntax

property SignerCertEncoded: String read get_SignerCertEncoded write set_SignerCertEncoded;
property SignerCertEncodedB: TBytes read get_SignerCertEncodedB write set_SignerCertEncodedB;

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

This property is not available at design time.

SignerCertStore Property (SAML Component)

This is the name of the certificate store for the client certificate.

Syntax

property SignerCertStore: String read get_SignerCertStore write set_SignerCertStore;
property SignerCertStoreB: TBytes read get_SignerCertStoreB write set_SignerCertStoreB;

Default Value

'MY'

Remarks

This is the name of the certificate store for the client certificate.

The StoreType property denotes the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject property to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

This property is not available at design time.

SignerCertStorePassword Property (SAML Component)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

property SignerCertStorePassword: String read get_SignerCertStorePassword write set_SignerCertStorePassword;

Default Value

''

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is not available at design time.

SignerCertStoreType Property (SAML Component)

This is the type of certificate store for this certificate.

Syntax

property SignerCertStoreType: TipaCertStoreTypes read get_SignerCertStoreType write set_SignerCertStoreType;

TipaCertStoreTypes = (
  cstUser,
  cstMachine,
  cstPFXFile,
  cstPFXBlob,
  cstJKSFile,
  cstJKSBlob,
  cstPEMKeyFile,
  cstPEMKeyBlob,
  cstPublicKeyFile,
  cstPublicKeyBlob,
  cstSSHPublicKeyBlob,
  cstP7BFile,
  cstP7BBlob,
  cstSSHPublicKeyFile,
  cstPPKFile,
  cstPPKBlob,
  cstXMLFile,
  cstXMLBlob,
  cstJWKFile,
  cstJWKBlob,
  cstSecurityKey,
  cstBCFKSFile,
  cstBCFKSBlob,
  cstPKCS11,
  cstAuto
);

Default Value

cstUser

Remarks

This is the type of certificate store for this certificate.

The component supports both public and private keys in a variety of formats. When the cstAuto value is used the component will automatically determine the type. This property can take one of the following values:

This property is not available at design time.

SignerCertSubject Property (SAML Component)

This is the subject of the certificate used for client authentication.

Syntax

property SignerCertSubject: String read get_SignerCertSubject write set_SignerCertSubject;

Default Value

''

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are displayed below.

If a field value contains a comma it must be quoted.

This property is not available at design time.

SSLAcceptServerCertEncoded Property (SAML Component)

This is the certificate (PEM/base64 encoded).

Syntax

property SSLAcceptServerCertEncoded: String read get_SSLAcceptServerCertEncoded write set_SSLAcceptServerCertEncoded;
property SSLAcceptServerCertEncodedB: TBytes read get_SSLAcceptServerCertEncodedB write set_SSLAcceptServerCertEncodedB;

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

This property is not available at design time.

SSLCertEncoded Property (SAML Component)

This is the certificate (PEM/base64 encoded).

Syntax

property SSLCertEncoded: String read get_SSLCertEncoded write set_SSLCertEncoded;
property SSLCertEncodedB: TBytes read get_SSLCertEncodedB write set_SSLCertEncodedB;

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

This property is not available at design time.

SSLCertStore Property (SAML Component)

This is the name of the certificate store for the client certificate.

Syntax

property SSLCertStore: String read get_SSLCertStore write set_SSLCertStore;
property SSLCertStoreB: TBytes read get_SSLCertStoreB write set_SSLCertStoreB;

Default Value

'MY'

Remarks

This is the name of the certificate store for the client certificate.

The StoreType property denotes the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject property to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

SSLCertStorePassword Property (SAML Component)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

property SSLCertStorePassword: String read get_SSLCertStorePassword write set_SSLCertStorePassword;

Default Value

''

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

SSLCertStoreType Property (SAML Component)

This is the type of certificate store for this certificate.

Syntax

property SSLCertStoreType: TipaCertStoreTypes read get_SSLCertStoreType write set_SSLCertStoreType;

TipaCertStoreTypes = (
  cstUser,
  cstMachine,
  cstPFXFile,
  cstPFXBlob,
  cstJKSFile,
  cstJKSBlob,
  cstPEMKeyFile,
  cstPEMKeyBlob,
  cstPublicKeyFile,
  cstPublicKeyBlob,
  cstSSHPublicKeyBlob,
  cstP7BFile,
  cstP7BBlob,
  cstSSHPublicKeyFile,
  cstPPKFile,
  cstPPKBlob,
  cstXMLFile,
  cstXMLBlob,
  cstJWKFile,
  cstJWKBlob,
  cstSecurityKey,
  cstBCFKSFile,
  cstBCFKSBlob,
  cstPKCS11,
  cstAuto
);

Default Value

cstUser

Remarks

This is the type of certificate store for this certificate.

The component supports both public and private keys in a variety of formats. When the cstAuto value is used the component will automatically determine the type. This property can take one of the following values:

SSLCertSubject Property (SAML Component)

This is the subject of the certificate used for client authentication.

Syntax

property SSLCertSubject: String read get_SSLCertSubject write set_SSLCertSubject;

Default Value

''

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are displayed below.

If a field value contains a comma it must be quoted.

SSLProvider Property (SAML Component)

This specifies the SSL/TLS implementation to use.

Syntax

property SSLProvider: TipaTSSLProviders read get_SSLProvider write set_SSLProvider;

TipaTSSLProviders = (
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
);

Default Value

sslpAutomatic

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the component will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

Additional Notes

In most cases using the default value (Automatic) is recommended. The component will select a provider depending on the current platform.

When Automatic is selected, on Windows the component will use the platform implementation. On Linux/macOS the component will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used on all platforms.

SSLServerCertEncoded Property (SAML Component)

This is the certificate (PEM/base64 encoded).

Syntax

property SSLServerCertEncoded: String read get_SSLServerCertEncoded;
property SSLServerCertEncodedB: TBytes read get_SSLServerCertEncodedB;

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties also may be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate; otherwise, Subject is set to an empty string.

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

User Property (SAML Component)

The username.

Syntax

property User: String read get_User write set_User;

Default Value

''

Remarks

This property specifies the username. This must be set before calling GetAssertion or GetSecurityToken.

This property is not available at design time.

XAttributes Property (SAML Component)

A collection of attributes of the current element.

Syntax

property XAttributes: TipaXMLAttributeList read get_XAttributes write set_XAttributes;

Remarks

This collection consists of all attributes of the current XML element. The component parses each attribute into a collection of XMLAttribute types.

This property is not available at design time.

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

XChildren Property (SAML Component)

Collection of child elements of the currently selected XML element.

Syntax

property XChildren: TipaXMLElementList read get_XChildren write set_XChildren;

Remarks

This property contains a collection of child elements of the currently selected XML element. The elements are provided in the collection in the same order they are found in the XML document.

This property is not available at design time.

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

XElement Property (SAML Component)

The name of the current element.

Syntax

property XElement: String read get_XElement write set_XElement;

Default Value

''

Remarks

The current element is specified via the XPath property.

XNamespace Property (SAML Component)

The namespace of the current element.

Syntax

property XNamespace: String read get_XNamespace write set_XNamespace;

Default Value

''

Remarks

The current element is specified via the XPath property.

XParent Property (SAML Component)

The parent of the current element.

Syntax

property XParent: String read get_XParent;

Default Value

''

Remarks

The current element is specified via the XPath property.

This property is read-only.

XPath Property (SAML Component)

Provides a way to point to a specific element in the document.

Syntax

property XPath: String read get_XPath write set_XPath;

Default Value

''

Remarks

XPath implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML documents.

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location.

The following are possible values for an element accessor:

When XPath is set to a valid path, XElement points to the name of the element, with XParent, XNamespace, XPrefix, Name, Namespace, Prefix, XText, and XText providing other properties of the element. The attributes of the current element are provided in the Name, Namespace, Prefix, and Value properties.

BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.

Example (Setting XPath):

XPrefix Property (SAML Component)

The prefix of the current element.

Syntax

property XPrefix: String read get_XPrefix write set_XPrefix;

Default Value

''

Remarks

The current element is specified via the XPath property.

XSubTree Property (SAML Component)

A snapshot of the current element in the document.

Syntax

property XSubTree: String read get_XSubTree;

Default Value

''

Remarks

The current element is specified via the XPath property. In order for this property to work you must have the CacheContent set to true.

This property is read-only.

XText Property (SAML Component)

The text of the current element.

Syntax

property XText: String read get_XText write set_XText;

Default Value

''

Remarks

The current element is specified via the XPath property.

Config Method (SAML 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.

GetAssertion Method (SAML Component)

Gets the assertion.

Syntax

procedure GetAssertion();

Remarks

This method communicates with LocalSTS as to obtain an assertion.

When AuthMode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) the component will automatically populate various properties to known values to reduce the number of required settings. Typically only the following properties are required:

• User
• Password
• ApplicationURN

When AuthMode is set to 2 (camADFS) or 3 (camCustom) the following properties are required:

• User
• Password
• ApplicationURN
• LocalSTS

If the assertion is signed the component will use the certificate specified in SignerCert to verify the signature. If SignerCert is not set the component will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• AssertionId
• AssertionIssueInstant
• AssertionIssuer
• AssertionNotBefore
• AssertionNotOnOrAfter
• AssertionSubject
• AssertionVersion
• AssertionXML
• Claim* properties

GetSecurityToken Method (SAML Component)

Gets the security token.

Syntax

procedure GetSecurityToken();

Remarks

This method communicates with FederationSTS and LocalSTS as applicable to obtain a security token. The SecurityTokenXML property will be populated with the retrieved token.

When AuthMode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) the component will automatically populate various properties to known values to reduce the number of required settings. Typically only the following properties are required:

• User
• Password
• ApplicationURN

When AuthMode is set to 2 (camADFS) or 3 (camCustom) the following properties are required:

• User
• Password
• ApplicationURN
• LocalSTS
• FederationSTS
• FederationURN

ParseAssertion Method (SAML Component)

Parses the specified assertion.

Syntax

procedure ParseAssertion(assertion: String);

Remarks

This method parses the assertion specified by the assertion parameter. If the assertion is signed the component will use the certificate specified in SignerCert to verify the signature. If SignerCert is not set the component will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• AssertionId
• AssertionIssueInstant
• AssertionIssuer
• AssertionNotBefore
• AssertionNotOnOrAfter
• AssertionSubject
• AssertionVersion
• AssertionXML
• Claim* properties

Characters Event (SAML Component)

Fired for plain text segments of the input stream.

Syntax

type TCharactersEvent = procedure (
  Sender: TObject;
  const Text: String
) of Object;

property OnCharacters: TCharactersEvent read FOnCharacters write FOnCharacters;

Remarks

The Characters event provides the plain text content of the XML document (i.e. the text inside the tags). The text is provided through the Text parameter.

The text includes white space as well as end of line characters, except for ignorable whitespace which is fired through the IgnorableWhitespace event.

Comment Event (SAML Component)

Fired when a comment section is encountered.

Syntax

type TCommentEvent = procedure (
  Sender: TObject;
  const Text: String
) of Object;

property OnComment: TCommentEvent read FOnComment write FOnComment;

Remarks

The Comment event is fired whenever a comment section (<!-- ..text... -->) is found in the document.

The full text of the comment is provided by the Text parameter.

EndElement Event (SAML Component)

Fired when an end-element tag is encountered.

Syntax

type TEndElementEvent = procedure (
  Sender: TObject;
  const Namespace: String;
  const Element: String;
  const QName: String;
  IsEmpty: Boolean
) of Object;

property OnEndElement: TEndElementEvent read FOnEndElement write FOnEndElement;

Remarks

The EndElement event is fired when an end-element tag is found in the document.

The element name is provided by the Element parameter.

The IsEmpty parameter is true when the event corresponds with an empty element declaration.

Error Event (SAML Component)

Information about errors during data delivery.

Syntax

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

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component raises an exception.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

PI Event (SAML Component)

Fired when a processing instruction section is encountered.

Syntax

type TPIEvent = procedure (
  Sender: TObject;
  const Text: String
) of Object;

property OnPI: TPIEvent read FOnPI write FOnPI;

Remarks

The PI event is fired whenever a processing instruction section (<? ..text... ?>) is found in the document.

The full text of the processing instruction is provided by the Text parameter.

SSLServerAuthentication Event (SAML Component)

Fired after the server presents its certificate to the client.

Syntax

type TSSLServerAuthenticationEvent = procedure (
  Sender: TObject;
  CertEncoded: String;
  CertEncodedB: TBytes;
  const CertSubject: String;
  const CertIssuer: String;
  const Status: String;
  var Accept: Boolean
) of Object;

property OnSSLServerAuthentication: TSSLServerAuthenticationEvent read FOnSSLServerAuthentication write FOnSSLServerAuthentication;

Remarks

This event is where the client can decide whether to continue with the connection process or not. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK"). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (SAML Component)

Shows the progress of the secure connection.

Syntax

type TSSLStatusEvent = procedure (
  Sender: TObject;
  const Message: String
) of Object;

property OnSSLStatus: TSSLStatusEvent read FOnSSLStatus write FOnSSLStatus;

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

StartElement Event (SAML Component)

Fired when a begin-element tag is encountered in the document.

Syntax

type TStartElementEvent = procedure (
  Sender: TObject;
  const Namespace: String;
  const Element: String;
  const QName: String;
  IsEmpty: Boolean
) of Object;

property OnStartElement: TStartElementEvent read FOnStartElement write FOnStartElement;

Remarks

The StartElement event is fired when a begin-element tag is found in the document.

The element name is provided through the Element parameter. The attribute names and values (if any) are provided through the Name, Namespace, Prefix, and Value properties.

The IsEmpty parameter is true when the event corresponds with an empty element declaration.

Claim Type

The claim.

Remarks

This type describes the claim.

Fields

Constructors

constructor Create();

constructor Create(valTypeName: String; valValue: String; valValueType: String; valIssuerName: String; valOriginalIssuer: String);

Proxy Type

This is the proxy the component will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

Fields

Constructors

constructor Create();

constructor Create(valServer: String; valPort: Integer);

constructor Create(valServer: String; valPort: Integer; valUser: String; valPassword: String);

XMLAttribute Type

An XML attribute from the current XML element.

Remarks

This type describes an XML attribute from the current element. It includes fields to denote information about the attribute being defined.

Fields

Constructors

constructor Create();

XMLElement Type

An element contained within the XML document.

Remarks

This type describes an XML element. The fields for this type describe the element Name, Prefix, and Namespace of the given element.

The elements are inserted into the array in the same order they are found in the document.

Fields

Constructors

constructor Create();

Config Settings (SAML 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.

SAML Config Settings

Base Config Settings

Trappable Errors (SAML Component)

SAML Errors

	603   Cannot obtain assertion. LocalSTS must be set.

The component may also return one of the following error codes, which are inherited from other components.

HTTP Errors

	118   Firewall Error. Error description contains detailed message.
	143   Busy executing current method.
	151   HTTP protocol error. The error message has the server response.
	152   No server specified in URL
	153   Specified URLScheme is invalid.
	155   Range operation is not supported by server.
	156   Invalid cookie index (out of range).
	301   Interrupted.
	302   Can't open AttachedFile.

The component may also return one of the following error codes, which are inherited from other components.

TCPClient Errors

	100   You cannot change the RemotePort at this time. A connection is in progress.
	101   You cannot change the RemoteHost (Server) at this time. A connection is in progress.
	102   The RemoteHost address is invalid (0.0.0.0).
	104   Already connected. If you want to reconnect, close the current connection first.
	106   You cannot change the LocalPort at this time. A connection is in progress.
	107   You cannot change the LocalHost at this time. A connection is in progress.
	112   You cannot change MaxLineLength at this time. A connection is in progress.
	116   RemotePort cannot be zero. Please specify a valid service port number.
	117   You cannot change the UseConnection option while the component is active.
	135   Operation would block.
	201   Timeout.
	211   Action impossible in control's present state.
	212   Action impossible while not connected.
	213   Action impossible while listening.
	301   Timeout.
	302   Could not open file.
	434   Unable to convert string to selected CodePage.
	1105   Already connecting. If you want to reconnect, close the current connection first.
	1117   You need to connect first.
	1119   You cannot change the LocalHost at this time. A connection is in progress.
	1120   Connection dropped by remote host.

TCP/IP Errors

	10004   [10004] Interrupted system call.
	10009   [10009] Bad file number.
	10013   [10013] Access denied.
	10014   [10014] Bad address.
	10022   [10022] Invalid argument.
	10024   [10024] Too many open files.
	10035   [10035] Operation would block.
	10036   [10036] Operation now in progress.
	10037   [10037] Operation already in progress.
	10038   [10038] Socket operation on non-socket.
	10039   [10039] Destination address required.
	10040   [10040] Message too long.
	10041   [10041] Protocol wrong type for socket.
	10042   [10042] Bad protocol option.
	10043   [10043] Protocol not supported.
	10044   [10044] Socket type not supported.
	10045   [10045] Operation not supported on socket.
	10046   [10046] Protocol family not supported.
	10047   [10047] Address family not supported by protocol family.
	10048   [10048] Address already in use.
	10049   [10049] Can't assign requested address.
	10050   [10050] Network is down.
	10051   [10051] Network is unreachable.
	10052   [10052] Net dropped connection or reset.
	10053   [10053] Software caused connection abort.
	10054   [10054] Connection reset by peer.
	10055   [10055] No buffer space available.
	10056   [10056] Socket is already connected.
	10057   [10057] Socket is not connected.
	10058   [10058] Can't send after socket shutdown.
	10059   [10059] Too many references, can't splice.
	10060   [10060] Connection timed out.
	10061   [10061] Connection refused.
	10062   [10062] Too many levels of symbolic links.
	10063   [10063] File name too long.
	10064   [10064] Host is down.
	10065   [10065] No route to host.
	10066   [10066] Directory not empty
	10067   [10067] Too many processes.
	10068   [10068] Too many users.
	10069   [10069] Disc Quota Exceeded.
	10070   [10070] Stale NFS file handle.
	10071   [10071] Too many levels of remote in path.
	10091   [10091] Network subsystem is unavailable.
	10092   [10092] WINSOCK DLL Version out of range.
	10093   [10093] Winsock not loaded yet.
	11001   [11001] Host not found.
	11002   [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
	11003   [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
	11004   [11004] Valid name, no data record (check DNS setup).