SAML Class

Properties   Methods   Events   Config Settings   Errors  

The SAML class is used to obtain security tokens and assertions.

Syntax

class ipworksauth.SAML

Remarks

The SAML class provides an easy-to-use interface to obtain security tokens and assertions. The class can also be used to parse assertions and inspect the claims within.

The component has built in support for working with Microsoft SharePoint Online and Microsoft Dynamics CRM Online. This support means only a minimum of information needs to be supplied to the component.

Microsoft SharePoint Online and Dynamics CRM Online

To begin working with SharePoint Online or Dynamics CRM Online first set the auth_mode to the appropriate value. The class will automatically populate several properties to known values. Set the user, password, application_urn properties and call get_security_token. For instance:

component.AuthMode = SAMLAuthModes.amDynamicsCRM; //dynamic crm component.User = "user@mycrm.onmicrosoft.com"; component.Password = "password"; component.ApplicationURN = "urn:crmapac:dynamics.com"; component.GetSecurityToken(); After calling get_security_token the security_token_xml property will be populated.

ADFS and Others

When working with ADFS or another Security Token Service (STS) the get_assertion method may be used to obtain an assertion. To begin set auth_mode to either amADFS or amCustom. Then set local_sts, user, password, and application_urn. For instance:

component.AuthMode = SAMLAuthModes.amADFS; component.User = "administrator"; component.Password = "admin"; component.LocalSTS = "https://adfs.contoso.com"; component.ApplicationURN = "https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/"; component.GetAssertion(); If the assertion is signed the class will use the certificate specified in signer_cert to verify the signature. If signer_cert is not set the class will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• assertion_id
• assertion_issue_instant
• assertion_issuer
• assertion_not_before
• assertion_not_on_or_after
• assertion_subject
• assertion_version
• assertion_xml
• Claim* properties

Parsing an Assertion

The class may also be used to parse an existing assertion without contacting a STS. To parse an existing assertion call parse_assertion with the assertion XML. If the assertion is signed the class will use the certificate specified in signer_cert to verify the signature. If signer_cert is not set the class will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• assertion_id
• assertion_issue_instant
• assertion_issuer
• assertion_not_before
• assertion_not_on_or_after
• assertion_subject
• assertion_version
• assertion_xml
• Claim* properties

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.

application_urn Property

The application's Uniform Resource Name (URN).

Syntax

def get_application_urn() -> str: ...
def set_application_urn(value: str) -> None: ...

application_urn = property(get_application_urn, set_application_urn)

Default Value

""

Remarks

This property specifies the application's Uniform Resource Name (URN). This must be set before calling get_assertion or get_security_token.

When auth_mode is set to amDynamicsCRM the value specified here depends on the location of the account. Valid values are:

When auth_mode is set to camSharePointOnline this value is typically the URL to your site. For instance: "https://mycrm.sharepoint.com".

assertion_id Property

The assertion id.

Syntax

def get_assertion_id() -> str: ...

assertion_id = property(get_assertion_id, None)

Default Value

""

Remarks

This property hold the id of the assertion.

This property is read-only.

assertion_issue_instant Property

The time in UTC that the assertion was issued.

Syntax

def get_assertion_issue_instant() -> str: ...

assertion_issue_instant = property(get_assertion_issue_instant, None)

Default Value

""

Remarks

This property holds the time that the assertion was issued.

This is in the standard xsd:dateTime format "YYYY-MM-DDThh:mm:ss". The date is specified in UTC.

This property is read-only.

assertion_issuer Property

The assertion issuer.

Syntax

def get_assertion_issuer() -> str: ...

assertion_issuer = property(get_assertion_issuer, None)

Default Value

""

Remarks

This property holds the issuer of the assertion.

This property is read-only.

assertion_not_before Property

The date on which the assertion becomes valid.

Syntax

def get_assertion_not_before() -> str: ...

assertion_not_before = property(get_assertion_not_before, None)

