jam.saml.base

__base__

Classes:

Name	Description
BaseSAML	SAML 2.0 module.

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.