SAMLDesktop Control

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

SAMLDesktop

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.

The SAMLDesktop control is intended for desktop applications that need to add web-based SAML SSO support. The control simplifies the process by building the requests, launching the browser, receiving the response, and validating the assertion for your desktop application with a few simple method calls.

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

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

Additionally, the control needs to be configured with the information about the Service Provider (i.e., your application). The ServiceProviderSigningCert, WebServerBindings, WebServerPort, and WebServerSSLEnabled properties can be used to provide information about the Service Provider. These are used by the control to build a valid SAML request and to verify the SAML response and its assertions. These settings should typically be considered constant between multiple requests.

Additionally, to easily supply this information to an Identity Provider, the ServiceProviderMetadata property can be used with the BuildServiceMetadata method to create a SAML Metadata Document that describes your application (the Service Provider) to the Identity Provider.

Usage: Configuring Service Provider Metadata Document

 
 Copy
saml.ServiceProviderSigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*");

saml.WebServerBindings = WebServerBindings.cwbAutomatic;
saml.WebServerPort = 8888;
saml.WebServerEnabled = false;

saml.ServiceProviderMetadata.EntityId = "ServiceProviderId";
saml.ServiceProviderMetadata.AuthnRequestSigned = true;
saml.ServiceProviderMetadata.WantAssertionsSigned = true;

saml.BuildServiceMetadata();

Authentication

Once the ServiceProviderSigningCert and WebServer* properties are configured, the SAMLRequestSettings property can be configured when the application is ready to make an authentication request by calling AuthenticateUser.

Issuer

The SAMLRequestIssuer field is required and be configured to the Entity Id that was provided to the Identity Provider. If the BuildServiceMetadata method was used to create a metadata document that was provided to the Identity Provider, this will match the ServiceProviderMetadataEntityId field. The SAMLRequestIssuer field is also used to validate the SAML response once Identity Provider responds.

Binding

The SAMLRequestBinding field is also required and controls how the control communicates the authentication request to the Identity Provider. This does not control how the Identity Provider responds to the request. The control supports two request bindings: HTTP-Redirect and HTTP-POST.

The HTTP-Redirect binding (default) sends the SAML request using an HTTP redirect and provides the parameters through a query string. Typically, this binding requires that UseDetachedSignatures is set to true as the signature causes the request to become to long if held within the actual request.

The HTTP-POST binding sends the SAML request using an HTTP form post to send the parameters through an HTTP POST instead. Internally, this is done by launching the browser to an HTML page that contains an automatic form post.

SignRequest

The SAMLRequestSignRequest field can be set to true to have the control sign the SAML request using the ServiceProviderSigningCert certificate. f the BuildServiceMetadata method was used to create a metadata document that was provided to the Identity Provider, the ServiceProviderSigningCert should be the same certificate that was set when the metadata document was built.

RelayState

The RelayState property can be set have the control send the RelayState parameter along with the SAML request. When the Identity Provider returns with the SAML response, it will also return a RelayState parameter with the same value.

Once the authentication request has been configured, call AuthenticateUser to start the authentication process.

Usage: Authenticate User

 
 Copy
saml.RequestIdentityMetadata("https://example.com/federationmetadata/federationmetadata.xml");

saml.ServiceProviderSigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*");

saml.WebServerBindings = WebServerBindings.cwbAutomatic;
saml.WebServerPort = 8888;
saml.WebServerEnabled = false;

saml.SAMLRequestSettings.Issuer = "ServiceProviderId"; 
saml.SAMLRequestSettings.Binding = SAMLBindings.sbHTTPRedirect;
saml.SAMLRequestSettings.SignRequest = true;

saml.RelayState = "Relay_State";

saml.AuthenticateUser;

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 AssertionAuthnContextClassReference) and the session identifier created by the Identity Provider for the Service Provider (see AssertionAuthnSessionIndex).

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.

 
 Copy
<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 through the 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:

 
 Copy
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].ValueCount; j++) {
      saml.AssertionAttributeInfo[i].ValueIndex = j;
      verified_emails.Add(saml.AssertionAttributeInfo[i].ValueData);
    }
  }
}

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:

 
 Copy
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.

AssertionAttributeCount Property (SAMLDesktop Control)

