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


#### Integrating the app into your Django project.
- 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`
- Add to the project settings
  - Development
    ```python
    # imports
    import socket
    import os
    # SP
    SP_HOST = "141.71.foo.bar"  # your SP host or IP address
    SP_PORT = 8000
    SP_SSL = False
    SP_FORCE_ENTITY_ID = "auto-{0}-{1}".format(socket.gethostname(), os.path.dirname(os.path.dirname(__file__)))
    # IDP
    IDP_META_URL = "https://idp-test.it.hs-hannover.de/idp/shibboleth"  # development
    # IDP_IGNORE = True  # set to True if you experience problems with the IDP (SSO will NOT work)
    ```
  - Production
    ```python
    # SP
    SP_HOST = "141.71.foo.bar"  # your SP host or IP address
    # IDP
    IDP_META_URL = "https://idp.hs-hannover.de/idp/shibboleth"  # production
    ```
- generate a new key pair:
  - create `cert` directory:
    - inside of project `settings` directory if it's a package
    - next to project `settings.py` file if it's a module
  - `openssl req -new -x509 -days 3650 -nodes -out sp.pem -keyout sp.key`
  - `./cert/sp.key` put the private key here
  - `./cert/sp.pem` put the certificate here, signing is optional

#### Integrating your project into the existing SSO infrastructure
- **Do this only if you want to use SSO. For development it's usually enough to use the dev view instead.**
- 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`)
  - **if using Firefox:** use "show source code" option or you will get invalid XML
- 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 & tail -fn0 /opt/shibboleth-idp/logs/idp-warn.log` (you now have some time to grab you a coffee)