SAML Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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 class, 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 class 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 class 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 specified HttpServletRequest object that contains the SAML response. To provide the HTTP headers and body that contain the SAML response directly to the class, 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 class fires the SAMLResponse and Assertion events. These events can be used to provide the class 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 class. 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 class with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

AssertionAttributeInfo Property (SAML Class)

Information about the attributes found in an assertion.

Syntax

public AssertionAttributeList getAssertionAttributeInfo();
public void setAssertionAttributeInfo(AssertionAttributeList assertionAttributeInfo);

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

Information about the AuthnStatement in an assertion.

Syntax

public AuthnStatementList getAssertionAuthnInfo();
public void setAssertionAuthnInfo(AuthnStatementList 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 Class)

Information about a parsed assertion.

Syntax

public AssertionInfo getAssertionInfo();
public void setAssertionInfo(AssertionInfo assertionInfo);

Remarks

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

Firewall Property (SAML Class)

A set of properties related to firewall access.

Syntax

public Firewall getFirewall();
public void setFirewall(Firewall firewall);

Remarks

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

FollowRedirects Property (SAML Class)

Determines what happens when the server issues a redirect.

Syntax

public int getFollowRedirects();
public void setFollowRedirects(int followRedirects);

Enumerated values:
  public final static int frNever = 0;
  public final static int frAlways = 1;
  public final static int frSameScheme = 2;

Default Value

0

Remarks

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

IdentityProviderEncryptingCert Property (SAML Class)

The certificate used to decrypt responses from an identity provider.

Syntax

public Certificate getIdentityProviderEncryptingCert();
public void setIdentityProviderEncryptingCert(Certificate 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 Class)

Information about the identity provider.

Syntax

public IdentityProviderMetadata getIdentityProviderMetadata();
public void setIdentityProviderMetadata(IdentityProviderMetadata 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 Class)

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

Syntax

public Certificate getIdentityProviderSigningCert();
public void setIdentityProviderSigningCert(Certificate 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 Class)

The URIs for an identity provider.

Syntax

public URIList getIdentityProviderURIs();
public void setIdentityProviderURIs(URIList identityProviderURIs);

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

The HTTP body for a SAML logout request.

Syntax

public byte[] getLogoutRequestBody();
public void setLogoutRequestBody(byte[] logoutRequestBody);

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

The HTTP headers for a SAML logout request.

Syntax

public String getLogoutRequestHeaders();
public void setLogoutRequestHeaders(String 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 Class)

Information about a SAML logout request.

Syntax

public LogoutRequestInfo getLogoutRequestInfo();
public void setLogoutRequestInfo(LogoutRequestInfo 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 class. This property is not set with the information about a logout request built by the class by calling the BuildLogoutRequest method.

LogoutResponseBody Property (SAML Class)

The HTTP body for a built logout response.

Syntax

public byte[] getLogoutResponseBody();

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

The settings for a SAML logout response.

Syntax

public LogoutResponseSettings getLogoutResponseSettings();
public void setLogoutResponseSettings(LogoutResponseSettings logoutResponseSettings);

Remarks

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

LogoutResponseURL Property (SAML Class)

The URL for SAML logout responses.

Syntax

public String getLogoutResponseURL();

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

A set of properties related to proxy access.

Syntax

public Proxy getProxy();
public void setProxy(Proxy proxy);

Remarks

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

RelayState Property (SAML Class)

The RelayState for a SAML request or response.

Syntax

public String getRelayState();
public void setRelayState(String 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 Class)

The HTTP body for a SAML request.

Syntax

public byte[] getSAMLRequestBody();

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

The settings for a SAML request.

Syntax

public SAMLRequestSettings getSAMLRequestSettings();
public void setSAMLRequestSettings(SAMLRequestSettings SAMLRequestSettings);

Remarks

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

SAMLRequestURL Property (SAML Class)

The URL for SAML requests.

Syntax

public String getSAMLRequestURL();

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

The HTTP body for a SAML response.

Syntax

public byte[] getSAMLResponseBody();
public void setSAMLResponseBody(byte[] SAMLResponseBody);

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

The HTTP headers for a SAML response.

Syntax

public String getSAMLResponseHeaders();
public void setSAMLResponseHeaders(String 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 Class)

Information about a SAML response.

Syntax

public SAMLResponseInfo getSAMLResponseInfo();
public void setSAMLResponseInfo(SAMLResponseInfo 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 class.

ServiceProviderMetadata Property (SAML Class)

Information about a service provider's SAML metadata document.

Syntax

public ServiceProviderMetadata getServiceProviderMetadata();
public void setServiceProviderMetadata(ServiceProviderMetadata 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 Class)

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

Syntax

public Certificate getServiceProviderSigningCert();
public void setServiceProviderSigningCert(Certificate 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 Class)

Information about the URIs for a service provider.

Syntax

public URIList getServiceProviderURIs();
public void setServiceProviderURIs(URIList serviceProviderURIs);

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 class 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 Class)

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

Syntax

public Certificate getSSLAcceptServerCert();
public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert);

Remarks

If it finds any issues with the certificate presented by the server, the class 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 Class)

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

Syntax

public Certificate getSSLCert();
public void setSSLCert(Certificate SSLCert);

Remarks

This property includes the digital certificate that the class 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 Class)

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

