From 04419e8eaae7d5f63818ce319c962c2e41eb0aa9 Mon Sep 17 00:00:00 2001
From: Anthony Eden <anthony@mediarealm.com.au>
Date: Fri, 15 Mar 2019 23:00:37 +1100
Subject: [PATCH] Include basic SAML setup documentation

---
 docs/installation/5-saml.md               | 58 +++++++++++++++++++++++
 docs/installation/index.md                |  1 +
 docs/installation/migrating-to-python3.md |  6 +++
 docs/installation/upgrading.md            |  6 +++
 4 files changed, 71 insertions(+)
 create mode 100644 docs/installation/5-saml.md

diff --git a/docs/installation/5-saml.md b/docs/installation/5-saml.md
new file mode 100644
index 000000000..cc960afe4
--- /dev/null
+++ b/docs/installation/5-saml.md
@@ -0,0 +1,58 @@
+This guide explains how to implement SAML authentication using an external SAML2 SSO provider. Local user authentication is still available.
+
+# Requirements
+
+## Install xmlsec1
+
+On Ubuntu:
+
+```no-highlight
+sudo apt-get install -y xmlsec1
+```
+
+On CentOS:
+
+```no-highlight
+sudo yum install -y xmlsec1
+```
+
+## Install django-saml2-auth
+
+```no-highlight
+pip3 install django-saml2-auth
+```
+
+# Configuration
+
+Create a file in the same directory as `configuration.py` (typically `netbox/netbox/`) named `saml_config.py`. Define all of the parameters required below in `saml_config.py`. Complete documentation of all `django-saml2-auth` configuration options is included in the project's [official documentation](https://github.com/fangli/django-saml2-auth).
+
+## General Server Configuration
+
+```python
+
+SAML2_AUTH = {
+    # Metadata is required. Specify either a remote url or local file path
+    'METADATA_AUTO_CONF_URL': '[The auto(dynamic) metadata configuration URL of SAML2]',
+    'METADATA_LOCAL_FILE_PATH': '[The metadata configuration local file path]',
+
+    # Optional settings below
+    'CREATE_USER': 'TRUE', # Create a new Django/NetBox user when a new user logs in. Defaults to True.
+    'NEW_USER_PROFILE': {
+        'USER_GROUPS': [],  # The default group name when a new user logs in
+        'ACTIVE_STATUS': True,  # The default active status for new users
+        'STAFF_STATUS': True,  # The staff status for new users
+        'SUPERUSER_STATUS': False,  # The superuser status for new users
+    },
+    'ATTRIBUTES_MAP': {  # Change Email/UserName/FirstName/LastName to corresponding SAML2 userprofile attributes.
+        'email': 'Email',
+        'username': 'UserName',
+        'first_name': 'FirstName',
+        'last_name': 'LastName',
+    },
+    'ENTITY_ID': 'https://mysite.com/saml2_auth/acs/', # Populates the Issuer element in authn request
+}
+```
+
+# Troubleshooting SAML
+
+`supervisorctl restart netbox` restarts the Netbox service, and initiates any changes made to `saml_config.py`. If there are syntax errors present, the NetBox process will not spawn an instance, and errors should be logged to `/var/log/supervisor/`.
diff --git a/docs/installation/index.md b/docs/installation/index.md
index 54daa62e3..158649987 100644
--- a/docs/installation/index.md
+++ b/docs/installation/index.md
@@ -6,6 +6,7 @@ The following sections detail how to set up a new instance of NetBox:
 2. [NetBox components](2-netbox.md)
 3. [HTTP dameon](3-http-daemon.md)
 4. [LDAP authentication](4-ldap.md) (optional)
+4. [SAML authentication](5-saml.md) (optional)
 
 # Upgrading
 
diff --git a/docs/installation/migrating-to-python3.md b/docs/installation/migrating-to-python3.md
index 1d5ceb977..289bbf9c9 100644
--- a/docs/installation/migrating-to-python3.md
+++ b/docs/installation/migrating-to-python3.md
@@ -37,6 +37,12 @@ If using LDAP authentication, install the `django-auth-ldap` package:
 # pip3 install django-auth-ldap
 ```
 
+If using SAML authentication, install the `django-saml2-auth` package:
+
+```no-highlight
+# pip3 install django-saml2-auth
+```
+
 If using Webhooks, install the `django-rq` package:
 
 ```no-highlight
diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md
index 6dc8a3c7a..01b103ae4 100644
--- a/docs/installation/upgrading.md
+++ b/docs/installation/upgrading.md
@@ -45,6 +45,12 @@ Copy the LDAP configuration if using LDAP:
 # cp netbox-X.Y.Z/netbox/netbox/ldap_config.py netbox/netbox/netbox/ldap_config.py
 ```
 
+Copy the SAML configuration if using SAML:
+
+```no-highlight
+# cp netbox-X.Y.Z/netbox/netbox/saml_config.py netbox/netbox/netbox/saml_config.py
+```
+
 ## Option B: Clone the Git Repository (latest master release)
 
 This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most recent iteration of the master branch: