API Reference

Request

minisaml.request.get_request_redirect_url

minisaml.request.get_request_redirect_url(*, saml_endpoint: str, expected_audience: str, acs_url: str, force_reauthentication: bool = False, request_id: Optional[str] = None, relay_state: Optional[str] = None) → str

Parameters:

• saml_endpoint – Absolute URL to the SAML endpoint of the Identity Provider.

• expected_audience – Audience of your Identity Provider.

• acs_url – Absolute URL to the Assertion Consumer Service handler of your application.

• force_reauthentication – Request re-authentication of the user, even if the user is already authenticated on the Identity Provider. Not all Identity Providers support this option.

• request_id – To prevent Identity Provider initiated SSO, you can specify a unique request ID. It is your own responsibility to verify this when validating SAML Responses. If you don’t provide a request ID, a random value will be used.

• relay_state – Any Relay State you want to include in the SAML Request.

Returns:

Absolute URL to which the user should be redirected to using a temporary HTTP redirect.

Response

minisaml.response.validate_response

minisaml.response.validate_response(*, data: ~typing.Union[bytes, str], certificate: ~typing.Union[~cryptography.x509.base.Certificate, ~typing.Collection[~cryptography.x509.base.Certificate]], expected_audience: str, idp_issuer: str, signature_verification_config: ~minisignxml.config.VerifyConfig = VerifyConfig(allowed_signature_method={<class 'cryptography.hazmat.primitives.hashes.SHA256'>}, allowed_digest_method={<class 'cryptography.hazmat.primitives.hashes.SHA256'>}), allowed_time_drift: ~minisaml.response.TimeDriftLimits = TimeDriftLimits(not_before_max_drift=datetime.timedelta(0), not_on_or_after_max_drift=datetime.timedelta(0))) → Response

Use this to validate a response if you know the issuer. This should be the case if your app only supports a single tenant or if each tenant has a separate Assertion Consumer Service endpoint. For multi-tenant apps using a single Assertion Consumer Service, use minisaml.response.validate_multi_tenant_response() instead.

Parameters:

• data – SAML Response as extracted from the HTTP form field SAMLResponse.

• certificate – Certificate or collection of certificates used by the Identity Provider.

• expected_audience – Issuer of your Service Provider.

• idp_issuer – The Issuer of the Identity Provider which issued the response.

• signature_verification_config – If the Identity Provider uses an algorithm other than SHA-256 for response signing, you have to enable it by passing an appropriate minisignxml.config.VerifyConfig instance.

• allowed_time_drift – Limits the amount of clock inaccuracy tolerated. Defaults to no inaccuracy allowed.

Returns:

Validated response.

Raises:

• minisaml.errors.MalformedSAMLResponse –

• minisaml.errors.ResponseExpired –

• minisaml.errors.ResponseTooEarly –

• minisaml.errors.AudienceMismatch –

• minisaml.errors.IssuerMismatch –

• lxml.etree.LxmlError –

minisaml.response.validate_multi_tenant_response(*, data: Union[bytes, str], get_config_for_issuer: Callable[[str], Tuple[ValidationConfig, State]], expected_audience: str) → Tuple[Response, State]

minisaml.response.validate_multi_tenant_response(*, data: Union[bytes, str], get_config_for_issuer: Callable[[str], Awaitable[Tuple[ValidationConfig, State]]], expected_audience: str) → Awaitable[Tuple[Response, State]]

This function allows for easy support of multi-tenant systems, where a single Assertion Consumer Service is used for multiple Identity Providers and the configuration to validate the response depends on the Issuer of the Identity Provider.

MiniSAML will parse the response and call the function passed to get_config_for_issuer with the Issuer as the only argument. This function should then return a tuple of a minisaml.response.ValidationConfig instance to use to validate the response and a second value which will be returned by minisaml.response.validate_multi_tenant_response(). This second value can be used to re-use values calculated in get_config_for_issuer, if no such values are needed, use None as the second item in the tuple instead. Any exceptions raised in the get_config_for_issuer function will be forwarded to the caller of minisaml.response.validate_multi_tenant_response(), as such, exceptions should be used to signal an unsupported Issuer.

The other arguments to this function and the attributes on minisaml.response.ValidationConfig have the same semantics as the arguments to minisaml.response.validate_response().

Note

The get_config_for_issuer argument can be either a synchronous or an asynchronous function. If it is asynchronous, the return value of this function will also be asynchronous.

Returns:

Validated response or an awaitable future of the validated response.

Raises:

