README.md

Minimal Intro:

• SSO: Single Sign On
• SP: Service Provider (your client)
• IdP: Identity Provider (server, Shibboleth)
• Metadata/Meta: an XML that describes SP or IdP (or another entity)
• SAML/SAML2: It's just another XML-based enterprise-grade standard that will make you cry blood

Necessary stuff

• Binary dependencies: sudo apt install libxml2-dev libxslt1-dev xmlsec1 libxmlsec1-dev pkg-config
• Python dependencies: see requirements.txt or setup.py
• Add the app into INSTALLED_APPS
• Include the app's urls.py into the project urls.py urlpatterns, preferably without a prefix

Development setup

• If you don't need a fully functional SSO, you don't need to configure anything at all. Use the dev view: localhost:8000/dev/ (might change depending on your urlconf and settings).

• If you need a fully functional SSO during development, here's an example:

""" settings/dev.py """

from django import urls
import socket
import os

IDP_META_URL = "https://idp-test.it.hs-hannover.de/idp/shibboleth"

SP_KEY = "{project_settings}/cert/sp.key"
SP_CERT = "{project_settings}/cert/sp.pem"
SP_FORCE_ENTITY_ID = "dev-auto-id-{0}-{1}".format(socket.gethostname(), os.path.dirname(os.path.dirname(__file__)))

SP_HOST = "localhost"
SP_PORT = 8000
SP_SSL = False

LOGIN_URL = urls.reverse_lazy("sso-dev")

Groups

To receive groups over SSO you need a mapping. You can manage group mapping with group_mapping management command. Example:

group_mapping add myproject_superusers "CN=MyProjectSuperusers,OU=Foo,OU=Bar,DC=fh-h,DC=de"

Groups are not mapped automatically. Because automatic mapping can pose security risks. Imagine auto-mapping that expects group with name "Superusers"; an intruder could create a new group with this name under any path they own and/or create an alias/reference and receive superuser permissions in your project.

Production setup

""" settings/prod.py """
from django import urls

SP_HOST = "141.71.foo.bar"  # your SP host or IP address
IDP_META_URL = "https://idp.hs-hannover.de/idp/shibboleth"  # production

LOGIN_URL = urls.reverse_lazy("sso-login")

You will also need to configure the SSO

SSO configuration

• create a key pair:
  • if you don't need your cert to be signed you can use openssl req -new -x509 -days 3650 -nodes -out sp.pem -keyout sp.key
  • create cert directory:
    • inside of project settings directory if it's a package
    • next to project settings.py file if it's a module
  • ./cert/sp.key put the private key here
  • ./cert/sp.pem put the certificate here, signing is optional
• configure the IdP:
  • Ask somebody who knows more. Seriously.
  • Try on the test IdP before you brick the production!
  • Grab your meta
    • Run your project.
    • Find meta of your SP (relative path /saml2/meta or view name sso-saml2-meta)
    • Use Ctrl+U ("view source") to get the actual XML, otherwise your browser could mess it up
  • configure the IdP:
    • SSH to the IdP and locate the Shibboleth directory, most likely /opt/shibboleth-idp/
    • put your meta into a new file in ./metadata/ and give it a nice verbose name
    • edit ./conf/metadata-providers.xml
      • create a new <MetadataProvider .../> element, your best guess is to copy an existing line that belongs to some existing Django project
      • id should be unique
      • metadataFile should point on your new metadata
    • edit ./conf/attribute-filter.xml
      • add a new <Rule .../> element inside of <AttributeFilterPolicy id="releaseToDjango">
      • value (looks like URI) should be the entityID of your SP (you find it in your meta)
    • systemctl restart tomcat8 (you now have some time to grab you a coffee)
    • ensure the IdP works after restarting!