README.md

#### Minimal Intro:
- [SSO](https://lmddgtfy.net/?q=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:

```python
""" 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

```python
""" 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!