SAML Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

nsoftware.CloudSSO.SAML

Remarks

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

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

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

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

Setup

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

Usage: Requesting and Reloading the Identity Provider Metadata Document

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

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

Usage: Configuring Service Provider Metadata

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

Authentication Request

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

Usage: Building an Authn Request

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

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

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

Authentication Response

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

To handle an incoming HTTP request that contains the SAML response, the ProcessSAMLResponse or ParseSAMLResponse methods can be used. These methods will attempt to read the HTTP request headers and body from the current HttpContext that contains the SAML response. The component may be used within any .NET Standard-compatible platform, including .NET Core and ASP.NET Core. When using SAML within a .NET 6+ application, the component needs the HttpContext provided to it in the constructor of the SAML class. For instance: SAML saml = new SAML(HttpContext); To provide the HTTP headers and body that contain the SAML response directly to the component, the SAMLResponseHeaders and SAMLResponseBody properties can be set before calling ParseSAMLResponse or ProcessSAMLResponse. For example:

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

If working in a framework that does not provide the raw HTTP request that contains the SAML response to the application, the ResponseContent can be set directly with the SAML response before calling the ProcessSAMLResponse or ParseSAMLResponse methods.

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

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

Assertions

The SAML 2.0 specification gives Identity Providers many different options for what can be included in an assertion. In the Web SSO profile, typically the assertion will contain the Issuer, Signature, Subject, Conditions, AttributeStatement, and AuthnStatement. Information found from the Issuer, Signature, Subject, and Conditions sections of the assertion can be found in the AssertionInfo property. Along with providing information about the assertion, these fields are also used to verify the assertion. An important field to note is the SubjectNameId field. This field 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 ContextClassReference) and the session identifier created by the Identity Provider for the Service Provider (see SessionIndex).

Assertion Attributes

Along with the SubjectNameId, 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 collection will be populated with each attribute found. Each attribute has a name and one or more values. For example, take the following attribute that describes a list of emails attached to the user.

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

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

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

Property List

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

Method List

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

Event List

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

Config Settings

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

AssertionAttributeInfo Property (SAML Component)

Information about the attributes found in an assertion.

Syntax

• C#
• VB.NET

public AssertionAttributeList AssertionAttributeInfo { get; }

Public Property AssertionAttributeInfo As AssertionAttributeList

Remarks

This collection provides the information for each attribute in all of the AttributeStatement elements from the parsed assertion found in the AssertionInfo property. The ProcessSAMLResponse and ParseAssertion methods can set this collection.

AssertionAuthnInfo Property (SAML Component)

Information about the AuthnStatement in an assertion.

Syntax

• C#
• VB.NET

public AuthnStatementList AssertionAuthnInfo { get; }

Public Property AssertionAuthnInfo As AuthnStatementList

Remarks

This property provides information about the AuthnStatement from the parsed assertion in the AssertionInfo property. The ProcessSAMLResponse and ParseAssertion methods can set this collection.

AssertionInfo Property (SAML Component)

Information about a parsed assertion.

Syntax

• C#
• VB.NET

public AssertionInfo AssertionInfo { get; set; }

Public Property AssertionInfo As AssertionInfo

Remarks

This property provides information about the recently parsed assertion. It can also be used to provide a cached assertion manually to the component. The ProcessSAMLResponse and ParseAssertion methods can set this collection.

Firewall Property (SAML Component)

A set of properties related to firewall access.

Syntax

• C#
• VB.NET

public Firewall Firewall { get; set; }

Public Property Firewall As Firewall

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the component will attempt to connect.

FollowRedirects Property (SAML Component)

Determines what happens when the server issues a redirect.

Syntax

• C#
• VB.NET

public SAMLFollowRedirects FollowRedirects { get; set; }

enum SAMLFollowRedirects {
  frNever,
  frAlways,
  frSameScheme
}

Public Property FollowRedirects As SamlFollowRedirects

Enum SAMLFollowRedirects
  frNever
  frAlways
  frSameScheme
End Enum

Default Value

0

Remarks

This property determines what happens when the server issues a redirect. Normally, the component 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 component throws an exception.

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 component throws an exception instead.

IdentityProviderEncryptingCert Property (SAML Component)

The certificate used to decrypt responses from an identity provider.

Syntax

• C#
• VB.NET

