SAML Class

Properties Methods Events Configuration 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:

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:

Property List

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


application_urn	The application's Uniform Resource Name (URN).
assertion_id	The assertion id.
assertion_issue_instant	The time in UTC that the assertion was issued.
assertion_issuer	The assertion issuer.
assertion_not_before	The date on which the assertion becomes valid.
assertion_not_on_or_after	The time at which the assertion expires.
assertion_subject	The subject of the assertion.
assertion_version	The version of the assertion.
assertion_xml	The assertion XML.
auth_mode	The authentication mode.
cert_encoded	The certificate (PEM/base64 encoded).
cert_store	The name of the certificate store for the client certificate.
cert_store_password	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
cert_store_type	The type of certificate store for this certificate.
cert_subject	The subject of the certificate used for client authentication.
claim_count	The number of records in the Claim arrays.
claim_issuer_name	The name of the issuer.
claim_original_issuer	The name of the original issuer.
claim_property_count	The number of properties in the claim.
claim_property_index	Selects a property.
claim_property_name	The name of the property.
claim_property_value	The value of the property.
claim_type_name	The type name of the claim.
claim_value	The value of the claim.
claim_value_type	The type of value.
federation_sts	The URL of the federation Security Token Service (STS).
federation_urn	The federation Uniform Resource Name (URN).
local_sts	The local Security Token Service (STS).
password	The user's password.
proxy_auth_scheme	This property is used to tell the class which type of authorization to perform when connecting to the proxy.
proxy_auto_detect	This property tells the class whether or not to automatically detect and use proxy system settings, if available.
proxy_password	This property contains a password if authentication is to be used for the proxy.
proxy_port	This property contains the TCP port for the proxy Server (default 80).
proxy_server	If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.
proxy_ssl	This property determines when to use SSL for the connection to the proxy.
proxy_user	This property contains a user name, if authentication is to be used for the proxy.
security_token_xml	The security token XML.
signer_cert_encoded	The certificate (PEM/base64 encoded).
signer_cert_store	The name of the certificate store for the client certificate.
signer_cert_store_password	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
signer_cert_store_type	The type of certificate store for this certificate.
signer_cert_subject	The subject of the certificate used for client authentication.
ssl_accept_server_cert_encoded	The certificate (PEM/base64 encoded).
ssl_cert_encoded	The certificate (PEM/base64 encoded).
ssl_cert_store	The name of the certificate store for the client certificate.
ssl_cert_store_password	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
ssl_cert_store_type	The type of certificate store for this certificate.
ssl_cert_subject	The subject of the certificate used for client authentication.
ssl_server_cert_encoded	The certificate (PEM/base64 encoded).
user	The username.
attr_count	The number of records in the Attr arrays.
attr_name	The Name provides the local name (without prefix) of the attribute.
attr_namespace	Attribute namespace.
attr_prefix	Attribute prefix (if any).
attr_value	Attribute value.
x_child_count	The number of records in the XChild arrays.
x_child_name	The Name property provides the local name (without prefix) of the element.
x_child_namespace	Namespace of the element.
x_child_prefix	Prefix of the element (if any).
x_child_x_text	The inner text of the element.
x_element	The name of the current element.
x_namespace	The namespace of the current element.
x_parent	The parent of the current element.
x_path	Provides a way to point to a specific element in the document.
x_prefix	The prefix of the current element.
x_sub_tree	A snapshot of the current element in the document.
x_text	The text of the current element.

Method List

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


config	Sets or retrieves a configuration setting.
get_assertion	Gets the assertion.
get_security_token	Gets the security token.
parse_assertion	Parses the specified assertion.

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.


on_characters	Fired for plain text segments of the input stream.
on_comment	Fired when a comment section is encountered.
on_end_element	Fired when an end-element tag is encountered.
on_error	Information about errors during data delivery.
on_pi	Fired when a processing instruction section is encountered.
on_ssl_server_authentication	Fired after the server presents its certificate to the client.
on_ssl_status	Shows the progress of the secure connection.
on_start_element	Fired when a begin-element tag is encountered in the document.

Configuration Settings

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


AssertionXPath	The XPath to the assertion.
DecryptAssertion	Whether to decrypt the assertion.
EncryptedAssertionXPath	The XPath to the encrypted assertion.
RawRequest	Returns the raw HTTP request.
RawResponse	Returns the raw HTTP response.
UserRealm	The URL of a web service to determine the LocalSTS (if any).
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.