The number of records in the AssertionAttribute arrays.

Syntax

samldesktopcontrol.AssertionAttributeCount[=integer]

Default Value

0

Remarks

This property controls the size of the following arrays:

• AssertionAttributeContent
• AssertionAttributeFriendlyName
• AssertionAttributeName
• AssertionAttributeNameFormat
• AssertionAttributeValueCount
• AssertionAttributeValueData
• AssertionAttributeValueIndex

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

This property is not available at design time.

Data Type

Integer

AssertionAttributeContent Property (SAMLDesktop Control)

The raw XML of the attribute.

Syntax

samldesktopcontrol.AssertionAttributeContent(AssertionAttributeIdx)

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 AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

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

Data Type

String

AssertionAttributeFriendlyName Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.AssertionAttributeFriendlyName(AssertionAttributeIdx)

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 AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

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

Data Type

String

AssertionAttributeName Property (SAMLDesktop Control)

The name of the attribute.

Syntax

samldesktopcontrol.AssertionAttributeName(AssertionAttributeIdx)

Default Value

""

Remarks

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

The AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

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

Data Type

String

AssertionAttributeNameFormat Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.AssertionAttributeNameFormat(AssertionAttributeIdx)

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 AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

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

Data Type

String

AssertionAttributeValueCount Property (SAMLDesktop 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

samldesktopcontrol.AssertionAttributeValueCount(AssertionAttributeIdx)

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 AssertionValueIndex for more information.

The AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

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

Data Type

Integer

AssertionAttributeValueData Property (SAMLDesktop Control)

The content of the attribute value selected by ValueIndex .

Syntax

samldesktopcontrol.AssertionAttributeValueData(AssertionAttributeIdx)

Default Value

""

Remarks

The content of the attribute value selected by AssertionValueIndex.

The AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

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

Data Type

String

AssertionAttributeValueIndex Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.AssertionAttributeValueIndex(AssertionAttributeIdx)[=integer]

Default Value

0

Remarks

The index of the attribute value that should be populated in the AssertionValueData property. Valid ranges for this property are from 0 to AssertionValueCount - 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

 
 Copy
<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

 
 Copy
for (int i = 0; i < saml.AssertionAttributeInfo[0].ValueCount; i++) {
  saml.AssertionAttributeInfo[0].ValueIndex = i;
  string attribute_value = saml.AssertionAttributeInfo[0].ValueData;
  //... the rest of the processing
}

The AssertionAttributeIdx parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAttributeCount property.

This property is not available at design time.

Data Type

Integer

AssertionAuthnCount Property (SAMLDesktop Control)

The number of records in the AssertionAuthn arrays.

Syntax

samldesktopcontrol.AssertionAuthnCount[=integer]

Default Value

0

Remarks

This property controls the size of the following arrays:

• AssertionAuthnAuthenticatingAuthorites
• AssertionAuthnContent
• AssertionAuthnContextClassReference
• AssertionAuthnContextDeclaration
• AssertionAuthnInstant
• AssertionAuthnSessionExpiration
• AssertionAuthnSessionIndex

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

This property is not available at design time.

Data Type

Integer

AssertionAuthnAuthenticatingAuthorites Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.AssertionAuthnAuthenticatingAuthorites(AssertionAuthnIndex)

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 AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionAuthnContent Property (SAMLDesktop Control)

The raw XML of the Authn statement.

Syntax

samldesktopcontrol.AssertionAuthnContent(AssertionAuthnIndex)

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 AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionAuthnContextClassReference Property (SAMLDesktop Control)

A predefined URI reference identifying an authentication context class that describes how authentication was provided.

Syntax

samldesktopcontrol.AssertionAuthnContextClassReference(AssertionAuthnIndex)

Default Value

""

Remarks

A predefined 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 AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionAuthnContextDeclaration Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.AssertionAuthnContextDeclaration(AssertionAuthnIndex)

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 AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionAuthnInstant Property (SAMLDesktop Control)

The time at which the authentication took place that was used to issue the assertion.

Syntax

samldesktopcontrol.AssertionAuthnInstant(AssertionAuthnIndex)

Default Value

""

Remarks

The time at which the authentication took place that was used to issue 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

The AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionAuthnSessionExpiration Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.AssertionAuthnSessionExpiration(AssertionAuthnIndex)

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 AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionAuthnSessionIndex Property (SAMLDesktop 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

samldesktopcontrol.AssertionAuthnSessionIndex(AssertionAuthnIndex)

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). Additionally, it is common practice to provide the session index when performing SLO (Single Logout) if supported.

The AssertionAuthnIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AssertionAuthnCount property.

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

Data Type

String

AssertionContent Property (SAMLDesktop Control)

The raw XML of the assertion.

Syntax

samldesktopcontrol.AssertionContent[=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 or ValidateAssertion methods to parse or validate the assertion without the SAML response.

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

Data Type

Binary String

AssertionExpirationDate Property (SAMLDesktop Control)

When the parsed assertion is expired.

Syntax

samldesktopcontrol.AssertionExpirationDate

Default Value

""

Remarks

When the parsed assertion is expired. If expired, a new assertion should be requested from the Identity Provider for the subject. 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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 pf the SAML response, but rather to the assertion itself.

This property is read-only.

Data Type

String

AssertionIsSigned Property (SAMLDesktop Control)

Whether the assertion has been signed by the identity provider.

Syntax

samldesktopcontrol.AssertionIsSigned

Default Value

False

Remarks

Whether the assertion has been signed by the identity provider. The signature is used to verify that the assertion has not been tampered with during transmission. Typically, the assertion is signed along with the SAML response that stores it. This is set to when the Signature element is present in the assertion.

This property is read-only.

Data Type

Boolean

AssertionIssuedTime Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The issuer of the assertion.

Syntax

samldesktopcontrol.AssertionIssuer

Default Value

""

Remarks

The issuer of the assertion. Typically, this is the same as the identity provider that provided the SAML response. The issuer of the SAML response can differ if Identity Provider is an intermediary between the service provider and the final Identity Provider. This property represents the Issuer element in the Assertion element.

This property is read-only.

Data Type

String

AssertionNotBeforeDate Property (SAMLDesktop Control)

The time at which the assertion becomes valid.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The unique name identifier for the subject of the current assertion.

Syntax

samldesktopcontrol.AssertionSubjectNameId

Default Value

""

Remarks

The unique name identifier for the subject of the current assertion. In the SSO SAML profile, the subject is the user that is being authenticated. Since this value is unique to the user (from the Identity Provider) this value is typically used to also identify the user in an application. 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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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

FirewallAutoDetect Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.FirewallAutoDetect[=boolean]

Default Value

False

Remarks

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

Data Type

Boolean

FirewallType Property (SAMLDesktop Control)

The type of firewall to connect through.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

Determines what happens when the server issues a redirect.

Syntax

samldesktopcontrol.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

IdentityProviderEncryptingCertEffectiveDate Property (SAMLDesktop Control)

The date on which this certificate becomes valid.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertEffectiveDate

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertExpirationDate Property (SAMLDesktop Control)

The date on which the certificate expires.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertExpirationDate

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertExtendedKeyUsage Property (SAMLDesktop Control)

A comma-delimited list of extended key usage identifiers.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertExtendedKeyUsage

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertFingerprint Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertFingerprint

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertFingerprintSHA1 Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertFingerprintSHA1

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertFingerprintSHA256 Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertFingerprintSHA256

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertIssuer Property (SAMLDesktop Control)

The issuer of the certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertIssuer

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertPrivateKey Property (SAMLDesktop Control)

The private key of the certificate (if available).

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertPrivateKey

Default Value

""

Remarks

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

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

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

Data Type

String

IdentityProviderEncryptingCertPrivateKeyAvailable Property (SAMLDesktop Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertPrivateKeyAvailable

Default Value

False

Remarks

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

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

Data Type

Boolean

IdentityProviderEncryptingCertPrivateKeyContainer Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertPrivateKeyContainer

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderEncryptingCertPublicKey Property (SAMLDesktop Control)

The public key of the certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertPublicKey

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderEncryptingCertPublicKeyAlgorithm Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertPublicKeyAlgorithm

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertPublicKeyLength Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertPublicKeyLength

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 and not available at design time.

Data Type

Integer

IdentityProviderEncryptingCertSerialNumber Property (SAMLDesktop Control)

The serial number of the certificate encoded as a string.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertSerialNumber

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertSignatureAlgorithm Property (SAMLDesktop Control)

The text description of the certificate's signature algorithm.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertSignatureAlgorithm

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertStore Property (SAMLDesktop Control)

The name of the certificate store for the client certificate.

Syntax

samldesktopcontrol.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 (SAMLDesktop 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

samldesktopcontrol.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 (SAMLDesktop Control)

The type of certificate store for this certificate.

Syntax

samldesktopcontrol.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:

C#
 Copy
certmgr.CertStoreType = CertStoreTypes.cstPKCS11;
certmgr.OnCertList += (s, e) => {
  secKeyBlob = e.CertEncoded;
};
certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll";
certmgr.CertStorePassword = "123456"; //PIN
certmgr.ListStoreCertificates();

sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*");
sftp.SSHUser = "test";
sftp.SSHLogon("myhost", 22);

This property is not available at design time.

Data Type

Integer

IdentityProviderEncryptingCertSubjectAltNames Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertSubjectAltNames

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderEncryptingCertThumbprintMD5 Property (SAMLDesktop Control)

The MD5 hash of the certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertThumbprintMD5

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertThumbprintSHA1 Property (SAMLDesktop Control)

The SHA-1 hash of the certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertThumbprintSHA1

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertThumbprintSHA256 Property (SAMLDesktop Control)

The SHA-256 hash of the certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertThumbprintSHA256

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertUsage Property (SAMLDesktop Control)

The text description of UsageFlags .

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertUsage

Default Value

""

Remarks

The text description of IdentityProviderEncryptingCertUsageFlags.

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 and not available at design time.

Data Type

String

IdentityProviderEncryptingCertUsageFlags Property (SAMLDesktop Control)

The flags that show intended use for the certificate.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertUsageFlags

Default Value

0

Remarks

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

Please see the IdentityProviderEncryptingCertUsage property for a text representation of IdentityProviderEncryptingCertUsageFlags.

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

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

Data Type

Integer

IdentityProviderEncryptingCertVersion Property (SAMLDesktop Control)

The certificate's version number.

Syntax

samldesktopcontrol.IdentityProviderEncryptingCertVersion

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderEncryptingCertSubject Property (SAMLDesktop Control)

The subject of the certificate used for client authentication.

Syntax

samldesktopcontrol.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=example@email.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 (SAMLDesktop Control)

The certificate (PEM/Base64 encoded).

Syntax

samldesktopcontrol.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

IdentityProviderMetadataContent Property (SAMLDesktop Control)

The raw metadata for the identity provider.

Syntax

samldesktopcontrol.IdentityProviderMetadataContent[=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 .IdentityProviderMetadataContentB.

Data Type

Binary String

IdentityProviderMetadataEntityId Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 SAML response or assertion.

Data Type

String

IdentityProviderMetadataExpirationDate Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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

IdentityProviderMetadataRequestsSignedAuthnRequests Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderMetadataRequestsSignedAuthnRequests[=boolean]

Default Value

False

Remarks

Whether the identity provider requests that authentication (Authn) requests are signed. If , the SignRequest setting should be set to true before initiating authentication.

Data Type

Boolean

IdentityProviderMetadataSignedMetadata Property (SAMLDesktop Control)

Whether the identity provider's parsed metadata is signed.

Syntax

samldesktopcontrol.IdentityProviderMetadataSignedMetadata

Default Value

False

Remarks

Whether the identity provider's parsed metadata is signed. This signature is used to insure that the metadata was not tampered with during transit.

This property is read-only.

Data Type

Boolean

IdentityProviderMetadataSupportedAttributeProfiles Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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

IdentityProviderSigningCertEffectiveDate Property (SAMLDesktop Control)

The date on which this certificate becomes valid.

Syntax

samldesktopcontrol.IdentityProviderSigningCertEffectiveDate

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertExpirationDate Property (SAMLDesktop Control)

The date on which the certificate expires.

Syntax

samldesktopcontrol.IdentityProviderSigningCertExpirationDate

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertExtendedKeyUsage Property (SAMLDesktop Control)

A comma-delimited list of extended key usage identifiers.

Syntax

samldesktopcontrol.IdentityProviderSigningCertExtendedKeyUsage

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertFingerprint Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertFingerprint

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertFingerprintSHA1 Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertFingerprintSHA1

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertFingerprintSHA256 Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertFingerprintSHA256

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertIssuer Property (SAMLDesktop Control)

The issuer of the certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertIssuer

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertPrivateKey Property (SAMLDesktop Control)

The private key of the certificate (if available).

Syntax

samldesktopcontrol.IdentityProviderSigningCertPrivateKey

Default Value

""

Remarks

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

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

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

Data Type

String

IdentityProviderSigningCertPrivateKeyAvailable Property (SAMLDesktop Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertPrivateKeyAvailable

Default Value

False

Remarks

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

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

Data Type

Boolean

IdentityProviderSigningCertPrivateKeyContainer Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertPrivateKeyContainer

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderSigningCertPublicKey Property (SAMLDesktop Control)

The public key of the certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertPublicKey

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderSigningCertPublicKeyAlgorithm Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertPublicKeyAlgorithm

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertPublicKeyLength Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertPublicKeyLength

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 and not available at design time.

Data Type

Integer

IdentityProviderSigningCertSerialNumber Property (SAMLDesktop Control)

The serial number of the certificate encoded as a string.

Syntax

samldesktopcontrol.IdentityProviderSigningCertSerialNumber

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertSignatureAlgorithm Property (SAMLDesktop Control)

The text description of the certificate's signature algorithm.

Syntax

samldesktopcontrol.IdentityProviderSigningCertSignatureAlgorithm

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertStore Property (SAMLDesktop Control)

The name of the certificate store for the client certificate.

Syntax

samldesktopcontrol.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 (SAMLDesktop 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

samldesktopcontrol.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 (SAMLDesktop Control)

The type of certificate store for this certificate.

Syntax

samldesktopcontrol.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:

C#
 Copy
certmgr.CertStoreType = CertStoreTypes.cstPKCS11;
certmgr.OnCertList += (s, e) => {
  secKeyBlob = e.CertEncoded;
};
certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll";
certmgr.CertStorePassword = "123456"; //PIN
certmgr.ListStoreCertificates();

sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*");
sftp.SSHUser = "test";
sftp.SSHLogon("myhost", 22);

This property is not available at design time.

Data Type

Integer

IdentityProviderSigningCertSubjectAltNames Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.IdentityProviderSigningCertSubjectAltNames

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderSigningCertThumbprintMD5 Property (SAMLDesktop Control)

The MD5 hash of the certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertThumbprintMD5

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertThumbprintSHA1 Property (SAMLDesktop Control)

The SHA-1 hash of the certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertThumbprintSHA1

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertThumbprintSHA256 Property (SAMLDesktop Control)

The SHA-256 hash of the certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertThumbprintSHA256

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertUsage Property (SAMLDesktop Control)

The text description of UsageFlags .

Syntax

samldesktopcontrol.IdentityProviderSigningCertUsage

Default Value

""

Remarks

The text description of IdentityProviderSigningCertUsageFlags.

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 and not available at design time.

Data Type

String

IdentityProviderSigningCertUsageFlags Property (SAMLDesktop Control)

The flags that show intended use for the certificate.

Syntax

samldesktopcontrol.IdentityProviderSigningCertUsageFlags

Default Value

0

Remarks

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

Please see the IdentityProviderSigningCertUsage property for a text representation of IdentityProviderSigningCertUsageFlags.

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

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

Data Type

Integer

IdentityProviderSigningCertVersion Property (SAMLDesktop Control)

The certificate's version number.

Syntax

samldesktopcontrol.IdentityProviderSigningCertVersion

Default Value

""

Remarks

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

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

Data Type

String

IdentityProviderSigningCertSubject Property (SAMLDesktop Control)

The subject of the certificate used for client authentication.

Syntax

samldesktopcontrol.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=example@email.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 (SAMLDesktop Control)

The certificate (PEM/Base64 encoded).

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The number of records in the IdentityProviderURI arrays.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The URI reference for the set BindingType .

Syntax

samldesktopcontrol.IdentityProviderURIBindingRef(IdentityProviderURIIdx)[=string]

Default Value

"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

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

The type of binding that is supported for this URI.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The address of the URI.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The purpose of the URI.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

The RelayState for a SAML request or response.

Syntax

samldesktopcontrol.RelayState[=string]

Default Value

""

Remarks

When set before building a request using the AuthenticateUser method, this property will set the RelayState parameter that is provided with the SAML request. 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.

After receiving the response from the Identity Provider, this setting will then be set to match the RelayState parameter if it was provided by the Identity Provider. This does not work if the SAML response was provided directly to the methods using the SAMLResponseInfo property.

Data Type

String

ReturnURL Property (SAMLDesktop Control)

The URL where the user (browser) returns after authenticating with the Identity Provider.

Syntax

samldesktopcontrol.ReturnURL[=string]

Default Value

""

Remarks

Typically this property will be automatically set by the component when calling AuthenticateUser or BuildServiceMetadata based on how the WebServerBindings, WebServerPort, and WebServerSSLEnabled properties are configured. Additionally, the WebServerHost configuration setting can be specify the domain which is localhost by default. For example, some service prefer the use of 127.0.0.1.

When manually validating a SAML response or assertion, this setting will need to be set for validation to succeeded.

Can be set to override the URL that is provided in the authenticate request or metadata if needed. For example, if using a relay server to pass information from the Identity Provider to the application, ReturnURL should be set to the location of the relay server. The relay server should then pass the information to the embedded web server.

Data Type

String

SAMLRequestAllowCreate Property (SAMLDesktop Control)

This setting is only used for authentication requests.

Syntax

samldesktopcontrol.SAMLRequestAllowCreate[=boolean]

Default Value

False

Remarks

This setting is only used for authentication requests. It controls 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

SAMLRequestBinding Property (SAMLDesktop Control)

This setting controls the binding that will be used to make the request.

Syntax

samldesktopcontrol.SAMLRequestBinding[=integer]

Possible Values

sbHTTPRedirect(0), 
sbHTTPPost(1)

Default Value

0

Remarks

This setting controls the binding that will be used to make the request.

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

If set to the sbHTTPPost binding, the SAMLRequest value 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

SAMLRequestConsent Property (SAMLDesktop Control)

This setting specifies whether consent from a principal was provided when this request was sent.

Syntax

samldesktopcontrol.SAMLRequestConsent[=integer]

Possible Values

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

Default Value

0

Remarks

This setting specifies 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 SAML request.

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 CustomConsent configuration setting will be used instead.

Data Type

Integer

SAMLRequestDestination Property (SAMLDesktop Control)

This setting specifies a URI reference for the intended destination for the SAML request.

Syntax

samldesktopcontrol.SAMLRequestDestination[=string]

Default Value

""

Remarks

This setting specifies a URI reference for the intended destination for the SAML request. This is useful to prevent malicious forwarding of responses to unintended recipients. If left blank the control will set this to match the endpoint selected by the control. See SAMLRequestUseDefaultEndpoint and SAMLRequestSelectedEndpoint for more information.

Data Type

String

SAMLRequestId Property (SAMLDesktop Control)

This setting specifies the unique Id of the SAML request.

Syntax

samldesktopcontrol.SAMLRequestId[=string]

Default Value

""

Remarks

This setting specifies the unique Id of the SAML request.

When building a SAML request using the BuildAuthnRequest or BuildLogoutRequest methods, the control will use this value for the Id attribute in the request. If left empty before building the request, the control will generate a new one.

When validating a SAML response or assertion, this property is used to provide the Id of the request to the control. The SAML response and assertion both have an InResponseTo attribute that needs to match this property. See SAMLRequestInResponseTo for more information. This is important, to check to ensure that the SAML response or assertion was in response to a request that was made by this application.

Due to needing the value for validation purposes this setting, (along with the SAMLRequestIssuer property) should be cached in a secure location for later. This Id should match the Id of the InResponseTo attribute of the matching SAMLResponse . Due to this, after BuildAuthnRequest or BuildLogoutRequest is used to create a request, this setting

Data Type

String

SAMLRequestIssuedTime Property (SAMLDesktop Control)

This setting sets the time at which the SAML request was issued.

Syntax

samldesktopcontrol.SAMLRequestIssuedTime[=string]

Default Value

""

Remarks

This setting sets the time at which the SAML request 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 (SAMLDesktop Control)

The issuer for the SAML request.

Syntax

samldesktopcontrol.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 (SAMLDesktop Control)

This setting is only used for authentication requests.

Syntax

samldesktopcontrol.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

This setting is only used for authentication requests. If supported by the Identity Provider, this setting can be used to tailor the name identifier for the subject in the response to an authentication request.

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 authentication request. If a format needs to be used that is not listed here, the snidCustom value can be used instead. When set, the CustomNameIdFormat configuration setting will be used instead.

Data Type

Integer

SAMLRequestSelectedEndpoint Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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

SAMLRequestSessionIndex Property (SAMLDesktop Control)

This setting only applies when building SAML logout requests.

Syntax

samldesktopcontrol.SAMLRequestSessionIndex[=string]

Default Value

""

Remarks

This setting only applies when building SAML logout requests. SAMLRequestSessionIndex identifies the current session of the user that is being ended when the BuildLogoutRequest method is called. When the ProcessSAMLResponse or ParseAssertion methods are called, the SAMLRequestSessionIndex property will be set to the session index from the Identity Provider. Providing the session index with the logout request will typically cause the Identity Provider to send logout requests to all participating services that are also part of the session.

Data Type

String

SAMLRequestSignRequest Property (SAMLDesktop Control)

This setting controls whether the SAML request should be signed when using the BuildAuthnRequest or BuildLogoutRequest methods.

Syntax

samldesktopcontrol.SAMLRequestSignRequest[=boolean]

Default Value

False

Remarks

This setting controls whether the SAML request should be signed when 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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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

SAMLResponseConsent Property (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.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 matches the method 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:2.0:consent:prior
• 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

SAMLResponseContent Property (SAMLDesktop Control)

The full XML of the SAML response after being parsed or processed by the control.

Syntax

samldesktopcontrol.SAMLResponseContent[=string]

Default Value

""

Remarks

The full XML of the SAML response after being parsed or processed by the control. Optionally, this setting can be set to provide a SAML response directly to the control to be parsed or processed.

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

Data Type

Binary String

SAMLResponseDestination Property (SAMLDesktop Control)

A URI reference for the intended destination for the SAML response.

Syntax

samldesktopcontrol.SAMLResponseDestination

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SAMLResponseId Property (SAMLDesktop Control)

The unique Id for the SAML response that was created by the Issuer .

Syntax

samldesktopcontrol.SAMLResponseId

Default Value

""

Remarks

The unique Id for the SAML response that was created by the SAMLResponseIssuer.

This property is read-only.

Data Type

String

SAMLResponseInResponseTo Property (SAMLDesktop Control)

The Id of the SAML request that requested the Identity Provider to issue this SAML response.

Syntax

samldesktopcontrol.SAMLResponseInResponseTo

Default Value

""

Remarks

The Id of the SAML request that requested the Identity Provider to issue this SAML response. The control validates this property against the original Id of the SAML request which SAMLResponseId should be set to.

This property is read-only.

Data Type

String

SAMLResponseIssuedTime Property (SAMLDesktop Control)

The time at which the SAML response was issued by the Issuer .

Syntax

samldesktopcontrol.SAMLResponseIssuedTime

Default Value

""

Remarks

The time at which the SAML response 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 (SAMLDesktop Control)

The Entity Id of the issuer of the SAML response.

Syntax

samldesktopcontrol.SAMLResponseIssuer

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

SAMLResponseType Property (SAMLDesktop Control)

The type of SAML response that was parsed or processed.

Syntax

samldesktopcontrol.SAMLResponseType

Possible Values

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

Default Value

0

Remarks

The type of SAML response that was parsed or processed.

This property is read-only.

Data Type

Integer

SAMLResponseSigned Property (SAMLDesktop Control)

Whether the SAML response is signed.

Syntax

samldesktopcontrol.SAMLResponseSigned

Default Value

False

Remarks

Whether the SAML response is signed. If the SAML response 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 (SAMLDesktop Control)

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

Syntax

samldesktopcontrol.SAMLResponseStatusCodes

Default Value

""

Remarks

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