SAML Control

Properties   Methods   Events   Config Settings   Errors  

The SAML control provides an easy way to add SAML-based SSO to your application.

Syntax

SAML

Remarks

The Security Assertion Markup Language (SAML) protocol provides a standardized way to add Single Sign-on (SSO) to applications. Service Providers (i.e., your application) using SAML-based SSO can eliminate the need to store and manage user passwords. When using SAML, the responsibility of identifying a user can be shifted to the Identity Provider.

In a Web environment, this is typically done by redirecting a user with a SAMLRequest from your application to the Identity Provider's login page where a user already has an account. The user will login, and the Identity Provider will return an assertion in a SAMLResponse, which is a set of information about the user and the authentication steps taken to identify the user.

When a Service Provider (i.e., your web application) receives this SAMLResponse, it will verify both the SAMLResponse and its accompanying assertion to ensure that both were requested by the Service Provider and issued by the Identity Provider. Once the SAMLResponse and assertion have been verified, the assertion will typically contain attributes about the user and its profile with the Identity Provider.

SAML also supports Single Logout (SLO) that can be used to log a user out of the Identity Provider and, depending on the configuration of the Identity Provider, all other accounts that used the Identity Provider to authenticate the user.

Setup

To get started with the control, information about the Identity Provider is needed. Typically, this information is provided by a SAML Metadata Document that is either provided during the setup or requested from a URI. The RequestIdentityMetadata and LoadIdentityMetadata methods are both ways to populate the IdentityProviderMetadata, IdentityProviderSigningCert, and IdentityProviderURIs properties.

Usage: Requesting and Reloading the Identity Provider Metadata Document

saml.RequestIdentityMetadata("https://example.com/federationmetadata/federationmetadata.xml"); string raw_document = saml.IdentityProviderMetadata.MetadataContent; //... saml.LoadIdentityMetadata(raw_document, true);

Additionally, the control needs to be configured with the information about the Service Provider (i.e., your application). The ServiceProviderMetadata, ServiceProviderSigningCert, and ServiceProviderURIs properties can be used to provide information about the Service Provider. These are used by the control to build a valid SAMLRequest and to verify the SAMLResponse and its assertions. Additionally, to easily supply this information to an Identity Provider, the BuildServiceMetadata method can be used to create a SAML Metadata Document that describes your application (the Service Provider) to the Identity Provider.

Usage: Configuring Service Provider Metadata

saml.ServiceProviderMetadata.EntityId = "ServiceProviderId"; saml.ServiceProviderMetadata.AuthnRequestSigned = true; saml.ServiceProviderMetadata.WantAssertionsSigned = true; saml.ServiceProviderSigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); URI acs = new URI(); acs.URIType = SAMLURITypes.sutACS; acs.Location = "https://service_provider.com/acs/"; acs.BindingType = subPost; saml.ServiceProviderURIs.Add(acs); URI logout = new URI(); logout.URIType = SAMLURITypes.sutLogout; logout.Location = "https://service_provider.com/logout/"; logout.Binding = subRedirect; saml.ServiceProviderURIs.Add(acs); saml.BuildServiceMetadata();

Authentication Request

Once configured, the BuildAuthnRequest method can be used to build a SAMLRequest that has been configured by the SAMLRequestSettings. Additionally, to provide state information between the request and the response, the RelayState property can be set. Typically the RelayState property can be used to return a user back to the location within the application once they have been authenticated. After the request has been created, the SAMLRequestId and SAMLRequestIssuer properties need to be saved for verification purposes. The SAMLRequestIssuer property will be used to check that the SAMLResponse is meant for this Service Provider. The SAMLRequestId property is used to verify that the response corresponds to a request that was made by the Service Provider.

Usage: Building an Authn Request

saml.SAMLRequestSettings.Issuer = "ServiceProviderId"; saml.SAMLRequestSettings.RequestBinding = SAMLRequestBindings.srbHTTPRedirect; saml.SAMLRequestSettings.SignRequest = true; saml.RelayState = "https://service_provider.com/landing"; saml.BuildAuthnRequest(); string requestId = saml.SAMLRequestSettings.Id; //save for later

Depending on how the SAMLRequestRequestBinding property is configured, the results will be provided through the SAMLRequestBody and SAMLRequestURL properties. Using the information from the properties, the user that needs identifying should be directed to the SAMLRequestURL. If using the srbHTTPRedirect binding, this is typically done by redirecting the user to the URL. This URL will contain the SAMLRequest and RelayState as query parameters that are parsed by the Identity Provider. If using the srbHTTPPost binding, this is done by using an HTML form post as seen below:

string htmlContent = $@" <!DOCTYPE html> <html> <head> <title>SAML POST</title> </head> <body onload='document.forms[0].submit()'> <form method='post' action='{saml.SAMLRequestURL}'> <input type='hidden' name='SAMLRequest' value='{saml.SAMLRequestBody}'/> <input type='hidden' name='RelayState' value='{saml.RelayState}'/> </form> </body> </html>";

Authentication Response

Once the user has completed authentication, the Identity Provider will return the user to the Assertion Consumer Service (ASC) URI that was configured in the ServiceProviderURIs properties. If authentication was successful, this response should also contain an assertion as well as information about the authentication context.

To handle an incoming HTTP request that contains the SAMLResponse, the ProcessSAMLResponse or ParseSAMLResponse methods can be used. To provide the HTTP headers and body that contain the SAMLResponse directly to the control, the SAMLResponseHeaders and SAMLResponseBody properties can be set before calling ParseSAMLResponse or ProcessSAMLResponse. For example:

saml.SAMLResponseBody = "HTTP Body"; saml.SAMLResponseHeaders = "HTTP Headers";

Once the HTTP request that contains the SAMLResponse has been provided, the application can then call the ProcessSAMLResponse method. While the ProcessSAMLResponse method processes the SAMLResponse, the control fires the SAMLResponse and Assertion events. These events can be used to provide the control the information needed to correctly verify the SAMLResponse such as the SAMLRequestId and SAMLRequestIssuer properties that were saved after creating the SAMLRequest. If the SAMLResponse and assertion are valid, the method will return without any errors. Additionally, the SAMLResponseInfo, AssertionInfo, AssertionAttributeInfo, and AssertionAuthnInfo properties will be populated. saml.RequestIdentityMetadata("https://example.com/federationmetadata/federationmetadata.xml"); //Setup Service Provider URI acs = new URI(); acs.URIType = SAMLURITypes.sutACS; acs.Location = "https://service_provider.com/acs/"; acs.BindingType = URIBindings.subPost saml.ServiceProviderURIs.Add(acs); //Provide information about the SAMLRequest. saml.SAMLRequestSettings.Issuer = "ServiceProviderId"; saml.SAMLRequestSettings.Id = requestId; saml.ProcessSAMLResponse();

The ProcessSAMLResponse method performs multiple steps automatically, making it a simple method to handle the SAMLResponse. The method is the equivalent to calling the ParseSAMLResponse, ValidateSAMLResponse, ParseAssertion, and ValidateAssertion methods. These methods can be used in place of calling ProcessSAMLResponse if there are additional considerations or extra control is needed by your application. saml.ParseSAMLResponse(); saml.ValidateSAMLResponse(); saml.ParseAssertion(); saml.ValidateAssertion();

Assertions

The SAML 2.0 specification gives Identity Providers many different options for what can be included in an assertion. In the Web SSO profile, typically the assertion will contain the Issuer, Signature, Subject, Conditions, AttributeStatement, and AuthnStatement. Information found from the Issuer, Signature, Subject, and Conditions sections of the assertion can be found in the AssertionInfo property. Along with providing information about the assertion, these fields are also used to verify the assertion. An important field to note is the AssertionSubjectNameId property. This property provides the unique identifier for the user which can be used for authorization purposes. See below for information about the AttributeStatement and AuthnStatement sections.

Assertion Authentication Context

The AuthnStatement section is used by the Identity Provider to provide the Service Provider with information about its authentication session with the user. The statement is parsed to the AssertionAuthnInfo property. Some commonly used information is how the user authenticated with the Identity Provider (see AssertionAuthnInfoContextClassReference) and the session identifier created by the Identity Provider for the Service Provider (see AssertionAuthnInfoSessionIndex).

Assertion Attributes

Along with the AssertionSubjectNameId, the Identity Provider may give additional information about the user in the AttributeStatement section. What exactly is provided depends on how the connection between the Identity Provider and Service Provider was configured. Since there is no defined list of attributes, the AssertionAttributeInfo properties will be populated with each attribute found. Each attribute has a name and one or more values. For example, take the following attribute that describes a list of emails attached to the user.

<Attribute Name="verified_emails"> <AttributeValue>email@test.com</AttributeValue> <AttributeValue>other@example.com</AttributeValue> </Attribute>

In this assertion attribute statement, the user has two emails that have been verified. There are two ways to get this information using the SAML control. First, using the collection, the application can iterate through the collection for the attribute and then iterate through the associated values. Using this method is useful if there are multiple acceptable names for the attributes that could be accepted. For example: List<string> verified_emails = new List<string>(); for (int i = 0; i < saml.AssertionAttributeInfo.Count; i++) { if (saml.AssertionAttributeInfo[i].Name == "verified_emails" || saml.AssertionAttributeInfo[i].Name == "verified_email") { for (int j = 0; j < saml.AssertionAttributeInfo[i].AttributeValueCount; j++) { saml.AssertionAttributeInfo[i].AttributeValueIndex = j; verified_emails.Add(saml.AssertionAttributeInfo[i].AttributeValueData); } } }

The other option is to use the GetAssertionAttribute method. This method will search the assertion's attribute statement for the first attribute with a matching name. Like in the example above, if the attribute has multiple values, the method will return them in a semicolon-separated list. This method simplifies the process of searching the collection for a specific attribute if the name of the attribute is known ahead of time. For example: string[] verified_emails = saml.GetAssertionAttribute("verified_emails").Split(';');

Property List

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

Method List

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

Event List

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

Config Settings

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

AssertionAttributeInfoCount Property (SAML Control)

The number of records in the AssertionAttributeInfo arrays.

Syntax

samlcontrol.AssertionAttributeInfoCount[=integer]

Default Value

0

Remarks

This property controls the size of the following arrays:

• AssertionAttributeInfoAttributeContent
• AssertionAttributeInfoAttributeValueCount
• AssertionAttributeInfoAttributeValueData
• AssertionAttributeInfoAttributeValueIndex
• AssertionAttributeInfoFriendlyName
• AssertionAttributeInfoName
• AssertionAttributeInfoNameFormat

The array indices start at 0 and end at AssertionAttributeInfoCount - 1.

This property is not available at design time.

Data Type

Integer

AssertionAttributeInfoAttributeContent Property (SAML Control)

The raw XML of the attribute.

Syntax

samlcontrol.AssertionAttributeInfoAttributeContent(AssertionAttributeInfoIndex)

Default Value

""

Remarks