Syntax

public int getSSLProvider();
public void setSSLProvider(int SSLProvider);

Enumerated values:
  public final static int sslpAutomatic = 0;
  public final static int sslpPlatform = 1;
  public final static int sslpInternal = 2;

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the class 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 class will select a provider depending on the current platform.

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

SSLServerCert Property (SAML Class)

The server certificate for the last established connection.

Syntax

public Certificate getSSLServerCert();

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

Builds an Authentication Request.

Syntax

public void 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 class will use that index in the request. Otherwise, the class 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 Class)

Builds a Single Logout request.

Syntax

public void buildLogoutRequest(String nameIdentifier);

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

Builds a Single Logout response.

Syntax

public void 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 field is set.

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

BuildServiceMetadata Method (SAML Class)

Builds a metadata document for a service provider.

Syntax

public void 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 Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

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

This method processes events from the internal message queue.

Syntax

public void doEvents();

Remarks

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

GetAssertionAttribute Method (SAML Class)

Searches for a specific assertion attribute.

Syntax

public String getAssertionAttribute(String attrName);

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

This method interrupts the current method.

Syntax

public void interrupt();

Remarks

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

LoadIdentityMetadata Method (SAML Class)

Loads an identity provider's metadata document.

Syntax

public void loadIdentityMetadata(String metadataDocument, boolean validate);

Remarks

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

ParseAssertion Method (SAML Class)

Parses an assertion.

Syntax

public void parseAssertion();

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

Parses a SAML logout request.

Syntax

public void parseLogoutRequest(Object request);

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 class 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 class 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 Class)

Parses a SAML response.

Syntax

public void parseSAMLResponse(Object request);

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 class 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 class 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 Class)

Processes a SAML logout request.

Syntax

public void processLogoutRequest(Object request);

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 class 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 class 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 Class)

Processes a SAML response.

Syntax

public void processSAMLResponse(Object request);

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 class will automatically process the assertion as well.

The HTTP request containing the SAMLResponse parameter can be provided to the class 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 class 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 Class)

Requests an identity provider's SAML metadata document.

Syntax

public void requestIdentityMetadata(String URL);

Remarks

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

Reset Method (SAML Class)

This method will reset the class.

Syntax

public void reset();

Remarks

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

ValidateAssertion Method (SAML Class)

Validates an assertion.

Syntax

public void 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 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 class 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 Class)

Validates a SAML logout request.

Syntax

public void validateLogoutRequest();

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 class 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 Class)

Validates a SAML response.

Syntax

public void 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 class 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 Class)

Fired when an assertion is validated.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void assertion(SAMLAssertionEvent e) {}
  ...
}

public class SAMLAssertionEvent {
  public String issuer;
  public String inResponseTo;
}

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

Fired when information is available about errors during data delivery.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void error(SAMLErrorEvent e) {}
  ...
}

public class SAMLErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

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

Fired once for each log message.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void log(SAMLLogEvent e) {}
  ...
}

public class SAMLLogEvent {
  public int logLevel;
  public String message;
  public String logType;
}

Remarks

This event is fired once for each log message generated by the class. 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 Class)

Fired when a logout request is validated.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void logoutRequest(SAMLLogoutRequestEvent e) {}
  ...
}

public class SAMLLogoutRequestEvent {
  public String issuer;
}

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 class for the specified Identity Provider before continuing with validation.

Redirect Event (SAML Class)

Fired when a redirection is received from the server.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void redirect(SAMLRedirectEvent e) {}
  ...
}

public class SAMLRedirectEvent {
  public String location;
  public boolean accept; //read-write
}

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 class 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 Class)

Fired when a SAML response is validated.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void SAMLResponse(SAMLSAMLResponseEvent e) {}
  ...
}

public class SAMLSAMLResponseEvent {
  public String issuer;
  public String inResponseTo;
}

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

Fired after the server presents its certificate to the client.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void SSLServerAuthentication(SAMLSSLServerAuthenticationEvent e) {}
  ...
}

public class SAMLSSLServerAuthenticationEvent {
  public byte[] certEncoded;
  public String certSubject;
  public String certIssuer;
  public String status;
  public boolean accept; //read-write
}

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

Fired when secure connection progress messages are available.

Syntax

public class DefaultSAMLEventListener implements SAMLEventListener {
  ...
  public void SSLStatus(SAMLSSLStatusEvent e) {}
  ...
}

public class SAMLSSLStatusEvent {
  public String message;
}

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

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

Fields

Constructors

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

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

public Certificate();

public Certificate( certificateFile);

public Certificate( encoded);

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

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

public Certificate( storeType,  store,  storePassword,  encoded);

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

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

public Certificate( storeType,  store,  storePassword,  encoded);

Firewall Type

The firewall the class 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

public Firewall();

IdentityProviderMetadata Type

The metadata for the Identity Provider.

Remarks

This type represents the metadata for a specific Identity Provider.

Fields

Constructors

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 class. This type does not specify information about a logout request that was built by this class.

Fields

Constructors

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

public LogoutResponseSettings();

Proxy Type

The proxy the class 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

public Proxy();

public Proxy( server,  port);

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

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

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

Fields

Constructors

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

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

public URI();

Config Settings (SAML Class)

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

SAML Errors

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors