SAML Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

nsoftware.IPWorksAuth.Saml

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
• Claims

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
• Claims

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

• C#
• VB.NET

public string ApplicationURN { get; set; }

Public Property ApplicationURN As String

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

• C#
• VB.NET

public string AssertionId { get; }

Public ReadOnly Property AssertionId As String

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

• C#
• VB.NET

public string AssertionIssueInstant { get; }

Public ReadOnly Property AssertionIssueInstant As String

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

• C#
• VB.NET

public string AssertionIssuer { get; }

Public ReadOnly Property AssertionIssuer As String

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

• C#
• VB.NET

public string AssertionNotBefore { get; }

Public ReadOnly Property AssertionNotBefore As String

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

• C#
• VB.NET

public string AssertionNotOnOrAfter { get; }

Public ReadOnly Property AssertionNotOnOrAfter As String

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

• C#
• VB.NET

public string AssertionSubject { get; }

Public ReadOnly Property AssertionSubject As String

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

• C#
• VB.NET

public SamlAssertionVersions AssertionVersion { get; set; }

enum SamlAssertionVersions {
  svSAMLv11,
  svSAMLv20
}

Public Property AssertionVersion As SamlAssertionVersions

Enum SamlAssertionVersions
  svSAMLv11
  svSAMLv20
End Enum

Default Value

0

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

• C#
• VB.NET

public string AssertionXML { get; }

Public ReadOnly Property AssertionXML As String

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

• C#
• VB.NET

public SamlAuthModes AuthMode { get; set; }

enum SamlAuthModes {
  camSharePointOnline,
  camDynamicsCRM,
  camADFS,
  camCustom
}

Public Property AuthMode As SamlAuthModes

Enum SamlAuthModes
  camSharePointOnline
  camDynamicsCRM
  camADFS
  camCustom
End Enum

Default Value

0

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.

Certificate Property (SAML Component)

The certificate used for decryption.

Syntax

• C#
• VB.NET

public Certificate Certificate { get; set; }

Public Property Certificate As Certificate

Remarks

This property specifies the certificate used for decryption. This is only applicable if DecryptAssertion is set to True.

This property is not available at design time.

Claims Property (SAML Component)

A collection of claims.

Syntax

• C#
• VB.NET

public ClaimList Claims { get; }

Public ReadOnly Property Claims As ClaimList

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.

FederationSTS Property (SAML Component)

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

Syntax

• C#
• VB.NET

public string FederationSTS { get; set; }

Public Property FederationSTS As String

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

• C#
• VB.NET

public string FederationURN { get; set; }

Public Property FederationURN As String

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

• C#
• VB.NET

public string LocalSTS { get; set; }

Public Property LocalSTS As String

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

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

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

• C#
• VB.NET

public Proxy Proxy { get; set; }

Public Property Proxy As Proxy

Remarks

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

SecurityTokenXML Property (SAML Component)

The security token XML.

Syntax

• C#
• VB.NET

public string SecurityTokenXML { get; }

Public ReadOnly Property SecurityTokenXML As String

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.

SignerCert Property (SAML Component)

The certificate used for signature verification.

Syntax

• C#
• VB.NET

public Certificate SignerCert { get; set; }

Public Property SignerCert As Certificate

Remarks

This property optionally specifies a certificate used for signature verification. When calling GetAssertion or ParseAssertion, if the assertion is signed the component will use the certificate specified in this property to verify the signature. If this property is not set the component will attempt to parse the certificate present in the assertion to perform verification.

This property is not available at design time.

SSLAcceptServerCert Property (SAML Component)

Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

• C#
• VB.NET

public Certificate SSLAcceptServerCert { get; set; }

Public Property SSLAcceptServerCert As Certificate

Remarks

If it finds any issues with the certificate presented by the server, the component will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

SSLCert Property (SAML Component)

The certificate to be used during SSL negotiation.

Syntax

• C#
• VB.NET

public Certificate SSLCert { get; set; }

Public Property SSLCert As Certificate

Remarks

The digital certificate that the component will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

SSLProvider Property (SAML Component)

This specifies the SSL/TLS implementation to use.

Syntax

• C#
• VB.NET

public SamlSSLProviders SSLProvider { get; set; }

enum SamlSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Public Property SSLProvider As SamlSSLProviders

Enum SamlSSLProviders
  sslpAutomatic
  sslpPlatform
  sslpInternal
End Enum

Default Value

0

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:

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.

The .NET Standard library will always use the internal implementation on all platforms.

