From ce7d9bbfa0d619076e55c994ea2b9827ee41b0ec Mon Sep 17 00:00:00 2001
From: Art Lukyanchyk <artiom.lukyanchyk@hs-hannover.de>
Date: Thu, 28 Sep 2017 13:55:27 +0200
Subject: [PATCH] Update README.md
---
README.md | 103 ++++++++++++++++++++++++++++++++----------------------
1 file changed, 61 insertions(+), 42 deletions(-)
diff --git a/README.md b/README.md
index 274bf80..6e9b518 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!
--
GitLab