diff --git a/README.md b/README.md index 274bf800d194c55f7b32176fd692d677ff9ebcb9..6e9b5186bf7099b2eeb87f6df46572a2d221246e 100644 --- a/README.md +++ b/README.md @@ -8,58 +8,77 @@ - SAML/SAML2: It's just another XML-based enterprise-grade standard that will make you cry blood -#### Integrating the app into your Django project. +#### 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` -- 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 +- 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 = "auto-{0}-{1}".format(socket.gethostname(), os.path.dirname(os.path.dirname(__file__))) - # IDP + 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 - # 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: +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 - - `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) + - 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!