332 lines
9.9 KiB
Plaintext
332 lines
9.9 KiB
Plaintext
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
|