Metadata-Version: 1.0
Name: django-mellon
Version: 1.22
Summary: SAML 2.0 authentication for Django
Home-page: http://dev.entrouvert.org/projects/django-mellon/
Author: Entr'ouvert
Author-email: info@entrouvert.org
License: AGPLv3 or later
Description: django-mellon
        =============
        
        SAML 2.0 authentication for Django
        
        Usage
        =====
        
        You need to have the Python binding for the Lasso library installed, you can
        find source and package for Debian on http://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 define `mellon_login` as you main `LOGIN_URL`::
        
            LOGIN_URL = 'mellon_login'
            LOGOUT_URL = 'mellon_logout'
        
        Your metadata will be downloadable through HTTP on 
        
            http://whatever.example.net/accounts/mellon/metadata
        
        If your identity provider ask for your assertion consumer URL it's on
        
            http://whatever.example.net/accounts/mellon/login
        
        If your identity provider ask for your logout URL it's on
        
            http://whatever.example.net/accounts/mellon/logout
        
        Session
        =======
        
        After an authentication attributes are stored in the session using a
        dictionary, the key is `mellon_session`. The dictionary contains:
        
         - issuer: the EntityID of the identity provider
         - name_id_content: the value of the NameID
         - name_id_format: the format of the NameID
         - authn_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 setting
           `MELLON_AUTHN_CLASSREF`.
         - all attributes extracted from the assertion.
        
        Settings
        ========
        
        All generic setting apart from `MELLON_IDENTITY_PROVIDERS` can be
        overridden in the identity provider settings by removing the
        `MELLON_` prefix.
        
        MELLON_IDENTITY_PROVIDERS
        -------------------------
        
        A list of dictionaries, they must contain at least one of the keys `METADATA`
        (inline copy of the identity provider metadata), `METADATA_URL` URL of the IdP
        metadata file, or `METADATA_PATH` an 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 the `MEDIA_ROOT`
        directory of your application in the directory named `mellon_metadata_cache`.
        If you restart the application and the URL is unavailable, the file cache will
        be used. The cache will be refreshed every `MELLON_METADATA_CACHE_TIME` seconds.
        If the HTTP retrieval of the metadata URL takes longer thant
        `METTON_METADATA_HTTP_TIMEOUT` seconds, 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_KEYS
        ------------------
        
        List of public keys of this service provider, add multiple keys for
        doing key roll-over
        
        MELLON_PRIVATE_KEY
        ------------------
        
        The 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_PASSWORD
        ---------------------------
        
        Password for the private key if needed, default is None
        
        MELLON_PRIVATE_KEYS
        -------------------
        
        A 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_FORMATS
        ----------------------
        
        NameID formats to advertise in the metadata file, default is ().
        
        MELLON_NAME_ID_POLICY_FORMAT
        ----------------------------
        
        The NameID format to request, default is None.
        
        MELLON_FORCE_AUTHN
        ------------------
        
        Whether to force authentication on each authencation request,
        default is False.
        
        MELLON_ADAPTER
        --------------
        
        A list of class providings methods handling SAML authorization, user
        lookup and provisioning. Optional methods on theses classes are
        
         - authorize(idp, saml_attributes) -> boolean
        
           If 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 / None
        
           Each 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 -> None
        
           This 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 adapter
        ===============================
        
        The following settings are used by the default adapter
        `mellon.adapters.DefaulAdapter` if you use your own adapter you can
        ignore them. If your adapter inherit from the default adapter those
        settings can still be applicable.
        
        MELLON_REALM
        ------------
        
        The default realm to associate to user created with the default
        adapter, default is 'saml'.
        
        MELLON_PROVISION
        ----------------
        
        Whether to create user if their username does not already exists,
        default is True.
        
        MELLON_USERNAME_TEMPLATE
        ------------------------
        
        The 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:
        
         - realm
         - idp (current setting for the idp issuing the assertion)
         - attributes
        
        The 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_MAPPING
        ------------------------
        
        Maps 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_MAPPING
        ------------------------
        
        Attributes superuser flags to user if a SAML attribute contains a given value,
        default is {}. Ex.::
        
            MELLON_SUPERUSER_MAPPING = {
                'roles': 'Admin',
            }
        
        MELLON_AUTHN_CLASSREF
        ---------------------
        
        Authorized 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_ATTRIBUTE
        ----------------------
        
        Name of the SAML attribute to map to Django group names, default is None. Ex.::
        
           MELLON_GROUP_ATTRIBUTE = 'role'
        
        MELLON_CREATE_GROUP
        -------------------
        
        Whether to create group or only assign existing groups, default is True.
        
        MELLON_ERROR_URL
        ----------------
        
        URL 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_TIMEOUT
        -----------------------------------
        
        Timeout in seconds before automatically redirecting the user to the
        continue URL when authentication has failed. Default is 120 seconds.
        
        MELLON_VERIFY_SSL_CERTIFICATE
        -----------------------------
        
        Verify SSL certificate when doing HTTP requests, used when resolving artifacts.
        Default is True.
        
        MELLON_TRANSIENT_FEDERATION_ATTRIBUTE
        -------------------------------------
        
        Name 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_BINDING
        -----------------------------------------
        
        Should be post or artifact. Default is post. You can refer to the SAML 2.0
        specification to learn the difference.
        
        MELLON_LOOKUP_BY_ATTRIBUTES
        ---------------------------
        
        Allow looking for user with some SAML attributes if the received NameID is
        still unknown. It must be a list of dictionnaries with two mandatory keys
        `user_field` and `saml_attribute`. The optionnal key `ignore-case` should 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 named `email` and 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_TIME
        --------------------------
        
        When 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.
        
        METTON_METADATA_HTTP_TIMEOUT
        ----------------------------
        
        Timeout in seconds for HTTP call made to retrieve metadata files. Default is 10
        seconds.
        
        Tests
        =====
        
        Unit tests are written using pytest and launched using tox, and can be run with:
        
           tox
        
        Remarks
        =======
        
        To 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.db
        
        and
        
            mellon.sessions_backends.cached_db
        
Platform: UNKNOWN