public Certificate IdentityProviderEncryptingCert { get; set; }

Public Property IdentityProviderEncryptingCert As Certificate

Remarks

This property contains the certificate used to decrypt if encryption is found while parsing. This certificate will need to have access to its private key to be able to successfully decrypt.

This property is not available at design time.

IdentityProviderMetadata Property (SAML Component)

Information about the identity provider.

Syntax

• C#
• VB.NET

public IdentityProviderMetadata IdentityProviderMetadata { get; set; }

Public Property IdentityProviderMetadata As IdentityProviderMetadata

Remarks

This property contains information about the identity provider that is used when building requests or validating SAML responses or assertions. This can be set manually, by calling the LoadIdentityMetadata method, or by retrieving it using the RequestIdentityMetadata method.

IdentityProviderSigningCert Property (SAML Component)

The certificate used to verify signatures in responses from an identity provider.

Syntax

• C#
• VB.NET

public Certificate IdentityProviderSigningCert { get; set; }

Public Property IdentityProviderSigningCert As Certificate

Remarks

This property contains the public certificate from the identity provider that will be used to verify any signatures found. Typically, this certificate is provided by the identity provider's SAML metadata document. See LoadIdentityMetadata and RequestIdentityMetadata for more information.

This property is not available at design time.

IdentityProviderURIs Property (SAML Component)

The URIs for an identity provider.

Syntax

• C#
• VB.NET

public URIList IdentityProviderURIs { get; }

Public Property IdentityProviderURIs As URIList

Remarks

This collection contains a list of URIs that are supported by the Identity Provider. Typically, these URIs are provided by the identity provider's SAML metadata document. See LoadIdentityMetadata and RequestIdentityMetadata for more information.

LogoutRequestBody Property (SAML Component)

The HTTP body for a SAML logout request.

Syntax

• C#
• VB.NET

public string LogoutRequestBody { get; set; }
public byte[] LogoutRequestBodyB { get; set; }

Public Property LogoutRequestBody As String
Public Property LogoutRequestBodyB As Byte()

Default Value

""

Remarks

This property can be set before calling the ParseLogoutRequest or ProcessLogoutRequest methods to directly provide the HTTP body of a logout request that should be parsed or processed. If using the HTTP context, this property is populated with the HTTP body containing the logout request that was parsed from the HTTP context after calling ParseLogoutRequest or ProcessLogoutRequest.

LogoutRequestHeaders Property (SAML Component)

The HTTP headers for a SAML logout request.

Syntax

• C#
• VB.NET

public string LogoutRequestHeaders { get; set; }

Public Property LogoutRequestHeaders As String

Default Value

""

Remarks

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

LogoutRequestInfo Property (SAML Component)

Information about a SAML logout request.

Syntax

• C#
• VB.NET

public LogoutRequestInfo LogoutRequestInfo { get; set; }

Public Property LogoutRequestInfo As LogoutRequestInfo

Remarks

This property provides information about the recently parsed logout request. It can be set when calling the ProcessLogoutRequest or ParseLogoutRequest methods. It can also be used to provide a stored logout request manually to the component. This property is not set with the information about a logout request built by the component by calling the BuildLogoutRequest method.

LogoutResponseBody Property (SAML Component)

The HTTP body for a built logout response.

Syntax

• C#
• VB.NET

public string LogoutResponseBody { get; }
public byte[] LogoutResponseBodyB { get; }

Public ReadOnly Property LogoutResponseBody As String
Public ReadOnly Property LogoutResponseBodyB As Byte()

Default Value

""

Remarks

This property contains the generated HTTP body for the response that should be provided to the LogoutResponseURL if required by the selected binding. It is generated alongside the LogoutResponseURL property when calling BuildLogoutResponse.

This property is read-only.

LogoutResponseSettings Property (SAML Component)

The settings for a SAML logout response.

Syntax

• C#
• VB.NET

public LogoutResponseSettings LogoutResponseSettings { get; set; }

Public Property LogoutResponseSettings As LogoutResponseSettings

Remarks

This property is used to configure the SAML logout response built by the BuildLogoutResponse method.

LogoutResponseURL Property (SAML Component)

The URL for SAML logout responses.

Syntax

• C#
• VB.NET

public string LogoutResponseURL { get; }

