api.saml.metadata package

Subpackages

Submodules

api.saml.metadata.filter module

class api.saml.metadata.filter.SAMLSubjectFilter(dsl_evaluator)[source]

Bases: object

Executes filter expressions.

execute(expression, subject)[source]

Apply the expression to the subject and return a boolean value indicating whether it’s a valid subject.

Parameters:
Returns:

Boolean value indicating whether it’s a valid subject

Return type:

bool

Raises:

SAMLSubjectFilterError – in the case of any errors occurred during expression evaluation

validate(expression)[source]

Validate the filter expression.

Try to apply the expression to a dummy Subject object containing all the known SAML attributes.

Parameters:

expression (str) – String containing the filter expression

Raise:

SAMLSubjectFilterError

exception api.saml.metadata.filter.SAMLSubjectFilterError(inner_exception)[source]

Bases: BaseError

Raised in the case of any errors during execution of a filter expression.

api.saml.metadata.model module

class api.saml.metadata.model.SAMLAttribute(name, values, friendly_name=None, name_format=None)[source]

Bases: object

Represents saml2:Attribute

property friendly_name

Returns the attribute’s friendly name

Returns:

Attribute’s friendly name

Return type:

string

property name

Returns the attribute’s name

Returns:

Attribute’s name

Return type:

string

property name_format

Returns the attribute’s name format

Returns:

Attribute’s name format

Return type:

string

property values

Returns a list of the attribute’s values

Returns:

List of the attribute’s values

Return type:

List

class api.saml.metadata.model.SAMLAttributeStatement(attributes)[source]

Bases: object

Represents saml2:AttributeStatement

property attributes

Returns an attributes dictionary

Returns:

Dictionary containing attributes

Return type:

Dict[string, Attribute]

class api.saml.metadata.model.SAMLAttributeType(value)[source]

Bases: Enum

Enumeration of different attributes supported by different SAML IdPs

displayName = 'urn:oid:2.16.840.1.113730.3.1.241'
eduOrg = 'urn:oid:1.3.6.1.4.1.5923.1.2.2'
eduOrgHomePageURI = 'urn:oid:1.3.6.1.4.1.5923.1.2.1.2'
eduOrgIdentityAuthNPolicyURI = 'urn:oid:1.3.6.1.4.1.5923.1.2.1.3'
eduOrgLegalName = 'urn:oid:1.3.6.1.4.1.5923.1.2.1.4'
eduOrgSuperiorURI = 'urn:oid:1.3.6.1.4.1.5923.1.2.1.5'
eduOrgWhitePagesURI = 'urn:oid:1.3.6.1.4.1.5923.1.2.1.6'
eduPerson = 'urn:oid:1.3.6.1.4.1.5923.1.1.2'
eduPersonAffiliation = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.1'
eduPersonAssurance = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.11'
eduPersonEntitlement = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7'
eduPersonNickname = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.2'
eduPersonOrcid = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.12'
eduPersonOrgDN = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.3'
eduPersonOrgUnitDN = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.4'
eduPersonPrimaryAffiliation = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.5'
eduPersonPrimaryOrgUnitDN = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.8'
eduPersonPrincipalName = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.6'
eduPersonPrincipalNamePrior = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.16'
eduPersonScopedAffiliation = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.9'
eduPersonTargetedID = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.10'
eduPersonUniqueId = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.13'
givenName = 'urn:oid:2.5.4.42'
mail = 'urn:oid:0.9.2342.19200300.100.1.3'
surname = 'urn:oid:2.5.4.4'
uid = 'urn:oid:0.9.2342.19200300.100.1.1'
class api.saml.metadata.model.SAMLBinding(value)[source]

Bases: Enum

Enumeration of SAML bindings

DEFLATE = 'urn:oasis:names:tc:SAML:2.0:bindings:URL-Encoding:DEFLATE'
HTTP_ARTIFACT = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact'
HTTP_POST = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'
HTTP_REDIRECT = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
SOAP = 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP'
class api.saml.metadata.model.SAMLIdentityProviderMetadata(entity_id, ui_info, organization, name_id_format, sso_service, slo_service=None, want_authn_requests_signed=False, signing_certificates=None, encryption_certificates=None)[source]

Bases: SAMLProviderMetadata

Represents IdP metadata

property encryption_certificates

Returns a list of encryption certificates

Returns:

List of encryption certificates

Return type:

List[string]

property signing_certificates

Returns a list of signing certificates

Returns:

List of signing certificates

Return type:

List[string]

property slo_service

Returns Single Log-Out service’s metadata

Returns:

Single Log-Out service’s metadata

Return type:

SAMLService

property sso_service

Returns Single Sign-On service’s metadata

Returns:

Single Sign-On service’s metadata

Return type:

SAMLService

property want_authn_requests_signed

Returns the boolean value indicating to service providers whether or not they can expect an unsigned <AuthnRequest> message to be accepted by the identity provider

Returns:

Boolean value indicating to service providers whether or not they can expect an unsigned <AuthnRequest> message to be accepted by the identity provider

Return type:

bool

class api.saml.metadata.model.SAMLLocalizedMetadataItem(value, language=None)[source]

Bases: object

Represents md:localizedNameType.

property language

Return the value’s language.

Returns:

Value’s language

Return type:

string

property value

Return the actual value.

Returns:

Actual value

Return type:

string

class api.saml.metadata.model.SAMLNameID(name_format, name_qualifier, sp_name_qualifier, name_id)[source]

Bases: object

Represents saml2:NameID

property name_format

Returns name ID’s format

Returns:

Name ID’s format

Return type:

string

property name_id

Returns name ID

Returns:

Name ID

Return type:

string

property name_qualifier

Returns the security or administrative domain that qualifies the name identifier of the subject. This attribute provides a means to federate names from disparate user stores without collision

Returns:

Security or administrative domain that qualifies the name identifier of the subject. This attribute provides a means to federate names from disparate user stores without collision

Return type:

string

property sp_name_qualifier

Returns the attribute that further qualifies a federated name identifier with the name of the service provider or affiliation of providers which has federated the principal’s identity

Returns:

Attribute that further qualifies a federated name identifier with the name of the service provider or affiliation of providers which has federated the principal’s identity

Return type:

string

class api.saml.metadata.model.SAMLNameIDFormat(value)[source]

Bases: Enum

Enumeration of SAML name ID formats

EMAIL_ADDRESS = 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress'
ENCRYPTED = 'urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted'
ENTITY = 'urn:oasis:names:tc:SAML:2.0:nameid-format:entity'
KERBEROS = 'urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos'
PERSISTENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
TRANSIENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
UNSPECIFIED = 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'
WINDOWS_DOMAIN_QUALIFIED_NAME = 'urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName'
X509_SUBJECT_NAME = 'urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName'
class api.saml.metadata.model.SAMLOrganization(organization_names=None, organization_display_names=None, organization_urls=None)[source]

Bases: object

Represents md:Organization and contains basic information about an organization responsible for a SAML entity or role.

property organization_display_names

Return a list of localized organization names that suitable for human consumption.

Returns:

List of localized organization names that suitable for human consumption

Return type:

Optional[List[SAMLLocalizedMetadataItem]]

property organization_names

Return a list of localized organization names that may or may not be suitable for human consumption.

Returns:

List of localized organization names that may or may not be suitable for human consumption

Return type:

Optional[List[SAMLLocalizedMetadataItem]]

property organization_urls

Return a list of localized organization URIs that specify a location to which to direct a user for additional information.

Returns:

List of localized organization URIs that specify a location to which to direct a user for additional information

Return type:

Optional[List[SAMLLocalizedMetadataItem]]

class api.saml.metadata.model.SAMLProviderMetadata(entity_id, ui_info, organization, name_id_format=SAMLNameIDFormat.UNSPECIFIED)[source]

Bases: object

Base class for IdentityProvider and ServiceProvider classes

property entity_id

Returns the provider’s entityID

Returns:

Provider’s entityID

Return type:

string

property name_id_format

Returns the name ID format

Returns:

Name ID format

Return type:

string

property organization

Returns the provider’s Organization object :return: Provider’s Organization object :rtype: SAMLOrganization

property ui_info

Returns the provider’s UIInfo object :return: Provider’s UIInfo object :rtype: SAMLUIInfo

class api.saml.metadata.model.SAMLService(url, binding)[source]

Bases: object

Represents a service: IdP’s SingleSignOnService, SingleLogOutService, SP’s AssertionConsumerService

property binding

Returns the service’s binding

Returns:

Service’s binding

Return type:

SAMLBinding

property url

Returns the service’s URL

Returns:

