SAML Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

class 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 SAMLRequest from your application to the Identity Provider's login page where a user already has an account. The user will login, and the Identity Provider will return an assertion in a SAMLResponse, which is a set of information about the user and the authentication steps taken to identify the user.

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

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

Setup

To get started with the 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 request_identity_metadata and load_identity_metadata methods are both ways to populate the identity_provider_metadata, identity_provider_signing_cert, and identity_provider_ur_is 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 service_provider_metadata, service_provider_signing_cert, and service_provider_ur_is properties can be used to provide information about the Service Provider. These are used by the class to build a valid SAMLRequest and to verify the SAMLResponse and its assertions. Additionally, to easily supply this information to an Identity Provider, the build_service_metadata 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 build_authn_request method can be used to build a SAMLRequest that has been configured by the saml_request_settings. Additionally, to provide state information between the request and the response, the relay_state property can be set. Typically the relay_state 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 saml_request_id and saml_request_issuer properties need to be saved for verification purposes. The saml_request_issuer property will be used to check that the SAMLResponse is meant for this Service Provider. The saml_request_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 saml_request_request_binding property is configured, the results will be provided through the saml_request_body and saml_request_url properties. Using the information from the properties, the user that needs identifying should be directed to the saml_request_url. 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 service_provider_ur_is properties. If authentication was successful, this response should also contain an assertion as well as information about the authentication context.

To handle an incoming HTTP request that contains the SAMLResponse, the process_saml_response or parse_saml_response methods can be used. To provide the HTTP headers and body that contain the SAMLResponse directly to the class, the saml_response_headers and saml_response_body properties can be set before calling parse_saml_response or process_saml_response. For example:

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

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

The process_saml_response method performs multiple steps automatically, making it a simple method to handle the SAMLResponse. The method is the equivalent to calling the parse_saml_response, validate_saml_response, parse_assertion, and validate_assertion methods. These methods can be used in place of calling process_saml_response 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 assertion_info property. Along with providing information about the assertion, these fields are also used to verify the assertion. An important field to note is the assertion_subject_name_id 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 assertion_authn_info property. Some commonly used information is how the user authenticated with the Identity Provider (see assertion_authn_info_context_class_reference) and the session identifier created by the Identity Provider for the Service Provider (see assertion_authn_info_session_index).

Assertion Attributes

Along with the assertion_subject_name_id, 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 assertion_attribute_info 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 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 get_assertion_attribute 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.

assertion_attribute_info_count Property

The number of records in the AssertionAttributeInfo arrays.

Syntax

def get_assertion_attribute_info_count() -> int: ...
def set_assertion_attribute_info_count(value: int) -> None: ...