Public ReadOnly Property LogoutResponseURL As String

Default Value

""

Remarks

This property contains the generated URL to an identity provider for a logoff service. Depending on the binding used, the URL may contain the SAMLResponse parameter, or the LogoutResponseBody property will be populated to be sent along with the response. It is generated using the BuildLogoutResponse method.

This property is read-only.

Proxy Property (SAML Component)

A set of properties related to proxy access.

Syntax

• C#
• VB.NET

public Proxy Proxy { get; set; }

Public Property Proxy As Proxy

Remarks

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

RelayState Property (SAML Component)

The RelayState for a SAML request or response.

Syntax

• C#
• VB.NET

public string RelayState { get; set; }

Public Property RelayState As String

Default Value

""

Remarks

When set before building a request using the BuildAuthnRequest and BuildLogoutRequest methods, 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 calling ProcessSAMLResponse or ParseSAMLResponse on an HTTP request that contains a response from the Identity Provider, this setting will also 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.

SAMLRequestBody Property (SAML Component)

The HTTP body for a SAML request.

Syntax

• C#
• VB.NET

public string SAMLRequestBody { get; }
public byte[] SAMLRequestBodyB { get; }

Public ReadOnly Property SAMLRequestBody As String
Public ReadOnly Property SAMLRequestBodyB As Byte()

Default Value

""

Remarks

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

This property is read-only.

SAMLRequestSettings Property (SAML Component)

The settings for a SAML request.

Syntax

• C#
• VB.NET

public SAMLRequestSettings SAMLRequestSettings { get; set; }

Public Property SAMLRequestSettings As SAMLRequestSettings

Remarks

This property is used to configure the SAML request built by the BuildAuthnRequest or BuildLogoutRequest methods.

SAMLRequestURL Property (SAML Component)

The URL for SAML requests.

Syntax

• C#
• VB.NET

public string SAMLRequestURL { get; }

Public ReadOnly Property SAMLRequestURL As String

Default Value

""

Remarks

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

This property is read-only.

SAMLResponseBody Property (SAML Component)

The HTTP body for a SAML response.

Syntax

• C#
• VB.NET

public string SAMLResponseBody { get; set; }
public byte[] SAMLResponseBodyB { get; set; }

Public Property SAMLResponseBody As String
Public Property SAMLResponseBodyB As Byte()

Default Value

""

Remarks

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

SAMLResponseHeaders Property (SAML Component)

The HTTP headers for a SAML response.

Syntax

• C#
• VB.NET

public string SAMLResponseHeaders { get; set; }

Public Property SAMLResponseHeaders As String

Default Value

""

Remarks

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

SAMLResponseInfo Property (SAML Component)

Information about a SAML response.

Syntax

• C#
• VB.NET

public SAMLResponseInfo SAMLResponseInfo { get; set; }

Public Property SAMLResponseInfo As SAMLResponseInfo

Remarks

This property provides information about the recently parsed SAML response. It can be set when calling the ProcessSAMLResponse or ParseSAMLResponse methods. It can also be used to provide a stored SAML response manually to the component.

ServiceProviderMetadata Property (SAML Component)

Information about a service provider's SAML metadata document.

Syntax

• C#
• VB.NET

public ServiceProviderMetadata ServiceProviderMetadata { get; set; }

Public Property ServiceProviderMetadata As ServiceProviderMetadata

Remarks

This property contains the settings needed to generate the service provider's (this application) SAML metadata document to be given to the identity provider.

ServiceProviderSigningCert Property (SAML Component)

The certificate used by the service provider when signing a SAMLRequest or SAML metadata document.

Syntax

• C#
• VB.NET

public Certificate ServiceProviderSigningCert { get; set; }

Public Property ServiceProviderSigningCert As Certificate

Remarks

This property contains the certificate that should be used if the SAML request (Authn and Logout) needs to be signed when calling BuildAuthnRequest or BuildLogoutRequest. Additionally, if required, this certificate is used to sign a SAML metadata document when calling the BuildServiceMetadata method.

This property is not available at design time.

ServiceProviderURIs Property (SAML Component)

Information about the URIs for a service provider.

Syntax

• C#
• VB.NET

public URIList ServiceProviderURIs { get; }

Public Property ServiceProviderURIs As URIList

Remarks