SSLServerCert Property (SAML Component)

The server certificate for the last established connection.

Syntax

• C#
• VB.NET

public Certificate SSLServerCert { get; }

Public ReadOnly Property SSLServerCert As Certificate

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

User Property (SAML Component)

The username.

Syntax

• C#
• VB.NET

public string User { get; set; }

Public Property User As String

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

• C#
• VB.NET

public XMLAttributeList XAttributes { get; }

Public Property XAttributes As XMLAttributeList

Remarks

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

This collection is indexed from 0 to count -1.

This property is not available at design time.

XChildren Property (SAML Component)

Collection of child elements of the currently selected XML element.

Syntax

• C#
• VB.NET

public XMLElementList XChildren { get; }

Public Property XChildren As XMLElementList

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 collection is indexed from 0 to count -1.

This property is not available at design time.

XElement Property (SAML Component)

The name of the current element.

Syntax

• C#
• VB.NET

public string XElement { get; set; }

Public Property XElement As String

Default Value

""

Remarks

The current element is specified via the XPath property.

XNamespace Property (SAML Component)

The namespace of the current element.

Syntax

• C#
• VB.NET

public string XNamespace { get; set; }

Public Property XNamespace As String

Default Value

""

Remarks

The current element is specified via the XPath property.

XParent Property (SAML Component)

The parent of the current element.

Syntax

• C#
• VB.NET

public string XParent { get; }

Public ReadOnly Property XParent As String

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

• C#
• VB.NET

public string XPath { get; set; }

Public Property XPath As String

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:

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

• C#
• VB.NET

public string XPrefix { get; set; }

Public Property XPrefix As String

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

• C#
• VB.NET

public string XSubTree { get; }

Public ReadOnly Property XSubTree As String

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

• C#
• VB.NET

public string XText { get; set; }

Public Property XText As String

Default Value

""

Remarks

The current element is specified via the XPath property.

Config Method (SAML Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of 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

• C#
• VB.NET

public void GetAssertion();

Async Version
public async Task GetAssertion();
public async Task GetAssertion(CancellationToken cancellationToken);

Public Sub GetAssertion()

Async Version
Public Sub GetAssertion() As Task
Public Sub GetAssertion(cancellationToken As CancellationToken) As Task

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
• Claims

GetSecurityToken Method (SAML Component)

Gets the security token.

Syntax

• C#
• VB.NET

public void GetSecurityToken();

Async Version
public async Task GetSecurityToken();
public async Task GetSecurityToken(CancellationToken cancellationToken);

Public Sub GetSecurityToken()

Async Version
Public Sub GetSecurityToken() As Task
Public Sub GetSecurityToken(cancellationToken As CancellationToken) As Task

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

• C#
• VB.NET

public void ParseAssertion(string assertion);

Async Version
public async Task ParseAssertion(string assertion);
public async Task ParseAssertion(string assertion, CancellationToken cancellationToken);

Public Sub ParseAssertion(ByVal assertion As String)

Async Version
Public Sub ParseAssertion(ByVal assertion As String) As Task
Public Sub ParseAssertion(ByVal assertion As String, cancellationToken As CancellationToken) As Task

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
• Claims

Characters Event (SAML Component)

Fired for plain text segments of the input stream.

Syntax

• C#
• VB.NET

public event OnCharactersHandler OnCharacters;

public delegate void OnCharactersHandler(object sender, SamlCharactersEventArgs e);

public class SamlCharactersEventArgs : EventArgs {
  public string Text { get; }
}

Public Event OnCharacters As OnCharactersHandler

Public Delegate Sub OnCharactersHandler(sender As Object, e As SamlCharactersEventArgs)

Public Class SamlCharactersEventArgs Inherits EventArgs
  Public ReadOnly Property Text As String
End Class

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

• C#
• VB.NET

public event OnCommentHandler OnComment;

public delegate void OnCommentHandler(object sender, SamlCommentEventArgs e);

public class SamlCommentEventArgs : EventArgs {
  public string Text { get; }
}

Public Event OnComment As OnCommentHandler

Public Delegate Sub OnCommentHandler(sender As Object, e As SamlCommentEventArgs)

Public Class SamlCommentEventArgs Inherits EventArgs
  Public ReadOnly Property Text As String
End Class

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

• C#
• VB.NET

public event OnEndElementHandler OnEndElement;

public delegate void OnEndElementHandler(object sender, SamlEndElementEventArgs e);

public class SamlEndElementEventArgs : EventArgs {
  public string Namespace { get; }
  public string Element { get; }
  public string QName { get; }
  public bool IsEmpty { get; }
}

Public Event OnEndElement As OnEndElementHandler

Public Delegate Sub OnEndElementHandler(sender As Object, e As SamlEndElementEventArgs)

Public Class SamlEndElementEventArgs Inherits EventArgs
  Public ReadOnly Property Namespace As String
  Public ReadOnly Property Element As String
  Public ReadOnly Property QName As String
  Public ReadOnly Property IsEmpty As Boolean
End Class

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

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, SamlErrorEventArgs e);