assertion_attribute_info_count = property(get_assertion_attribute_info_count, set_assertion_attribute_info_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• assertion_attribute_info_attribute_content
• assertion_attribute_info_attribute_value_count
• assertion_attribute_info_attribute_value_data
• assertion_attribute_info_attribute_value_index
• assertion_attribute_info_friendly_name
• assertion_attribute_info_name
• assertion_attribute_info_name_format

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

assertion_attribute_info_attribute_content Property

The raw XML of the attribute.

Syntax

def get_assertion_attribute_info_attribute_content(assertion_attribute_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

This property is read-only.

assertion_attribute_info_attribute_value_count Property

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

Syntax

def get_assertion_attribute_info_attribute_value_count(assertion_attribute_info_index: int) -> int: ...

Default Value

0

Remarks

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

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

This property is read-only.

assertion_attribute_info_attribute_value_data Property

The content of the attribute value selected by AttributeValueIndex .

Syntax

def get_assertion_attribute_info_attribute_value_data(assertion_attribute_info_index: int) -> str: ...

Default Value

""

Remarks

The content of the attribute value selected by assertion_attribute_value_index.

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

This property is read-only.

assertion_attribute_info_attribute_value_index Property

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

Syntax

def get_assertion_attribute_info_attribute_value_index(assertion_attribute_info_index: int) -> int: ...
def set_assertion_attribute_info_attribute_value_index(assertion_attribute_info_index: int, value: int) -> None: ...

Default Value

0

Remarks

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

Multi-value attribute

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

Iterating through each value in an attribute

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

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

assertion_attribute_info_friendly_name Property

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

Syntax

def get_assertion_attribute_info_friendly_name(assertion_attribute_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

This property is read-only.

assertion_attribute_info_name Property

The name of the attribute.

Syntax

def get_assertion_attribute_info_name(assertion_attribute_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

This property is read-only.

assertion_attribute_info_name_format Property

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

Syntax

def get_assertion_attribute_info_name_format(assertion_attribute_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_attribute_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_attribute_info_count property.

This property is read-only.

assertion_authn_info_count Property

The number of records in the AssertionAuthnInfo arrays.

Syntax

def get_assertion_authn_info_count() -> int: ...
def set_assertion_authn_info_count(value: int) -> None: ...

assertion_authn_info_count = property(get_assertion_authn_info_count, set_assertion_authn_info_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• assertion_authn_info_authenticating_authorites
• assertion_authn_info_authn_instant
• assertion_authn_info_context_class_reference
• assertion_authn_info_context_declaration
• assertion_authn_info_session_expiration
• assertion_authn_info_session_index
• assertion_authn_info_statement_content

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

assertion_authn_info_authenticating_authorites Property

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

Syntax

def get_assertion_authn_info_authenticating_authorites(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_authn_info_authn_instant Property

The time at which the authentication took place.

Syntax

def get_assertion_authn_info_authn_instant(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

The time at which the authentication took place.

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_authn_info_context_class_reference Property

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

Syntax

def get_assertion_authn_info_context_class_reference(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_authn_info_context_declaration Property

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

Syntax

def get_assertion_authn_info_context_declaration(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_authn_info_session_expiration Property

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

Syntax

def get_assertion_authn_info_session_expiration(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

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

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_authn_info_session_index Property

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

Syntax

def get_assertion_authn_info_session_index(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_authn_info_statement_content Property

The raw XML of the Authn statement.

Syntax

def get_assertion_authn_info_statement_content(assertion_authn_info_index: int) -> str: ...

Default Value

""

Remarks

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

The assertion_authn_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the assertion_authn_info_count property.

This property is read-only.

assertion_assertion_content Property

The raw XML of the assertion.

Syntax

def get_assertion_assertion_content() -> bytes: ...
def set_assertion_assertion_content(value: bytes) -> None: ...

assertion_assertion_content = property(get_assertion_assertion_content, set_assertion_assertion_content)

Default Value

""

Remarks

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

assertion_expiration_date Property

When the assertion expires.

Syntax

def get_assertion_expiration_date() -> str: ...

assertion_expiration_date = property(get_assertion_expiration_date, None)

Default Value

""

Remarks

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

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

This property is read-only.

assertion_id Property

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

Syntax

def get_assertion_id() -> str: ...

assertion_id = property(get_assertion_id, None)

Default Value

""

Remarks

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

This property is read-only.

assertion_is_signed Property

Whether the assertion has been signed by the identity provider.

Syntax

def get_assertion_is_signed() -> bool: ...

assertion_is_signed = property(get_assertion_is_signed, None)

Default Value

FALSE

Remarks

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

This property is read-only.

assertion_issued_time Property

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

Syntax

def get_assertion_issued_time() -> str: ...

assertion_issued_time = property(get_assertion_issued_time, None)

Default Value

""

Remarks

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

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

This property is read-only.

assertion_issuer Property

The issuer of the assertion.

Syntax

def get_assertion_issuer() -> str: ...

assertion_issuer = property(get_assertion_issuer, None)

Default Value

""

Remarks

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

This property is read-only.

assertion_not_before_date Property

The time at which the assertion becomes valid.

Syntax

def get_assertion_not_before_date() -> str: ...

assertion_not_before_date = property(get_assertion_not_before_date, None)

Default Value

""

Remarks

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

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

This property is read-only.

assertion_one_time_use Property

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

Syntax

def get_assertion_one_time_use() -> bool: ...

assertion_one_time_use = property(get_assertion_one_time_use, None)

Default Value

FALSE

Remarks

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

This property is read-only.

assertion_subject_name_id Property

The NameId for the subject of the assertion.

Syntax

def get_assertion_subject_name_id() -> str: ...

assertion_subject_name_id = property(get_assertion_subject_name_id, None)

Default Value

""

Remarks

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

This property is read-only.

assertion_subject_name_id_format Property

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

Syntax

def get_assertion_subject_name_id_format() -> str: ...

assertion_subject_name_id_format = property(get_assertion_subject_name_id_format, None)

Default Value

""

Remarks

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

This property is read-only.

assertion_user_info_address Property

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

Syntax

def get_assertion_user_info_address() -> str: ...

assertion_user_info_address = property(get_assertion_user_info_address, None)

Default Value

""

Remarks

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

This property is read-only.

assertion_user_info_email Property

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

Syntax

def get_assertion_user_info_email() -> str: ...

assertion_user_info_email = property(get_assertion_user_info_email, None)

Default Value

""

Remarks

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

This property is read-only.

assertion_user_info_name Property

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

Syntax

def get_assertion_user_info_name() -> str: ...

assertion_user_info_name = property(get_assertion_user_info_name, None)

Default Value

""

Remarks

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

This property is read-only.

firewall_auto_detect Property

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

Syntax

def get_firewall_auto_detect() -> bool: ...
def set_firewall_auto_detect(value: bool) -> None: ...

firewall_auto_detect = property(get_firewall_auto_detect, set_firewall_auto_detect)

Default Value

FALSE

Remarks

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

firewall_type Property

The type of firewall to connect through.

Syntax

def get_firewall_type() -> int: ...
def set_firewall_type(value: int) -> None: ...

firewall_type = property(get_firewall_type, set_firewall_type)

Default Value

0

Remarks

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

firewall_host Property

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

Syntax

def get_firewall_host() -> str: ...
def set_firewall_host(value: str) -> None: ...

firewall_host = property(get_firewall_host, set_firewall_host)

Default Value

""

Remarks

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

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

firewall_password Property

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

Syntax

def get_firewall_password() -> str: ...
def set_firewall_password(value: str) -> None: ...

firewall_password = property(get_firewall_password, set_firewall_password)

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

firewall_port Property

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

Syntax

def get_firewall_port() -> int: ...
def set_firewall_port(value: int) -> None: ...

firewall_port = property(get_firewall_port, set_firewall_port)

Default Value

0

Remarks

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

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

firewall_user Property

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

Syntax

def get_firewall_user() -> str: ...
def set_firewall_user(value: str) -> None: ...

firewall_user = property(get_firewall_user, set_firewall_user)

Default Value

""

Remarks

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

follow_redirects Property

Determines what happens when the server issues a redirect.

Syntax

def get_follow_redirects() -> int: ...
def set_follow_redirects(value: int) -> None: ...

follow_redirects = property(get_follow_redirects, set_follow_redirects)

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 url_scheme is the same; otherwise, the class fails with an error.

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

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

A on_redirect event is fired for every URL the product is redirected to. In the case of automatic redirections, the on_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 fails with an error instead.

identity_provider_encrypting_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_identity_provider_encrypting_cert_store() -> bytes: ...
def set_identity_provider_encrypting_cert_store(value: bytes) -> None: ...

identity_provider_encrypting_cert_store = property(get_identity_provider_encrypting_cert_store, set_identity_provider_encrypting_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The identity_provider_encrypting_cert_store_type property denotes the type of the certificate store specified by identity_provider_encrypting_cert_store. If the store is password-protected, specify the password in identity_provider_encrypting_cert_store_password.

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

Designations of certificate stores are platform dependent.

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

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

identity_provider_encrypting_cert_store_password Property

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

Syntax

def get_identity_provider_encrypting_cert_store_password() -> str: ...
def set_identity_provider_encrypting_cert_store_password(value: str) -> None: ...

identity_provider_encrypting_cert_store_password = property(get_identity_provider_encrypting_cert_store_password, set_identity_provider_encrypting_cert_store_password)

Default Value

""

Remarks

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

identity_provider_encrypting_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_identity_provider_encrypting_cert_store_type() -> int: ...
def set_identity_provider_encrypting_cert_store_type(value: int) -> None: ...

identity_provider_encrypting_cert_store_type = property(get_identity_provider_encrypting_cert_store_type, set_identity_provider_encrypting_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

identity_provider_encrypting_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_identity_provider_encrypting_cert_subject() -> str: ...
def set_identity_provider_encrypting_cert_subject(value: str) -> None: ...

identity_provider_encrypting_cert_subject = property(get_identity_provider_encrypting_cert_subject, set_identity_provider_encrypting_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

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

identity_provider_encrypting_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_identity_provider_encrypting_cert_encoded() -> bytes: ...
def set_identity_provider_encrypting_cert_encoded(value: bytes) -> None: ...

identity_provider_encrypting_cert_encoded = property(get_identity_provider_encrypting_cert_encoded, set_identity_provider_encrypting_cert_encoded)

Default Value

""

Remarks

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

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

identity_provider_metadata_entity_id Property

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

Syntax

def get_identity_provider_metadata_entity_id() -> str: ...
def set_identity_provider_metadata_entity_id(value: str) -> None: ...

identity_provider_metadata_entity_id = property(get_identity_provider_metadata_entity_id, set_identity_provider_metadata_entity_id)

Default Value

""

Remarks

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

identity_provider_metadata_expiration_date Property

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

Syntax

def get_identity_provider_metadata_expiration_date() -> str: ...

identity_provider_metadata_expiration_date = property(get_identity_provider_metadata_expiration_date, None)

Default Value

""

Remarks

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

This property is read-only.

identity_provider_metadata_metadata_content Property

The raw metadata for the identity provider.

Syntax

def get_identity_provider_metadata_metadata_content() -> bytes: ...
def set_identity_provider_metadata_metadata_content(value: bytes) -> None: ...

identity_provider_metadata_metadata_content = property(get_identity_provider_metadata_metadata_content, set_identity_provider_metadata_metadata_content)

Default Value

""

Remarks

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

identity_provider_metadata_requests_signed_authn_requests Property

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

Syntax

def get_identity_provider_metadata_requests_signed_authn_requests() -> bool: ...
def set_identity_provider_metadata_requests_signed_authn_requests(value: bool) -> None: ...

identity_provider_metadata_requests_signed_authn_requests = property(get_identity_provider_metadata_requests_signed_authn_requests, set_identity_provider_metadata_requests_signed_authn_requests)

Default Value

FALSE

Remarks

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

identity_provider_metadata_signed_metadata Property

Whether the identity provider's parsed metadata is signed.

Syntax

def get_identity_provider_metadata_signed_metadata() -> bool: ...

identity_provider_metadata_signed_metadata = property(get_identity_provider_metadata_signed_metadata, None)

Default Value

FALSE

Remarks

Whether the identity provider's parsed metadata is signed.

This property is read-only.

identity_provider_metadata_supported_attribute_profiles Property

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

Syntax

def get_identity_provider_metadata_supported_attribute_profiles() -> str: ...

identity_provider_metadata_supported_attribute_profiles = property(get_identity_provider_metadata_supported_attribute_profiles, None)

Default Value

""

Remarks

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

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

This property is read-only.

identity_provider_metadata_supported_attributes Property

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

Syntax

def get_identity_provider_metadata_supported_attributes() -> str: ...

identity_provider_metadata_supported_attributes = property(get_identity_provider_metadata_supported_attributes, None)

Default Value

""

Remarks

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

This property is read-only.

identity_provider_metadata_supported_name_id_formats Property

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

Syntax

def get_identity_provider_metadata_supported_name_id_formats() -> str: ...

identity_provider_metadata_supported_name_id_formats = property(get_identity_provider_metadata_supported_name_id_formats, None)

Default Value

""

Remarks

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

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

This property is read-only.

identity_provider_signing_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_identity_provider_signing_cert_store() -> bytes: ...
def set_identity_provider_signing_cert_store(value: bytes) -> None: ...

identity_provider_signing_cert_store = property(get_identity_provider_signing_cert_store, set_identity_provider_signing_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The identity_provider_signing_cert_store_type property denotes the type of the certificate store specified by identity_provider_signing_cert_store. If the store is password-protected, specify the password in identity_provider_signing_cert_store_password.

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

Designations of certificate stores are platform dependent.

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

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

identity_provider_signing_cert_store_password Property

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

Syntax

def get_identity_provider_signing_cert_store_password() -> str: ...
def set_identity_provider_signing_cert_store_password(value: str) -> None: ...

identity_provider_signing_cert_store_password = property(get_identity_provider_signing_cert_store_password, set_identity_provider_signing_cert_store_password)

Default Value

""

Remarks

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

identity_provider_signing_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_identity_provider_signing_cert_store_type() -> int: ...
def set_identity_provider_signing_cert_store_type(value: int) -> None: ...

identity_provider_signing_cert_store_type = property(get_identity_provider_signing_cert_store_type, set_identity_provider_signing_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

identity_provider_signing_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_identity_provider_signing_cert_subject() -> str: ...
def set_identity_provider_signing_cert_subject(value: str) -> None: ...

identity_provider_signing_cert_subject = property(get_identity_provider_signing_cert_subject, set_identity_provider_signing_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

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

identity_provider_signing_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_identity_provider_signing_cert_encoded() -> bytes: ...
def set_identity_provider_signing_cert_encoded(value: bytes) -> None: ...

identity_provider_signing_cert_encoded = property(get_identity_provider_signing_cert_encoded, set_identity_provider_signing_cert_encoded)

Default Value

""

Remarks

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

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

identity_provider_uri_count Property

The number of records in the IdentityProviderURI arrays.

Syntax

def get_identity_provider_uri_count() -> int: ...
def set_identity_provider_uri_count(value: int) -> None: ...

identity_provider_uri_count = property(get_identity_provider_uri_count, set_identity_provider_uri_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• identity_provider_uri_binding_ref
• identity_provider_uri_binding_type
• identity_provider_uri_index
• identity_provider_uri_is_default
• identity_provider_uri_location
• identity_provider_uri_type

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

identity_provider_uri_binding_ref Property

The URI reference for the set BindingType .

Syntax

def get_identity_provider_uri_binding_ref(identity_provider_uri_idx: int) -> str: ...
def set_identity_provider_uri_binding_ref(identity_provider_uri_idx: int, value: str) -> None: ...

Default Value

""

Remarks

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

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

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

The identity_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the identity_provider_uri_count property.

identity_provider_uri_binding_type Property

The type of binding that is supported for this URI.

Syntax

def get_identity_provider_uri_binding_type(identity_provider_uri_idx: int) -> int: ...
def set_identity_provider_uri_binding_type(identity_provider_uri_idx: int, value: int) -> None: ...

Default Value

0

Remarks

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

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

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

The identity_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the identity_provider_uri_count property.

identity_provider_uri_is_default Property

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

Syntax

def get_identity_provider_uri_is_default(identity_provider_uri_idx: int) -> bool: ...
def set_identity_provider_uri_is_default(identity_provider_uri_idx: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Whether this URI is the default URI that should be used for the specific identity_provider_uriuri_type and identity_provider_uri_binding_type combination.

The identity_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the identity_provider_uri_count property.

identity_provider_uri_location Property

The address of the URI.

Syntax

def get_identity_provider_uri_location(identity_provider_uri_idx: int) -> str: ...
def set_identity_provider_uri_location(identity_provider_uri_idx: int, value: str) -> None: ...

Default Value

""

Remarks

The address of the URI.

The identity_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the identity_provider_uri_count property.

identity_provider_uri_index Property

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

Syntax

def get_identity_provider_uri_index(identity_provider_uri_idx: int) -> int: ...
def set_identity_provider_uri_index(identity_provider_uri_idx: int, value: int) -> None: ...

Default Value

0

Remarks

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

The identity_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the identity_provider_uri_count property.

identity_provider_uri_type Property

The purpose of the URI.

Syntax

def get_identity_provider_uri_type(identity_provider_uri_idx: int) -> int: ...
def set_identity_provider_uri_type(identity_provider_uri_idx: int, value: int) -> None: ...

Default Value

0

Remarks

The purpose of the URI. Possible values are:

The identity_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the identity_provider_uri_count property.

proxy_auth_scheme Property

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

Syntax

def get_proxy_auth_scheme() -> int: ...
def set_proxy_auth_scheme(value: int) -> None: ...

proxy_auth_scheme = property(get_proxy_auth_scheme, set_proxy_auth_scheme)

Default Value

0

Remarks

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

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

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the class will attempt basic authentication.

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

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

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

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

proxy_auto_detect Property

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

Syntax

def get_proxy_auto_detect() -> bool: ...
def set_proxy_auto_detect(value: bool) -> None: ...

proxy_auto_detect = property(get_proxy_auto_detect, set_proxy_auto_detect)

Default Value

FALSE

Remarks

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

proxy_password Property

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

Syntax

def get_proxy_password() -> str: ...
def set_proxy_password(value: str) -> None: ...

proxy_password = property(get_proxy_password, set_proxy_password)

Default Value

""

Remarks

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

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

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

proxy_port Property

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

Syntax

def get_proxy_port() -> int: ...
def set_proxy_port(value: int) -> None: ...

proxy_port = property(get_proxy_port, set_proxy_port)

Default Value

80

Remarks

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

proxy_server Property

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

Syntax

def get_proxy_server() -> str: ...
def set_proxy_server(value: str) -> None: ...

proxy_server = property(get_proxy_server, set_proxy_server)

Default Value

""

Remarks

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

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

proxy_ssl Property

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

Syntax

def get_proxy_ssl() -> int: ...
def set_proxy_ssl(value: int) -> None: ...

proxy_ssl = property(get_proxy_ssl, set_proxy_ssl)

Default Value

0

Remarks

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

proxy_user Property

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

Syntax

def get_proxy_user() -> str: ...
def set_proxy_user(value: str) -> None: ...

proxy_user = property(get_proxy_user, set_proxy_user)

Default Value

""

Remarks

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

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

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

relay_state Property

The RelayState for a SAMLRequest or SAMLResponse.

Syntax

def get_relay_state() -> str: ...
def set_relay_state(value: str) -> None: ...

relay_state = property(get_relay_state, set_relay_state)

Default Value

""

Remarks

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

saml_request_body Property

The HTTP body for a SAMLRequest.

Syntax

def get_saml_request_body() -> bytes: ...

saml_request_body = property(get_saml_request_body, None)

Default Value

""

Remarks

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

This property is read-only.

saml_request_allow_create Property

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

Syntax

def get_saml_request_allow_create() -> bool: ...
def set_saml_request_allow_create(value: bool) -> None: ...

saml_request_allow_create = property(get_saml_request_allow_create, set_saml_request_allow_create)

Default Value

FALSE

Remarks

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

saml_request_consent Property

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

Syntax

def get_saml_request_consent() -> int: ...
def set_saml_request_consent(value: int) -> None: ...

saml_request_consent = property(get_saml_request_consent, set_saml_request_consent)

Default Value

0

Remarks

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

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

saml_request_destination Property

A URI reference for the intended destination for the SAMLRequest.

Syntax

def get_saml_request_destination() -> str: ...
def set_saml_request_destination(value: str) -> None: ...

saml_request_destination = property(get_saml_request_destination, set_saml_request_destination)

Default Value

""

Remarks

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

saml_request_id Property

A unique Id of the SAMLRequest.

Syntax

def get_saml_request_id() -> str: ...
def set_saml_request_id(value: str) -> None: ...

saml_request_id = property(get_saml_request_id, set_saml_request_id)

Default Value

""

Remarks

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

saml_request_issued_time Property

The time at which the SAMLRequest was issued.

Syntax

def get_saml_request_issued_time() -> str: ...
def set_saml_request_issued_time(value: str) -> None: ...

saml_request_issued_time = property(get_saml_request_issued_time, set_saml_request_issued_time)

Default Value

""

Remarks

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

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

saml_request_issuer Property

The issuer for the SAML Request.

Syntax

def get_saml_request_issuer() -> str: ...
def set_saml_request_issuer(value: str) -> None: ...

saml_request_issuer = property(get_saml_request_issuer, set_saml_request_issuer)

Default Value

""

Remarks

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

saml_request_name_id_format Property

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

Syntax

def get_saml_request_name_id_format() -> int: ...
def set_saml_request_name_id_format(value: int) -> None: ...

saml_request_name_id_format = property(get_saml_request_name_id_format, set_saml_request_name_id_format)

Default Value

0

Remarks

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

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

saml_request_request_binding Property

The binding that will be used to make the request.

Syntax

def get_saml_request_request_binding() -> int: ...
def set_saml_request_request_binding(value: int) -> None: ...

saml_request_request_binding = property(get_saml_request_request_binding, set_saml_request_request_binding)

Default Value

0

Remarks

The binding that will be used to make the request.

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

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

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

saml_request_selected_endpoint Property

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

Syntax

def get_saml_request_selected_endpoint() -> int: ...
def set_saml_request_selected_endpoint(value: int) -> None: ...

saml_request_selected_endpoint = property(get_saml_request_selected_endpoint, set_saml_request_selected_endpoint)

Default Value

-1

Remarks

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

saml_request_sign_request Property

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

Syntax

def get_saml_request_sign_request() -> bool: ...
def set_saml_request_sign_request(value: bool) -> None: ...

saml_request_sign_request = property(get_saml_request_sign_request, set_saml_request_sign_request)

Default Value

FALSE

Remarks

Whether the SAMLRequest should be signed when building the SAMLRequest using the build_authn_request or build_logout_request methods. The class will use the certificate set in the service_provider_signing_cert property to sign the request.

saml_request_use_default_endpoint Property

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

Syntax

def get_saml_request_use_default_endpoint() -> bool: ...
def set_saml_request_use_default_endpoint(value: bool) -> None: ...

saml_request_use_default_endpoint = property(get_saml_request_use_default_endpoint, set_saml_request_use_default_endpoint)

Default Value

FALSE

Remarks

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

saml_request_url Property

The URL for SAMLRequests.

Syntax

def get_saml_request_url() -> str: ...

saml_request_url = property(get_saml_request_url, None)

Default Value

""

Remarks

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

This property is read-only.

saml_response_body Property

The HTTP body for the current SAMLResponse.

Syntax

def get_saml_response_body() -> bytes: ...
def set_saml_response_body(value: bytes) -> None: ...

saml_response_body = property(get_saml_response_body, set_saml_response_body)

Default Value

""

Remarks

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

saml_response_headers Property

The HTTP headers for the current SAMLResponse.

Syntax

def get_saml_response_headers() -> str: ...
def set_saml_response_headers(value: str) -> None: ...

saml_response_headers = property(get_saml_response_headers, set_saml_response_headers)

Default Value

""

Remarks

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

saml_response_consent Property

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

Syntax

def get_saml_response_consent() -> str: ...

saml_response_consent = property(get_saml_response_consent, None)

Default Value

""

Remarks

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

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

This property is read-only.

saml_response_destination Property

A URI reference for the intended destination for the SAMLResponse.

Syntax

def get_saml_response_destination() -> str: ...

saml_response_destination = property(get_saml_response_destination, None)

Default Value

""

Remarks

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

This property is read-only.

saml_response_in_response_to Property

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

Syntax

def get_saml_response_in_response_to() -> str: ...

saml_response_in_response_to = property(get_saml_response_in_response_to, None)

Default Value

""

Remarks

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

This property is read-only.

saml_response_issued_time Property

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

Syntax

def get_saml_response_issued_time() -> str: ...

saml_response_issued_time = property(get_saml_response_issued_time, None)

Default Value

""

Remarks

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

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

This property is read-only.

saml_response_issuer Property

The Entity Id of the issuer of the SAMLResponse.

Syntax

def get_saml_response_issuer() -> str: ...

saml_response_issuer = property(get_saml_response_issuer, None)

Default Value

""

Remarks

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

This property is read-only.

saml_response_response_content Property

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

Syntax

def get_saml_response_response_content() -> bytes: ...
def set_saml_response_response_content(value: bytes) -> None: ...

saml_response_response_content = property(get_saml_response_response_content, set_saml_response_response_content)

Default Value

""

Remarks

The full XML of the SAMLResponse after being parsed or processed by the class after calling parse_http_request or process_http_request. Optionally, this setting can be set to provide a SAMLResponse directly to the class to be used with the parse_saml_response method.

saml_response_response_id Property

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

Syntax

def get_saml_response_response_id() -> str: ...

saml_response_response_id = property(get_saml_response_response_id, None)

Default Value

""

Remarks

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

This property is read-only.

saml_response_response_type Property

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

Syntax

def get_saml_response_response_type() -> int: ...

saml_response_response_type = property(get_saml_response_response_type, None)

Default Value

0

Remarks

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

This property is read-only.

saml_response_signed Property

Whether the SAMLResponse is signed.

Syntax

def get_saml_response_signed() -> bool: ...

saml_response_signed = property(get_saml_response_signed, None)

Default Value

FALSE

Remarks

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

This property is read-only.

saml_response_status_codes Property

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

Syntax

def get_saml_response_status_codes() -> str: ...

saml_response_status_codes = property(get_saml_response_status_codes, None)

Default Value

""

Remarks

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

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

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

This property is read-only.

saml_response_status_message Property

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

Syntax

def get_saml_response_status_message() -> str: ...

saml_response_status_message = property(get_saml_response_status_message, None)

Default Value

""

Remarks

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

This property is read-only.

service_provider_metadata_authn_request_signed Property

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

Syntax

def get_service_provider_metadata_authn_request_signed() -> bool: ...
def set_service_provider_metadata_authn_request_signed(value: bool) -> None: ...

service_provider_metadata_authn_request_signed = property(get_service_provider_metadata_authn_request_signed, set_service_provider_metadata_authn_request_signed)

Default Value

FALSE

Remarks

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

service_provider_metadata_entity_id Property

The Entity Id for this service provider.

Syntax

def get_service_provider_metadata_entity_id() -> str: ...
def set_service_provider_metadata_entity_id(value: str) -> None: ...

service_provider_metadata_entity_id = property(get_service_provider_metadata_entity_id, set_service_provider_metadata_entity_id)

Default Value

""

Remarks

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

service_provider_metadata_metadata_content Property

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

Syntax

def get_service_provider_metadata_metadata_content() -> bytes: ...
def set_service_provider_metadata_metadata_content(value: bytes) -> None: ...

service_provider_metadata_metadata_content = property(get_service_provider_metadata_metadata_content, set_service_provider_metadata_metadata_content)

Default Value

""

Remarks

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

service_provider_metadata_signed_metadata Property

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

Syntax

def get_service_provider_metadata_signed_metadata() -> bool: ...
def set_service_provider_metadata_signed_metadata(value: bool) -> None: ...

service_provider_metadata_signed_metadata = property(get_service_provider_metadata_signed_metadata, set_service_provider_metadata_signed_metadata)

Default Value

FALSE

Remarks

Whether the class will sign the metadata document when it is being generated. When the build_service_metadata method is used to generate the metadata document, the class will use the service_provider_signing_cert property to sign the document.

service_provider_metadata_supported_name_id_formats Property

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

Syntax

def get_service_provider_metadata_supported_name_id_formats() -> str: ...
def set_service_provider_metadata_supported_name_id_formats(value: str) -> None: ...

service_provider_metadata_supported_name_id_formats = property(get_service_provider_metadata_supported_name_id_formats, set_service_provider_metadata_supported_name_id_formats)

Default Value

""

Remarks

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

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

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

service_provider_metadata_want_assertions_signed Property

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

Syntax

def get_service_provider_metadata_want_assertions_signed() -> bool: ...
def set_service_provider_metadata_want_assertions_signed(value: bool) -> None: ...

service_provider_metadata_want_assertions_signed = property(get_service_provider_metadata_want_assertions_signed, set_service_provider_metadata_want_assertions_signed)

Default Value

FALSE

Remarks

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

service_provider_signing_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_service_provider_signing_cert_store() -> bytes: ...
def set_service_provider_signing_cert_store(value: bytes) -> None: ...

service_provider_signing_cert_store = property(get_service_provider_signing_cert_store, set_service_provider_signing_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The service_provider_signing_cert_store_type property denotes the type of the certificate store specified by service_provider_signing_cert_store. If the store is password-protected, specify the password in service_provider_signing_cert_store_password.

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

Designations of certificate stores are platform dependent.

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

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

service_provider_signing_cert_store_password Property

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

Syntax

def get_service_provider_signing_cert_store_password() -> str: ...
def set_service_provider_signing_cert_store_password(value: str) -> None: ...

service_provider_signing_cert_store_password = property(get_service_provider_signing_cert_store_password, set_service_provider_signing_cert_store_password)

Default Value

""

Remarks

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

service_provider_signing_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_service_provider_signing_cert_store_type() -> int: ...
def set_service_provider_signing_cert_store_type(value: int) -> None: ...

service_provider_signing_cert_store_type = property(get_service_provider_signing_cert_store_type, set_service_provider_signing_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

service_provider_signing_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_service_provider_signing_cert_subject() -> str: ...
def set_service_provider_signing_cert_subject(value: str) -> None: ...

service_provider_signing_cert_subject = property(get_service_provider_signing_cert_subject, set_service_provider_signing_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

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

service_provider_signing_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_service_provider_signing_cert_encoded() -> bytes: ...
def set_service_provider_signing_cert_encoded(value: bytes) -> None: ...

service_provider_signing_cert_encoded = property(get_service_provider_signing_cert_encoded, set_service_provider_signing_cert_encoded)

Default Value

""

Remarks

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

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

service_provider_uri_count Property

The number of records in the ServiceProviderURI arrays.

Syntax

def get_service_provider_uri_count() -> int: ...
def set_service_provider_uri_count(value: int) -> None: ...

service_provider_uri_count = property(get_service_provider_uri_count, set_service_provider_uri_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• service_provider_uri_binding_ref
• service_provider_uri_binding_type
• service_provider_uri_index
• service_provider_uri_is_default
• service_provider_uri_location
• service_provider_uri_type

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

service_provider_uri_binding_ref Property

The URI reference for the set BindingType .

Syntax

def get_service_provider_uri_binding_ref(service_provider_uri_idx: int) -> str: ...
def set_service_provider_uri_binding_ref(service_provider_uri_idx: int, value: str) -> None: ...

Default Value

""

Remarks

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

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

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

The service_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the service_provider_uri_count property.

service_provider_uri_binding_type Property

The type of binding that is supported for this URI.

Syntax

def get_service_provider_uri_binding_type(service_provider_uri_idx: int) -> int: ...
def set_service_provider_uri_binding_type(service_provider_uri_idx: int, value: int) -> None: ...

Default Value

0

Remarks

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

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

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

The service_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the service_provider_uri_count property.

service_provider_uri_is_default Property

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

Syntax

def get_service_provider_uri_is_default(service_provider_uri_idx: int) -> bool: ...
def set_service_provider_uri_is_default(service_provider_uri_idx: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Whether this URI is the default URI that should be used for the specific service_provider_uriuri_type and service_provider_uri_binding_type combination.

The service_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the service_provider_uri_count property.

service_provider_uri_location Property

The address of the URI.

Syntax

def get_service_provider_uri_location(service_provider_uri_idx: int) -> str: ...
def set_service_provider_uri_location(service_provider_uri_idx: int, value: str) -> None: ...

Default Value

""

Remarks

The address of the URI.

The service_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the service_provider_uri_count property.

service_provider_uri_index Property

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

Syntax

def get_service_provider_uri_index(service_provider_uri_idx: int) -> int: ...
def set_service_provider_uri_index(service_provider_uri_idx: int, value: int) -> None: ...

Default Value

0

Remarks

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

The service_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the service_provider_uri_count property.

service_provider_uri_type Property

The purpose of the URI.

Syntax

def get_service_provider_uri_type(service_provider_uri_idx: int) -> int: ...
def set_service_provider_uri_type(service_provider_uri_idx: int, value: int) -> None: ...

Default Value

0

Remarks

The purpose of the URI. Possible values are:

The service_provider_uri_idx parameter specifies the index of the item in the array. The size of the array is controlled by the service_provider_uri_count property.

ssl_accept_server_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_ssl_accept_server_cert_effective_date() -> str: ...

ssl_accept_server_cert_effective_date = property(get_ssl_accept_server_cert_effective_date, None)

Default Value

""

Remarks

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

23-Jan-2000 15:00:00.

This property is read-only.

ssl_accept_server_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_ssl_accept_server_cert_expiration_date() -> str: ...

ssl_accept_server_cert_expiration_date = property(get_ssl_accept_server_cert_expiration_date, None)

Default Value

""

Remarks

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

23-Jan-2001 15:00:00.

This property is read-only.

ssl_accept_server_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_accept_server_cert_extended_key_usage() -> str: ...

ssl_accept_server_cert_extended_key_usage = property(get_ssl_accept_server_cert_extended_key_usage, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_fingerprint Property

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

Syntax

def get_ssl_accept_server_cert_fingerprint() -> str: ...

ssl_accept_server_cert_fingerprint = property(get_ssl_accept_server_cert_fingerprint, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_accept_server_cert_fingerprint_sha1 Property

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

Syntax

def get_ssl_accept_server_cert_fingerprint_sha1() -> str: ...

ssl_accept_server_cert_fingerprint_sha1 = property(get_ssl_accept_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_accept_server_cert_fingerprint_sha256 Property

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

Syntax

def get_ssl_accept_server_cert_fingerprint_sha256() -> str: ...

ssl_accept_server_cert_fingerprint_sha256 = property(get_ssl_accept_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_accept_server_cert_issuer Property

The issuer of the certificate.

Syntax

def get_ssl_accept_server_cert_issuer() -> str: ...

ssl_accept_server_cert_issuer = property(get_ssl_accept_server_cert_issuer, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key() -> str: ...

ssl_accept_server_cert_private_key = property(get_ssl_accept_server_cert_private_key, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_accept_server_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_accept_server_cert_private_key_available() -> bool: ...

ssl_accept_server_cert_private_key_available = property(get_ssl_accept_server_cert_private_key_available, None)

Default Value

FALSE

Remarks

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

This property is read-only.

ssl_accept_server_cert_private_key_container Property

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

Syntax

def get_ssl_accept_server_cert_private_key_container() -> str: ...

ssl_accept_server_cert_private_key_container = property(get_ssl_accept_server_cert_private_key_container, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_public_key Property

The public key of the certificate.

Syntax

def get_ssl_accept_server_cert_public_key() -> str: ...

ssl_accept_server_cert_public_key = property(get_ssl_accept_server_cert_public_key, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_public_key_algorithm Property

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

Syntax

def get_ssl_accept_server_cert_public_key_algorithm() -> str: ...

ssl_accept_server_cert_public_key_algorithm = property(get_ssl_accept_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_public_key_length Property

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

Syntax

def get_ssl_accept_server_cert_public_key_length() -> int: ...

ssl_accept_server_cert_public_key_length = property(get_ssl_accept_server_cert_public_key_length, None)

Default Value

0

Remarks

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

This property is read-only.

ssl_accept_server_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_accept_server_cert_serial_number() -> str: ...

ssl_accept_server_cert_serial_number = property(get_ssl_accept_server_cert_serial_number, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_accept_server_cert_signature_algorithm() -> str: ...

ssl_accept_server_cert_signature_algorithm = property(get_ssl_accept_server_cert_signature_algorithm, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_accept_server_cert_store() -> bytes: ...
def set_ssl_accept_server_cert_store(value: bytes) -> None: ...

ssl_accept_server_cert_store = property(get_ssl_accept_server_cert_store, set_ssl_accept_server_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password-protected, specify the password in ssl_accept_server_cert_store_password.

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

Designations of certificate stores are platform dependent.

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

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

ssl_accept_server_cert_store_password Property

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

Syntax

def get_ssl_accept_server_cert_store_password() -> str: ...
def set_ssl_accept_server_cert_store_password(value: str) -> None: ...

ssl_accept_server_cert_store_password = property(get_ssl_accept_server_cert_store_password, set_ssl_accept_server_cert_store_password)

Default Value

""

Remarks

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

ssl_accept_server_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_ssl_accept_server_cert_store_type() -> int: ...
def set_ssl_accept_server_cert_store_type(value: int) -> None: ...

ssl_accept_server_cert_store_type = property(get_ssl_accept_server_cert_store_type, set_ssl_accept_server_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

ssl_accept_server_cert_subject_alt_names Property

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

Syntax

def get_ssl_accept_server_cert_subject_alt_names() -> str: ...

ssl_accept_server_cert_subject_alt_names = property(get_ssl_accept_server_cert_subject_alt_names, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_md5() -> str: ...

ssl_accept_server_cert_thumbprint_md5 = property(get_ssl_accept_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha1() -> str: ...

ssl_accept_server_cert_thumbprint_sha1 = property(get_ssl_accept_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha256() -> str: ...

ssl_accept_server_cert_thumbprint_sha256 = property(get_ssl_accept_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_usage Property

The text description of UsageFlags .

Syntax

def get_ssl_accept_server_cert_usage() -> str: ...

ssl_accept_server_cert_usage = property(get_ssl_accept_server_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_accept_server_cert_usage_flags.

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

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

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

This property is read-only.

ssl_accept_server_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_ssl_accept_server_cert_usage_flags() -> int: ...

ssl_accept_server_cert_usage_flags = property(get_ssl_accept_server_cert_usage_flags, None)

Default Value

0

Remarks

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

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

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

This property is read-only.

ssl_accept_server_cert_version Property

The certificate's version number.

Syntax

def get_ssl_accept_server_cert_version() -> str: ...

ssl_accept_server_cert_version = property(get_ssl_accept_server_cert_version, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_accept_server_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_accept_server_cert_subject() -> str: ...
def set_ssl_accept_server_cert_subject(value: str) -> None: ...

ssl_accept_server_cert_subject = property(get_ssl_accept_server_cert_subject, set_ssl_accept_server_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

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

ssl_accept_server_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_accept_server_cert_encoded() -> bytes: ...
def set_ssl_accept_server_cert_encoded(value: bytes) -> None: ...

ssl_accept_server_cert_encoded = property(get_ssl_accept_server_cert_encoded, set_ssl_accept_server_cert_encoded)

Default Value

""

Remarks

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

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

ssl_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_ssl_cert_effective_date() -> str: ...

ssl_cert_effective_date = property(get_ssl_cert_effective_date, None)

Default Value

""

Remarks

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

23-Jan-2000 15:00:00.

This property is read-only.

ssl_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_ssl_cert_expiration_date() -> str: ...

ssl_cert_expiration_date = property(get_ssl_cert_expiration_date, None)

Default Value

""

Remarks

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

23-Jan-2001 15:00:00.

This property is read-only.

ssl_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_cert_extended_key_usage() -> str: ...

ssl_cert_extended_key_usage = property(get_ssl_cert_extended_key_usage, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_fingerprint Property

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

Syntax

def get_ssl_cert_fingerprint() -> str: ...

ssl_cert_fingerprint = property(get_ssl_cert_fingerprint, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_cert_fingerprint_sha1 Property

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

Syntax

def get_ssl_cert_fingerprint_sha1() -> str: ...

ssl_cert_fingerprint_sha1 = property(get_ssl_cert_fingerprint_sha1, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_cert_fingerprint_sha256 Property

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

Syntax

def get_ssl_cert_fingerprint_sha256() -> str: ...

ssl_cert_fingerprint_sha256 = property(get_ssl_cert_fingerprint_sha256, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_cert_issuer Property

The issuer of the certificate.

Syntax

def get_ssl_cert_issuer() -> str: ...

ssl_cert_issuer = property(get_ssl_cert_issuer, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_ssl_cert_private_key() -> str: ...

ssl_cert_private_key = property(get_ssl_cert_private_key, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_cert_private_key_available() -> bool: ...

ssl_cert_private_key_available = property(get_ssl_cert_private_key_available, None)

Default Value

FALSE

Remarks

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

This property is read-only.

ssl_cert_private_key_container Property

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

Syntax

def get_ssl_cert_private_key_container() -> str: ...

ssl_cert_private_key_container = property(get_ssl_cert_private_key_container, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_public_key Property

The public key of the certificate.

Syntax

def get_ssl_cert_public_key() -> str: ...

ssl_cert_public_key = property(get_ssl_cert_public_key, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_public_key_algorithm Property

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

Syntax

def get_ssl_cert_public_key_algorithm() -> str: ...

ssl_cert_public_key_algorithm = property(get_ssl_cert_public_key_algorithm, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_public_key_length Property

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

Syntax

def get_ssl_cert_public_key_length() -> int: ...

ssl_cert_public_key_length = property(get_ssl_cert_public_key_length, None)

Default Value

0

Remarks

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

This property is read-only.

ssl_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_cert_serial_number() -> str: ...

ssl_cert_serial_number = property(get_ssl_cert_serial_number, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_cert_signature_algorithm() -> str: ...

ssl_cert_signature_algorithm = property(get_ssl_cert_signature_algorithm, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_cert_store() -> bytes: ...
def set_ssl_cert_store(value: bytes) -> None: ...

ssl_cert_store = property(get_ssl_cert_store, set_ssl_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

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

Designations of certificate stores are platform dependent.

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

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

ssl_cert_store_password Property

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

Syntax

def get_ssl_cert_store_password() -> str: ...
def set_ssl_cert_store_password(value: str) -> None: ...

ssl_cert_store_password = property(get_ssl_cert_store_password, set_ssl_cert_store_password)

Default Value

""

Remarks

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

ssl_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_ssl_cert_store_type() -> int: ...
def set_ssl_cert_store_type(value: int) -> None: ...

ssl_cert_store_type = property(get_ssl_cert_store_type, set_ssl_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

ssl_cert_subject_alt_names Property

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

Syntax

def get_ssl_cert_subject_alt_names() -> str: ...

ssl_cert_subject_alt_names = property(get_ssl_cert_subject_alt_names, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_md5() -> str: ...

ssl_cert_thumbprint_md5 = property(get_ssl_cert_thumbprint_md5, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha1() -> str: ...

ssl_cert_thumbprint_sha1 = property(get_ssl_cert_thumbprint_sha1, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha256() -> str: ...

ssl_cert_thumbprint_sha256 = property(get_ssl_cert_thumbprint_sha256, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_usage Property

The text description of UsageFlags .

Syntax

def get_ssl_cert_usage() -> str: ...

ssl_cert_usage = property(get_ssl_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

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

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

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

This property is read-only.

ssl_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_ssl_cert_usage_flags() -> int: ...

ssl_cert_usage_flags = property(get_ssl_cert_usage_flags, None)

Default Value

0

Remarks

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

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

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

This property is read-only.

ssl_cert_version Property

The certificate's version number.

Syntax

def get_ssl_cert_version() -> str: ...

ssl_cert_version = property(get_ssl_cert_version, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_cert_subject() -> str: ...
def set_ssl_cert_subject(value: str) -> None: ...

ssl_cert_subject = property(get_ssl_cert_subject, set_ssl_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

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

ssl_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_cert_encoded() -> bytes: ...
def set_ssl_cert_encoded(value: bytes) -> None: ...

ssl_cert_encoded = property(get_ssl_cert_encoded, set_ssl_cert_encoded)

Default Value

""

Remarks

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

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

ssl_provider Property

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

Syntax

def get_ssl_provider() -> int: ...
def set_ssl_provider(value: int) -> None: ...

ssl_provider = property(get_ssl_provider, set_ssl_provider)

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, on Windows, the class will use the platform implementation. On Linux/macOS, the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.

ssl_server_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_ssl_server_cert_effective_date() -> str: ...

ssl_server_cert_effective_date = property(get_ssl_server_cert_effective_date, None)

Default Value

""

Remarks

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

23-Jan-2000 15:00:00.

This property is read-only.

ssl_server_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_ssl_server_cert_expiration_date() -> str: ...

ssl_server_cert_expiration_date = property(get_ssl_server_cert_expiration_date, None)

Default Value

""

Remarks

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

23-Jan-2001 15:00:00.

This property is read-only.

ssl_server_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_server_cert_extended_key_usage() -> str: ...

ssl_server_cert_extended_key_usage = property(get_ssl_server_cert_extended_key_usage, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_fingerprint Property

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

Syntax

def get_ssl_server_cert_fingerprint() -> str: ...

ssl_server_cert_fingerprint = property(get_ssl_server_cert_fingerprint, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_server_cert_fingerprint_sha1 Property

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

Syntax

def get_ssl_server_cert_fingerprint_sha1() -> str: ...

ssl_server_cert_fingerprint_sha1 = property(get_ssl_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_server_cert_fingerprint_sha256 Property

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

Syntax

def get_ssl_server_cert_fingerprint_sha256() -> str: ...

ssl_server_cert_fingerprint_sha256 = property(get_ssl_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_server_cert_issuer Property

The issuer of the certificate.

Syntax

def get_ssl_server_cert_issuer() -> str: ...

ssl_server_cert_issuer = property(get_ssl_server_cert_issuer, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_ssl_server_cert_private_key() -> str: ...

ssl_server_cert_private_key = property(get_ssl_server_cert_private_key, None)

Default Value

""

Remarks

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

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

This property is read-only.

ssl_server_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_server_cert_private_key_available() -> bool: ...

ssl_server_cert_private_key_available = property(get_ssl_server_cert_private_key_available, None)

Default Value

FALSE

Remarks

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

This property is read-only.

ssl_server_cert_private_key_container Property

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

Syntax

def get_ssl_server_cert_private_key_container() -> str: ...

ssl_server_cert_private_key_container = property(get_ssl_server_cert_private_key_container, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_public_key Property

The public key of the certificate.

Syntax

def get_ssl_server_cert_public_key() -> str: ...

ssl_server_cert_public_key = property(get_ssl_server_cert_public_key, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_public_key_algorithm Property

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

Syntax

def get_ssl_server_cert_public_key_algorithm() -> str: ...

ssl_server_cert_public_key_algorithm = property(get_ssl_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_public_key_length Property

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

Syntax

def get_ssl_server_cert_public_key_length() -> int: ...

ssl_server_cert_public_key_length = property(get_ssl_server_cert_public_key_length, None)

Default Value

0

Remarks

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

This property is read-only.

ssl_server_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_server_cert_serial_number() -> str: ...

ssl_server_cert_serial_number = property(get_ssl_server_cert_serial_number, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_server_cert_signature_algorithm() -> str: ...

ssl_server_cert_signature_algorithm = property(get_ssl_server_cert_signature_algorithm, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_server_cert_store() -> bytes: ...

ssl_server_cert_store = property(get_ssl_server_cert_store, None)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_server_cert_store_type property denotes the type of the certificate store specified by ssl_server_cert_store. If the store is password-protected, specify the password in ssl_server_cert_store_password.

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

Designations of certificate stores are platform dependent.

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

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

This property is read-only.

ssl_server_cert_store_password Property

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

Syntax

def get_ssl_server_cert_store_password() -> str: ...

ssl_server_cert_store_password = property(get_ssl_server_cert_store_password, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_ssl_server_cert_store_type() -> int: ...

ssl_server_cert_store_type = property(get_ssl_server_cert_store_type, None)

Default Value

0

Remarks

The type of certificate store for this certificate.

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

This property is read-only.

ssl_server_cert_subject_alt_names Property

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

Syntax

def get_ssl_server_cert_subject_alt_names() -> str: ...

ssl_server_cert_subject_alt_names = property(get_ssl_server_cert_subject_alt_names, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_md5() -> str: ...

ssl_server_cert_thumbprint_md5 = property(get_ssl_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_sha1() -> str: ...

ssl_server_cert_thumbprint_sha1 = property(get_ssl_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_sha256() -> str: ...

ssl_server_cert_thumbprint_sha256 = property(get_ssl_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_usage Property

The text description of UsageFlags .

Syntax

def get_ssl_server_cert_usage() -> str: ...

ssl_server_cert_usage = property(get_ssl_server_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_server_cert_usage_flags.

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

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

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

This property is read-only.

ssl_server_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_ssl_server_cert_usage_flags() -> int: ...

ssl_server_cert_usage_flags = property(get_ssl_server_cert_usage_flags, None)

Default Value

0

Remarks

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

Please see the ssl_server_cert_usage property for a text representation of ssl_server_cert_usage_flags.

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

This property is read-only.

ssl_server_cert_version Property

The certificate's version number.

Syntax

def get_ssl_server_cert_version() -> str: ...

ssl_server_cert_version = property(get_ssl_server_cert_version, None)

Default Value

""

Remarks

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

This property is read-only.

ssl_server_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_server_cert_subject() -> str: ...

ssl_server_cert_subject = property(get_ssl_server_cert_subject, None)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

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

This property is read-only.

ssl_server_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_server_cert_encoded() -> bytes: ...

ssl_server_cert_encoded = property(get_ssl_server_cert_encoded, None)

Default Value

""

Remarks

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

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

This property is read-only.

build_authn_request Method

Builds an Authentication Request.

Syntax

def build_authn_request() -> None: ...

Remarks

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

• HTTP Redirect - saml_request_url
• HTTP Post - saml_request_url, saml_request_body

The Assertion Consumer Service that should handle the response specified in the request depends on how saml_request_settings is configured. If saml_request_use_default_endpoint is set, the request will specify that the Identity Provider should use the URI that is configured as the default. If saml_request_selected_endpoint is set, the class will use that index in the request. Otherwise, the class will select the first URI set in the service_provider_ur_is properties.

build_logout_request Method

Builds a Single Logout request.

Syntax

def build_logout_request(name_identifier: str) -> None: ...

Remarks

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

• HTTP Redirect - saml_request_url
• HTTP Post - saml_request_url, saml_request_body

build_service_metadata Method

Builds a metadata document for a service provider.

Syntax

def build_service_metadata() -> None: ...

Remarks

This method uses the service_provider_metadata 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:

• service_provider_metadata_authn_request_signed
• service_provider_metadata_entity_id
• service_provider_metadata_signed_metadata
• service_provider_metadata_supported_name_id_formats
• service_provider_metadata_want_assertions_signed
• service_provider_signing_cert
• service_provider_ur_is

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

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.

do_events Method

This method processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

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

get_assertion_attribute Method

Searches for a specific assertion attribute.

Syntax

def get_assertion_attribute(attr_name: str) -> str: ...

Remarks

This method will search the current assertion_attribute_info 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

This method interrupts the current method.

Syntax

def interrupt() -> None: ...

Remarks

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

load_identity_metadata Method

Loads an identity provider's metadata document.

Syntax

def load_identity_metadata(metadata_document: str, validate: bool) -> None: ...

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 identity_provider_encrypting_cert, identity_provider_metadata, identity_provider_signing_cert and identity_provider_ur_is 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.

parse_assertion Method

Parses an assertion.

Syntax

def parse_assertion() -> None: ...

Remarks

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

parse_saml_response Method

Parses a SAMLResponse.

Syntax

def parse_saml_response() -> None: ...

Remarks

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

To validate a SAMLResponse, see validate_saml_response.

Additionally, if the saml_response_response_type is srtAuthn, the assertion_assertion_content property will be populated. See validate_assertion and parse_assertion for more information on validating and parsing the assertion.

process_saml_response Method

Processes the SAMLResponse from the current HTTP request.

Syntax

def process_saml_response() -> None: ...

Remarks

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

• parse_saml_response
• validate_saml_response
• parse_assertion
• validate_assertion

request_identity_metadata Method

Requests an identity provider's SAML metadata document.

Syntax

def request_identity_metadata(url: str) -> None: ...

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 identity_provider_encrypting_cert, identity_provider_metadata, identity_provider_signing_cert, and identity_provider_ur_is properties will be populated with the information that is available in the document.

reset Method

This method will reset the class.

Syntax

def reset() -> None: ...

Remarks

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

validate_assertion Method

Validates an assertion.

Syntax

def validate_assertion() -> None: ...

Remarks

This method validates the assertion found in the assertion_info property. The assertion can either be manually set via the assertion_assertion_content property or by first calling parse_saml_response on a SAMLResponse that contains an assertion. Before attempting this validation, the on_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.

validate_saml_response Method

Validates a SAMLResponse.

Syntax

def validate_saml_response() -> None: ...

Remarks

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

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

on_assertion Event

Fired when an assertion is validated.

Syntax

class SAMLAssertionEventParams(object):
  @property
  def issuer() -> str: ...

  @property
  def in_response_to() -> str: ...

# In class SAML:
@property
def on_assertion() -> Callable[[SAMLAssertionEventParams], None]: ...
@on_assertion.setter
def on_assertion(event_hook: Callable[[SAMLAssertionEventParams], None]) -> None: ...

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

on_error Event

Fired when information is available about errors during data delivery.

Syntax

class SAMLErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class SAML:
@property
def on_error() -> Callable[[SAMLErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[SAMLErrorEventParams], None]) -> None: ...

Remarks

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

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

on_log Event

Fired once for each log message.

Syntax

class SAMLLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class SAML:
@property
def on_log() -> Callable[[SAMLLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[SAMLLogEventParams], None]) -> None: ...

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"

on_redirect Event

Fired when a redirection is received from the server.

Syntax

class SAMLRedirectEventParams(object):
  @property
  def location() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class SAML:
@property
def on_redirect() -> Callable[[SAMLRedirectEventParams], None]: ...
@on_redirect.setter
def on_redirect(event_hook: Callable[[SAMLRedirectEventParams], None]) -> None: ...

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 fails with an error. Location is the location to which the client is being redirected. Further control over redirection is provided in the follow_redirects property.

on_saml_response Event

Fired when a SAMLResponse is validated.

Syntax

class SAMLSAMLResponseEventParams(object):
  @property
  def issuer() -> str: ...

  @property
  def in_response_to() -> str: ...

# In class SAML:
@property
def on_saml_response() -> Callable[[SAMLSAMLResponseEventParams], None]: ...
@on_saml_response.setter
def on_saml_response(event_hook: Callable[[SAMLSAMLResponseEventParams], None]) -> None: ...

Remarks

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

on_ssl_server_authentication Event

Fired after the server presents its certificate to the client.

Syntax

class SAMLSSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def status() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class SAML:
@property
def on_ssl_server_authentication() -> Callable[[SAMLSSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[SAMLSSLServerAuthenticationEventParams], None]) -> None: ...

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.

on_ssl_status Event

Fired when secure connection progress messages are available.

Syntax

class SAMLSSLStatusEventParams(object):
  @property
  def message() -> str: ...

# In class SAML:
@property
def on_ssl_status() -> Callable[[SAMLSSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[SAMLSSLStatusEventParams], None]) -> None: ...

Remarks

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

SAML Config Settings

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