• minisaml.errors.MalformedSAMLResponse –

• minisaml.errors.ResponseExpired –

• minisaml.errors.ResponseTooEarly –

• minisaml.errors.AudienceMismatch –

• minisaml.errors.IssuerMismatch –

• lxml.etree.LxmlError –

Data Types

minisaml.response.ValidationConfig

class minisaml.response.ValidationConfig(certificate: Union[cryptography.x509.base.Certificate, Collection[cryptography.x509.base.Certificate]], signature_verification_config: minisignxml.config.VerifyConfig = VerifyConfig(allowed_signature_method={<class 'cryptography.hazmat.primitives.hashes.SHA256'>}, allowed_digest_method={<class 'cryptography.hazmat.primitives.hashes.SHA256'>}), allowed_time_drift: minisaml.response.TimeDriftLimits = TimeDriftLimits(not_before_max_drift=datetime.timedelta(0), not_on_or_after_max_drift=datetime.timedelta(0)))

allowed_time_drift: TimeDriftLimits = TimeDriftLimits(not_before_max_drift=datetime.timedelta(0), not_on_or_after_max_drift=datetime.timedelta(0))

certificate: Union[Certificate, Collection[Certificate]]

signature_verification_config: VerifyConfig = VerifyConfig(allowed_signature_method={<class 'cryptography.hazmat.primitives.hashes.SHA256'>}, allowed_digest_method={<class 'cryptography.hazmat.primitives.hashes.SHA256'>})

minisaml.response.Response

class minisaml.response.Response

issuer: str

Issuer of the Identity Provider

name_id: str

User identifier. The value and format of this depend on the Identity Provider.

audience: str

Audience of the Service Provider.

attributes: List[Attribute]

Extra attributes in the SAML Response.

session_not_on_or_after: Optional[datetime.datetime]

A Identity Provider may suggest a time after which the session created by this SAML Response should be invalidated.

in_response_to: Optional[str]

If the SAML Response was generated in response to a SAML Request, this will contain the request ID of that request. It is your responsibility to verify this value if you want to prevent Identity Provider Initiated SSO.

attrs: Dict[str, str]

The attributes from minisaml.response.Response.attributes as a dictionary. If the attributes contain multiple attributes with the same name, this dictionary will only hold one of them, use minisaml.response.Response.attributes instead.

certificate: cryptography.x509.Certificate

The certificate used to sign this response.

minisaml.response.Attribute

class minisaml.response.Attribute

name: str

Name of the attribute

value: Optional[str]

Value of the attribute, if it has one. If the attribute has multiple values, the first one is returned. See minisaml.response.Attribute.values to get all values.

values: List[str]

All values for this attribute, if any are given.

format: Optional[str]

Format of the value if specified.

extra_attributes: Dict[str, str]

Extra XML attributes on the attribute element.

minisaml.response.TimeDriftLimits

class minisaml.response.TimeDriftLimits

not_before_max_drift: datetime.timedelta

not_on_or_after_max_drift: datetime.timedelta

classmethod none()

Returns an instance which allows for no drift.

Exceptions

minisaml.errors.MiniSAMLError

exception minisaml.errors.MiniSAMLError

The base class for all errors raised by MiniSAML. Note that if you pass objects of the wrong types to MiniSAML APIs, normal Python exceptions such as TypeError may be raised as well. If the XML you pass to a response validation function is invalid, lxml may also raise an error.

minisaml.errors.MalformedSAMLResponse

exception minisaml.errors.MalformedSAMLResponse

The response was valid XML but not a valid SAML Response. Specifically, the signed element was neither a SAML Assertion nor a SAML Response.

minisaml.errors.ResponseExpired

exception minisaml.errors.ResponseExpired

The response being validated is expired, beyond the time drift allowed by minisaml.response.TimeDriftLimits.

observed_time: datetime.datetime

not_on_or_after: datetime.datetime

minisaml.errors.ResponseTooEarly

exception minisaml.errors.ResponseTooEarly

The response being validated is too early, beyond the time drift allowed by minisaml.response.TimeDriftLimits.

observed_time: datetime.datetime

not_before: datetime.datetime

minisaml.errors.AudienceMismatch

exception minisaml.errors.AudienceMismatch

The audience in the SAML Response does not match the expected one passed to the validation function.

received_audience: str

expected_audience: str

minisaml.errors.IssuerMismatch

exception minisaml.errors.IssuerMismatch

The issuer of the SAML Response does not match the expected one passed to the validation function.

received_issuer: str

expected_issuer: str