public class SamlErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As SamlErrorEventArgs)

Public Class SamlErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws 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

• C#
• VB.NET

public event OnPIHandler OnPI;

public delegate void OnPIHandler(object sender, SamlPIEventArgs e);

public class SamlPIEventArgs : EventArgs {
  public string Text { get; }
}

Public Event OnPI As OnPIHandler

Public Delegate Sub OnPIHandler(sender As Object, e As SamlPIEventArgs)

Public Class SamlPIEventArgs Inherits EventArgs
  Public ReadOnly Property Text As String
End Class

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

• C#
• VB.NET

public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication;

public delegate void OnSSLServerAuthenticationHandler(object sender, SamlSSLServerAuthenticationEventArgs e);

public class SamlSSLServerAuthenticationEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string Status { get; }
  public bool Accept { get; set; }
}

Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler

Public Delegate Sub OnSSLServerAuthenticationHandler(sender As Object, e As SamlSSLServerAuthenticationEventArgs)

Public Class SamlSSLServerAuthenticationEventArgs Inherits EventArgs
  Public ReadOnly Property CertEncoded As String
  Public ReadOnly Property CertEncodedB As Byte()
  Public ReadOnly Property CertSubject As String
  Public ReadOnly Property CertIssuer As String
  Public ReadOnly Property Status As String
  Public Property Accept As Boolean
End Class

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

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

public delegate void OnSSLStatusHandler(object sender, SamlSSLStatusEventArgs e);

public class SamlSSLStatusEventArgs : EventArgs {
  public string Message { get; }
}

Public Event OnSSLStatus As OnSSLStatusHandler

Public Delegate Sub OnSSLStatusHandler(sender As Object, e As SamlSSLStatusEventArgs)

Public Class SamlSSLStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Message As String
End Class

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

• C#
• VB.NET

public event OnStartElementHandler OnStartElement;

public delegate void OnStartElementHandler(object sender, SamlStartElementEventArgs e);

public class SamlStartElementEventArgs : EventArgs {
  public string Namespace { get; }
  public string Element { get; }
  public string QName { get; }
  public bool IsEmpty { get; }
}

Public Event OnStartElement As OnStartElementHandler

Public Delegate Sub OnStartElementHandler(sender As Object, e As SamlStartElementEventArgs)

Public Class SamlStartElementEventArgs Inherits EventArgs
  Public ReadOnly Property Namespace As String
  Public ReadOnly Property Element As String
  Public ReadOnly Property QName As String
  Public ReadOnly Property IsEmpty As Boolean
End Class

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 XAttributes collection.

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

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X509 public key.

• C#
• VB.NET

public Certificate(byte[] certificateData);

Public Certificate(ByVal CertificateData As Byte())

Parses CertificateData as an X509 public key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

Claim Type

The claim.

Remarks

This type describes the claim.

Fields

Constructors

• C#
• VB.NET

public Claim();

Public Claim()

• C#
• VB.NET

public Claim(string typeName, string value, string valueType, string issuerName, string originalIssuer);

Public Claim(ByVal TypeName As String, ByVal Value As String, ByVal ValueType As String, ByVal IssuerName As String, ByVal OriginalIssuer As 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

• C#
• VB.NET

public Proxy();

Public Proxy()

• C#
• VB.NET

public Proxy(string server, int port);

Public Proxy(ByVal Server As String, ByVal Port As Integer)

• C#
• VB.NET

public Proxy(string server, int port, string user, string password);

Public Proxy(ByVal Server As String, ByVal Port As Integer, ByVal User As String, ByVal Password As 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

• C#
• VB.NET

public XMLAttribute();

Public XMLAttribute()

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

• C#
• VB.NET

public XMLElement();

Public XMLElement()

Config Settings (SAML Component)

SAML Config Settings

Base Config Settings

Trappable Errors (SAML Component)

SAML Errors

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

HTTP Errors

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

TCPClient Errors

TCP/IP Errors