The raw XML of the attribute. In cases where the content of the attribute is complex, this property can be used to do additional XML parsing.

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

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

Data Type

String

AssertionAttributeInfoAttributeValueCount Property (SAML Control)

In cases where there are multiple values for a single attribute, this count will be updated to reflect the size of the list.

Syntax

samlcontrol.AssertionAttributeInfoAttributeValueCount(AssertionAttributeInfoIndex)

Default Value

0

Remarks

In cases where there are multiple values for a single attribute, this count will be updated to reflect the size of the list. If the value of the attribute is not a list, the count will be set to 1. See AssertionAttributeValueIndex for more information.

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

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

Data Type

Integer

AssertionAttributeInfoAttributeValueData Property (SAML Control)

The content of the attribute value selected by AttributeValueIndex .

Syntax

samlcontrol.AssertionAttributeInfoAttributeValueData(AssertionAttributeInfoIndex)

Default Value

""

Remarks

The content of the attribute value selected by AssertionAttributeValueIndex.

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

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

Data Type

String

AssertionAttributeInfoAttributeValueIndex Property (SAML Control)

The index of the attribute value that should be populated in the AttributeValueData property.

Syntax

samlcontrol.AssertionAttributeInfoAttributeValueIndex(AssertionAttributeInfoIndex)[=integer]

Default Value

0

Remarks

The index of the attribute value that should be populated in the AssertionAttributeValueData property. Valid ranges for this property are from 0 to AssertionAttributeValueCount - 1. By default, this property is set to 0. In cases where there is only a singular value, that value will be at index 0. For example:

Multi-value attribute

<Attribute Name="ValueName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <AttributeValue>Value1</AttributeValue> <AttributeValue>Value2</AttributeValue> </Attribute>

Iterating through each value in an attribute