Service’s URL

Return type:

string

class api.saml.metadata.model.SAMLServiceProviderMetadata(entity_id, ui_info, organization, name_id_format, acs_service, authn_requests_signed=False, want_assertions_signed=False, certificate=None, private_key=None)[source]

Bases: SAMLProviderMetadata

Represents SP metadata

property acs_service

Returns Assertion Consumer service’s metadata

Returns:

Assertion Consumer service’s metadata

Return type:

SAMLService

property authn_requests_signed

Returns the value that indicates whether the <samlp:AuthnRequest> messages sent by this service provider will be signed

Returns:

Value that indicates whether the <samlp:AuthnRequest> messages sent by this service provider will be signed

Return type:

bool

property certificate

Returns the certificate in X.509 format containing the public key used for signing SAML requests

Returns:

Certificate in X.509 format containing the public key used for signing SAML requests

Return type:

string

property private_key

Returns the private key used for encrypting SAML requests

Returns:

Private key used for encrypting SAML requests

Return type:

string

property want_assertions_signed

Returns the value that indicates a requirement for the <saml:Assertion> elements received by this service provider to be signed

Returns:

Value that indicates a requirement for the <saml:Assertion> elements received by this service provider to be signed

Return type:

bool

class api.saml.metadata.model.SAMLSubject(name_id, attribute_statement, valid_till=None)[source]

Bases: object

Contains a name ID and a attribute statement

property attribute_statement

Returns the attribute statement

Returns:

Attribute statement

Return type:

SAMLAttributeStatement

property name_id

Returns the name ID

Returns:

Name ID

Return type:

SAMLNameID

property valid_till

Returns the time till which the subject is valid. The default value is 30 minutes. Please refer to the Shibboleth IdP documentation for more details: - https://wiki.shibboleth.net/confluence/display/IDP30/SessionConfiguration

Returns:

Time till which the subject is valid

Return type:

datetime.timedelta

class api.saml.metadata.model.SAMLSubjectJSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)[source]

Bases: JSONDecoder

Subject’s JSON decoder.

decode(raw_subject, _w=<built-in method match of re.Pattern object>)[source]

Decode a JSON document into Subject object.

Parameters:

  • raw_subject (str) – String containing JSON document

  • _w (RegEx) – Regular expression used to match white spaces

Returns:

Subject object

Return type:

api.saml.metadata.Subject

class api.saml.metadata.model.SAMLSubjectJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: JSONEncoder

Subject’s JSON encoder

default(subject)[source]

Serializers a Subject object to JSON

Parameters:

subject (api.saml.metadata.Subject) – Subject object

Returns:

String containing JSON representation of the Subject object

Return type:

string

class api.saml.metadata.model.SAMLSubjectPatronIDExtractor(use_name_id=True, attributes=None, regular_expression=None)[source]

Bases: object

Extracts a unique patron ID from SAML subjects.

This class accepts several parameters in its constructor, allowing it to override its behavior. The default behavior is described below.

