SAML Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

TciSAML

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 properties need to be saved for verification purposes. The Issuer property will be used to check that the SAML response is meant for this Service Provider. The Id property is used to verify that the response corresponds to a request that was made by the Service Provider.

Usage: Building an Authn Request

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

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

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

Authentication Response

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

To handle an incoming HTTP request that contains the SAML response, the ProcessSAMLResponse or ParseSAMLResponse methods can be used. 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 properties 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 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 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 properties will be populated with each attribute found. Each attribute has a name and one or more values. For example, take the following attribute that describes a list of emails attached to the user.

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

In this assertion attribute statement, the user has two emails that have been verified. There are two ways to get this information using the SAML 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

property AssertionAttributeInfo: TciAssertionAttributeList read get_AssertionAttributeInfo write set_AssertionAttributeInfo;

Remarks

This properties 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

property AssertionAuthnInfo: TciAuthnStatementList read get_AssertionAuthnInfo write set_AssertionAuthnInfo;

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

property AssertionInfo: TciAssertionInfo read get_AssertionInfo write set_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

property Firewall: TciFirewall read get_Firewall write set_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

property FollowRedirects: TciTFollowRedirects read get_FollowRedirects write set_FollowRedirects;

TciTFollowRedirects = (
  frNever,
  frAlways,
  frSameScheme
);

Default Value

frNever

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

IdentityProviderEncryptingCert Property (SAML Component)

The certificate used to decrypt responses from an identity provider.

Syntax

property IdentityProviderEncryptingCert: TciCertificate read get_IdentityProviderEncryptingCert write set_IdentityProviderEncryptingCert;

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

property IdentityProviderMetadata: TciIdentityProviderMetadata read get_IdentityProviderMetadata write set_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

property IdentityProviderSigningCert: TciCertificate read get_IdentityProviderSigningCert write set_IdentityProviderSigningCert;

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

property IdentityProviderURIs: TciURIList read get_IdentityProviderURIs write set_IdentityProviderURIs;

Remarks

This properties 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

property LogoutRequestBody: String read get_LogoutRequestBody write set_LogoutRequestBody;
property LogoutRequestBodyB: TBytes read get_LogoutRequestBodyB write set_LogoutRequestBodyB;

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

property LogoutRequestHeaders: String read get_LogoutRequestHeaders write set_LogoutRequestHeaders;

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

property LogoutRequestInfo: TciLogoutRequestInfo read get_LogoutRequestInfo write set_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

property LogoutResponseBody: String read get_LogoutResponseBody;
property LogoutResponseBodyB: TBytes read get_LogoutResponseBodyB;

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

property LogoutResponseSettings: TciLogoutResponseSettings read get_LogoutResponseSettings write set_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

property LogoutResponseURL: String read get_LogoutResponseURL;

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

property Proxy: TciProxy read get_Proxy write set_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

property RelayState: String read get_RelayState write set_RelayState;

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

property SAMLRequestBody: String read get_SAMLRequestBody;
property SAMLRequestBodyB: TBytes read get_SAMLRequestBodyB;

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

property SAMLRequestSettings: TciSAMLRequestSettings read get_SAMLRequestSettings write set_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

property SAMLRequestURL: String read get_SAMLRequestURL;

Default Value

''

Remarks

This property contains the generated URL to an identity provider for a sign-on or logoff service. Depending on the binding used, the URL may contain the SAMLRequest 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

property SAMLResponseBody: String read get_SAMLResponseBody write set_SAMLResponseBody;
property SAMLResponseBodyB: TBytes read get_SAMLResponseBodyB write set_SAMLResponseBodyB;

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

property SAMLResponseHeaders: String read get_SAMLResponseHeaders write set_SAMLResponseHeaders;

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

property SAMLResponseInfo: TciSAMLResponseInfo read get_SAMLResponseInfo write set_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

property ServiceProviderMetadata: TciServiceProviderMetadata read get_ServiceProviderMetadata write set_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

property ServiceProviderSigningCert: TciCertificate read get_ServiceProviderSigningCert write set_ServiceProviderSigningCert;

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

property ServiceProviderURIs: TciURIList read get_ServiceProviderURIs write set_ServiceProviderURIs;

Remarks

This properties 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 properties 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

property SSLAcceptServerCert: TciCertificate read get_SSLAcceptServerCert write set_SSLAcceptServerCert;

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

property SSLCert: TciCertificate read get_SSLCert write set_SSLCert;

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

property SSLProvider: TciTSSLProviders read get_SSLProvider write set_SSLProvider;

TciTSSLProviders = (
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
);

Default Value

sslpAutomatic

Remarks

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

Possible values are 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.

SSLServerCert Property (SAML Component)

The server certificate for the last established connection.

Syntax

property SSLServerCert: TciCertificate read get_SSLServerCert;

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

procedure BuildAuthnRequest();

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

After the request is built, the following properties are set depending on how the RequestBinding property 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

