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
This is what you normally want during the development.
```python
""" settings/dev.py """

import socket
import os

DO_YOU_WANT_SSO = False

if DO_YOU_WANT_SSO:
    SP_HOST = "localhost"
    SP_PORT = 8000
    SP_SSL = False
    SP_FORCE_ENTITY_ID = "dev-auto-id-{0}-{1}".format(socket.gethostname(), os.path.dirname(os.path.dirname(__file__)))
    IDP_META_URL = "https://idp-test.it.hs-hannover.de/idp/shibboleth"  # development
else:
    SSO_DISABLED = True
```

Use `localhost:8000/dev/` to acces the development view.

The code snippet above disables the actual SSO. If you need it:
  - change `DO_YOU_WANT_SSO` to True
  - see the SSO configuration section

#### Production setup

```python
""" settings/prod.py """

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

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