jam.saml

saml

Security Assertion Markup Language (SAML 2.0).

Supports both Service Provider and Identity Provider roles. Zero external dependencies — built on stdlib xml + cryptography.

Modules:

Name	Description
binding
encryption
metadata
saml
signature
types
xml

Classes:

Name	Description
BaseSAML	SAML 2.0 module.
SAML	Concrete SAML 2.0 implementation.
SAMLArtifactResolve	Parsed SAML ArtifactResolve.
SAMLArtifactResponse	Parsed SAML ArtifactResponse.
SAMLAssertion	Parsed SAML assertion data.
SAMLAttributeQuery	Parsed SAML AttributeQuery.
SAMLAuthnStatement	SAML authentication statement.
SAMLConditions	SAML assertion conditions (time constraints + audience).
SAMLLogoutRequest	Parsed SAML LogoutRequest.
SAMLLogoutResponse	Parsed SAML LogoutResponse.
SAMLManageNameIDRequest	Parsed SAML ManageNameIDRequest.
SAMLManageNameIDResponse	Parsed SAML ManageNameIDResponse.
SAMLMetadata	Parsed SAML metadata.
SAMLRequest	Parsed SAML AuthnRequest.
SAMLResponse	Parsed SAML protocol Response.
SAMLSubject	SAML assertion subject (NameID + confirmation).

Functions:

Name	Description
create_instance	Create a SAML instance.

BaseSAML

Bases: ABC

SAML 2.0 module.

Supports both Service Provider (SP) and Identity Provider (IdP) roles.

Methods:

Name	Description
build_artifact	Create a SAML 2.0 artifact (Base64 string).
build_artifact_resolve	Build a SAML ArtifactResolve.
build_artifact_response	Build a SAML ArtifactResponse wrapping the original message.
build_attribute_query	Build a SAML AttributeQuery.
build_attribute_query_response	Build a SAML Response for an AttributeQuery.
build_logout_request	Build a SAML LogoutRequest.
build_logout_response	Build a SAML LogoutResponse.
build_manage_name_id_request	Build a SAML ManageNameIDRequest.
build_manage_name_id_response	Build a SAML ManageNameIDResponse.
build_response	Build (and optionally encrypt) a SAML Response containing an Assertion.
generate_metadata	Generate SAML 2.0 metadata XML.
parse_artifact_resolve	Parse an incoming SAML ArtifactResolve.
parse_artifact_response	Parse a SAML ArtifactResponse.
parse_attribute_query	Parse an incoming SAML AttributeQuery.
parse_attribute_query_response	Parse a SAML Response from an AttributeQuery.
parse_authn_request	Parse an incoming AuthnRequest from an SP.
parse_logout_request	Parse a SAML LogoutRequest.
parse_logout_response	Parse a SAML LogoutResponse.
parse_manage_name_id_request	Parse a SAML ManageNameIDRequest.
parse_manage_name_id_response	Parse a SAML ManageNameIDResponse.
parse_metadata	Parse SAML 2.0 metadata XML.
parse_response	Parse and validate a SAML Response from an IdP.
prepare_authn_request	Build an AuthnRequest for the given IdP SSO URL.
resolve_artifact	Resolve a SAML artifact via SOAP to the IdP's resolve endpoint.

build_artifact abstractmethod

build_artifact(
    source_message_id: str, *, issuer: str
) -> str

Create a SAML 2.0 artifact (Base64 string).

Parameters:

Name	Type	Description	Default
source_message_id	str	The ID of the message the artifact references.	required
issuer	str	Entity ID of the issuer.	required

Returns:

Type	Description
str	Base64-encoded artifact string.

build_artifact_resolve abstractmethod

build_artifact_resolve(
    artifact: str,
    *,
    issuer: str,
    destination: str,
    **kwargs: Any,
) -> str

Build a SAML ArtifactResolve.

Parameters:

Name	Type	Description	Default
artifact	str	The artifact to resolve.	required
issuer	str	Entity ID of the requester (SP).	required
destination	str	IdP artifact resolution service URL.	required
**kwargs	Any	binding ("post" or "redirect" or "soap").	{}

Returns:

Type	Description
str	Signed ArtifactResolve XML / SOAP envelope.

build_artifact_response abstractmethod

build_artifact_response(
    in_response_to: str,
    original_message_xml: str,
    *,
    issuer: str,
    destination: str,
    **kwargs: Any,
) -> str

Build a SAML ArtifactResponse wrapping the original message.

Parameters:

Name	Type	Description	Default
in_response_to	str	ArtifactResolve ID being responded to.	required
original_message_xml	str	The original XML message to embed.	required
issuer	str	Entity ID of the responder (IdP).	required
destination	str	SP endpoint URL.	required
**kwargs	Any	binding, status_code.	{}

Returns:

Type	Description
str	Signed ArtifactResponse XML / SOAP envelope.

build_attribute_query abstractmethod

build_attribute_query(
    subject: str,
    *,
    issuer: str,
    destination: str,
    attribute_names: list[str] | None = None,
    binding: str = "post",
    **kwargs: Any,
) -> str

Build a SAML AttributeQuery.

Parameters:

Name	Type	Description	Default
subject	str	The subject to query attributes for.	required
issuer	str	Entity ID of the requester (SP).	required
destination	str	IdP attribute query endpoint URL.	required
attribute_names	list[str] | None	Specific attributes to request (None = all).	None
binding	str	"post" (default) or "redirect".	'post'
**kwargs	Any	relay_state, etc.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_attribute_query_response abstractmethod

build_attribute_query_response(
    in_response_to: str,
    subject: str,
    attributes: dict[str, Any],
    *,
    issuer: str,
    audience: str,
    **kwargs: Any,
) -> str

Build a SAML Response for an AttributeQuery.

Parameters:

Name	Type	Description	Default
in_response_to	str	AttributeQuery ID being responded to.	required
subject	str	The subject.	required
attributes	dict[str, Any]	User attributes dict.	required
issuer	str	IdP entity ID.	required
audience	str	SP entity ID.	required
**kwargs	Any	destination, name_id_format.	{}

Returns:

Type	Description
str	Signed SAML Response XML string.

build_logout_request abstractmethod

build_logout_request(
    name_id: str,
    *,
    issuer: str,
    destination: str,
    session_index: str | None = None,
    **kwargs: Any,
) -> str

Build a SAML LogoutRequest.

Parameters:

Name	Type	Description	Default
name_id	str	The user identifier being logged out.	required
issuer	str	Entity ID of the sender (IdP or SP).	required
destination	str	SLO endpoint URL of the recipient.	required
session_index	str | None	Session identifier (optional).	None
**kwargs	Any	Extra params (binding, relay_state, etc.).	{}

Returns:

Type	Description
str	Signed LogoutRequest XML (POST → Base64, Redirect → URL).

build_logout_response abstractmethod

build_logout_response(
    in_response_to: str,
    *,
    issuer: str,
    destination: str,
    status_code: str = "urn:oasis:names:tc:SAML:2.0:status:Success",
    **kwargs: Any,
) -> str

Build a SAML LogoutResponse.

Parameters:

Name	Type	Description	Default
in_response_to	str	ID of the LogoutRequest being responded to.	required
issuer	str	Entity ID of the sender.	required
destination	str	SLO endpoint URL of the recipient.	required
status_code	str	SAML status code (default Success).	'urn:oasis:names:tc:SAML:2.0:status:Success'
**kwargs	Any	Extra params (binding, relay_state, etc.).	{}

Returns:

Type	Description
str	Signed LogoutResponse XML (POST → Base64, Redirect → URL).

build_manage_name_id_request abstractmethod

build_manage_name_id_request(
    name_id: str,
    *,
    issuer: str,
    destination: str,
    new_id: str | None = None,
    binding: str = "post",
    **kwargs: Any,
) -> str

Build a SAML ManageNameIDRequest.

Parameters:

Name	Type	Description	Default
name_id	str	Current NameID.	required
issuer	str	Entity ID of the requester.	required
destination	str	Entity endpoint URL.	required
new_id	str | None	New identifier (None = terminate).	None
binding	str	"post" (default) or "redirect".	'post'
**kwargs	Any	relay_state, name_id_format.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_manage_name_id_response abstractmethod

build_manage_name_id_response(
    in_response_to: str,
    *,
    issuer: str,
    destination: str,
    status_code: str = "urn:oasis:names:tc:SAML:2.0:status:Success",
    **kwargs: Any,
) -> str

Build a SAML ManageNameIDResponse.

Parameters:

Name	Type	Description	Default
in_response_to	str	ManageNameIDRequest ID.	required
issuer	str	Entity ID of the responder.	required
destination	str	Endpoint URL of the requester.	required
status_code	str	SAML status code (default Success).	'urn:oasis:names:tc:SAML:2.0:status:Success'
**kwargs	Any	binding, relay_state.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_response abstractmethod

build_response(
    subject: str,
    attributes: dict[str, Any],
    *,
    issuer: str,
    audience: str,
    **kwargs: Any,
) -> str

