jam.saml.saml¶

saml ¶

Classes:

Name	Description
`SAML`	Concrete SAML 2.0 implementation.

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.