Default Value

""

Remarks

This property specifies the earliest time instant at which the assertion is valid.

This is in the standard xsd:dateTime format "YYYY-MM-DDThh:mm:ss". The date is specified in UTC.

This property is read-only.

assertion_not_on_or_after Property

The time at which the assertion expires.

Syntax

def get_assertion_not_on_or_after() -> str: ...

assertion_not_on_or_after = property(get_assertion_not_on_or_after, None)

Default Value

""

Remarks

This property specifies the time instant at which the assertion has expired.

This is in the standard xsd:dateTime format "YYYY-MM-DDThh:mm:ss". The date is specified in UTC.

This property is read-only.

assertion_subject Property

The subject of the assertion.

Syntax

def get_assertion_subject() -> str: ...

assertion_subject = property(get_assertion_subject, None)

Default Value

""

Remarks

This property holds the subject of the assertion.

This property is read-only.

assertion_version Property

The version of the assertion.

Syntax

def get_assertion_version() -> int: ...
def set_assertion_version(value: int) -> None: ...

assertion_version = property(get_assertion_version, set_assertion_version)

Default Value

0

Remarks

This property specifies the version of the assertion. This may be set before calling get_assertion. This will be populated after calling parse_assertion. Possible values are:

assertion_xml Property

The assertion XML.

Syntax

def get_assertion_xml() -> str: ...

assertion_xml = property(get_assertion_xml, None)

Default Value

""

Remarks

This property holds the returned assertion. This is populated after calling get_assertion.

This property is read-only.

auth_mode Property

The authentication mode.

Syntax

def get_auth_mode() -> int: ...
def set_auth_mode(value: int) -> None: ...

auth_mode = property(get_auth_mode, set_auth_mode)

Default Value

0

Remarks

This property specifies the authentication mode. Possible values are:

When this property is set the component is initialized based on common settings for the selected mode.

Setting this property to 2 (camADFS) or 3 (camCustom) will clear the values in federation_urn, and federation_sts. There is no functional difference between 2 (camADFS) and 3 (camCustom), they operate identically.

Setting this property to 0 (camSharePointOnline) or 1 (camDynamicsCRM) will populate federation_urn, and federation_sts with known valid values for federation_urn, and federation_sts.

The table below shows which properties are set depending on the value of this property.

The value 3 (camCustom) may be used with any STS as long as WS-TRUST is supported.

cert_encoded Property

This is the certificate (PEM/base64 encoded).

Syntax

def get_cert_encoded() -> bytes: ...
def set_cert_encoded(value: bytes) -> None: ...