This collection contains a list of URIs that are used by the service provider (this application) and should be provided to the identity provider. This is used when building the service provider's SAML metadata document during the BuildServiceMetadata method. When building an authentication request using the BuildAuthnRequest method, the component will use the first URI from this collection if UseDefaultEndpoint and SelectedEndpoint are not set. When validating a SAML response or assertion, these URIs are used to validate the destination or recipient attributes respectively. See ValidateSAMLResponse and ValidateAssertion for more information.

SSLAcceptServerCert Property (SAML Component)

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

Syntax

• C#
• VB.NET

public Certificate SSLAcceptServerCert { get; set; }

Public Property SSLAcceptServerCert As Certificate

Remarks

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

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

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

SSLCert Property (SAML Component)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

• C#
• VB.NET

public Certificate SSLCert { get; set; }

Public Property SSLCert As Certificate

Remarks

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

SSLProvider Property (SAML Component)

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

Syntax

• C#
• VB.NET

public SAMLSSLProviders SSLProvider { get; set; }

enum SAMLSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Public Property SSLProvider As SamlSSLProviders

Enum SAMLSSLProviders
  sslpAutomatic
  sslpPlatform
  sslpInternal
End Enum

Default Value

0

Remarks

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

Possible values are as follows:

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

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

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

SSLServerCert Property (SAML Component)

The server certificate for the last established connection.

Syntax

• C#
• VB.NET

public Certificate SSLServerCert { get; }

Public ReadOnly Property SSLServerCert As Certificate

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

BuildAuthnRequest Method (SAML Component)

Builds an Authentication Request.

Syntax

• C#
• VB.NET

public void BuildAuthnRequest();

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

Public Sub BuildAuthnRequest()

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

Remarks

Using the SAMLRequestSettings, this method will build a SAML request meant for authenticating the current user. To help keep track of a user's state in your application, the RelayState property can be set to add a RelayState to the request. The value set in the RelayState property will then be present in the response from the Identity Provider.

The Assertion Consumer Service (ACS) that should handle the response specified in the request depends on how SAMLRequestSettings is configured. If UseDefaultEndpoint is set, the request will specify that the Identity Provider should use the URI that is configured as the default. If SelectedEndpoint is set, the component will use that index in the request. Otherwise, the component will select the first URI set in the ServiceProviderURIs collection.

After the request is built, the following properties are set depending on how the RequestBinding field is set.

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

Example: Redirect Binding

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

Example: HTML Post Binding

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

BuildLogoutRequest Method (SAML Component)

Builds a Single Logout request.

Syntax

• C#
• VB.NET

public void BuildLogoutRequest(string nameIdentifier);

Async Version
public async Task BuildLogoutRequest(string nameIdentifier);
public async Task BuildLogoutRequest(string nameIdentifier, CancellationToken cancellationToken);

Public Sub BuildLogoutRequest(ByVal NameIdentifier As String)

Async Version
Public Sub BuildLogoutRequest(ByVal NameIdentifier As String) As Task
Public Sub BuildLogoutRequest(ByVal NameIdentifier As String, cancellationToken As CancellationToken) As Task

Remarks

This method uses the SAMLRequestSettings property to build a SAML logout request that is meant for logging out the user identified by the NameIdentifier parameter. To help keep track of a user's state in your application, the RelayState property can be set to add a RelayState to the request. The value set in the RelayState property will then be present in the response from the Identity Provider. Typically, if supported, the Identity Provider will also issue logout requests for all other sessions that are active for the user. If a user is part of an active session, the SessionIndex setting can be used to provide the user's current session index to be included in the logout request.

After the request is built, the following properties are set depending on how the RequestBinding field is set.

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

BuildLogoutResponse Method (SAML Component)

Builds a Single Logout response.

Syntax

• C#
• VB.NET

public void BuildLogoutResponse();

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

Public Sub BuildLogoutResponse()

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

Remarks

This method uses the LogoutResponseSettings property to build a SAML logout response that is meant to respond to a logout request for a specific user.

After the request is built, the following properties are set depending on how the ResponseBinding field is set.

• HTTP Redirect - LogoutResponseURL
• HTTP Post - LogoutResponseURL, LogoutResponseBody

BuildServiceMetadata Method (SAML Component)

Builds a metadata document for a service provider.

Syntax