procedure BuildLogoutRequest(NameIdentifier: String);

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 property is set.

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

BuildLogoutResponse Method (SAML Component)

Builds a Single Logout response.

Syntax

procedure BuildLogoutResponse();

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 property is set.

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

BuildServiceMetadata Method (SAML Component)

Builds a metadata document for a service provider.

Syntax

procedure BuildServiceMetadata();

Remarks

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

The following fields and properties are used:

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

Config Method (SAML Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

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

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

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

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

DoEvents Method (SAML Component)

This method processes events from the internal message queue.

Syntax

procedure DoEvents();

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

function GetAssertionAttribute(attrName: String): String;

Remarks

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

Interrupt Method (SAML Component)

This method interrupts the current method.

Syntax

procedure Interrupt();

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

procedure LoadIdentityMetadata(metadataDocument: String; validate: Boolean);

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

procedure ParseAssertion();

Remarks

This method parses the assertion found in the AssertionInfo property. The assertion can either be manually set by setting the AssertionContent property 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

procedure ParseLogoutRequest();

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

procedure ParseSAMLResponse();

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

procedure ProcessLogoutRequest();

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

procedure ProcessSAMLResponse();

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

procedure RequestIdentityMetadata(URL: String);

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

procedure Reset();

Remarks

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

ValidateAssertion Method (SAML Component)

Validates an assertion.

Syntax

procedure ValidateAssertion();

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

procedure ValidateLogoutRequest();

Remarks

This method validates a logout request. If a logout request is successfully validated, then the application should use the NameId and SessionIndex properties 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

procedure ValidateSAMLResponse();

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

type TAssertionEvent = procedure (
  Sender: TObject;
  const Issuer: String;
  const InResponseTo: String
) of Object;

property OnAssertion: TAssertionEvent read FOnAssertion write FOnAssertion;

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 properties respectively. This event allows certain settings to be configured before the validation checks happen to ensure the assertion is validated correctly. See ValidateAssertion for more information about the validation process.

Error Event (SAML Component)

Fired when information is available about errors during data delivery.

Syntax

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

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

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

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

type TLogEvent = procedure (
  Sender: TObject;
  LogLevel: Integer;
  const Message: String;
  const LogType: String
) of Object;

property OnLog: TLogEvent read FOnLog write FOnLog;

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

type TLogoutRequestEvent = procedure (
  Sender: TObject;
  const Issuer: String
) of Object;

property OnLogoutRequest: TLogoutRequestEvent read FOnLogoutRequest write FOnLogoutRequest;

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

type TRedirectEvent = procedure (
  Sender: TObject;
  const Location: String;
  var Accept: Boolean
) of Object;

property OnRedirect: TRedirectEvent read FOnRedirect write FOnRedirect;

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

type TSAMLResponseEvent = procedure (
  Sender: TObject;
  const Issuer: String;
  const InResponseTo: String
) of Object;

property OnSAMLResponse: TSAMLResponseEvent read FOnSAMLResponse write FOnSAMLResponse;

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

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

property OnSSLServerAuthentication: TSSLServerAuthenticationEvent read FOnSSLServerAuthentication write FOnSSLServerAuthentication;

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

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

property OnSSLStatus: TSSLStatusEvent read FOnSSLStatus write FOnSSLStatus;

Remarks

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

AssertionAttribute Type

Holds information about an attribute.

Remarks

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

Fields

Constructors

constructor Create();

AssertionInfo Type

Holds information about an assertion.

Remarks

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

Fields

Constructors

constructor Create();

AuthnStatement Type

An Authn statement from an assertion.

Remarks

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

Fields

Constructors

constructor Create();

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

>

constructor Create();

constructor Create(valEncoded: TBytes);

constructor Create(valStoreType: TciCertStoreTypes; valStore: String; valStorePassword: String; valSubject: String);

constructor Create(valStoreType: TciCertStoreTypes; valStore: TBytes; valStorePassword: String; valSubject: String);

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

constructor Create();

IdentityProviderMetadata Type

The metadata for the Identity Provider.

Remarks

This type represents the metadata for a specific Identity Provider.

Fields

Constructors

constructor Create();

LogoutRequestInfo Type

Holds information about a logout request.

Remarks

The properties 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

constructor Create();

LogoutResponseSettings Type

Settings used when building a SAML logout response.

Remarks

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

Fields

Constructors

constructor Create();

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

constructor Create();

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

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

SAMLRequestSettings Type

Settings used when building a SAML request.

Remarks

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

Fields

Constructors

constructor Create();

SAMLResponseInfo Type

Holds information about a SAML response.

Remarks

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

Fields

Constructors

constructor Create();

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

constructor Create();

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

constructor Create();

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

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

Socket Config Settings

Base Config Settings

Trappable Errors (SAML Component)

SAML Errors

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

HTTP Errors

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

TCPClient Errors

SSL Errors

TCP/IP Errors