cert_encoded = property(get_cert_encoded, set_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The cert_store and cert_subject properties also may be used to specify a certificate.

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

cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_cert_store() -> bytes: ...
def set_cert_store(value: bytes) -> None: ...

cert_store = property(get_cert_store, set_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The cert_store_type property denotes the type of the certificate store specified by cert_store. If the store is password protected, specify the password in cert_store_password.

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

Designations of certificate stores are platform-dependent.

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

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

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_cert_store_password() -> str: ...
def set_cert_store_password(value: str) -> None: ...

cert_store_password = property(get_cert_store_password, set_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.

cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_cert_store_type() -> int: ...
def set_cert_store_type(value: int) -> None: ...

cert_store_type = property(get_cert_store_type, set_cert_store_type)

Default Value

0

Remarks

This is 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:

cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_cert_subject() -> str: ...
def set_cert_subject(value: str) -> None: ...

cert_subject = property(get_cert_subject, set_cert_subject)

Default Value

""

Remarks

This is 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 displayed below.

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

claim_count Property

The number of records in the Claim arrays.

Syntax

def get_claim_count() -> int: ...

claim_count = property(get_claim_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• claim_issuer_name
• claim_original_issuer
• claim_property_count
• claim_property_index
• claim_property_name
• claim_property_value
• claim_type_name
• claim_value
• claim_value_type

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

This property is read-only.

claim_issuer_name Property

The name of the issuer.

Syntax

def get_claim_issuer_name(claim_index: int) -> str: ...

Default Value

""

Remarks

The name of the issuer. This may be a URL like "http://adfs.contoso.com/adfs/services/trust".

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_original_issuer Property

The name of the original issuer.

Syntax

def get_claim_original_issuer(claim_index: int) -> str: ...

Default Value

""

Remarks

The name of the original issuer. This may be a URL like "http://adfs.contoso.com/adfs/services/trust".

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_property_count Property

The number of properties in the claim.

Syntax

def get_claim_property_count(claim_index: int) -> int: ...

Default Value

0

Remarks

The number of properties in the claim.

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_property_index Property

Selects a property.

Syntax

def get_claim_property_index(claim_index: int) -> int: ...
def set_claim_property_index(claim_index: int, value: int) -> None: ...

Default Value

0

Remarks

Selects a property. This is valid from 0 to claim_property_count. To inspect a property, first set this property and then inspect claim_property_name and claim_property_value. For instance: for(int i=0;i<component.Claims[0].PropertyCount;i++) { component.Claims[0].PropertyIndex = i; Console.WriteLine(component.Claims[0].PropertyName + ": " + component.Claims[0].PropertyValue); }

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

claim_property_name Property

The name of the property.

Syntax

def get_claim_property_name(claim_index: int) -> str: ...

Default Value

""

Remarks

The name of the property.

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_property_value Property

The value of the property.

Syntax

def get_claim_property_value(claim_index: int) -> str: ...

Default Value

""

Remarks

The value of the property.

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_type_name Property

The type name of the claim.

Syntax

def get_claim_type_name(claim_index: int) -> str: ...

Default Value

""

Remarks

The type name of the claim. This may be a value like "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier".

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_value Property

The value of the claim.

Syntax

def get_claim_value(claim_index: int) -> str: ...

Default Value

""

Remarks

The value of the claim.

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

claim_value_type Property

The type of value.

Syntax

def get_claim_value_type(claim_index: int) -> str: ...

Default Value

""

Remarks

The type of value. This may be a value like "http://www.w3.org/2001/XMLSchema#string".

The claim_index parameter specifies the index of the item in the array. The size of the array is controlled by the claim_count property.

This property is read-only.

federation_sts Property

The URL of the federation Security Token Service (STS).

Syntax

def get_federation_sts() -> str: ...
def set_federation_sts(value: str) -> None: ...

federation_sts = property(get_federation_sts, set_federation_sts)

Default Value

""

Remarks

This property specifies the URL of the federation Security Token Service (STS). When auth_mode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) this property is automatically populated.

federation_urn Property

The federation Uniform Resource Name (URN).

Syntax

def get_federation_urn() -> str: ...
def set_federation_urn(value: str) -> None: ...

federation_urn = property(get_federation_urn, set_federation_urn)

Default Value

""

Remarks

This property specifies the federation Uniform Resource Name (URN). This property is automatically populated when auth_mode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM).

local_sts Property

The local Security Token Service (STS).

Syntax

def get_local_sts() -> str: ...
def set_local_sts(value: str) -> None: ...

local_sts = property(get_local_sts, set_local_sts)

Default Value

""

Remarks

This property specifies the URL of the local Security Token Service(STS).

When auth_mode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) if this is not specified, then the class will attempt to determine this value automatically by querying the UserRealm.

When auth_mode is set to 2 (camADFS) or 3 (camCustom) this property is required.

password Property

The user's password.

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

Default Value

""

Remarks

This property specifies the user's password. This must be set before calling get_assertion or get_security_token.

proxy_auth_scheme Property

This property is used to tell the class which 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

This property is used to tell the class which 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 component 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

This property tells the class whether or not 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

This property tells the class whether or not to automatically detect and use proxy system settings, if available. The default value is False.

proxy_password Property

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

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

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

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

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

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

proxy_user Property

This property contains a user name, 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

This property contains a user name, if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password 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.

security_token_xml Property

The security token XML.

Syntax

def get_security_token_xml() -> str: ...

security_token_xml = property(get_security_token_xml, None)

Default Value

""

Remarks

This property holds the security token. This is populated after calling get_security_token.

This property is read-only.

signer_cert_encoded Property

This is the certificate (PEM/base64 encoded).

Syntax

def get_signer_cert_encoded() -> bytes: ...
def set_signer_cert_encoded(value: bytes) -> None: ...

signer_cert_encoded = property(get_signer_cert_encoded, set_signer_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The signer_cert_store and signer_cert_subject properties also may be used to specify a certificate.

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

signer_cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_signer_cert_store() -> bytes: ...
def set_signer_cert_store(value: bytes) -> None: ...

signer_cert_store = property(get_signer_cert_store, set_signer_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The signer_cert_store_type property denotes the type of the certificate store specified by signer_cert_store. If the store is password protected, specify the password in signer_cert_store_password.

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

Designations of certificate stores are platform-dependent.

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

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

signer_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_signer_cert_store_password() -> str: ...
def set_signer_cert_store_password(value: str) -> None: ...

signer_cert_store_password = property(get_signer_cert_store_password, set_signer_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.

signer_cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_signer_cert_store_type() -> int: ...
def set_signer_cert_store_type(value: int) -> None: ...

signer_cert_store_type = property(get_signer_cert_store_type, set_signer_cert_store_type)

Default Value

0

Remarks

This is 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:

signer_cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_signer_cert_subject() -> str: ...
def set_signer_cert_subject(value: str) -> None: ...

signer_cert_subject = property(get_signer_cert_subject, set_signer_cert_subject)

Default Value

""

Remarks

This is 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 displayed below.

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

ssl_accept_server_cert_encoded Property

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

This is 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_encoded Property

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

This is 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_cert_store Property

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

This is 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 are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 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

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

This is 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 Property

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

This is 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 displayed below.

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

ssl_provider Property

This specifies the 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:

Additional Notes

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

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

This is 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.

user Property

The username.

Syntax

def get_user() -> str: ...
def set_user(value: str) -> None: ...

user = property(get_user, set_user)

Default Value

""

Remarks

This property specifies the username. This must be set before calling get_assertion or get_security_token.

attr_count Property

The number of records in the Attr arrays.

Syntax

def get_attr_count() -> int: ...
def set_attr_count(value: int) -> None: ...

attr_count = property(get_attr_count, set_attr_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• attr_name
• attr_namespace
• attr_prefix
• attr_value

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

attr_name Property

The Name provides the local name (without prefix) of the attribute.

Syntax

def get_attr_name(attr_index: int) -> str: ...

Default Value

""

Remarks

The attr_name provides the local name (without prefix) of the attribute.

The attr_index parameter specifies the index of the item in the array. The size of the array is controlled by the attr_count property.

This property is read-only.

attr_namespace Property

Attribute namespace.

Syntax

def get_attr_namespace(attr_index: int) -> str: ...

Default Value

""

Remarks

Attribute namespace.

The attr_index parameter specifies the index of the item in the array. The size of the array is controlled by the attr_count property.

This property is read-only.

attr_prefix Property

Attribute prefix (if any).

Syntax

def get_attr_prefix(attr_index: int) -> str: ...

Default Value

""

Remarks

Attribute prefix (if any). If the attribute does not have a prefix, this property is empty.

The attr_index parameter specifies the index of the item in the array. The size of the array is controlled by the attr_count property.

This property is read-only.

attr_value Property

Attribute value.

Syntax

def get_attr_value(attr_index: int) -> str: ...

Default Value

""

Remarks

Attribute value.

The attr_index parameter specifies the index of the item in the array. The size of the array is controlled by the attr_count property.

This property is read-only.

x_child_count Property

The number of records in the XChild arrays.

Syntax

def get_x_child_count() -> int: ...
def set_x_child_count(value: int) -> None: ...

x_child_count = property(get_x_child_count, set_x_child_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• x_child_name
• x_child_namespace
• x_child_prefix
• x_child_x_text

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

x_child_name Property

The Name property provides the local name (without prefix) of the element.

Syntax

def get_x_child_name(x_child_index: int) -> str: ...

Default Value

""

Remarks

The x_child_name property provides the local name (without prefix) of the element.

The x_child_index parameter specifies the index of the item in the array. The size of the array is controlled by the x_child_count property.

This property is read-only.

x_child_namespace Property

Namespace of the element.

Syntax

def get_x_child_namespace(x_child_index: int) -> str: ...

Default Value

""

Remarks

Namespace of the element.

The x_child_index parameter specifies the index of the item in the array. The size of the array is controlled by the x_child_count property.

This property is read-only.

x_child_prefix Property

Prefix of the element (if any).

Syntax

def get_x_child_prefix(x_child_index: int) -> str: ...

Default Value

""

Remarks

Prefix of the element (if any). If the element does not have a prefix, this property is empty.

The x_child_index parameter specifies the index of the item in the array. The size of the array is controlled by the x_child_count property.

This property is read-only.

x_child_x_text Property

The inner text of the element.

Syntax

def get_x_child_x_text(x_child_index: int) -> str: ...

Default Value

""

Remarks

The inner text of the element.

The x_child_index parameter specifies the index of the item in the array. The size of the array is controlled by the x_child_count property.

This property is read-only.

x_element Property

The name of the current element.

Syntax

def get_x_element() -> str: ...
def set_x_element(value: str) -> None: ...

x_element = property(get_x_element, set_x_element)

Default Value

""

Remarks

The current element is specified via the xpath property.

x_namespace Property

The namespace of the current element.

Syntax

def get_x_namespace() -> str: ...
def set_x_namespace(value: str) -> None: ...

x_namespace = property(get_x_namespace, set_x_namespace)

Default Value

""

Remarks

The current element is specified via the xpath property.

x_parent Property

The parent of the current element.

Syntax

def get_x_parent() -> str: ...

x_parent = property(get_x_parent, None)

Default Value

""

Remarks

The current element is specified via the xpath property.

This property is read-only.

xpath Property

Provides a way to point to a specific element in the document.

Syntax

def get_xpath() -> str: ...
def set_xpath(value: str) -> None: ...

xpath = property(get_xpath, set_xpath)

Default Value

""

Remarks

xpath implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML documents.

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current xpath location.

The following are possible values for an element accessor:

When xpath is set to a valid path, x_element points to the name of the element, with x_parent, x_namespace, x_prefix, x_child_name, x_child_namespace, x_child_prefix, x_child_x_text, and x_text providing other properties of the element. The attributes of the current element are provided in the attr_name, attr_namespace, attr_prefix, and attr_value properties.

build_dom must be set to True prior to parsing the document for the xpath functionality to be available.

Example (Setting XPath):

x_prefix Property

The prefix of the current element.

Syntax

def get_x_prefix() -> str: ...
def set_x_prefix(value: str) -> None: ...

x_prefix = property(get_x_prefix, set_x_prefix)

Default Value

""

Remarks

The current element is specified via the xpath property.

x_sub_tree Property

A snapshot of the current element in the document.

Syntax

def get_x_sub_tree() -> str: ...

x_sub_tree = property(get_x_sub_tree, None)

Default Value

""

Remarks

The current element is specified via the xpath property. In order for this property to work you must have the CacheContent set to true.

This property is read-only.

x_text Property

The text of the current element.

Syntax

def get_x_text() -> str: ...
def set_x_text(value: str) -> None: ...

x_text = property(get_x_text, set_x_text)

Default Value

""

Remarks

The current element is specified via the xpath property.

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.

get_assertion Method

Gets the assertion.

Syntax

def get_assertion() -> None: ...

Remarks

This method communicates with local_sts as to obtain an assertion.

When auth_mode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) the class will automatically populate various properties to known values to reduce the number of required settings. Typically only the following properties are required:

• user
• password
• application_urn

When auth_mode is set to 2 (camADFS) or 3 (camCustom) the following properties are required:

• user
• password
• application_urn
• local_sts

If the assertion is signed the class will use the certificate specified in signer_cert to verify the signature. If signer_cert is not set the class will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• assertion_id
• assertion_issue_instant
• assertion_issuer
• assertion_not_before
• assertion_not_on_or_after
• assertion_subject
• assertion_version
• assertion_xml
• Claim* properties

get_security_token Method

Gets the security token.

Syntax

def get_security_token() -> None: ...

Remarks

This method communicates with federation_sts and local_sts as applicable to obtain a security token. The security_token_xml property will be populated with the retrieved token.

When auth_mode is set to 0 (camSharePointOnline) or 1 (camDynamicsCRM) the class will automatically populate various properties to known values to reduce the number of required settings. Typically only the following properties are required:

• user
• password
• application_urn

When auth_mode is set to 2 (camADFS) or 3 (camCustom) the following properties are required:

• user
• password
• application_urn
• local_sts
• federation_sts
• federation_urn

parse_assertion Method

Parses the specified assertion.

Syntax

def parse_assertion(assertion: str) -> None: ...

Remarks

This method parses the assertion specified by the assertion parameter. If the assertion is signed the class will use the certificate specified in signer_cert to verify the signature. If signer_cert is not set the class will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

• assertion_id
• assertion_issue_instant
• assertion_issuer
• assertion_not_before
• assertion_not_on_or_after
• assertion_subject
• assertion_version
• assertion_xml
• Claim* properties

on_characters Event

Fired for plain text segments of the input stream.

Syntax

class SAMLCharactersEventParams(object):
  @property
  def text() -> str: ...

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

Remarks

The on_characters event provides the plain text content of the XML document (i.e. the text inside the tags). The text is provided through the Text parameter.

The text includes white space as well as end of line characters, except for ignorable whitespace which is fired through the on_ignorable_whitespace event.

on_comment Event

Fired when a comment section is encountered.

Syntax

class SAMLCommentEventParams(object):
  @property
  def text() -> str: ...

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

Remarks

The on_comment event is fired whenever a comment section (<!-- ..text... -->) is found in the document.

The full text of the comment is provided by the Text parameter.

on_end_element Event

Fired when an end-element tag is encountered.

Syntax

class SAMLEndElementEventParams(object):
  @property
  def namespace() -> str: ...

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

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

  @property
  def is_empty() -> bool: ...

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

Remarks

The on_end_element event is fired when an end-element tag is found in the document.

The element name is provided by the Element parameter.

The IsEmpty parameter is true when the event corresponds with an empty element declaration.

on_error Event

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

ErrorCode contains an error code and Description 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_pi Event

Fired when a processing instruction section is encountered.

Syntax

class SAMLPIEventParams(object):
  @property
  def text() -> str: ...

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

Remarks

The on_pi event is fired whenever a processing instruction section (<? ..text... ?>) is found in the document.

The full text of the processing instruction is provided by the Text parameter.

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

This event is where the client can decide whether to continue with the connection process or not. 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 to continue or not.

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

Shows the progress of the secure connection.

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. Used to track the progress of the connection.

on_start_element Event

Fired when a begin-element tag is encountered in the document.

Syntax

class SAMLStartElementEventParams(object):
  @property
  def namespace() -> str: ...

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

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

  @property
  def is_empty() -> bool: ...

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

Remarks

The on_start_element event is fired when a begin-element tag is found in the document.

The element name is provided through the Element parameter. The attribute names and values (if any) are provided through the attr_name, attr_namespace, attr_prefix, and attr_value properties.

The IsEmpty parameter is true when the event corresponds with an empty element declaration.

SAML Config Settings

The class accepts one or more of the following configuration settings. Configuration 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.

SAML Config Settings

Base Config Settings

SAML Errors

SAML Errors

	603   Cannot obtain assertion. LocalSTS must be set.

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

HTTP Errors

	118   Firewall Error. Error description contains detailed message.
	143   Busy executing current method.
	151   HTTP protocol error. The error message has the server response.
	152   No server specified in url
	153   Specified url_scheme is invalid.
	155   Range operation is not supported by server.
	156   Invalid cookie index (out of range).
	301   Interrupted.
	302   Can't open attached_file.

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

TCPClient Errors

	100   You cannot change the remote_port at this time. A connection is in progress.
	101   You cannot change the remote_host (Server) at this time. A connection is in progress.
	102   The remote_host address is invalid (0.0.0.0).
	104   Already connected. If you want to reconnect, close the current connection first.
	106   You cannot change the local_port at this time. A connection is in progress.
	107   You cannot change the local_host at this time. A connection is in progress.
	112   You cannot change MaxLineLength at this time. A connection is in progress.
	116   remote_port cannot be zero. Please specify a valid service port number.
	117   You cannot change the UseConnection option while the class is active.
	135   Operation would block.
	201   Timeout.
	211   Action impossible in control's present state.
	212   Action impossible while not connected.
	213   Action impossible while listening.
	301   Timeout.
	302   Could not open file.
	434   Unable to convert string to selected CodePage.
	1105   Already connecting. If you want to reconnect, close the current connection first.
	1117   You need to connect first.
	1119   You cannot change the LocalHost at this time. A connection is in progress.
	1120   Connection dropped by remote host.

TCP/IP Errors

	10004   [10004] Interrupted system call.
	10009   [10009] Bad file number.
	10013   [10013] Access denied.
	10014   [10014] Bad address.
	10022   [10022] Invalid argument.
	10024   [10024] Too many open files.
	10035   [10035] Operation would block.
	10036   [10036] Operation now in progress.
	10037   [10037] Operation already in progress.
	10038   [10038] Socket operation on non-socket.
	10039   [10039] Destination address required.
	10040   [10040] Message too long.
	10041   [10041] Protocol wrong type for socket.
	10042   [10042] Bad protocol option.
	10043   [10043] Protocol not supported.
	10044   [10044] Socket type not supported.
	10045   [10045] Operation not supported on socket.
	10046   [10046] Protocol family not supported.
	10047   [10047] Address family not supported by protocol family.
	10048   [10048] Address already in use.
	10049   [10049] Can't assign requested address.
	10050   [10050] Network is down.
	10051   [10051] Network is unreachable.
	10052   [10052] Net dropped connection or reset.
	10053   [10053] Software caused connection abort.
	10054   [10054] Connection reset by peer.
	10055   [10055] No buffer space available.
	10056   [10056] Socket is already connected.
	10057   [10057] Socket is not connected.
	10058   [10058] Can't send after socket shutdown.
	10059   [10059] Too many references, can't splice.
	10060   [10060] Connection timed out.
	10061   [10061] Connection refused.
	10062   [10062] Too many levels of symbolic links.
	10063   [10063] File name too long.
	10064   [10064] Host is down.
	10065   [10065] No route to host.
	10066   [10066] Directory not empty
	10067   [10067] Too many processes.
	10068   [10068] Too many users.
	10069   [10069] Disc Quota Exceeded.
	10070   [10070] Stale NFS file handle.
	10071   [10071] Too many levels of remote in path.
	10091   [10091] Network subsystem is unavailable.
	10092   [10092] WINSOCK DLL Version out of range.
	10093   [10093] Winsock not loaded yet.
	11001   [11001] Host not found.
	11002   [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
	11003   [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
	11004   [11004] Valid name, no data record (check DNS setup).