• C#
• VB.NET

public void BuildServiceMetadata();

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

Public Sub BuildServiceMetadata()

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

Remarks

This method uses the ServiceProviderMetadata property to create a new federation metadata document that describes the service provider. This is typically used to provide information about the service provider to the identity provider.

The following fields and properties are used:

• AuthnRequestSigned
• EntityId
• SignedMetadata
• SupportedNameIdFormats
• WantAssertionsSigned
• ServiceProviderSigningCert
• ServiceProviderURIs

Config Method (SAML Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

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

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

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

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

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

DoEvents Method (SAML Component)

This method processes events from the internal message queue.

Syntax

• C#
• VB.NET

public void DoEvents();

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

Public Sub DoEvents()

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

Remarks

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

GetAssertionAttribute Method (SAML Component)

Searches for a specific assertion attribute.

Syntax

• C#
• VB.NET

public string GetAssertionAttribute(string attrName);

Async Version
public async Task<string> GetAssertionAttribute(string attrName);
public async Task<string> GetAssertionAttribute(string attrName, CancellationToken cancellationToken);

Public Function GetAssertionAttribute(ByVal attrName As String) As String

Async Version
Public Function GetAssertionAttribute(ByVal attrName As String) As Task(Of String)
Public Function GetAssertionAttribute(ByVal attrName As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

Interrupt Method (SAML Component)

This method interrupts the current method.

Syntax

• C#
• VB.NET

public void Interrupt();

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

Public Sub Interrupt()

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

Remarks

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

LoadIdentityMetadata Method (SAML Component)

Loads an identity provider's metadata document.

Syntax

• C#
• VB.NET

public void LoadIdentityMetadata(string metadataDocument, bool validate);

Async Version
public async Task LoadIdentityMetadata(string metadataDocument, bool validate);
public async Task LoadIdentityMetadata(string metadataDocument, bool validate, CancellationToken cancellationToken);

Public Sub LoadIdentityMetadata(ByVal metadataDocument As String, ByVal validate As Boolean)

Async Version
Public Sub LoadIdentityMetadata(ByVal metadataDocument As String, ByVal validate As Boolean) As Task
Public Sub LoadIdentityMetadata(ByVal metadataDocument As String, ByVal validate As Boolean, cancellationToken As CancellationToken) As Task

Remarks

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

ParseAssertion Method (SAML Component)

Parses an assertion.

Syntax

• C#
• VB.NET

public void ParseAssertion();

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

Public Sub ParseAssertion()

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

Remarks

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

ParseLogoutRequest Method (SAML Component)

Parses a SAML logout request.

Syntax

• C#
• VB.NET

public void ParseLogoutRequest();

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

Public Sub ParseLogoutRequest()

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

Remarks

This method parses the logout request found in the LogoutRequestInfo property or from the current HTTP request. The HTTP request containing the LogoutRequest parameter can be provided to the component either by setting the LogoutRequestBody and LogoutRequestHeaders properties or by accessing it from the current HTTP Context, if available.

The raw logout request can instead be provided directly to the component by setting the RequestContent field. If the method is able to successfully parse the logout request, the information fields in the LogoutRequestInfo property are populated.

To validate a logout request, see ValidateLogoutRequest.

ParseSAMLResponse Method (SAML Component)

Parses a SAML response.

Syntax

• C#
• VB.NET

public void ParseSAMLResponse();

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

Public Sub ParseSAMLResponse()

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

Remarks

This method parses the SAML response found in the SAMLResponseInfo property or from the current HTTP request. The HTTP request containing the SAMLResponse parameter can be provided to the component either by setting the SAMLResponseBody and SAMLResponseHeaders properties or by accessing it from the current HTTP Context, if available.

The raw SAML response can instead be provided directly to the component by setting the ResponseContent field. If the method is able to successfully parse the SAML response, the information fields in the SAMLResponseInfo property are populated.

To validate a SAML response, see ValidateSAMLResponse.

Additionally, if the ResponseType is srtAuthn, the AssertionContent field will be populated. See ValidateAssertion and ParseAssertion for more information on validating and parsing the assertion.

ProcessLogoutRequest Method (SAML Component)

Processes a SAML logout request.

Syntax

• C#
• VB.NET

public void ProcessLogoutRequest();

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

Public Sub ProcessLogoutRequest()

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

Remarks

This method processes the logout request found in the LogoutRequestInfo property or from the current HTTP request.

The HTTP request containing the LogoutRequest parameter can be provided to the component either by setting the LogoutRequestBody and LogoutRequestHeaders properties or by accessing it from the current HTTP Context, if available. The HTTP request is taken directly from the LogoutRequestHeaders and LogoutRequestBody properties if set; otherwise, it will try to read the HTTP context.

The raw logout request can instead be provided directly to the component by setting the RequestContent field. If the method is able to successfully parse the logout request, the information fields in the LogoutRequestInfo property are populated.

The method is equivalent to calling the following methods. See the specific methods for more information.

• ParseLogoutRequest
• ValidateLogoutRequest

ProcessSAMLResponse Method (SAML Component)

Processes a SAML response.

Syntax

• C#
• VB.NET

public void ProcessSAMLResponse();

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

Public Sub ProcessSAMLResponse()

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

Remarks

This method processes the SAML response found in the SAMLResponseInfo property or from the current HTTP request. If the SAMLResponse object contains an assertion, the component will automatically process the assertion as well.

The HTTP request containing the SAMLResponse parameter can be provided to the component either by setting the SAMLResponseBody and SAMLResponseHeaders properties or by accessing it from the current HTTP Context, if available. The HTTP request is taken directly from the SAMLResponseHeaders and SAMLResponseBody properties if set; otherwise, it will try to read the HTTP context.

The raw SAML response can instead be provided directly to the component by setting the ResponseContent field. If the method is able to successfully parse the SAML response, the information fields in the SAMLResponseInfo property are populated.

The method is equivalent to calling the following methods. See the specific methods for more information.

• ParseSAMLResponse
• ValidateSAMLResponse
• ParseAssertion
• ValidateAssertion

RequestIdentityMetadata Method (SAML Component)

Requests an identity provider's SAML metadata document.

Syntax

• C#
• VB.NET

public void RequestIdentityMetadata(string URL);

Async Version
public async Task RequestIdentityMetadata(string URL);
public async Task RequestIdentityMetadata(string URL, CancellationToken cancellationToken);

Public Sub RequestIdentityMetadata(ByVal URL As String)

Async Version
Public Sub RequestIdentityMetadata(ByVal URL As String) As Task
Public Sub RequestIdentityMetadata(ByVal URL As String, cancellationToken As CancellationToken) As Task

Remarks

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

Reset Method (SAML Component)

This method will reset the component.

Syntax

• C#
• VB.NET

public void Reset();

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

Public Sub Reset()

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

Remarks

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

ValidateAssertion Method (SAML Component)

Validates an assertion.

Syntax

• C#
• VB.NET

public void ValidateAssertion();

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

Public Sub ValidateAssertion()

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

Remarks

This method validates the assertion found in the AssertionInfo property. If an assertion is validated properly, then the user of the application can be authenticated as the subject of the assertion. If the validation fails, then the user should not be authenticated to the application.

The assertion can either be manually set via the AssertionContent field or by first calling ParseSAMLResponse on a SAML response that contains an assertion. Before attempting this validation, the Assertion event provides an opportunity to configure the component to successfully validate the assertion. If the validation fails at any point, the method will throw an exception with the error code corresponding to the reason.

The following checks are performed on the assertion:

To skip certain checks, see AssertionValidationFlags.

ValidateLogoutRequest Method (SAML Component)

Validates a SAML logout request.

Syntax

• C#
• VB.NET

public void ValidateLogoutRequest();

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

Public Sub ValidateLogoutRequest()

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

Remarks

This method validates a logout request. If a logout request is successfully validated, then the application should use the NameId and SessionIndex fields to logout the user from their current session with the application.

The logout request must first be parsed by calling the ParseLogoutRequest method. Before attempting validation, the LogoutRequest event provides an opportunity to configure the component to successfully validate the logout request.

The following checks are performed on the Logout Request:

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

ValidateSAMLResponse Method (SAML Component)

Validates a SAML response.

Syntax

• C#
• VB.NET

public void ValidateSAMLResponse();

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

Public Sub ValidateSAMLResponse()

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

Remarks

This method validates a SAML response. If a SAML response is successfully validated and in response to an authentication request, then the assertion should be parsed and validated to finish the authentication process. If it is in response to a logout request, then the application should finish it's logout process for the user.

The SAML response must first be parsed by calling the ParseSAMLResponse method. Before attempting validation, the SAMLResponse event provides an opportunity to configure the component to successfully validate the SAML response.

The following checks are performed on the SAML response:

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

Assertion Event (SAML Component)

Fired when an assertion is validated.

Syntax

• C#
• VB.NET

public event OnAssertionHandler OnAssertion;

public delegate void OnAssertionHandler(object sender, SAMLAssertionEventArgs e);

public class SAMLAssertionEventArgs : EventArgs {
  public string Issuer { get; }
  public string InResponseTo { get; }
}

Public Event OnAssertion As OnAssertionHandler

Public Delegate Sub OnAssertionHandler(sender As Object, e As SAMLAssertionEventArgs)

Public Class SAMLAssertionEventArgs Inherits EventArgs
  Public ReadOnly Property Issuer As String
  Public ReadOnly Property InResponseTo As String
End Class

Remarks

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

Error Event (SAML Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

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

Remarks

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

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

Log Event (SAML Component)

Fired once for each log message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, SAMLLogEventArgs e);

public class SAMLLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As SAMLLogEventArgs)

Public Class SAMLLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

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

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

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

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

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

Message is the log entry.

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

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

LogoutRequest Event (SAML Component)

Fired when a logout request is validated.

Syntax

• C#
• VB.NET

public event OnLogoutRequestHandler OnLogoutRequest;

public delegate void OnLogoutRequestHandler(object sender, SAMLLogoutRequestEventArgs e);

public class SAMLLogoutRequestEventArgs : EventArgs {
  public string Issuer { get; }
}

Public Event OnLogoutRequest As OnLogoutRequestHandler

Public Delegate Sub OnLogoutRequestHandler(sender As Object, e As SAMLLogoutRequestEventArgs)

Public Class SAMLLogoutRequestEventArgs Inherits EventArgs
  Public ReadOnly Property Issuer As String
End Class

Remarks

This event is fired before the logout request is validated. This event allows certain settings to be configured before the validation checks happen to ensure the logout request is validated correctly. See ValidateLogoutRequest for more information about the validation process.

The Issuer parameter is the ID attribute parsed from the current logout request. When validating, the ID attribute needs to match the EntityId field for validation to succeed. If there are multiple Identity Providers supported, this parameter allows you to configure the component for the specified Identity Provider before continuing with validation.

Redirect Event (SAML Component)

Fired when a redirection is received from the server.

Syntax

• C#
• VB.NET

public event OnRedirectHandler OnRedirect;

public delegate void OnRedirectHandler(object sender, SAMLRedirectEventArgs e);

public class SAMLRedirectEventArgs : EventArgs {
  public string Location { get; }
  public bool Accept { get; set; }
}

Public Event OnRedirect As OnRedirectHandler

Public Delegate Sub OnRedirectHandler(sender As Object, e As SAMLRedirectEventArgs)

Public Class SAMLRedirectEventArgs Inherits EventArgs
  Public ReadOnly Property Location As String
  Public Property Accept As Boolean
End Class

Remarks

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

SAMLResponse Event (SAML Component)

Fired when a SAML response is validated.

Syntax

• C#
• VB.NET

public event OnSAMLResponseHandler OnSAMLResponse;

public delegate void OnSAMLResponseHandler(object sender, SAMLSAMLResponseEventArgs e);

public class SAMLSAMLResponseEventArgs : EventArgs {
  public string Issuer { get; }
  public string InResponseTo { get; }
}

Public Event OnSAMLResponse As OnSAMLResponseHandler

Public Delegate Sub OnSAMLResponseHandler(sender As Object, e As SAMLSAMLResponseEventArgs)

Public Class SAMLSAMLResponseEventArgs Inherits EventArgs
  Public ReadOnly Property Issuer As String
  Public ReadOnly Property InResponseTo As String
End Class

Remarks

This event is fired before the SAML response is validated. This event allows certain settings to be configured before the validation checks happen to ensure the SAML response is validated correctly. See ValidateSAMLResponse for more information about the validation process.

The Issuer parameter is the ID attribute parsed from the current SAML response. When validating, the ID attribute needs to match the EntityId field for validation to succeed. If there are multiple Identity Provider's supported, this parameter allows you to configure the component for the specified identity provider before continuing with validation.

The InResponseTo parameter is the InResponseTo attribute parsed from the current SAML response. When validating, the InResponseTo attribute needs to match the Id field for validation to succeed. If there are multiple outstanding requests, this parameter allows you to configure the component for the specified request before continuing with validation.

SSLServerAuthentication Event (SAML Component)

Fired after the server presents its certificate to the client.

Syntax

• C#
• VB.NET

public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication;

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

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

Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler

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

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

Remarks

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

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

SSLStatus Event (SAML Component)

Fired when secure connection progress messages are available.

Syntax

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

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

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

Public Event OnSSLStatus As OnSSLStatusHandler

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

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

Remarks

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

AssertionAttribute Type

Holds information about an attribute.

Remarks

The fields of this type describe one of the attributes found in an assertion's attribute statement.

Fields

Constructors

• C#
• VB.NET

public AssertionAttribute();

Public AssertionAttribute()

AssertionInfo Type

Holds information about an assertion.

Remarks

The fields of this type describe an assertion that has been parsed or processed by the component.

Fields

Constructors

• C#
• VB.NET

public AssertionInfo();

Public AssertionInfo()

AuthnStatement Type

An Authn statement from an assertion.

Remarks

The fields of this type describe an authentication (Authn) statement from an assertion in response to an authentication request.

Fields

Constructors

• C#
• VB.NET

public AuthnStatement();

Public AuthnStatement()

Certificate Type

This is the digital certificate being used.

Remarks

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

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

• C#
• VB.NET

public Certificate(byte[] encoded);

Public Certificate(ByVal Encoded As Byte())

• C#
• VB.NET

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

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

• C#
• VB.NET

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

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

• C#
• VB.NET

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

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

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject);

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

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject, string configurationString);

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

