NBE SAML SSO

docs/netbox-enterprise/nbe-saml-group-map.md

@@ -0,0 +1,49 @@
+# Configuring SAML Group Mapping in NetBox Enterprise 
+
+Setting up Group Mapping for SAML requires the [base SAML SSO Setup](./nbe-saml.md) to be configured and working first.
+
+## Configure the IdP 
+
+NetBox Enterprise expects a SAML group attribute statement to be named `groups`, which contains a list of group names the user belongs to. If your IdP sends group information under a different attribute name, such as `MemberOf`, you must update its configuration to use `groups` to ensure proper mapping.
+
+Example:
+
+![SAML Settings](../images/netbox-enterprise/SAML/netbox-enterprise-saml-idp-groups.png)
+
+## Configuring Group Mappings  
+
+1. Desired groups must first be configured within NetBox
+2. In the Admin Console for NetBox Enterprise, navigate to the **Config** tab and scroll to the bottom to check **Advanced Settings**
+3. Apply the following into **NetBox Python Configuration Overrides**, replacing the relevant information.
+
+``` python
+SOCIAL_AUTH_PIPELINE = (
+'social_core.pipeline.social_auth.social_details',
+'social_core.pipeline.social_auth.social_uid',
+'social_core.pipeline.social_auth.social_user',
+'social_core.pipeline.user.get_username',
+'social_core.pipeline.social_auth.associate_by_email',
+'social_core.pipeline.user.create_user',
+'social_core.pipeline.social_auth.associate_user',
+'netbox.authentication.user_default_groups_handler',
+'social_core.pipeline.social_auth.load_extra_data',
+'social_core.pipeline.user.user_details',
+'nbc_auth_extensions.saml_authentication.saml_map_groups',
+)
+
+SOCIAL_AUTH_PIPELINE_CONFIG = {
+    'SAML_USER_FLAGS_BY_GROUP': {
+        "is_staff": {
+            "idp-staff-group-name" # remove this line if no group should be granted 'Staff'
+        },
+        "is_superuser": {
+            "idp-superuser-group-name" # remove this line if no group should be granted 'Superuser'
+        }
+    },
+    'SAML_GROUP_MAP': {
+        "idp-group-name-1": "netbox-group-name-1",
+        "idp-group-name-2": "netbox-group-name-2"
+    }
+}
+```
+

docs/netbox-enterprise/nbe-saml.md

@@ -0,0 +1,90 @@
+# NetBox Enterprise SAML Configuration Guide
+
+## Required Information
+
+- **Entity ID**: This is your IdP's Entity ID obtained from the SAML metadata
+- **SSO URL**: Your IdP's SSO login URL
+- **x509 Certificate**: The Base64-encoded X.509 certificate used to sign SAML assertions
+- **NetBox Enterprise URL**: URL For the NetBox Enterprise instance
+
+## Generate Public and Private Keys
+These will be used later during configuration and can be generated from anywhere. Be sure to keep the private key secure.
+
+``` shell
+openssl genpkey -algorithm RSA -out saml_private_key.pem -pkeyopt rsa_keygen_bits:2048
+
+openssl req -new -x509 -key saml_private_key.pem -out saml_cert.pem -days <specify number of days valid>
+```
+
+## Configure the IdP
+Set up the IdP using the public key from the previous section, and the ACS URL (based on the NetBox Enterprise URL). These steps will vary depending on the IdP in use.
+
+**ACS URL**: "{NetBox Enterprise URL}/oauth/complete/saml/"
+**SP Entity ID**: "{NetBox Enterprise URL}"
+
+Example:
+
+![SAML Settings](../images/netbox-enterprise/SAML/netbox-enterprise-saml-idp.png)
+
+### Configure Attributes or Claims
+Setup similar mappings in the IdP's "Attributes" or "Claims" section. Names may vary on different platforms.
+
+``` shell
+"attr_first_name": "first_name"
+"attr_last_name": "last_name"
+"attr_username": "email"
+"attr_email": "email"
+```
+
+Example:
+
+![Attribute Settings](../images/netbox-enterprise/SAML/netbox-enterprise-saml-attributes.png)
+
+### Capture x509 Certificate
+After setting up the IdP, generate a certificate in the IdP (this may be done by default). The x509 certificate can either be downloaded or viewed in the SAML metadata URL. This certificate data will be used in the next step.
+
+## Update NetBox Enterprise Config
+1. In the Admin Console for NetBox Enterprise, navigate to the **Config** tab and scroll to the bottom to check **Advanced Settings**
+2. Apply the following into **NetBox Python Configuration Overrides**, replacing the relevant information from previous steps.
+
+``` shell
+REMOTE_AUTH_ENABLED = True
+REMOTE_AUTH_AUTO_CREATE_USER = True
+REMOTE_AUTH_BACKEND = 'social_core.backends.saml.SAMLAuth'
+SOCIAL_AUTH_REDIRECT_IS_HTTPS = True
+
+SOCIAL_AUTH_SAML_SP_ENTITY_ID = "<NetBox Enterprise Instance URL>"
+SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = "-----BEGIN CERTIFICATE-----<Public Key goes here>-----END CERTIFICATE-----"
+SOCIAL_AUTH_SAML_SP_PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----<Private Key goes here>-----END PRIVATE KEY-----"
+
+SOCIAL_AUTH_SAML_ORG_INFO = {
+    "en-US": {
+        "name": "<Org Name>",
+        "displayname": "<Org Display Name>",
+        "url": "<Org Website>",
+    }
+}
+
+SOCIAL_AUTH_SAML_TECHNICAL_CONTACT = {
+    "givenName": "support",
+    "emailAddress": "[<Support Email Address>](mailto:<Support Email Address>)"
+}
+
+SOCIAL_AUTH_SAML_SUPPORT_CONTACT = {
+    "givenName": "support",
+    "emailAddress": "[<Support Email Address>](mailto:<Support Email Address>)"
+}
+
+SOCIAL_AUTH_SAML_ENABLED_IDPS = {
+    "idp": {
+        "entity_id": "<SAML Entity ID>",
+        "url": "<SAML Sign-on URL>",
+        "x509cert": "<x509 Certificate>",
+        "attr_user_permanent_id": "email",
+        "attr_first_name": "first_name",
+        "attr_last_name": "last_name",
+        "attr_username": "email",
+        "attr_email": "email",
+    }
+}
+```

mkdocs.yml

@@ -113,6 +113,9 @@ nav:
       - Entra ID:
         - Microsoft Entra ID SSO: "netbox-enterprise/nbe-azure-sso.md"
         - Entra ID Group Mapping: "netbox-enterprise/nbe-azure-group-mapping.md"
+      - SAML: 
+        - SAML SSO Setup: "netbox-enterprise/nbe-saml.md"
+        - SAML Group Mapping: "netbox-enterprise/nbe-saml-group-map.md"
       - LDAP: "netbox-enterprise/nbe-ldap.md"
     - "Administration":
       - "TLS and Ingress": "netbox-enterprise/nbe-tls-ingress.md"