Build (and optionally encrypt) a SAML Response containing an Assertion.

Parameters:

Name	Type	Description	Default
subject	str	The authenticated user identifier.	required
attributes	dict[str, Any]	User attributes (email, roles, etc.).	required
issuer	str	IdP entity ID.	required
audience	str	SP entity ID (the intended audience).	required
**kwargs	Any	in_response_to, name_id_format, session_index, encrypt (bool, default False).	{}

Returns:

Type	Description
str	Signed (and optionally encrypted) SAML Response XML string.

generate_metadata abstractmethod

generate_metadata(
    *,
    entity_id: str,
    sso_url: str | None = None,
    acs_url: str | None = None,
    role: str | None = None,
) -> str

Generate SAML 2.0 metadata XML.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity ID of the IdP or SP.	required
sso_url	str | None	SSO URL (required for IdP metadata).	None
acs_url	str | None	ACS URL (required for SP metadata).	None
role	str | None	"idp" or "sp". Auto-detected if omitted.	None

Returns:

Type	Description
str	SAML metadata XML string.

parse_artifact_resolve abstractmethod

parse_artifact_resolve(
    saml_request: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLArtifactResolve

Parse an incoming SAML ArtifactResolve.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw ArtifactResolve data.	required
binding	str	"post" (default), "redirect", or "soap".	'post'
**kwargs	Any	issuer (expected issuer for validation).	{}

Returns:

Type	Description
SAMLArtifactResolve	Parsed SAMLArtifactResolve.

parse_artifact_response abstractmethod

parse_artifact_response(
    saml_response: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLArtifactResponse

Parse a SAML ArtifactResponse.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw ArtifactResponse data.	required
binding	str	"post" (default), "redirect", or "soap".	'post'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLArtifactResponse	Parsed SAMLArtifactResponse.

parse_attribute_query abstractmethod

parse_attribute_query(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLAttributeQuery

Parse an incoming SAML AttributeQuery.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw AttributeQuery data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer for validation).	{}

Returns:

Type	Description
SAMLAttributeQuery	Parsed SAMLAttributeQuery.

parse_attribute_query_response abstractmethod

parse_attribute_query_response(
    saml_response: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLResponse

Parse a SAML Response from an AttributeQuery.

Delegates to parse_response.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw SAMLResponse data.	required
binding	str	"post" (default) or "redirect".	'post'
**kwargs	Any	audience, issuer, etc.	{}

Returns:

Type	Description
SAMLResponse	Parsed SAMLResponse.

parse_authn_request abstractmethod

parse_authn_request(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLRequest

Parse an incoming AuthnRequest from an SP.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw SAMLRequest data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	Expected issuer (for validation).	{}

Returns:

Type	Description
SAMLRequest	Parsed SAMLRequest data.

Raises:

Type	Description
JamSAMLInvalidIssuer	Issuer doesn't match expected.

parse_logout_request abstractmethod

parse_logout_request(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLLogoutRequest

Parse a SAML LogoutRequest.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw LogoutRequest data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer for validation).	{}

Returns:

Type	Description
SAMLLogoutRequest	Parsed SAMLLogoutRequest.

Raises:

Type	Description
JamSAMLInvalidIssuer	Issuer doesn't match expected.

parse_logout_response abstractmethod

parse_logout_response(
    saml_response: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLLogoutResponse

Parse a SAML LogoutResponse.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw LogoutResponse data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer for validation).	{}

Returns:

Type	Description
SAMLLogoutResponse	Parsed SAMLLogoutResponse.

Raises:

Type	Description
JamSAMLInvalidIssuer	Issuer doesn't match expected.

parse_manage_name_id_request abstractmethod

parse_manage_name_id_request(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLManageNameIDRequest

Parse a SAML ManageNameIDRequest.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw ManageNameIDRequest data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLManageNameIDRequest	Parsed SAMLManageNameIDRequest.

parse_manage_name_id_response abstractmethod

parse_manage_name_id_response(
    saml_response: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLManageNameIDResponse

Parse a SAML ManageNameIDResponse.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw ManageNameIDResponse data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLManageNameIDResponse	Parsed SAMLManageNameIDResponse.

parse_metadata abstractmethod

parse_metadata(metadata_xml: str) -> Any

Parse SAML 2.0 metadata XML.

Parameters:

Name	Type	Description	Default
metadata_xml	str	Raw metadata XML string.	required

Returns:

Type	Description
Any	SAMLMetadata with parsed fields.

parse_response abstractmethod

parse_response(
    saml_response: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLResponse

Parse and validate a SAML Response from an IdP.

Automatically decrypts <saml:EncryptedAssertion> if the instance has a private_key configured.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw SAMLResponse data (Base64 string for POST, query-string for Redirect).	required
binding	str	"post" (default) or "redirect".	'post'
**kwargs	Any	Expected audience, expected issuer, etc.	{}

Returns:

Type	Description
SAMLResponse	Parsed SAMLResponse with assertion data.

Raises:

Type	Description
JamSAMLExpired	Assertion is expired.
JamSAMLNotYetValid	Assertion is not yet valid.
JamSAMLInvalidAudience	Audience doesn't match.
JamSAMLInvalidIssuer	Issuer doesn't match.
JamSAMLValidationError	Signature verification failed.

prepare_authn_request abstractmethod

prepare_authn_request(
    idp_sso_url: str,
    *,
    acs_url: str,
    binding: str = "redirect",
    **kwargs: Any,
) -> str

Build an AuthnRequest for the given IdP SSO URL.

Parameters:

Name	Type	Description	Default
idp_sso_url	str	IdP single sign-on endpoint URL.	required
acs_url	str	SP assertion consumer service URL.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	Extra params (relay_state, force_authn, etc.).	{}

Returns:

Name	Type	Description
Redirect	str	IdP URL with signed AuthnRequest.
POST	str	Base64-encoded SAMLRequest as a string (embed in form).

resolve_artifact abstractmethod

resolve_artifact(
    artifact: str,
    *,
    issuer: str,
    resolve_url: str,
    **kwargs: Any,
) -> str

Resolve a SAML artifact via SOAP to the IdP's resolve endpoint.

Parameters:

Name	Type	Description	Default
artifact	str	The artifact to resolve.	required
issuer	str	Entity ID of the requester (SP).	required
resolve_url	str	IdP artifact resolution service URL.	required
**kwargs	Any	Extra params (timeout, headers, expected_issuer, etc.).	{}

Returns:

Type	Description
str	The original SAML message XML extracted from the ArtifactResponse.

SAML

SAML(
    *,
    role: str = "sp",
    private_key: str | None = None,
    public_key: str | None = None,
    certificate: str | None = None,
    entity_id: str | None = None,
    acs_url: str | None = None,
    sso_url: str | None = None,
    idp_public_key: str | None = None,
    sp_public_key: str | None = None,
    encryption_key: str | None = None,
    default_exp: int = 300,
    allowed_clock_skew: int = 120,
    want_assertions_signed: bool = True,
    id_store: dict | None = None,
    replay_ttl: int = 300,
)

Bases: BaseSAML

Concrete SAML 2.0 implementation.

Parameters:

Name	Type	Description	Default
role	str	"sp" or "idp".	'sp'
private_key	str | None	PEM string or path to private key file.	None
public_key	str | None	PEM string or path to public key / certificate.	None
certificate	str | None	PEM cert string (included in metadata/KeyInfo).	None
entity_id	str | None	Entity ID of this party.	None
acs_url	str | None	ACS URL (sp role).	None
sso_url	str | None	SSO URL (idp role).	None
idp_public_key	str | None	IdP public key for signature verification (sp).	None
sp_public_key	str | None	SP public key for signature verification (idp).	None
encryption_key	str | None	SP public key PEM for assertion encryption (idp).	None
default_exp	int	Default assertion lifetime in seconds.	300
allowed_clock_skew	int	Clock skew tolerance in seconds (default 120).	120
want_assertions_signed	bool	Require signed assertions (sp, default True).	True
id_store	dict | None	Dict for replay attack protection. Auto-created if None.	None
replay_ttl	int	Seconds before a consumed ID is eligible for cleanup.	300

Methods:

Name	Description
build_artifact	Create a SAML 2.0 artifact from a message ID.
build_artifact_resolve	Build a signed SAML ArtifactResolve.
build_artifact_response	Build a signed SAML ArtifactResponse wrapping the original message.
build_attribute_query	Build a signed SAML AttributeQuery.
build_attribute_query_response	Build a SAML Response for an AttributeQuery (no AuthnStatement).
build_logout_request	Build a SAML LogoutRequest.
build_logout_response	Build a SAML LogoutResponse.
build_manage_name_id_request	Build a signed SAML ManageNameIDRequest.
build_manage_name_id_response	Build a signed SAML ManageNameIDResponse.
build_response	Build and sign a SAML Response with an Assertion.
generate_metadata	Generate SAML metadata XML.
parse_artifact_resolve	Parse an incoming SAML ArtifactResolve.
parse_artifact_response	Parse a SAML ArtifactResponse.
parse_attribute_query	Parse an incoming SAML AttributeQuery.
parse_attribute_query_response	Parse a SAML Response from an AttributeQuery.
parse_authn_request	Parse an incoming AuthnRequest from an SP.
parse_logout_request	Parse a SAML LogoutRequest.
parse_logout_response	Parse a SAML LogoutResponse.
parse_manage_name_id_request	Parse a SAML ManageNameIDRequest.
parse_manage_name_id_response	Parse a SAML ManageNameIDResponse.
parse_metadata	Parse SAML metadata XML into a SAMLMetadata object.
parse_response	Parse and validate a SAML Response from an IdP.
prepare_authn_request	Build AuthnRequest and return IdP redirect URL or POST form data.
resolve_artifact	Resolve a SAML artifact via SOAP/HTTP to the IdP resolve endpoint.

build_artifact

build_artifact(
    source_message_id: str, *, issuer: str
) -> str

Create a SAML 2.0 artifact from a message ID.

2 bytes type code (0x0001) + 2 bytes endpoint index

• 40 random bytes → Base64.

Parameters:

Name	Type	Description	Default
source_message_id	str	The ID of the referenced message (unused in artifact format, stored for reference).	required
issuer	str	Entity ID of the issuer (stored for reference).	required

Returns:

Type	Description
str	Base64-encoded artifact string.

build_artifact_resolve

build_artifact_resolve(
    artifact: str,
    *,
    issuer: str,
    destination: str,
    **kwargs: Any,
) -> str

Build a signed SAML ArtifactResolve.

Parameters:

Name	Type	Description	Default
artifact	str	The artifact to resolve.	required
issuer	str	SP entity ID.	required
destination	str	IdP artifact resolution service URL.	required
**kwargs	Any	binding ("post", "redirect", or "soap").	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.
SOAP	str	Raw XML.

build_artifact_response

build_artifact_response(
    in_response_to: str,
    original_message_xml: str,
    *,
    issuer: str,
    destination: str,
    **kwargs: Any,
) -> str

Build a signed SAML ArtifactResponse wrapping the original message.

Parameters:

Name	Type	Description	Default
in_response_to	str	ArtifactResolve ID.	required
original_message_xml	str	The original SAML message XML to embed.	required
issuer	str	IdP entity ID.	required
destination	str	SP endpoint URL.	required
**kwargs	Any	binding, status_code.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.
SOAP	str	Raw XML.

build_attribute_query

build_attribute_query(
    subject: str,
    *,
    issuer: str,
    destination: str,
    attribute_names: list[str] | None = None,
    binding: str = "post",
    **kwargs: Any,
) -> str

Build a signed SAML AttributeQuery.

Parameters:

Name	Type	Description	Default
subject	str	Subject to query attributes for.	required
issuer	str	SP entity ID.	required
destination	str	IdP attribute query endpoint URL.	required
attribute_names	list[str] | None	Specific attributes to request (None = all).	None
binding	str	"post" (default) or "redirect".	'post'
**kwargs	Any	relay_state, name_id_format.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_attribute_query_response

build_attribute_query_response(
    in_response_to: str,
    subject: str,
    attributes: dict[str, Any],
    *,
    issuer: str,
    audience: str,
    **kwargs: Any,
) -> str

Build a SAML Response for an AttributeQuery (no AuthnStatement).

Parameters:

Name	Type	Description	Default
in_response_to	str	AttributeQuery ID.	required
subject	str	The subject.	required
attributes	dict[str, Any]	User attributes dict.	required
issuer	str	IdP entity ID.	required
audience	str	SP entity ID.	required
**kwargs	Any	destination, name_id_format.	{}

Returns:

Type	Description
str	Signed SAML Response XML string.

build_logout_request

build_logout_request(
    name_id: str,
    *,
    issuer: str,
    destination: str,
    session_index: str | None = None,
    **kwargs: Any,
) -> str

Build a SAML LogoutRequest.

Parameters:

Name	Type	Description	Default
name_id	str	User identifier to log out.	required
issuer	str	Entity ID of the sender.	required
destination	str	SLO endpoint of the recipient.	required
session_index	str | None	Session index (optional).	None
**kwargs	Any	binding, relay_state, name_id_format.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_logout_response

build_logout_response(
    in_response_to: str,
    *,
    issuer: str,
    destination: str,
    status_code: str = STATUS_SUCCESS,
    **kwargs: Any,
) -> str

Build a SAML LogoutResponse.

Parameters:

Name	Type	Description	Default
in_response_to	str	LogoutRequest ID to respond to.	required
issuer	str	Entity ID of the sender.	required
destination	str	SLO endpoint of the recipient.	required
status_code	str	SAML status code.	STATUS_SUCCESS
**kwargs	Any	binding, relay_state.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_manage_name_id_request

build_manage_name_id_request(
    name_id: str,
    *,
    issuer: str,
    destination: str,
    new_id: str | None = None,
    binding: str = "post",
    **kwargs: Any,
) -> str

Build a signed SAML ManageNameIDRequest.

Parameters:

Name	Type	Description	Default
name_id	str	Current NameID.	required
issuer	str	Entity ID of the requester.	required
destination	str	Recipient endpoint URL.	required
new_id	str | None	New identifier (None = terminate).	None
binding	str	"post" (default) or "redirect".	'post'
**kwargs	Any	relay_state, name_id_format.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_manage_name_id_response

build_manage_name_id_response(
    in_response_to: str,
    *,
    issuer: str,
    destination: str,
    status_code: str = STATUS_SUCCESS,
    **kwargs: Any,
) -> str

Build a signed SAML ManageNameIDResponse.

Parameters:

Name	Type	Description	Default
in_response_to	str	ManageNameIDRequest ID.	required
issuer	str	Entity ID of the responder.	required
destination	str	Endpoint URL of the requester.	required
status_code	str	SAML status code (default Success).	STATUS_SUCCESS
**kwargs	Any	binding, relay_state.	{}

Returns:

Name	Type	Description
POST	str	Base64-encoded signed XML.
Redirect	str	Signed redirect URL.

build_response

build_response(
    subject: str,
    attributes: dict[str, Any],
    *,
    issuer: str,
    audience: str,
    **kwargs: Any,
) -> str

Build and sign a SAML Response with an Assertion.

Parameters:

Name	Type	Description	Default
subject	str	Authenticated user identifier.	required
attributes	dict[str, Any]	User attributes dict.	required
issuer	str	IdP entity ID.	required
audience	str	SP entity ID.	required
**kwargs	Any	in_response_to, name_id_format, session_index, destination, encrypt (bool, default False).	{}

Returns:

Type	Description
str	Signed (and optionally encrypted) SAML Response XML string.

generate_metadata

generate_metadata(
    *,
    entity_id: str | None = None,
    sso_url: str | None = None,
    acs_url: str | None = None,
    role: str | None = None,
) -> str

Generate SAML metadata XML.

Parameters:

Name	Type	Description	Default
entity_id	str | None	Entity ID (defaults to instance entity_id).	None
sso_url	str | None	SSO URL (IdP metadata).	None
acs_url	str | None	ACS URL (SP metadata).	None
role	str | None	"idp" or "sp" (defaults to instance role).	None

Returns:

Type	Description
str	Metadata XML string.

parse_artifact_resolve

parse_artifact_resolve(
    saml_request: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLArtifactResolve

Parse an incoming SAML ArtifactResolve.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw ArtifactResolve data.	required
binding	str	"post" (default), "redirect", or "soap".	'post'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLArtifactResolve	Parsed SAMLArtifactResolve.

parse_artifact_response

parse_artifact_response(
    saml_response: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLArtifactResponse

Parse a SAML ArtifactResponse.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw ArtifactResponse data.	required
binding	str	"post" (default), "redirect", or "soap".	'post'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLArtifactResponse	Parsed SAMLArtifactResponse.

parse_attribute_query

parse_attribute_query(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLAttributeQuery

Parse an incoming SAML AttributeQuery.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw AttributeQuery data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLAttributeQuery	Parsed SAMLAttributeQuery.

parse_attribute_query_response

parse_attribute_query_response(
    saml_response: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLResponse

Parse a SAML Response from an AttributeQuery.

Delegates to parse_response.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw SAMLResponse data.	required
binding	str	"post" or "redirect".	'post'
**kwargs	Any	audience, issuer, etc.	{}

Returns:

Type	Description
SAMLResponse	Parsed SAMLResponse.

parse_authn_request

parse_authn_request(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLRequest

Parse an incoming AuthnRequest from an SP.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw SAMLRequest data.	required
binding	str	"redirect" or "post".	'redirect'
**kwargs	Any	issuer (expected issuer for validation).	{}

Returns:

Type	Description
SAMLRequest	Parsed SAMLRequest.

parse_logout_request

parse_logout_request(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLLogoutRequest

Parse a SAML LogoutRequest.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw LogoutRequest data.	required
binding	str	"redirect" or "post".	'redirect'
**kwargs	Any	issuer, public_key (override verification key).	{}

Returns:

Type	Description
SAMLLogoutRequest	Parsed SAMLLogoutRequest.

parse_logout_response

parse_logout_response(
    saml_response: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLLogoutResponse

Parse a SAML LogoutResponse.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw LogoutResponse data.	required
binding	str	"redirect" or "post".	'redirect'
**kwargs	Any	issuer, public_key (override verification key).	{}

Returns:

Type	Description
SAMLLogoutResponse	Parsed SAMLLogoutResponse.

parse_manage_name_id_request

parse_manage_name_id_request(
    saml_request: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLManageNameIDRequest

Parse a SAML ManageNameIDRequest.

Parameters:

Name	Type	Description	Default
saml_request	str	Raw ManageNameIDRequest data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLManageNameIDRequest	Parsed SAMLManageNameIDRequest.

parse_manage_name_id_response

parse_manage_name_id_response(
    saml_response: str,
    *,
    binding: str = "redirect",
    **kwargs: Any,
) -> SAMLManageNameIDResponse

Parse a SAML ManageNameIDResponse.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw ManageNameIDResponse data.	required
binding	str	"redirect" (default) or "post".	'redirect'
**kwargs	Any	issuer (expected issuer).	{}

Returns:

Type	Description
SAMLManageNameIDResponse	Parsed SAMLManageNameIDResponse.

parse_metadata

parse_metadata(metadata_xml: str) -> SAMLMetadata

Parse SAML metadata XML into a SAMLMetadata object.

Parameters:

Name	Type	Description	Default
metadata_xml	str	Raw metadata XML string.	required

Returns:

Type	Description
SAMLMetadata	SAMLMetadata with entity_id, endpoints, cert, etc.

parse_response

parse_response(
    saml_response: str,
    *,
    binding: str = "post",
    **kwargs: Any,
) -> SAMLResponse

Parse and validate a SAML Response from an IdP.

Parameters:

Name	Type	Description	Default
saml_response	str	Raw SAMLResponse (Base64 POST or query-string).	required
binding	str	"post" or "redirect".	'post'
**kwargs	Any	audience, issuer, verify_signature.	{}

Returns:

Type	Description
SAMLResponse	SAMLResponse with parsed assertion data.

prepare_authn_request

prepare_authn_request(
    idp_sso_url: str,
    *,
    acs_url: str | None = None,
    binding: str = "redirect",
    **kwargs: Any,
) -> str

Build AuthnRequest and return IdP redirect URL or POST form data.

Parameters:

Name	Type	Description	Default
idp_sso_url	str	IdP SSO endpoint URL.	required
acs_url	str | None	SP ACS URL.	None
binding	str	"redirect" or "post".	'redirect'
**kwargs	Any	relay_state, issuer, etc.	{}

Returns:

Type	Description
str	Redirect URL (binding="redirect") or Base64 form data ("post").

resolve_artifact

resolve_artifact(
    artifact: str,
    *,
    issuer: str,
    resolve_url: str,
    **kwargs: Any,
) -> str

Resolve a SAML artifact via SOAP/HTTP to the IdP resolve endpoint.

Parameters:

Name	Type	Description	Default
artifact	str	The artifact to resolve.	required
issuer	str	SP entity ID.	required
resolve_url	str	IdP artifact resolution service URL.	required
**kwargs	Any	timeout (int, default 10), expected_issuer (IdP entity ID to validate the ArtifactResponse issuer).	{}

Returns:

Type	Description
str	The original SAML message XML from the ArtifactResponse.

SAMLArtifactResolve dataclass

SAMLArtifactResolve(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    artifact: str,
)

Parsed SAML ArtifactResolve.

SAMLArtifactResponse dataclass

SAMLArtifactResponse(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    status_code: str = "urn:oasis:names:tc:SAML:2.0:status:Success",
    in_response_to: str | None = None,
    original_message: str | None = None,
)

Parsed SAML ArtifactResponse.

SAMLAssertion dataclass

SAMLAssertion(
    id: str,
    issuer: str,
    issue_instant: datetime,
    subject: SAMLSubject | None = None,
    conditions: SAMLConditions | None = None,
    attributes: dict[str, Any] = dict(),
    authn_statement: SAMLAuthnStatement | None = None,
)

Parsed SAML assertion data.

SAMLAttributeQuery dataclass

SAMLAttributeQuery(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    subject: str,
    destination: str | None = None,
    attribute_names: list[str] | None = None,
)

Parsed SAML AttributeQuery.

SAMLAuthnStatement dataclass

SAMLAuthnStatement(
    authn_instant: datetime,
    session_index: str | None = None,
)

SAML authentication statement.

SAMLConditions dataclass

SAMLConditions(
    not_before: datetime | None = None,
    not_on_or_after: datetime | None = None,
    audience_restriction: list[str] = list(),
)

SAML assertion conditions (time constraints + audience).

SAMLLogoutRequest dataclass

SAMLLogoutRequest(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    name_id: str,
    session_index: str | None = None,
    destination: str | None = None,
)

Parsed SAML LogoutRequest.

SAMLLogoutResponse dataclass

SAMLLogoutResponse(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    status_code: str = "urn:oasis:names:tc:SAML:2.0:status:Success",
    destination: str | None = None,
    in_response_to: str | None = None,
)

Parsed SAML LogoutResponse.

SAMLManageNameIDRequest dataclass

SAMLManageNameIDRequest(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    name_id: str,
    new_id: str | None = None,
    destination: str | None = None,
)

Parsed SAML ManageNameIDRequest.

SAMLManageNameIDResponse dataclass

SAMLManageNameIDResponse(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    status_code: str = "urn:oasis:names:tc:SAML:2.0:status:Success",
    destination: str | None = None,
    in_response_to: str | None = None,
)

Parsed SAML ManageNameIDResponse.

SAMLMetadata dataclass

SAMLMetadata(
    entity_id: str,
    role: str,
    sso_url: str | None = None,
    acs_url: str | None = None,
    certificate: str | None = None,
    want_authn_requests_signed: bool = False,
    authn_requests_signed: bool = False,
)

Parsed SAML metadata.

SAMLRequest dataclass

SAMLRequest(
    id: str,
    issuer: str | None,
    issue_instant: datetime,
    destination: str | None = None,
    acs_url: str | None = None,
    binding: str | None = None,
)

Parsed SAML AuthnRequest.

SAMLResponse dataclass

SAMLResponse(
    id: str,
    issuer: str,
    issue_instant: datetime,
    status_code: str = "urn:oasis:names:tc:SAML:2.0:status:Success",
    destination: str | None = None,
    in_response_to: str | None = None,
    assertion: SAMLAssertion | None = None,
)

Parsed SAML protocol Response.

SAMLSubject dataclass

SAMLSubject(
    name_id: str,
    format: str = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
    subject_confirmation_method: str = "urn:oasis:names:tc:SAML:2.0:cm:bearer",
    subject_confirmation_data: dict[str, Any] | None = None,
)

SAML assertion subject (NameID + confirmation).

create_instance

create_instance(
    role: str = "sp",
    private_key: str | None = None,
    public_key: str | None = None,
    certificate: str | None = None,
    entity_id: str | None = None,
    acs_url: str | None = None,
    sso_url: str | None = None,
    idp_public_key: str | None = None,
    sp_public_key: str | None = None,
    encryption_key: str | None = None,
    default_exp: int = 300,
    allowed_clock_skew: int = 120,
    want_assertions_signed: bool = True,
    replay_ttl: int = 300,
    **kwargs: Any,
) -> SAML

Create a SAML instance.

Parameters:

Name	Type	Description	Default
role	str	"sp" (Service Provider) or "idp" (Identity Provider).	'sp'
private_key	str | None	PEM string or path to private key file.	None
public_key	str | None	PEM string or path to public key / certificate file.	None
certificate	str | None	PEM string or path to certificate file (included in metadata/signature).	None
entity_id	str | None	Entity ID of this SAML party.	None
acs_url	str | None	Assertion Consumer Service URL (for SP role).	None
sso_url	str | None	Single Sign-On URL (for IdP role).	None
idp_public_key	str | None	IdP public key / certificate PEM (for SP — signature verification).	None
sp_public_key	str | None	SP public key / certificate PEM (for IdP — SLO verification).	None
encryption_key	str | None	SP public key PEM for assertion encryption (IdP).	None
default_exp	int	Default assertion lifetime in seconds (default 300).	300
allowed_clock_skew	int	Clock skew tolerance in seconds (default 120).	120
want_assertions_signed	bool	Require signed assertions (SP, default True).	True
replay_ttl	int	Seconds before a consumed ID is eligible for cleanup (default 300).	300
**kwargs	Any	Additional parameters passed to the SAML constructor.	{}

Returns:

Type	Description
SAML	SAML instance.