Unfortunately, there is no single standard regarding what attributes can be treated as unique IDs. Different systems use different attributes, and all of them have their pros and cons. By default, this class looks for a unique patron ID in the following attributes.

  1. eduPersonUniqueId (https://wiki.refeds.org/display/STAN/eduPerson+2020-01#eduPerson2020-01-eduPersonUniqueId)

    A long-lived, non re-assignable, omnidirectional identifier suitable for use as a principal identifier by authentication providers or as a unique external key by applications.

  2. eduPersonTargetedID (https://wiki.refeds.org/display/STAN/eduPerson+2020-01#eduPerson2020-01-eduPersonTargetedID)

    A persistent, non-reassigned, opaque identifier for a principal. eduPersonTargetedID is an abstracted version of the SAML V2.0 Name Identifier format of “urn:oasis:names:tc:SAML:2.0:nameid-format:persistent” (see http://www.oasis-open.org/committees/download.php/35711).

    NOTE: eduPersonTargetedID is DEPRECATED and will be marked as obsolete in a future version of this specification. Its equivalent definition in SAML 2.0 has been replaced by a new specification for standard Subject Identifier attributes [https://docs.oasis-open.org/security/saml-subject-id-attr/v1.0/saml-subject-id-attr-v1.0.html], one of which (”urn:oasis:names:tc:SAML:attribute:pairwise-id”) is a direct replacement for this identifier with a simpler syntax and safer comparison rules. Existing use of this attribute in SAML 1.1 or SAML 2.0 should be phased out in favor of the new Subject Identifier attributes.”

  3. uid (http://oid-info.com/get/0.9.2342.19200300.100.1.1)

    See IETF RFC 4519. IETF RFC 1274 uses the identifier “userid”.

  4. Name ID The extractor fetches the first name ID it could find as a last resort which may no be correct. It might be better to fetch only persistent name IDs.

Also, please note that eduPersonTargetedID attribute and name IDs should be phased out and replaced with the pairwise-id attribute from the OASIS SAML 2.0 SubjectID Attributes Profile. However, it’s not yet supported by most of the IdPs.

PATRON_ID_REGULAR_EXPRESSION_NAMED_GROUP = 'patron_id'
extract(subject)[source]

Extract a unique patron ID from the SAML subject.

Parameters:

subject (SAMLSubject) – SAML subject

Returns:

Unique ID

Return type:

string

Returns:

Unique patron ID if any

Return type:

Optional[str]

class api.saml.metadata.model.SAMLUIInfo(display_names=None, descriptions=None, information_urls=None, privacy_statement_urls=None, logo_urls=None)[source]

Bases: object

Represents mdui:UIInfoType and contains values that can be shown in the UI to describe IdPs/SPs.

property descriptions

Returns a list of localizable descriptions

Returns:

List of localizable descriptions

Return type:

List[LocalizableMetadataItem]

property display_names

Returns a list of localizable display names

Returns:

List of localizable display names

Return type:

List[LocalizableMetadataItem]

property information_urls

Returns a list of localizable information URLs

Returns:

List of localizable information URLs

Return type:

List[LocalizableMetadataItem]

property logo_urls

Returns a list of localizable logo URLs

Returns:

List of localizable logo URLs

Return type:

List[LocalizableMetadataItem]

property privacy_statement_urls

Returns a list of localizable privacy statement URLs

Returns:

List of localizable privacy statement URLs

Return type:

List[LocalizableMetadataItem]

api.saml.metadata.monitor module

class api.saml.metadata.monitor.SAMLMetadataMonitor(db, loader)[source]

Bases: Monitor

MAX_AGE = datetime.timedelta(days=1)
SERVICE_NAME = 'SAML Metadata Monitor'
run_once(progress)[source]

Do the actual work of the Monitor.

Parameters:

progress – A TimestampData representing the work done by the Monitor up to this point.

Returns:

A TimestampData representing how you want the Monitor’s entry in the timestamps table to look like from this point on. NOTE: Modifying the incoming progress and returning it is generally a bad idea, because the incoming progress is full of old data. Instead, return a new TimestampData containing data for only the fields you want to set.

api.saml.metadata.parser module

class api.saml.metadata.parser.SAMLMetadataParser(skip_incorrect_providers=False)[source]

Bases: object

Parses SAML metadata

parse(xml_metadata)[source]

Parses an XML string containing SAML metadata and translates it into a list of IdentityProviderMetadata/ServiceProviderMetadata objects

Parameters:

xml_metadata (string) – XML string containing SAML metadata

Returns:

List of SAMLMetadataParsingResult objects

Return type:

List[SAMLMetadataParsingResult]

Raise:

MetadataParsingError

exception api.saml.metadata.parser.SAMLMetadataParsingError(message=None, inner_exception=None)[source]

Bases: BaseError

Raised in the case of any errors occurred during parsing of SAML metadata

class api.saml.metadata.parser.SAMLMetadataParsingResult(provider, xml_node)[source]

Bases: object

property provider

Return the object containing either SP’s or IdP’s metadata.

Returns:

Object containing either SP’s or IdP’s metadata

Return type:

api.saml.metadata.model.SAMLProviderMetadata

property xml_node

Return the XML node containing metadata

Returns:

XML node containing metadata

Return type:

defusedxml.lxml.RestrictedElement

class api.saml.metadata.parser.SAMLSubjectParser[source]

Bases: object

Parses SAML response into Subject object

parse(auth)[source]

Parses OneLogin_Saml2_Auth object containing SAML response data into Subject

Parameters:

auth (OneLogin_Saml2_Auth) – OneLogin_Saml2_Auth object containing SAML response

Returns:

Subject object containing SAML attributes and NameID

Return type:

api.saml.metadata.Subject

Module contents