Package: django-mellon
django-mellonSAML 2.0 authentication for DjangoUsageYou need to have the Python binding for the Lasso library installed, you can
find source and package for Debian onhttp://lasso.entrouvert.org/download/.Add mellon to your installed apps:INSTALLED_APPS = (
   ...
   'mellon',
)Add the SAMLBacked to your authentication backends:AUTHENTICATION_BACKENDS = (
    ...
    'mellon.backends.SAMLBackend',
)Add mellon urls to your urls:urlpatterns = patterns('',
    ...
    url(r'^/accounts/mellon/', include('mellon.urls')),
)If SAML 2.0 should be your only authentication method you can definemellon_loginas you mainLOGIN_URL:LOGIN_URL = 'mellon_login'
LOGOUT_URL = 'mellon_logout'Your metadata will be downloadable through HTTP onhttp://whatever.example.net/accounts/mellon/metadataIf your identity provider ask for your assertion consumer URL it’s onhttp://whatever.example.net/accounts/mellon/loginIf your identity provider ask for your logout URL it’s onhttp://whatever.example.net/accounts/mellon/logoutSessionAfter an authentication attributes are stored in the session using a
dictionary, the key ismellon_session. The dictionary contains:issuer: the EntityID of the identity providername_id_content: the value of the NameIDname_id_format: the format of the NameIDauthn_instant: the ISO8601 date of the authentication on the identity provider, optional.session_not_on_or_after: the ISO8691 date after which the local
session should be closed. Note that we automatically set the
expiration of the Django session to this value if it’s available.authn_context_class_ref: the authentication method of the current
authentication on the identity provider. You can restrict
authorized authentication methods using the settingMELLON_AUTHN_CLASSREF.all attributes extracted from the assertion.SettingsAll generic setting apart fromMELLON_IDENTITY_PROVIDERScan be
overridden in the identity provider settings by removing theMELLON_prefix.MELLON_IDENTITY_PROVIDERSA list of dictionaries, they must contain at least one of the keysMETADATA(inline copy of the identity provider metadata),METADATA_URLURL of the IdP
metadata file, orMETADATA_PATHan absolute path to the IdP metadata file..
All other keys are override of generic settings.When using an URL, the URL is automatically cached in theMEDIA_ROOTdirectory of your application in the directory namedmellon_metadata_cache.
If you restart the application and the URL is unavailable, the file cache will
be used. The cache will be refreshed everyMELLON_METADATA_CACHE_TIMEseconds.
If the HTTP retrieval of the metadata URL takes longer thantMELLON_METADATA_HTTP_TIMEOUTseconds, retrieval will be skipped.When the cache is already loaded, retrievals are done in the background by a
thread.When using a local absolute path, the metadata is reloaded each time the
modification time of the file is superior to the last time it was loaded.MELLON_PUBLIC_KEYSList of public keys of this service provider, add multiple keys for
doing key roll-overMELLON_PRIVATE_KEYThe PKCS#8 PEM encoded private key. If neither MELLON_PRIVATE_KEYS and
MELLON_PRIVATE_KEY are set, request will not be signed.MELLON_PRIVATE_KEY_PASSWORDPassword for the private key if needed, default is NoneMELLON_PRIVATE_KEYSA list of private keys contained in strings (same format ass
MELLON_PRIVATE_KEY) or of tuple paris (private_key, private_key_password). If
MELLON_PRIVATE_KEY is None, the first key in MELLON_PRIVATE_KEYS will be used
to sign messages. Other keys are only for decrypting encrypted assertions.  If
the same key appear in MELLON_PRIVATE_KEY and MELLON_PRIVATE_KEYS it will be
ignored the second time. If neither MELLON_PRIVATE_KEYS and MELLON_PRIVATE_KEY
are set, request will not be signed.MELLON_NAME_ID_FORMATSNameID formats to advertise in the metadata file, default is ().MELLON_NAME_ID_POLICY_FORMATThe NameID format to request, default is None.MELLON_FORCE_AUTHNWhether to force authentication on each authencation request,
default is False.MELLON_ADAPTERA list of class providings methods handling SAML authorization, user
lookup and provisioning. Optional methods on theses classes areauthorize(idp, saml_attributes) -> booleanIf any adapter returns False, the authentication is refused. It’s
possible to raise PermissionDenied to show a specific message on
the login interface.lookup_user(idp, saml_attributes) -> User / NoneEach adapter is called in the order of the settings, the first
return value which is not None is kept as the authenticated user.provision(user, idp, saml_attributes -> NoneThis method is there to fill an existing user fields with data
from the SAML attributes or to provision any kind of object in the
application.Settings of the default adapterThe following settings are used by the default adaptermellon.adapters.DefaulAdapterif you use your own adapter you can
ignore them. If your adapter inherit from the default adapter those
settings can still be applicable.MELLON_REALMThe default realm to associate to user created with the default
adapter, default is ‘saml’.MELLON_PROVISIONWhether to create user if their username does not already exists,
default is True.MELLON_USERNAME_TEMPLATEThe template to build and/or retrieve a user from its username based
on received attributes, the syntax is the one from the str.format()
method of Python. Available variables are:realmidp (current setting for the idp issuing the assertion)attributesThe default value is{attributes{name_id_content]}@realm.Another example could be{atttributes[uid][0]}to set the passed
username as the username of the newly created user.MELLON_ATTRIBUTE_MAPPINGMaps templates based on SAML attributes to field of the user model.
Default is {}. To copy standard LDAP attributes into your Django user
model could for example do that:MELLON_ATTRIBUTE_MAPPING = {
    'email': '{attributes[mail][0]',
    'first_name': '{attributes[gn][0]}',
    'last_name': '{attributes[sn][0]}',
}MELLON_SUPERUSER_MAPPINGAttributes superuser flags to user if a SAML attribute contains a given value,
default is {}. Ex.:MELLON_SUPERUSER_MAPPING = {
    'roles': 'Admin',
}MELLON_AUTHN_CLASSREFAuthorized authentication class references, default is (). Empty
value means everything is authorized. Authentication class reference
must be obtained from your identity provider but SHOULD come from the
SAML 2.0 specification.MELLON_GROUP_ATTRIBUTEName of the SAML attribute to map to Django group names, default is None. Ex.:MELLON_GROUP_ATTRIBUTE = 'role'MELLON_CREATE_GROUPWhether to create group or only assign existing groups, default is True.MELLON_ERROR_URLURL for the continue link when authentication fails, default is
None. If not ERROR_URL is None, the RelayState is used. If there is
no RelayState, the LOGIN_REDIRECT_URL, which defaults to /, is used.MELLON_ERROR_REDIRECT_AFTER_TIMEOUTTimeout in seconds before automatically redirecting the user to the
continue URL when authentication has failed. Default is 120 seconds.MELLON_VERIFY_SSL_CERTIFICATEVerify SSL certificate when doing HTTP requests, used when resolving artifacts.
Default is True.MELLON_TRANSIENT_FEDERATION_ATTRIBUTEName of an attribute to use in replacement of the NameID content when the NameID
format is transient. Without it no login using a transient NameID can occur with
the default adapter.
Default is None.MELLON_DEFAULT_ASSERTION_CONSUMER_BINDINGShould be post or artifact. Default is post. You can refer to the SAML 2.0
specification to learn the difference.MELLON_LOOKUP_BY_ATTRIBUTESAllow looking for user with some SAML attributes if the received NameID is
still unknown. It must be a list of dictionnaries with two mandatory keysuser_fieldandsaml_attribute. The optionnal keyignore-caseshould be a
boolean indicating if the match is case-insensitive (default is to respect the
case).Each dictionnary is a rule for linking, applying all the rules should only
return one user, the boolean operator OR is applied between the rules.So for example if you received a SAML attribute namedemailand you want to
link user with the same email you would configured it like that:MELLON_LOOKUP_BY_ATTRIBUTES = [
    {
        'saml_attribute': 'email',
        'user_field': 'email',
    }
]The targeted user(s) field(s) should be as much as possible unique
individually, if not django-mellon will refuse to link multiple users matching
the rules.MELLON_METADATA_CACHE_TIMEWhen using METADATA_URL to reference a metadata file, it’s the duration in
secondes between refresh of the metadata file. Default is 3600 seconds, 1 hour.MELLON_METADATA_HTTP_TIMEOUTTimeout in seconds for HTTP call made to retrieve metadata files. Default is 10
seconds.MELLON_ASSERTION_CONSUMER_BINDINGSThe list of supported assertion consumer bindings. Default is:['post', 'artifact']TestsUnit tests are written using pytest and launched using tox, and can be run with:toxCode Styleblack is used to format the code, using thoses parameters:black –target-version py37 –skip-string-normalization –line-length 110There is .pre-commit-config.yaml to use pre-commit to automatically run black
before commits. (executepre-commit installto install the git hook.)isort is used to format the imports, using those parameter:isort –profile black –line-length 110pyupgrade is used to automatically upgrade syntax, using those parameters:pyupgrade –keep-percent-format –py37-plusdjhtml is used to automatically indent html files, using those parameters:djhtml –tabwidth 2django-upgrade is used to automatically upgrade Django syntax, using those parameters:django-upgrade –target-version 2.2There is .pre-commit-config.yaml to use pre-commit to automatically run these tools
before commits. (executepre-commit installto install the git hook.)RemarksTo honor the SessionNotOnOrAfter attribute sent by an IdP you must use a specific SessionEngine,
only db and cached_db are supported currently, the equivalent session engines are:mellon.sessions_backends.dbandmellon.sessions_backends.cached_db