for (int i = 0; i < saml.AssertionAttributeInfo[0].AttributeValueCount; i++) { saml.AssertionAttributeInfo[0].AttributeValueIndex = i; string attribute_value = saml.AssertionAttributeInfo[0].AttributeValueData; //... the rest of the processing }

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

This property is not available at design time.

Data Type

Integer

AssertionAttributeInfoFriendlyName Property (SAML Control)

A human-readable version of the attribute name, if provided.

Syntax

samlcontrol.AssertionAttributeInfoFriendlyName(AssertionAttributeInfoIndex)

Default Value

""

Remarks

A human-readable version of the attribute name, if provided. This value is intended to be used for informational and logging purposes only.

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

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

Data Type

String

AssertionAttributeInfoName Property (SAML Control)

The name of the attribute.

Syntax

samlcontrol.AssertionAttributeInfoName(AssertionAttributeInfoIndex)

Default Value

""

Remarks

The name of the attribute. The format of the name (if provided) can be found in the AssertionNameFormat property.

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

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

Data Type

String

AssertionAttributeInfoNameFormat Property (SAML Control)

A URI reference to how the Name of the attribute is formatted.

Syntax

samlcontrol.AssertionAttributeInfoNameFormat(AssertionAttributeInfoIndex)

Default Value

""

Remarks

A URI reference to how the AssertionName of the attribute is formatted. If not set, Unspecified is used. Some common values are:

The AssertionAttributeInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeInfoCount property.

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

Data Type

String

AssertionAuthnInfoCount Property (SAML Control)

The number of records in the AssertionAuthnInfo arrays.

Syntax

samlcontrol.AssertionAuthnInfoCount[=integer]

Default Value

0

Remarks

This property controls the size of the following arrays:

• AssertionAuthnInfoAuthenticatingAuthorites
• AssertionAuthnInfoAuthnInstant
• AssertionAuthnInfoContextClassReference
• AssertionAuthnInfoContextDeclaration
• AssertionAuthnInfoSessionExpiration
• AssertionAuthnInfoSessionIndex
• AssertionAuthnInfoStatementContent

The array indices start at 0 and end at AssertionAuthnInfoCount - 1.

This property is not available at design time.

Data Type

Integer

AssertionAuthnInfoAuthenticatingAuthorites Property (SAML Control)

A semicolon-separated list of authorities involved with the current authentication context.

Syntax

samlcontrol.AssertionAuthnInfoAuthenticatingAuthorites(AssertionAuthnInfoIndex)

Default Value

""

Remarks

A semicolon-separated list of authorities involved with the current authentication context. Typically, this list includes other parties involved with the authentication of the subject besides the issuer that issued the assertion.

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAuthnInfoAuthnInstant Property (SAML Control)

The time at which the authentication took place.

Syntax

samlcontrol.AssertionAuthnInfoAuthnInstant(AssertionAuthnInfoIndex)

Default Value

""

Remarks

The time at which the authentication took place.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAuthnInfoContextClassReference Property (SAML Control)

A per-defined URI reference identifying an authentication context class that describes how authentication was provided.

Syntax

samlcontrol.AssertionAuthnInfoContextClassReference(AssertionAuthnInfoIndex)

Default Value

""

Remarks

A per-defined URI reference identifying an authentication context class that describes how authentication was provided. For example, if the user used a password to perform authentication, this will be set to urn:oasis:names:tc:SAML:2.0:ac:classes:Password.

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAuthnInfoContextDeclaration Property (SAML Control)

A description or URI that describes additional information about the authentication context past the ContextClassReference .

Syntax

samlcontrol.AssertionAuthnInfoContextDeclaration(AssertionAuthnInfoIndex)

Default Value

""

Remarks

A description or URI that describes additional information about the authentication context past the AssertionContextClassReference. This provides more detail about the authentication process when provided by the Identity Provider.

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAuthnInfoSessionExpiration Property (SAML Control)

The time at which the session between the principal and Identity Provider must be considered ended.

Syntax

samlcontrol.AssertionAuthnInfoSessionExpiration(AssertionAuthnInfoIndex)

Default Value

""

Remarks

The time at which the session between the principal and Identity Provider must be considered ended.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAuthnInfoSessionIndex Property (SAML Control)

The unique identifier for a particular session established between the user (principal) and the Service Provider (SP), as provided by the Identity Provider (IdP).

Syntax

samlcontrol.AssertionAuthnInfoSessionIndex(AssertionAuthnInfoIndex)

Default Value

""

Remarks

The unique identifier for a particular session established between the user (principal) and the Service Provider (SP), as provided by the Identity Provider (IdP). It is common (but not required) to use this value as the session identifier between the user and the Service Provider (your application).

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAuthnInfoStatementContent Property (SAML Control)

The raw XML of the Authn statement.

Syntax

samlcontrol.AssertionAuthnInfoStatementContent(AssertionAuthnInfoIndex)

Default Value

""

Remarks

The raw XML of the Authn statement. Typically, this is used in cases to get additional information from the Authn statement that is not provided by the control.

The AssertionAuthnInfoIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnInfoCount property.

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

Data Type

String

AssertionAssertionContent Property (SAML Control)

The raw XML of the assertion.

Syntax

samlcontrol.AssertionAssertionContent[=string]

Default Value

""

Remarks

The raw XML of the assertion. This property can be set to provide the assertion to the control for the ParseAssertion method to parse the assertion without the SAML response.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .AssertionAssertionContentB.

Data Type

Binary String

AssertionExpirationDate Property (SAML Control)

When the assertion expires.

Syntax

samlcontrol.AssertionExpirationDate

Default Value

""

Remarks

When the assertion expires. This represents the NotOnOrAfter attribute of the Conditions element if the attribute is present in the assertion.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

This property is read-only.

Data Type

String

AssertionId Property (SAML Control)

The unique Id of the assertion generated by the identity provider.

Syntax

samlcontrol.AssertionId

Default Value

""

Remarks

The unique Id of the assertion generated by the identity provider. This is not an Id that is tied to a user but rather to the assertion itself.

This property is read-only.

Data Type

String

AssertionIsSigned Property (SAML Control)

Whether the assertion has been signed by the identity provider.

Syntax

samlcontrol.AssertionIsSigned

Default Value

False

Remarks

Whether the assertion has been signed by the identity provider. This is set to when the Signature element is present in the assertion.

This property is read-only.

Data Type

Boolean

AssertionIssuedTime Property (SAML Control)

The time at which the assertion was issued by the Issuer (typically the identity provider).

Syntax

samlcontrol.AssertionIssuedTime

Default Value

""

Remarks

The time at which the assertion was issued by the AssertionIssuer (typically the identity provider). This property represents the IssueInstant attribute of the Assertion element.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

This property is read-only.

Data Type

String

AssertionIssuer Property (SAML Control)

The issuer of the assertion.

Syntax

samlcontrol.AssertionIssuer

Default Value

""

Remarks

The issuer of the assertion. Typically, this is the same as the identity provider that provided the SAML response. This property represents the Issuer element in the Assertion element.

This property is read-only.

Data Type

String

AssertionNotBeforeDate Property (SAML Control)

The time at which the assertion becomes valid.

Syntax

samlcontrol.AssertionNotBeforeDate

Default Value

""

Remarks

The time at which the assertion becomes valid. If the current time is before this property, then the assertion is not considered valid yet. This represents the NotBefore attribute of the Conditions element if the attribute is present in the assertion.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

This property is read-only.

Data Type

String

AssertionOneTimeUse Property (SAML Control)

Whether the issuer only considers this information valid for this single instance.

Syntax

samlcontrol.AssertionOneTimeUse

Default Value

False

Remarks

Whether the issuer only considers this information valid for this single instance. The information saved here typically should not be cached or saved for future use. This represents the OneTimeUse element of the Conditions element if the element is present in the assertion.

This property is read-only.

Data Type

Boolean

AssertionSubjectNameId Property (SAML Control)

The NameId for the subject of the assertion.

Syntax

samlcontrol.AssertionSubjectNameId

Default Value

""

Remarks

The NameId for the subject of the assertion. Typically, the subject is the user that is being authenticated. The format of this name Id can be found in the AssertionSubjectNameIdFormat property. This represents the NameId element of the Subject element if the element is present in the assertion.

This property is read-only.

Data Type

String

AssertionSubjectNameIdFormat Property (SAML Control)

A URI reference to how the SubjectNameId of the element is formatted.

Syntax

samlcontrol.AssertionSubjectNameIdFormat

Default Value

""

Remarks

A URI reference to how the AssertionSubjectNameId of the element is formatted. If not set, Unspecified is used. This represents the Format attribute of the NameID element if the attribute is present in the assertion. Some common values are:

This property is read-only.

Data Type

String

AssertionUserInfoAddress Property (SAML Control)

The address for the user if one could be parsed from the assertion.

Syntax

samlcontrol.AssertionUserInfoAddress

Default Value

""

Remarks

The address for the user if one could be parsed from the assertion. The attribute names used to set this and other properties can be configured using the AttributeNameProfile configuration setting.

This property is read-only.

Data Type

String

AssertionUserInfoEmail Property (SAML Control)

The email for the user if one could be parsed from the assertion.

Syntax

samlcontrol.AssertionUserInfoEmail

Default Value

""

Remarks

The email for the user if one could be parsed from the assertion. The attribute names used to set this and other properties can be configured using the AttributeNameProfile configuration setting.

This property is read-only.

Data Type

String

AssertionUserInfoName Property (SAML Control)

The address for the user if one could be parsed from the assertion.

Syntax

samlcontrol.AssertionUserInfoName

Default Value

""

Remarks

The address for the user if one could be parsed from the assertion. The attribute names used to set this and other properties can be configured using the AttributeNameProfile configuration setting.

This property is read-only.

Data Type

String

FirewallAutoDetect Property (SAML Control)

Whether to automatically detect and use firewall system settings, if available.

Syntax

samlcontrol.FirewallAutoDetect[=boolean]

Default Value

False

Remarks

Whether to automatically detect and use firewall system settings, if available.

Data Type

Boolean

FirewallType Property (SAML Control)

The type of firewall to connect through.

Syntax

samlcontrol.FirewallType[=integer]

Possible Values

fwNone(0), 
fwTunnel(1), 
fwSOCKS4(2), 
fwSOCKS5(3), 
fwSOCKS4A(10)

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

Data Type

Integer

FirewallHost Property (SAML Control)

The name or IP address of the firewall (optional).

Syntax

samlcontrol.FirewallHost[=string]

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a FirewallHost is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the control fails with an error.

Data Type

String

FirewallPassword Property (SAML Control)

A password if authentication is to be used when connecting through the firewall.

Syntax

samlcontrol.FirewallPassword[=string]

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, the control fails with an error.

Data Type

String

FirewallPort Property (SAML Control)

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

samlcontrol.FirewallPort[=integer]

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall FirewallHost. See the description of the FirewallHost property for details.

Note: This property is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

Data Type

Integer

FirewallUser Property (SAML Control)

A username if authentication is to be used when connecting through a firewall.

Syntax

samlcontrol.FirewallUser[=string]

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If FirewallHost is specified, this property and the FirewallPassword property are used to connect and authenticate to the given Firewall. If the authentication fails, the control fails with an error.

Data Type

String

FollowRedirects Property (SAML Control)

Determines what happens when the server issues a redirect.

Syntax

samlcontrol.FollowRedirects[=integer]

Possible Values

frNever(0), 
frAlways(1), 
frSameScheme(2)

Default Value

0

Remarks

This property determines what happens when the server issues a redirect. Normally, the control returns an error if the server responds with an "Object Moved" message. If this property is set to frAlways (1), the new URL for the object is retrieved automatically every time.

If this property is set to frSameScheme (2), the new URL is retrieved automatically only if the URLScheme is the same; otherwise, the control fails with an error.

Note: Following the HTTP specification, unless this property is set to frAlways (1), automatic redirects will be performed only for GET or HEAD requests. Other methods potentially could change the conditions of the initial request and create security vulnerabilities.

Furthermore, if either the new URL server or port are different from the existing one, User and Password are also reset to empty. If, however, this property is set to frAlways (1), the same credentials are used to connect to the new server.

A Redirect event is fired for every URL the product is redirected to. In the case of automatic redirections, the Redirect event is a good place to set properties related to the new connection (e.g., new authentication parameters).

The default value is frNever (0). In this case, redirects are never followed, and the control fails with an error instead.

Data Type

Integer

IdentityProviderEncryptingCertStore Property (SAML Control)

The name of the certificate store for the client certificate.

Syntax

samlcontrol.IdentityProviderEncryptingCertStore[=string]

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The IdentityProviderEncryptingCertStoreType property denotes the type of the certificate store specified by IdentityProviderEncryptingCertStore. If the store is password-protected, specify the password in IdentityProviderEncryptingCertStorePassword.

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

Designations of certificate stores are platform dependent.

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

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .IdentityProviderEncryptingCertStoreB.

This property is not available at design time.

Data Type

Binary String

IdentityProviderEncryptingCertStorePassword Property (SAML Control)

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

Syntax

samlcontrol.IdentityProviderEncryptingCertStorePassword[=string]

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.

Data Type

String

IdentityProviderEncryptingCertStoreType Property (SAML Control)

The type of certificate store for this certificate.

Syntax

samlcontrol.IdentityProviderEncryptingCertStoreType[=integer]

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

This property is not available at design time.

Data Type

Integer

IdentityProviderEncryptingCertSubject Property (SAML Control)

The subject of the certificate used for client authentication.

Syntax

samlcontrol.IdentityProviderEncryptingCertSubject[=string]

Default Value

""

Remarks

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 as follows:

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

This property is not available at design time.

Data Type

String

IdentityProviderEncryptingCertEncoded Property (SAML Control)

The certificate (PEM/Base64 encoded).

Syntax

samlcontrol.IdentityProviderEncryptingCertEncoded[=string]

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The IdentityProviderEncryptingCertStore and IdentityProviderEncryptingCertSubject properties also may be used to specify a certificate.

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .IdentityProviderEncryptingCertEncodedB.

This property is not available at design time.

Data Type

Binary String

IdentityProviderMetadataEntityId Property (SAML Control)

The unique Id for the identity provider that is being described.

Syntax

samlcontrol.IdentityProviderMetadataEntityId[=string]

Default Value

""

Remarks

The unique Id for the identity provider that is being described. This is used for verification purposes when verifying the issuer of an assertion or SAMLResponse.

Data Type

String

IdentityProviderMetadataExpirationDate Property (SAML Control)

The expiration date of the Identity Provider description provided by the metadata document.

Syntax

samlcontrol.IdentityProviderMetadataExpirationDate

Default Value

""

Remarks

The expiration date of the Identity Provider description provided by the metadata document. This represents the valid attribute of the IDPSSODescriptor element if the attribute is present in the document.

This property is read-only.

Data Type

String

IdentityProviderMetadataMetadataContent Property (SAML Control)

The raw metadata for the identity provider.

Syntax

samlcontrol.IdentityProviderMetadataMetadataContent[=string]

Default Value

""

Remarks

The raw metadata for the identity provider. To avoid repeated requests to the Identity Provider, this value can be saved for later to be used with the LoadIdentityMetadata method.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .IdentityProviderMetadataMetadataContentB.

Data Type

Binary String

IdentityProviderMetadataRequestsSignedAuthnRequests Property (SAML Control)

Whether the identity provider requests that authentication (Authn) requests are signed.

Syntax

samlcontrol.IdentityProviderMetadataRequestsSignedAuthnRequests[=boolean]

Default Value

False

Remarks

Whether the identity provider requests that authentication (Authn) requests are signed.

Data Type

Boolean

IdentityProviderMetadataSignedMetadata Property (SAML Control)

Whether the identity provider's parsed metadata is signed.

Syntax

samlcontrol.IdentityProviderMetadataSignedMetadata

Default Value

False

Remarks

Whether the identity provider's parsed metadata is signed.

This property is read-only.

Data Type

Boolean

IdentityProviderMetadataSupportedAttributeProfiles Property (SAML Control)

A semicolon-separated list of attribute profiles supported by the identity provider.

Syntax

samlcontrol.IdentityProviderMetadataSupportedAttributeProfiles

Default Value

""

Remarks

A semicolon-separated list of attribute profiles supported by the identity provider. Some common attribute profiles are:

• urn:oasis:names:tc:SAML:2.0:profiles:attribute:basic
• urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500
• urn:oasis:names:tc:SAML:2.0:profiles:attribute:UUID
• urn:oasis:names:tc:SAML:2.0:profiles:attribute:DCE
• urn:oasis:names:tc:SAML:2.0:profiles:attribute:XACML

This property is read-only.

Data Type

String

IdentityProviderMetadataSupportedAttributes Property (SAML Control)

A semicolon-separated list of attributes supported by the identity provider as presented by the Identity Provider's metadata document.

Syntax

samlcontrol.IdentityProviderMetadataSupportedAttributes

Default Value

""

Remarks

A semicolon-separated list of attributes supported by the identity provider as presented by the Identity Provider's metadata document. This is a list of attributes that are explicitly supported by the Identity Provider but is not a full list of all the supported attributes. The list will contain the Name of each attribute found in the IDPSSODescriptor element.

This property is read-only.

Data Type

String

IdentityProviderMetadataSupportedNameIdFormats Property (SAML Control)

The name identifier formats supported by the identity provider if provided by the metadata document.

Syntax

samlcontrol.IdentityProviderMetadataSupportedNameIdFormats

Default Value

""

Remarks

The name identifier formats supported by the identity provider if provided by the metadata document. Some common values are:

• Unspecified - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
• Email Address - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• Windows Domain Qualified Name - urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

This property is read-only.

Data Type

String

IdentityProviderSigningCertStore Property (SAML Control)

The name of the certificate store for the client certificate.

Syntax

samlcontrol.IdentityProviderSigningCertStore[=string]

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The IdentityProviderSigningCertStoreType property denotes the type of the certificate store specified by IdentityProviderSigningCertStore. If the store is password-protected, specify the password in IdentityProviderSigningCertStorePassword.

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

Designations of certificate stores are platform dependent.

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

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .IdentityProviderSigningCertStoreB.

This property is not available at design time.

Data Type

Binary String

IdentityProviderSigningCertStorePassword Property (SAML Control)

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

Syntax

samlcontrol.IdentityProviderSigningCertStorePassword[=string]

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.

Data Type

String

IdentityProviderSigningCertStoreType Property (SAML Control)

The type of certificate store for this certificate.

Syntax

samlcontrol.IdentityProviderSigningCertStoreType[=integer]

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

This property is not available at design time.

Data Type

Integer

IdentityProviderSigningCertSubject Property (SAML Control)

The subject of the certificate used for client authentication.

Syntax

samlcontrol.IdentityProviderSigningCertSubject[=string]

Default Value

""

Remarks

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 as follows:

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

This property is not available at design time.

Data Type

String

IdentityProviderSigningCertEncoded Property (SAML Control)

The certificate (PEM/Base64 encoded).

Syntax

samlcontrol.IdentityProviderSigningCertEncoded[=string]

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The IdentityProviderSigningCertStore and IdentityProviderSigningCertSubject properties also may be used to specify a certificate.

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .IdentityProviderSigningCertEncodedB.

This property is not available at design time.

Data Type

Binary String

IdentityProviderURICount Property (SAML Control)

The number of records in the IdentityProviderURI arrays.

Syntax

samlcontrol.IdentityProviderURICount[=integer]

Default Value

0

Remarks

This property controls the size of the following arrays:

• IdentityProviderURIBindingRef
• IdentityProviderURIBindingType
• IdentityProviderURIIndex
• IdentityProviderURIIsDefault
• IdentityProviderURILocation
• IdentityProviderURIType

The array indices start at 0 and end at IdentityProviderURICount - 1.

This property is not available at design time.

Data Type

Integer

IdentityProviderURIBindingRef Property (SAML Control)

The URI reference for the set BindingType .

Syntax

samlcontrol.IdentityProviderURIBindingRef(IdentityProviderURIIdx)[=string]

Default Value

""

Remarks

The URI reference for the set IdentityProviderURIBindingType. When the IdentityProviderURIBindingType is set, this property will be updated to match. The exception is the subCustom value, which allows for any value to be placed in this property.

If this property is set instead, the control will attempt to set the IdentityProviderURIBindingType property to match. If it can't, subCustom will also be used.

When parsing a metadata document, the control will also use the subCustom value for any binding types that are not recognized by the control.

The IdentityProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the IdentityProviderURICount property.

This property is not available at design time.

Data Type

String

IdentityProviderURIBindingType Property (SAML Control)

The type of binding that is supported for this URI.

Syntax

samlcontrol.IdentityProviderURIBindingType(IdentityProviderURIIdx)[=integer]

Possible Values

subRedirect(0), 
subPost(1), 
subArtifact(2), 
subCustom(3)

Default Value

0

Remarks

The type of binding that is supported for this URI. The control only supports using the HTTP Redirect and HTTP Post bindings. The HTTP Artifact and other bindings are informational, and support for them must be implemented directly.

When setting this property, the IdentityProviderURIBindingRef property will also be updated with the matching URI. The exception is the subCustom value, which allows for any value to be placed in the IdentityProviderURIBindingRef property.

If the IdentityProviderURIBindingRef property is set, during the processing of a metadata document the control will attempt to set this property as well with the matching value. If it can't, subCustom will be used instead.

The IdentityProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the IdentityProviderURICount property.

This property is not available at design time.

Data Type

Integer

IdentityProviderURIIsDefault Property (SAML Control)

Whether this URI is the default URI that should be used for the specific URIType and BindingType combination.

Syntax

samlcontrol.IdentityProviderURIIsDefault(IdentityProviderURIIdx)[=boolean]

Default Value

False

Remarks

Whether this URI is the default URI that should be used for the specific IdentityProviderURIURIType and IdentityProviderURIBindingType combination.

The IdentityProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the IdentityProviderURICount property.

This property is not available at design time.

Data Type

Boolean

IdentityProviderURILocation Property (SAML Control)

The address of the URI.

Syntax

samlcontrol.IdentityProviderURILocation(IdentityProviderURIIdx)[=string]

Default Value

""

Remarks

The address of the URI.

The IdentityProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the IdentityProviderURICount property.

This property is not available at design time.

Data Type

String

IdentityProviderURIIndex Property (SAML Control)

The index for the URI that can be optionally used if multiple URIs of the same URIType and BindingType are provided.

Syntax

samlcontrol.IdentityProviderURIIndex(IdentityProviderURIIdx)[=integer]

Default Value

0

Remarks

The index for the URI that can be optionally used if multiple URIs of the same IdentityProviderURIURIType and IdentityProviderURIBindingType are provided.

The IdentityProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the IdentityProviderURICount property.

This property is not available at design time.

Data Type

Integer

IdentityProviderURIType Property (SAML Control)

The purpose of the URI.

Syntax

samlcontrol.IdentityProviderURIType(IdentityProviderURIIdx)[=integer]

Possible Values

sutSignon(0), 
sutLogout(1), 
sutACS(2)

Default Value

0

Remarks

The purpose of the URI. Possible values are:

The IdentityProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the IdentityProviderURICount property.

This property is not available at design time.

Data Type

Integer

ProxyAuthScheme Property (SAML Control)

The type of authorization to perform when connecting to the proxy.

Syntax

samlcontrol.ProxyAuthScheme[=integer]

Possible Values

authBasic(0), 
authDigest(1), 
authProprietary(2), 
authNone(3), 
authNtlm(4), 
authNegotiate(5)

Default Value

0

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the ProxyUser and ProxyPassword properties are set.

ProxyAuthScheme should be set to authNone (3) when no authentication is expected.

By default, ProxyAuthScheme is authBasic (0), and if the ProxyUser and ProxyPassword properties are set, the control will attempt basic authentication.

If ProxyAuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If ProxyAuthScheme is set to authProprietary (2), then the authorization token will not be generated by the control. Look at the configuration file for the control being used to find more information about manually setting this token.

If ProxyAuthScheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of ProxyUser and ProxyPassword.

Data Type

Integer

ProxyAutoDetect Property (SAML Control)

Whether to automatically detect and use proxy system settings, if available.

Syntax

samlcontrol.ProxyAutoDetect[=boolean]

Default Value

False

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is .

Data Type

Boolean

ProxyPassword Property (SAML Control)

A password if authentication is to be used for the proxy.

Syntax

samlcontrol.ProxyPassword[=string]

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ProxyPort Property (SAML Control)

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

samlcontrol.ProxyPort[=integer]

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy ProxyServer (default 80). See the description of the ProxyServer property for details.

Data Type

Integer

ProxyServer Property (SAML Control)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

samlcontrol.ProxyServer[=string]

Default Value

""

Remarks

If a proxy ProxyServer is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the ProxyServer property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

ProxySSL Property (SAML Control)

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

samlcontrol.ProxySSL[=integer]

Possible Values

psAutomatic(0), 
psAlways(1), 
psNever(2), 
psTunnel(3)

Default Value

0

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

Integer

ProxyUser Property (SAML Control)

A username if authentication is to be used for the proxy.

Syntax

samlcontrol.ProxyUser[=string]

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

RelayState Property (SAML Control)

The RelayState for a SAMLRequest or SAMLResponse.

Syntax

samlcontrol.RelayState[=string]

Default Value

""

Remarks

When set before building a request using the BuildAuthnRequest and BuildLogoutRequest methods, this property will set the RelayState parameter. Any value may be specified here and it will be returned exactly as it was sent. This can be used to maintain state within the application, and also may be used for security purposes. The contents of this property are treated as an opaque value.

Data Type

String

SAMLRequestBody Property (SAML Control)

The HTTP body for a SAMLRequest.

Syntax

samlcontrol.SAMLRequestBody

Default Value

""

Remarks

This property contains the generated HTTP body for the request that should be provided to the SAMLRequestURL if required by the selected binding. It is generated alongside the SAMLRequestURL property when calling BuildAuthnRequest or BuildLogoutRequest.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SAMLRequestBodyB.

This property is read-only.

Data Type

Binary String

SAMLRequestAllowCreate Property (SAML Control)

Whether the control will set the AllowCreate attribute in the NameIDPolicy element that is specific to the AuthnRequest element.

Syntax

samlcontrol.SAMLRequestAllowCreate[=boolean]

Default Value

False

Remarks

Whether the control will set the AllowCreate attribute in the NameIDPolicy element that is specific to the AuthnRequest element. When set to , this will inform the Identity Provider that it is allowed to create a new identifier to represent the principal. When set to (default), the Identity Provider should only issue an assertion if an acceptable identifier is already created.

Data Type

Boolean

SAMLRequestConsent Property (SAML Control)

Whether consent from a principal was provided when this request was sent.

Syntax

samlcontrol.SAMLRequestConsent[=integer]

Possible Values

scidUnspecified(0), 
scidObtained(1), 
scidPrior(2), 
scidImplicit(3), 
scidExplicit(4), 
scidUnavailable(5), 
scidInapplicable(6), 
scidCustom(7)

Default Value

0

Remarks

Whether consent from a principal was provided when this request was sent. This typically is set to some URI reference that was used by the application to obtain consent from the principal (user). This setting specifically sets the Consent attribute in the AuthnRequest or LogoutRequest elements in a SAMLRequest.

By default, the scidUnspecified value is used. If a format needs to be used that is not listed here, the snidCustom value can be used instead. When set, the SAMLRequestCustomConsent configuration setting will be used instead.

Data Type

Integer

SAMLRequestDestination Property (SAML Control)

A URI reference for the intended destination for the SAMLRequest.

Syntax

samlcontrol.SAMLRequestDestination[=string]

Default Value

""

Remarks

A URI reference for the intended destination for the SAMLRequest. This is useful to prevent malicious forwarding of responses to unintended recipients.

Data Type

String

SAMLRequestId Property (SAML Control)

A unique Id of the SAMLRequest.

Syntax

samlcontrol.SAMLRequestId[=string]

Default Value

""

Remarks

A unique Id of the SAMLRequest. If left empty before calling BuildAuthnRequest or BuildLogoutRequest, the control will automatically generate an Id. This Id should match the Id of the InResponseTo attribute of the matching SAMLResponse (see SAMLRequestInResponseTo for more information). Due to this, after BuildAuthnRequest or BuildLogoutRequest is used to create a request, this setting (along with the SAMLRequestIssuer property) should be cached for verification purposes.

Data Type

String

SAMLRequestIssuedTime Property (SAML Control)

The time at which the SAMLRequest was issued.

Syntax

samlcontrol.SAMLRequestIssuedTime[=string]

Default Value

""

Remarks

The time at which the SAMLRequest was issued. If not set, the control will use the current time.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

Data Type

String

SAMLRequestIssuer Property (SAML Control)

The issuer for the SAML Request.

Syntax

samlcontrol.SAMLRequestIssuer[=string]

Default Value

""

Remarks

The issuer for the SAML Request. Typically, this should be set to the Entity Id configured for the Identity Provider.

Data Type

String

SAMLRequestNameIdFormat Property (SAML Control)

If supported by the Identity Provider, this setting can be used to tailor the name identifier for the subject in the response to an Authn Request.

Syntax

samlcontrol.SAMLRequestNameIdFormat[=integer]

Possible Values

snidUnspecified(0), 
snidEmail(1), 
snidX509(2), 
snidWindowsDQ(3), 
snidKerberos(4), 
snidEntity(5), 
snidPersistent(6), 
snidTransitent(7), 
snidCustom(8)

Default Value

0

Remarks

If supported by the Identity Provider, this setting can be used to tailor the name identifier for the subject in the response to an Authn Request. This property is not used for Logout Requests.

By default, the snidUnspecified format will be used, which informs the Identity Provider to use whatever name identifier format they prefer. This setting specifically sets the Format attribute in the NameIDPolicy element in an AuthnRequest. If a format needs to be used that is not listed here, the snidCustom value can be used instead. When set, the SAMLRequestCustomNameIdFormat configuration setting will be used instead.

Data Type

Integer

SAMLRequestRequestBinding Property (SAML Control)

The binding that will be used to make the request.

Syntax

samlcontrol.SAMLRequestRequestBinding[=integer]

Possible Values

srbHTTPRedirect(0), 
srbHTTPPost(1)

Default Value

0

Remarks

The binding that will be used to make the request.

By default, the control will use the srbHTTPRedirect binding which provides the SAMLRequest through a query parameter. The srbHTTPRedirect binding will set just the SAMLRequestURL property.

If set to the srbHTTPPost binding, the SAMLResponse is provided in an HTML body that should be used to make a form post request. This will set both the SAMLRequestURL and SAMLRequestBody properties.

Note: This setting does not control the binding of the response, just how the request will be made.

Data Type

Integer

SAMLRequestSelectedEndpoint Property (SAML Control)

This setting only applies to Authn Requests since there can be multiple Assertion Consumer Service (ACS) endpoints per service provider.

Syntax

samlcontrol.SAMLRequestSelectedEndpoint[=integer]

Default Value

-1

Remarks

This setting only applies to Authn Requests since there can be multiple Assertion Consumer Service (ACS) endpoints per service provider. When building an Authn Request, the control will select the the ACS endpoint depending on how SAMLRequestSettings is configured. If SAMLRequestUseDefaultEndpoint is set to , the request will specify that the Identity Provider should use the URI that is configured as the default. If SAMLRequestSelectedEndpoint is set, the control will use that index in the request. Otherwise, the control will select the first URI available in the ServiceProviderURIs properties.

Data Type

Integer

SAMLRequestSignRequest Property (SAML Control)

Whether the SAMLRequest should be signed when building the SAMLRequest using the BuildAuthnRequest or BuildLogoutRequest methods.

Syntax

samlcontrol.SAMLRequestSignRequest[=boolean]

Default Value

False

Remarks

Whether the SAMLRequest should be signed when building the SAMLRequest using the BuildAuthnRequest or BuildLogoutRequest methods. The control will use the certificate set in the ServiceProviderSigningCert property to sign the request.

Data Type

Boolean

SAMLRequestUseDefaultEndpoint Property (SAML Control)

This setting only applies to Authn Requests since there can be multiple Assertion Consumer Service (ACS) endpoints per service provider.

Syntax

samlcontrol.SAMLRequestUseDefaultEndpoint[=boolean]

Default Value

False

Remarks

This setting only applies to Authn Requests since there can be multiple Assertion Consumer Service (ACS) endpoints per service provider. When multiple ACS endpoints are available, a single endpoint can be selected as the default endpoint. When building an Authn Request, the control will select the the ACS endpoint depending on how SAMLRequestSettings is configured. If SAMLRequestUseDefaultEndpoint is set to , the request will specify that the Identity Provider should use the URI that is configured as the default. If SAMLRequestSelectedEndpoint is set, then the control will use that index in the request. Otherwise, the control will select the first URI available in the ServiceProviderURIs properties.

Data Type

Boolean

SAMLRequestURL Property (SAML Control)

The URL for SAMLRequests.

Syntax

samlcontrol.SAMLRequestURL

Default Value

""

Remarks

This property contains the generated URL to an identity provider for a sign-on or logoff service. Depending on the binding used, the URL may contain the SAMLRequest, or the SAMLRequestBody property will be populated to be sent along with the request. It is generated using the BuildAuthnRequest or BuildLogoutRequest methods.

This property is read-only.

Data Type

String

SAMLResponseBody Property (SAML Control)

The HTTP body for the current SAMLResponse.

Syntax

samlcontrol.SAMLResponseBody[=string]

Default Value

""

Remarks

This property can be set before calling the ParseSAMLResponse or ProcessSAMLResponse methods to directly provide the HTTP body of the SAMLResponse that should be parsed. If using the HTTP context, this property is populated with the HTTP body containing the SAMLResponse that was parsed from the HTTP context after calling ParseSAMLResponse or ProcessSAMLResponse.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SAMLResponseBodyB.

Data Type

Binary String

SAMLResponseHeaders Property (SAML Control)

The HTTP headers for the current SAMLResponse.

Syntax

samlcontrol.SAMLResponseHeaders[=string]

Default Value

""

Remarks

This property can be set before calling the ParseSAMLResponse or ProcessSAMLResponse methods to directly provide the HTTP headers that contain the SAMLResponse from the Identity Provider. If using the HTTP context, this property is populated with the HTTP headers that were parsed from the HTTP context after calling ParseSAMLResponse or ProcessSAMLResponse.

Data Type

String

SAMLResponseConsent Property (SAML Control)

Whether consent from a principal was provided when this response was sent.

Syntax

samlcontrol.SAMLResponseConsent

Default Value

""

Remarks

Whether consent from a principal was provided when this response was sent. This typically is set to some URI reference that was used by the application to obtain consent from the principal (user). Some common URI values are:

• Unspecified - urn:oasis:names:tc:SAML:2.0:consent:unspecified
• Obtained - urn:oasis:names:tc:SAML:2.0:consent:obtained
• Prior - urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
• Implicit - urn:oasis:names:tc:SAML:2.0:consent:current-implicit
• Explicit - urn:oasis:names:tc:SAML:2.0:consent:current-explicit
• Unavailable - urn:oasis:names:tc:SAML:2.0:consent:unavailable
• Inapplicable - urn:oasis:names:tc:SAML:2.0:consent:inapplicable

This property is read-only.

Data Type

String

SAMLResponseDestination Property (SAML Control)

A URI reference for the intended destination for the SAMLResponse.

Syntax

samlcontrol.SAMLResponseDestination

Default Value

""

Remarks

A URI reference for the intended destination for the SAMLResponse. This is useful to prevent malicious forwarding of responses to unintended recipients.

This property is read-only.

Data Type

String

SAMLResponseInResponseTo Property (SAML Control)

The Id of the SAMLRequest that requested the Identity Provider to issue this SAMLResponse.

Syntax

samlcontrol.SAMLResponseInResponseTo

Default Value

""

Remarks

The Id of the SAMLRequest that requested the Identity Provider to issue this SAMLResponse. It can be checked with the original Id of the SAMLRequest (see SAMLResponseId for more information).

This property is read-only.

Data Type

String

SAMLResponseIssuedTime Property (SAML Control)

The time at which the SAMLResponse was issued by the Issuer .

Syntax

samlcontrol.SAMLResponseIssuedTime

Default Value

""

Remarks

The time at which the SAMLResponse was issued by the SAMLResponseIssuer.

Time-based values are specified by the SAML specification to be in UTC in the following format: YYYY-MM-DDTHH:mm:ss.sssZ

This property is read-only.

Data Type

String

SAMLResponseIssuer Property (SAML Control)

The Entity Id of the issuer of the SAMLResponse.

Syntax

samlcontrol.SAMLResponseIssuer

Default Value

""

Remarks

The Entity Id of the issuer of the SAMLResponse. Typically, this will be the SAMLResponseEntityId of the Identity Provider.

This property is read-only.

Data Type

String

SAMLResponseResponseContent Property (SAML Control)

The full XML of the SAMLResponse after being parsed or processed by the control after calling ParseHTTPRequest or ProcessHTTPRequest .

Syntax

samlcontrol.SAMLResponseResponseContent[=string]

Default Value

""

Remarks

The full XML of the SAMLResponse after being parsed or processed by the control after calling ParseHTTPRequest or ProcessHTTPRequest. Optionally, this setting can be set to provide a SAMLResponse directly to the control to be used with the ParseSAMLResponse method.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SAMLResponseResponseContentB.

Data Type

Binary String

SAMLResponseResponseId Property (SAML Control)

The unique Id for the SAMLResponse that was created by the Issuer .

Syntax

samlcontrol.SAMLResponseResponseId

Default Value

""

Remarks

The unique Id for the SAMLResponse that was created by the SAMLResponseIssuer.

This property is read-only.

Data Type

String

SAMLResponseResponseType Property (SAML Control)

The type of SAMLResponse that was processed when calling ProcessHTTPRequest or manually parsed using the ParseSAMLResponse method.

Syntax

samlcontrol.SAMLResponseResponseType

Possible Values

srtUnknown(0), 
srtAuthn(1), 
srtLogout(2)

Default Value

0

Remarks

The type of SAMLResponse that was processed when calling ProcessHTTPRequest or manually parsed using the ParseSAMLResponse method.

This property is read-only.

Data Type

Integer

SAMLResponseSigned Property (SAML Control)

Whether the SAMLResponse is signed.

Syntax

samlcontrol.SAMLResponseSigned

Default Value

False

Remarks

Whether the SAMLResponse is signed. If the SAMLResponse contains no signatures, or only the assertion is signed, then this property will be set to .

This property is read-only.

Data Type

Boolean

SAMLResponseStatusCodes Property (SAML Control)

A semicolon-separated list of status codes found in the SAMLResponse.

Syntax

samlcontrol.SAMLResponseStatusCodes

Default Value

""

Remarks

A semicolon-separated list of status codes found in the SAMLResponse. A compliant SAMLResponse will always contain a top-level response with one of the following values.

urn:oasis:names:tc:SAML:2.0:status:Responder;urn:oasis:names:tc:SAML:2.0:status:AuthnFailed

Sometimes, a message is also provided with the Status. See SAMLResponseStatusMessage for more information.

This property is read-only.

Data Type

String

SAMLResponseStatusMessage Property (SAML Control)

The message that was provided in the status of the SAMLResponse.

Syntax

samlcontrol.SAMLResponseStatusMessage

Default Value

""

Remarks

The message that was provided in the status of the SAMLResponse. This property is set alongside the SAMLResponseStatusCodes and can be used to provide more information about the status.

This property is read-only.

Data Type

String

ServiceProviderMetadataAuthnRequestSigned Property (SAML Control)

Whether the generated metadata document will inform the identity provider that this service provider will be sending signed requests.

Syntax

samlcontrol.ServiceProviderMetadataAuthnRequestSigned[=boolean]

Default Value

False

Remarks

Whether the generated metadata document will inform the identity provider that this service provider will be sending signed requests.

Data Type

Boolean

ServiceProviderMetadataEntityId Property (SAML Control)

The Entity Id for this service provider.

Syntax

samlcontrol.ServiceProviderMetadataEntityId[=string]

Default Value

""

Remarks

The Entity Id for this service provider. This is the unique Id that will be used by the Identity Provider and should be unique to this service provider.

Data Type

String

ServiceProviderMetadataMetadataContent Property (SAML Control)

The raw XML document that represents the metadata document for the configured service provider.

Syntax

samlcontrol.ServiceProviderMetadataMetadataContent[=string]

Default Value

""

Remarks

The raw XML document that represents the metadata document for the configured service provider. This property is populated when the BuildServiceMetadata method is used to generate a new document.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .ServiceProviderMetadataMetadataContentB.

Data Type

Binary String

ServiceProviderMetadataSignedMetadata Property (SAML Control)

Whether the control will sign the metadata document when it is being generated.

Syntax

samlcontrol.ServiceProviderMetadataSignedMetadata[=boolean]

Default Value

False

Remarks

Whether the control will sign the metadata document when it is being generated. When the BuildServiceMetadata method is used to generate the metadata document, the control will use the ServiceProviderSigningCert property to sign the document.

Data Type

Boolean

ServiceProviderMetadataSupportedNameIdFormats Property (SAML Control)

A semicolon-separated list of NameId formats that are supported by this service provider.

Syntax

samlcontrol.ServiceProviderMetadataSupportedNameIdFormats[=string]

Default Value

""

Remarks

A semicolon-separated list of NameId formats that are supported by this service provider. Some common values are:

To support both email addresses and Windows domain qualified name, this property would be set to:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress;urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

Data Type

String

ServiceProviderMetadataWantAssertionsSigned Property (SAML Control)

Whether the metadata document will inform the identity provider that this service provider wants issued assertions to be signed.

Syntax

samlcontrol.ServiceProviderMetadataWantAssertionsSigned[=boolean]

Default Value

False

Remarks

Whether the metadata document will inform the identity provider that this service provider wants issued assertions to be signed.

Data Type

Boolean

ServiceProviderSigningCertStore Property (SAML Control)

The name of the certificate store for the client certificate.

Syntax

samlcontrol.ServiceProviderSigningCertStore[=string]

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ServiceProviderSigningCertStoreType property denotes the type of the certificate store specified by ServiceProviderSigningCertStore. If the store is password-protected, specify the password in ServiceProviderSigningCertStorePassword.

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

Designations of certificate stores are platform dependent.

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

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .ServiceProviderSigningCertStoreB.

This property is not available at design time.

Data Type

Binary String

ServiceProviderSigningCertStorePassword Property (SAML Control)

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

Syntax

samlcontrol.ServiceProviderSigningCertStorePassword[=string]

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.

Data Type

String

ServiceProviderSigningCertStoreType Property (SAML Control)

The type of certificate store for this certificate.

Syntax

samlcontrol.ServiceProviderSigningCertStoreType[=integer]

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

This property is not available at design time.

Data Type

Integer

ServiceProviderSigningCertSubject Property (SAML Control)

The subject of the certificate used for client authentication.

Syntax

samlcontrol.ServiceProviderSigningCertSubject[=string]

Default Value

""

Remarks

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 as follows:

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

This property is not available at design time.

Data Type

String

ServiceProviderSigningCertEncoded Property (SAML Control)

The certificate (PEM/Base64 encoded).

Syntax

samlcontrol.ServiceProviderSigningCertEncoded[=string]

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ServiceProviderSigningCertStore and ServiceProviderSigningCertSubject properties also may be used to specify a certificate.

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .ServiceProviderSigningCertEncodedB.

This property is not available at design time.

Data Type

Binary String

ServiceProviderURICount Property (SAML Control)

The number of records in the ServiceProviderURI arrays.

Syntax

samlcontrol.ServiceProviderURICount[=integer]

Default Value

0

Remarks

This property controls the size of the following arrays:

• ServiceProviderURIBindingRef
• ServiceProviderURIBindingType
• ServiceProviderURIIndex
• ServiceProviderURIIsDefault
• ServiceProviderURILocation
• ServiceProviderURIType

The array indices start at 0 and end at ServiceProviderURICount - 1.

This property is not available at design time.

Data Type

Integer

ServiceProviderURIBindingRef Property (SAML Control)

The URI reference for the set BindingType .

Syntax

samlcontrol.ServiceProviderURIBindingRef(ServiceProviderURIIdx)[=string]

Default Value

""

Remarks

The URI reference for the set ServiceProviderURIBindingType. When the ServiceProviderURIBindingType is set, this property will be updated to match. The exception is the subCustom value, which allows for any value to be placed in this property.

If this property is set instead, the control will attempt to set the ServiceProviderURIBindingType property to match. If it can't, subCustom will also be used.

When parsing a metadata document, the control will also use the subCustom value for any binding types that are not recognized by the control.

The ServiceProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the ServiceProviderURICount property.

This property is not available at design time.

Data Type

String

ServiceProviderURIBindingType Property (SAML Control)

The type of binding that is supported for this URI.

Syntax

samlcontrol.ServiceProviderURIBindingType(ServiceProviderURIIdx)[=integer]

Possible Values

subRedirect(0), 
subPost(1), 
subArtifact(2), 
subCustom(3)

Default Value

0

Remarks

The type of binding that is supported for this URI. The control only supports using the HTTP Redirect and HTTP Post bindings. The HTTP Artifact and other bindings are informational, and support for them must be implemented directly.

When setting this property, the ServiceProviderURIBindingRef property will also be updated with the matching URI. The exception is the subCustom value, which allows for any value to be placed in the ServiceProviderURIBindingRef property.

If the ServiceProviderURIBindingRef property is set, during the processing of a metadata document the control will attempt to set this property as well with the matching value. If it can't, subCustom will be used instead.

The ServiceProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the ServiceProviderURICount property.

This property is not available at design time.

Data Type

Integer

ServiceProviderURIIsDefault Property (SAML Control)

Whether this URI is the default URI that should be used for the specific URIType and BindingType combination.

Syntax

samlcontrol.ServiceProviderURIIsDefault(ServiceProviderURIIdx)[=boolean]

Default Value

False

Remarks

Whether this URI is the default URI that should be used for the specific ServiceProviderURIURIType and ServiceProviderURIBindingType combination.

The ServiceProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the ServiceProviderURICount property.

This property is not available at design time.

Data Type

Boolean

ServiceProviderURILocation Property (SAML Control)

The address of the URI.

Syntax

samlcontrol.ServiceProviderURILocation(ServiceProviderURIIdx)[=string]

Default Value

""

Remarks

The address of the URI.

The ServiceProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the ServiceProviderURICount property.

This property is not available at design time.

Data Type

String

ServiceProviderURIIndex Property (SAML Control)

The index for the URI that can be optionally used if multiple URIs of the same URIType and BindingType are provided.

Syntax

samlcontrol.ServiceProviderURIIndex(ServiceProviderURIIdx)[=integer]

Default Value

0

Remarks

The index for the URI that can be optionally used if multiple URIs of the same ServiceProviderURIURIType and ServiceProviderURIBindingType are provided.

The ServiceProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the ServiceProviderURICount property.

This property is not available at design time.

Data Type

Integer

ServiceProviderURIType Property (SAML Control)

The purpose of the URI.

Syntax

samlcontrol.ServiceProviderURIType(ServiceProviderURIIdx)[=integer]

Possible Values

sutSignon(0), 
sutLogout(1), 
sutACS(2)

Default Value

0

Remarks

The purpose of the URI. Possible values are:

The ServiceProviderURIIdx parameter specifies the index of the item in the array. The size of the array is controlled by the ServiceProviderURICount property.

This property is not available at design time.

Data Type

Integer

SSLAcceptServerCertEffectiveDate Property (SAML Control)

The date on which this certificate becomes valid.

Syntax

samlcontrol.SSLAcceptServerCertEffectiveDate

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

SSLAcceptServerCertExpirationDate Property (SAML Control)

The date on which the certificate expires.

Syntax

samlcontrol.SSLAcceptServerCertExpirationDate

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

SSLAcceptServerCertExtendedKeyUsage Property (SAML Control)

A comma-delimited list of extended key usage identifiers.

Syntax

samlcontrol.SSLAcceptServerCertExtendedKeyUsage

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

SSLAcceptServerCertFingerprint Property (SAML Control)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertFingerprint

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

SSLAcceptServerCertFingerprintSHA1 Property (SAML Control)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertFingerprintSHA1

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

SSLAcceptServerCertFingerprintSHA256 Property (SAML Control)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertFingerprintSHA256

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

SSLAcceptServerCertIssuer Property (SAML Control)

The issuer of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertIssuer

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

SSLAcceptServerCertPrivateKey Property (SAML Control)

The private key of the certificate (if available).

Syntax

samlcontrol.SSLAcceptServerCertPrivateKey

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The SSLAcceptServerCertPrivateKey may be available but not exportable. In this case, SSLAcceptServerCertPrivateKey returns an empty string.

This property is read-only.

Data Type

String

SSLAcceptServerCertPrivateKeyAvailable Property (SAML Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

samlcontrol.SSLAcceptServerCertPrivateKeyAvailable

Default Value

False

Remarks

Whether a SSLAcceptServerCertPrivateKey is available for the selected certificate. If SSLAcceptServerCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

Boolean

SSLAcceptServerCertPrivateKeyContainer Property (SAML Control)

The name of the PrivateKey container for the certificate (if available).

Syntax

samlcontrol.SSLAcceptServerCertPrivateKeyContainer

Default Value

""

Remarks

The name of the SSLAcceptServerCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

SSLAcceptServerCertPublicKey Property (SAML Control)

The public key of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertPublicKey

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

SSLAcceptServerCertPublicKeyAlgorithm Property (SAML Control)

The textual description of the certificate's public key algorithm.

Syntax

samlcontrol.SSLAcceptServerCertPublicKeyAlgorithm

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

SSLAcceptServerCertPublicKeyLength Property (SAML Control)

The length of the certificate's public key (in bits).

Syntax

samlcontrol.SSLAcceptServerCertPublicKeyLength

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

Integer

SSLAcceptServerCertSerialNumber Property (SAML Control)

The serial number of the certificate encoded as a string.

Syntax

samlcontrol.SSLAcceptServerCertSerialNumber

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

SSLAcceptServerCertSignatureAlgorithm Property (SAML Control)

The text description of the certificate's signature algorithm.

Syntax

samlcontrol.SSLAcceptServerCertSignatureAlgorithm

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

SSLAcceptServerCertStore Property (SAML Control)

The name of the certificate store for the client certificate.

Syntax

samlcontrol.SSLAcceptServerCertStore[=string]

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The SSLAcceptServerCertStoreType property denotes the type of the certificate store specified by SSLAcceptServerCertStore. If the store is password-protected, specify the password in SSLAcceptServerCertStorePassword.

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

Designations of certificate stores are platform dependent.

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

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLAcceptServerCertStoreB.

Data Type

Binary String

SSLAcceptServerCertStorePassword Property (SAML Control)

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

Syntax

samlcontrol.SSLAcceptServerCertStorePassword[=string]

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.

Data Type

String

SSLAcceptServerCertStoreType Property (SAML Control)

The type of certificate store for this certificate.

Syntax

samlcontrol.SSLAcceptServerCertStoreType[=integer]

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

Data Type

Integer

SSLAcceptServerCertSubjectAltNames Property (SAML Control)

Comma-separated lists of alternative subject names for the certificate.

Syntax

samlcontrol.SSLAcceptServerCertSubjectAltNames

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintMD5 Property (SAML Control)

The MD5 hash of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertThumbprintMD5

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintSHA1 Property (SAML Control)

The SHA-1 hash of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertThumbprintSHA1

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLAcceptServerCertThumbprintSHA256 Property (SAML Control)

The SHA-256 hash of the certificate.

Syntax

samlcontrol.SSLAcceptServerCertThumbprintSHA256

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLAcceptServerCertUsage Property (SAML Control)

The text description of UsageFlags .

Syntax

samlcontrol.SSLAcceptServerCertUsage

Default Value

""

Remarks

The text description of SSLAcceptServerCertUsageFlags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

SSLAcceptServerCertUsageFlags Property (SAML Control)

The flags that show intended use for the certificate.

Syntax

samlcontrol.SSLAcceptServerCertUsageFlags

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of SSLAcceptServerCertUsageFlags is a combination of the following flags:

Please see the SSLAcceptServerCertUsage property for a text representation of SSLAcceptServerCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

Integer

SSLAcceptServerCertVersion Property (SAML Control)

The certificate's version number.

Syntax

samlcontrol.SSLAcceptServerCertVersion

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

SSLAcceptServerCertSubject Property (SAML Control)

The subject of the certificate used for client authentication.

Syntax

samlcontrol.SSLAcceptServerCertSubject[=string]

Default Value

""

Remarks

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 as follows:

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

Data Type

String

SSLAcceptServerCertEncoded Property (SAML Control)

The certificate (PEM/Base64 encoded).

Syntax

samlcontrol.SSLAcceptServerCertEncoded[=string]

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLAcceptServerCertStore and SSLAcceptServerCertSubject properties also may be used to specify a certificate.

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLAcceptServerCertEncodedB.

This property is not available at design time.

Data Type

Binary String

SSLCertEffectiveDate Property (SAML Control)

The date on which this certificate becomes valid.

Syntax

samlcontrol.SSLCertEffectiveDate

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

SSLCertExpirationDate Property (SAML Control)

The date on which the certificate expires.

Syntax

samlcontrol.SSLCertExpirationDate

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

SSLCertExtendedKeyUsage Property (SAML Control)

A comma-delimited list of extended key usage identifiers.

Syntax

samlcontrol.SSLCertExtendedKeyUsage

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

SSLCertFingerprint Property (SAML Control)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

samlcontrol.SSLCertFingerprint

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

SSLCertFingerprintSHA1 Property (SAML Control)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

samlcontrol.SSLCertFingerprintSHA1

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

SSLCertFingerprintSHA256 Property (SAML Control)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

samlcontrol.SSLCertFingerprintSHA256

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

SSLCertIssuer Property (SAML Control)

The issuer of the certificate.

Syntax

samlcontrol.SSLCertIssuer

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

SSLCertPrivateKey Property (SAML Control)

The private key of the certificate (if available).

Syntax

samlcontrol.SSLCertPrivateKey

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The SSLCertPrivateKey may be available but not exportable. In this case, SSLCertPrivateKey returns an empty string.

This property is read-only.

Data Type

String

SSLCertPrivateKeyAvailable Property (SAML Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

samlcontrol.SSLCertPrivateKeyAvailable

Default Value

False

Remarks

Whether a SSLCertPrivateKey is available for the selected certificate. If SSLCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

Boolean

SSLCertPrivateKeyContainer Property (SAML Control)

The name of the PrivateKey container for the certificate (if available).

Syntax

samlcontrol.SSLCertPrivateKeyContainer

Default Value

""

Remarks

The name of the SSLCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

SSLCertPublicKey Property (SAML Control)

The public key of the certificate.

Syntax

samlcontrol.SSLCertPublicKey

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

SSLCertPublicKeyAlgorithm Property (SAML Control)

The textual description of the certificate's public key algorithm.

Syntax

samlcontrol.SSLCertPublicKeyAlgorithm

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

SSLCertPublicKeyLength Property (SAML Control)

The length of the certificate's public key (in bits).

Syntax

samlcontrol.SSLCertPublicKeyLength

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

Integer

SSLCertSerialNumber Property (SAML Control)

The serial number of the certificate encoded as a string.

Syntax

samlcontrol.SSLCertSerialNumber

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

SSLCertSignatureAlgorithm Property (SAML Control)

The text description of the certificate's signature algorithm.

Syntax

samlcontrol.SSLCertSignatureAlgorithm

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

SSLCertStore Property (SAML Control)

The name of the certificate store for the client certificate.

Syntax

samlcontrol.SSLCertStore[=string]

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The SSLCertStoreType property denotes the type of the certificate store specified by SSLCertStore. If the store is password-protected, specify the password in SSLCertStorePassword.

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

Designations of certificate stores are platform dependent.

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

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLCertStoreB.

Data Type

Binary String

SSLCertStorePassword Property (SAML Control)

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

Syntax

samlcontrol.SSLCertStorePassword[=string]

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.

Data Type

String

SSLCertStoreType Property (SAML Control)

The type of certificate store for this certificate.

Syntax

samlcontrol.SSLCertStoreType[=integer]

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

Data Type

Integer

SSLCertSubjectAltNames Property (SAML Control)

Comma-separated lists of alternative subject names for the certificate.

Syntax

samlcontrol.SSLCertSubjectAltNames

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

SSLCertThumbprintMD5 Property (SAML Control)

The MD5 hash of the certificate.

Syntax

samlcontrol.SSLCertThumbprintMD5

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLCertThumbprintSHA1 Property (SAML Control)

The SHA-1 hash of the certificate.

Syntax

samlcontrol.SSLCertThumbprintSHA1

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLCertThumbprintSHA256 Property (SAML Control)

The SHA-256 hash of the certificate.

Syntax

samlcontrol.SSLCertThumbprintSHA256

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLCertUsage Property (SAML Control)

The text description of UsageFlags .

Syntax

samlcontrol.SSLCertUsage

Default Value

""

Remarks

The text description of SSLCertUsageFlags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

SSLCertUsageFlags Property (SAML Control)

The flags that show intended use for the certificate.

Syntax

samlcontrol.SSLCertUsageFlags

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of SSLCertUsageFlags is a combination of the following flags:

Please see the SSLCertUsage property for a text representation of SSLCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

Integer

SSLCertVersion Property (SAML Control)

The certificate's version number.

Syntax

samlcontrol.SSLCertVersion

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

SSLCertSubject Property (SAML Control)

The subject of the certificate used for client authentication.

Syntax

samlcontrol.SSLCertSubject[=string]

Default Value

""

Remarks

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 as follows:

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

Data Type

String

SSLCertEncoded Property (SAML Control)

The certificate (PEM/Base64 encoded).

Syntax

samlcontrol.SSLCertEncoded[=string]

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLCertStore and SSLCertSubject properties also may be used to specify a certificate.

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLCertEncodedB.

This property is not available at design time.

Data Type

Binary String

SSLProvider Property (SAML Control)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

samlcontrol.SSLProvider[=integer]

Possible Values

sslpAutomatic(0), 
sslpPlatform(1), 
sslpInternal(2)

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 control 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 as follows:

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

When Automatic is selected, the platform implementation is used by default. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used.

Data Type

Integer

SSLServerCertEffectiveDate Property (SAML Control)

The date on which this certificate becomes valid.

Syntax

samlcontrol.SSLServerCertEffectiveDate

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

SSLServerCertExpirationDate Property (SAML Control)

The date on which the certificate expires.

Syntax

samlcontrol.SSLServerCertExpirationDate

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

SSLServerCertExtendedKeyUsage Property (SAML Control)

A comma-delimited list of extended key usage identifiers.

Syntax

samlcontrol.SSLServerCertExtendedKeyUsage

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

SSLServerCertFingerprint Property (SAML Control)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

samlcontrol.SSLServerCertFingerprint

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

SSLServerCertFingerprintSHA1 Property (SAML Control)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

samlcontrol.SSLServerCertFingerprintSHA1

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

SSLServerCertFingerprintSHA256 Property (SAML Control)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

samlcontrol.SSLServerCertFingerprintSHA256

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

SSLServerCertIssuer Property (SAML Control)

The issuer of the certificate.

Syntax

samlcontrol.SSLServerCertIssuer

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

SSLServerCertPrivateKey Property (SAML Control)

The private key of the certificate (if available).

Syntax

samlcontrol.SSLServerCertPrivateKey

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The SSLServerCertPrivateKey may be available but not exportable. In this case, SSLServerCertPrivateKey returns an empty string.

This property is read-only.

Data Type

String

SSLServerCertPrivateKeyAvailable Property (SAML Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

samlcontrol.SSLServerCertPrivateKeyAvailable

Default Value

False

Remarks

Whether a SSLServerCertPrivateKey is available for the selected certificate. If SSLServerCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

Boolean

SSLServerCertPrivateKeyContainer Property (SAML Control)

The name of the PrivateKey container for the certificate (if available).

Syntax

samlcontrol.SSLServerCertPrivateKeyContainer

Default Value

""

Remarks

The name of the SSLServerCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

SSLServerCertPublicKey Property (SAML Control)

The public key of the certificate.

Syntax

samlcontrol.SSLServerCertPublicKey

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

SSLServerCertPublicKeyAlgorithm Property (SAML Control)

The textual description of the certificate's public key algorithm.

Syntax

samlcontrol.SSLServerCertPublicKeyAlgorithm

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

SSLServerCertPublicKeyLength Property (SAML Control)

The length of the certificate's public key (in bits).

Syntax

samlcontrol.SSLServerCertPublicKeyLength

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

Integer

SSLServerCertSerialNumber Property (SAML Control)

The serial number of the certificate encoded as a string.

Syntax

samlcontrol.SSLServerCertSerialNumber

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

SSLServerCertSignatureAlgorithm Property (SAML Control)

The text description of the certificate's signature algorithm.

Syntax

samlcontrol.SSLServerCertSignatureAlgorithm

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

SSLServerCertStore Property (SAML Control)

The name of the certificate store for the client certificate.

Syntax

samlcontrol.SSLServerCertStore

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The SSLServerCertStoreType property denotes the type of the certificate store specified by SSLServerCertStore. If the store is password-protected, specify the password in SSLServerCertStorePassword.

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

Designations of certificate stores are platform dependent.

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

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLServerCertStoreB.

This property is read-only.

Data Type

Binary String

SSLServerCertStorePassword Property (SAML Control)

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

Syntax

samlcontrol.SSLServerCertStorePassword

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 read-only.

Data Type

String

SSLServerCertStoreType Property (SAML Control)

The type of certificate store for this certificate.

Syntax

samlcontrol.SSLServerCertStoreType

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

This property is read-only.

Data Type

Integer

SSLServerCertSubjectAltNames Property (SAML Control)

Comma-separated lists of alternative subject names for the certificate.

Syntax

samlcontrol.SSLServerCertSubjectAltNames

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

SSLServerCertThumbprintMD5 Property (SAML Control)

The MD5 hash of the certificate.

Syntax

samlcontrol.SSLServerCertThumbprintMD5

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLServerCertThumbprintSHA1 Property (SAML Control)

The SHA-1 hash of the certificate.

Syntax

samlcontrol.SSLServerCertThumbprintSHA1

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLServerCertThumbprintSHA256 Property (SAML Control)

The SHA-256 hash of the certificate.

Syntax

samlcontrol.SSLServerCertThumbprintSHA256

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

SSLServerCertUsage Property (SAML Control)

The text description of UsageFlags .

Syntax

samlcontrol.SSLServerCertUsage

Default Value

""

Remarks

The text description of SSLServerCertUsageFlags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

SSLServerCertUsageFlags Property (SAML Control)

The flags that show intended use for the certificate.

Syntax

samlcontrol.SSLServerCertUsageFlags

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of SSLServerCertUsageFlags is a combination of the following flags:

Please see the SSLServerCertUsage property for a text representation of SSLServerCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

Integer

SSLServerCertVersion Property (SAML Control)

The certificate's version number.

Syntax

samlcontrol.SSLServerCertVersion

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

SSLServerCertSubject Property (SAML Control)

The subject of the certificate used for client authentication.

Syntax

samlcontrol.SSLServerCertSubject

Default Value

""

Remarks

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 as follows:

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

This property is read-only.

Data Type

String

SSLServerCertEncoded Property (SAML Control)

The certificate (PEM/Base64 encoded).

Syntax

samlcontrol.SSLServerCertEncoded

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLServerCertStore and SSLServerCertSubject properties also may be used to specify a certificate.

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

To read or write binary data to the property, a Variant (Byte Array) version is provided in .SSLServerCertEncodedB.

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

Data Type

Binary String

BuildAuthnRequest Method (SAML Control)

Builds an Authentication Request.

Syntax

samlcontrol.BuildAuthnRequest 

Remarks

Using the SAMLRequestSettings, this method will build a SAMLRequest meant for authenticating the current user. To help keep track of a user's state in your application, the RelayState property can be set to add a RelayState to the request. The value set in the RelayState property will then be present in the response from the Identity Provider. After the request is built, the following properties are set depending on how the SAMLRequestRequestBinding property is set.

• HTTP Redirect - SAMLRequestURL
• HTTP Post - SAMLRequestURL, SAMLRequestBody

The Assertion Consumer Service that should handle the response specified in the request depends on how SAMLRequestSettings is configured. If SAMLRequestUseDefaultEndpoint is set, the request will specify that the Identity Provider should use the URI that is configured as the default. If SAMLRequestSelectedEndpoint is set, the control will use that index in the request. Otherwise, the control will select the first URI set in the ServiceProviderURIs properties.

BuildLogoutRequest Method (SAML Control)

Builds a Single Logout request.

Syntax

samlcontrol.BuildLogoutRequest NameIdentifier

Remarks

This method uses the SAMLRequestSettings property to build a SAMLRequest that is meant for logging out the user identified by the NameIdentifier parameter. To help keep track of a user's state in your application, the RelayState property can be set to add a RelayState to the request. The value set in the RelayState property will then be present in the response from the Identity Provider. Typically, if supported, the identity provider will also issue logout requests for all other sessions that are active for the user. After the request is built, the following properties are set depending on how the SAMLRequestRequestBinding property is set.

• HTTP Redirect - SAMLRequestURL
• HTTP Post - SAMLRequestURL, SAMLRequestBody

BuildServiceMetadata Method (SAML Control)

Builds a metadata document for a service provider.

Syntax

samlcontrol.BuildServiceMetadata 

Remarks

This method uses the ServiceProviderMetadata property to create a new federation metadata document that describes the service provider. This is typically used to provide information about the service provider to the identity provider. The following fields and properties are used:

• ServiceProviderMetadataAuthnRequestSigned
• ServiceProviderMetadataEntityId
• ServiceProviderMetadataSignedMetadata
• ServiceProviderMetadataSupportedNameIdFormats
• ServiceProviderMetadataWantAssertionsSigned
• ServiceProviderSigningCert
• ServiceProviderURIs

Config Method (SAML Control)

Sets or retrieves a configuration setting.

Syntax

samlcontrol.Config ConfigurationString

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the control, 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.

DoEvents Method (SAML Control)

This method processes events from the internal message queue.

Syntax

samlcontrol.DoEvents 

Remarks

When DoEvents is called, the control processes any available events. If no events are available, it waits for a preset period of time, and then returns.

GetAssertionAttribute Method (SAML Control)

Searches for a specific assertion attribute.

Syntax

samlcontrol.GetAssertionAttribute attrName

Remarks

This method will search the current AssertionAttributeInfo properties for a specific attribute. The attrName parameter should be set to the attribute name. The method will then return the value of the attribute with the matching name. If there is more than one value, it will return the values in a semicolon-separated list.

Interrupt Method (SAML Control)

This method interrupts the current method.

Syntax

samlcontrol.Interrupt 

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

LoadIdentityMetadata Method (SAML Control)

Loads an identity provider's metadata document.

Syntax

samlcontrol.LoadIdentityMetadata metadataDocument, validate

Remarks

This method loads in the identity provider's metadata document that is provided through the metadataDocument parameter. After the document has been loaded, the IdentityProviderEncryptingCert, IdentityProviderMetadata, IdentityProviderSigningCert and IdentityProviderURIs properties will be set with the information that is available in the document. If the metadata document is signed and the validate parameter is , the method will also validate the metadata document's signature.

ParseAssertion Method (SAML Control)

Parses an assertion.

Syntax

samlcontrol.ParseAssertion 

Remarks

This method parses the assertion found in the AssertionInfo property. The assertion can either be manually set by setting the AssertionAssertionContent property or by first calling ParseSAMLResponse on a SAMLResponse that contains an assertion. If the method is able to successfully parse the assertion, the AssertionInfo property is populated along with the AssertionAttributeInfo and AssertionAuthnInfo collections, once for each type of statement found in the assertion.

ParseSAMLResponse Method (SAML Control)

Parses a SAMLResponse.

Syntax

samlcontrol.ParseSAMLResponse 

Remarks

This method parses the SAMLResponse found in the SAMLResponseInfo property or from the current HTTP request. The HTTP request can be found through the SAMLResponseBody and SAMLResponseHeaders properties or from the current HTTP Context if accessible. The SAMLResponse can also be manually set by setting the SAMLResponseResponseContent property. If the method is able to successfully parse the SAMLResponse, the information fields in the SAMLResponseInfo property are populated.

To validate a SAMLResponse, see ValidateSAMLResponse.

Additionally, if the SAMLResponseResponseType is srtAuthn, the AssertionAssertionContent property will be populated. See ValidateAssertion and ParseAssertion for more information on validating and parsing the assertion.

ProcessSAMLResponse Method (SAML Control)

Processes the SAMLResponse from the current HTTP request.

Syntax

samlcontrol.ProcessSAMLResponse 

Remarks

This method processes the SAMLResponse found in the current HTTP request and, if applicable, parses and validates the SAMLResponse and optional assertion from the request. The method is equivalent to calling the following methods. See the specific methods for more information.

• ParseSAMLResponse
• ValidateSAMLResponse
• ParseAssertion
• ValidateAssertion

RequestIdentityMetadata Method (SAML Control)

Requests an identity provider's SAML metadata document.

Syntax

samlcontrol.RequestIdentityMetadata URL

Remarks

This method makes an HTTP GET request to get the Identity Provider metadata document from the URL location. Once the document has been retrieved, the method will parse and validate the metadata document. After the document has been parsed, the IdentityProviderEncryptingCert, IdentityProviderMetadata, IdentityProviderSigningCert, and IdentityProviderURIs properties will be populated with the information that is available in the document.

Reset Method (SAML Control)

This method will reset the control.

Syntax

samlcontrol.Reset 

Remarks

This method will reset the control's properties to their default values.

ValidateAssertion Method (SAML Control)

Validates an assertion.

Syntax

samlcontrol.ValidateAssertion 

Remarks

This method validates the assertion found in the AssertionInfo property. The assertion can either be manually set via the AssertionAssertionContent property or by first calling ParseSAMLResponse on a SAMLResponse that contains an assertion. Before attempting this validation, the Assertion event provides an opportunity to configure the control to successfully validate the assertion. If the validation fails at any point, the method will throw an exception with the error code corresponding to the reason. The following checks are performed on the assertion:

To skip certain checks, see AssertionValidationFlags.

ValidateSAMLResponse Method (SAML Control)

Validates a SAMLResponse.

Syntax

samlcontrol.ValidateSAMLResponse 

Remarks

This method validates a SAMLResponse. The SAMLResponse can either be manually set via the SAMLResponseResponseContent property or by first calling ParseSAMLResponse on an HTTP request with a SAMLResponse. Before attempting validation, the SAMLResponse event provides an opportunity to configure the control to successfully validate the SAMLResponse. The following checks are performed on the SAMLResponse:

To skip certain checks, see SAMLResponseValidationFlags. Note that this method does not validate the assertion if one is found within the SAMLResponse. See ValidateAssertion and ParseAssertion for more information on validating and parsing the assertion.

Assertion Event (SAML Control)

Fired when an assertion is validated.

Syntax

Sub samlcontrol_Assertion(Issuer As String, InResponseTo As String)

Remarks

This event is fired before an assertion is validated. The Issuer parameter is the Id of the entity that issued the assertion. The InResponseTo parameter is the Id of the SAMLRequest that requested the assertion. Note that these two parameters are found in the assertion and are not set in the IdentityProviderMetadataEntityId and SAMLRequestId properties respectively. This event allows certain settings to be configured before the validation checks happen to ensure the assertion is validated correctly. See ValidateAssertion for more information about the validation process.

Error Event (SAML Control)

Fired when information is available about errors during data delivery.

Syntax

Sub samlcontrol_Error(ErrorCode As Integer, Description As String)

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the control fails with an error.

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

Log Event (SAML Control)

Fired once for each log message.

Syntax

Sub samlcontrol_Log(LogLevel As Integer, Message As String, LogType As String)

Remarks

This event is fired once for each log message generated by the control. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

Redirect Event (SAML Control)

Fired when a redirection is received from the server.

Syntax

Sub samlcontrol_Redirect(Location As String, Accept As Boolean)

Remarks

This event is fired in cases in which the client can decide whether or not to continue with the redirection process. The Accept parameter is always True by default, but if you do not want to follow the redirection, Accept may be set to False, in which case the control fails with an error. Location is the location to which the client is being redirected. Further control over redirection is provided in the FollowRedirects property.

SAMLResponse Event (SAML Control)

Fired when a SAMLResponse is validated.

Syntax

Sub samlcontrol_SAMLResponse(Issuer As String, InResponseTo As String)

Remarks

This event is fired before is SAMLResponse validated . The Issuer parameter is the Id of the entity that issued the SAMLResponse. The InResponseTo parameter is the Id of the SAMLRequest that requested the SAMLResponse. Note that these two parameters are found in the SAMLResponse and are not set in the IdentityProviderMetadataEntityId and SAMLRequestId properties respectively. This event allows certain settings to be configured before the validation checks happen to ensure the SAMLResponse is validated correctly. See ValidateSAMLResponse for more information about the validation process.

SSLServerAuthentication Event (SAML Control)

Fired after the server presents its certificate to the client.

Syntax

Sub samlcontrol_SSLServerAuthentication(CertEncoded As String, CertSubject As String, CertIssuer As String, Status As String, Accept As Boolean)

Remarks

During this event, the client can decide whether or not to continue with the connection process. 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 or not to continue.

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 Control)

Fired when secure connection progress messages are available.

Syntax

Sub samlcontrol_SSLStatus(Message As String)

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Config Settings (SAML Control)

SAML Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----