• C#
• VB.NET

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

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

Firewall Type

The firewall the component will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

Fields

Constructors

• C#
• VB.NET

public Firewall();

Public Firewall()

IdentityProviderMetadata Type

The metadata for the Identity Provider.

Remarks

This type represents the metadata for a specific Identity Provider.

Fields

Constructors

• C#
• VB.NET

public IdentityProviderMetadata();

Public IdentityProviderMetadata()

LogoutRequestInfo Type

Holds information about a logout request.

Remarks

The fields of this type describe a SAML logout request that has been parsed or processed by the component. This type does not specify information about a logout request that was built by this component.

Fields

Constructors

• C#
• VB.NET

public LogoutRequestInfo();

Public LogoutRequestInfo()

LogoutResponseSettings Type

Settings used when building a SAML logout response.

Remarks

The fields of this type are the settings used when building a logout response.

Fields

Constructors

• C#
• VB.NET

public LogoutResponseSettings();

Public LogoutResponseSettings()

Proxy Type

The proxy the component will connect to.

Remarks

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

Fields

Constructors

• C#
• VB.NET

public Proxy();

Public Proxy()

• C#
• VB.NET

public Proxy(string server, int port);

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

• C#
• VB.NET

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

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

SAMLRequestSettings Type

Settings used when building a SAML request.

Remarks

The fields of this type are the settings used when building a SAML request for an Authentication (Authn) or Logout.

Fields

Constructors

• C#
• VB.NET

public SAMLRequestSettings();

Public SAMLRequestSettings()

SAMLResponseInfo Type

Holds information about a SAML response.

Remarks

The fields of this type describe a SAML response that has been parsed or processed by the component.

Fields

Constructors

• C#
• VB.NET

public SAMLResponseInfo();

Public SAMLResponseInfo()

ServiceProviderMetadata Type

The metadata settings for a service provider.

Remarks

The metadata settings for a service provider. This is typically used when configuring an Identity Provider with the information about your application.

Fields

Constructors

• C#
• VB.NET

public ServiceProviderMetadata();

Public ServiceProviderMetadata()

URI Type

A URI endpoint that is used in the SAML protocol.

Remarks

A URI endpoint that is used in the SAML protocol. Service providers and identity providers provide information about the URI that should be used when making specific requests.

Fields

Constructors

• C#
• VB.NET

public URI();

Public URI()

Config Settings (SAML Component)

SAML Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

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

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