From bb34cd0200f582501a7adb5f2db6868b9c217095 Mon Sep 17 00:00:00 2001
From: Lars Lehmann <33843261+larsl-net@users.noreply.github.com>
Date: Sun, 25 Jun 2023 18:42:02 +0200
Subject: [PATCH] website/integrations: add Netbox integration (#5683)

* website: add Netbox integration

* website: fix Netbox spelling mistakes

* website: add NetBox groups and roles

* website: NetBox use default property mapping ad base

* website: add NetBox logout url

Signed-off-by: Lars Lehmann <33843261+larsl-net@users.noreply.github.com>

* website: fix NetBox logout url

Signed-off-by: Lars Lehmann <33843261+larsl-net@users.noreply.github.com>

* website: fix NetBox spelling

Signed-off-by: Lars Lehmann <33843261+larsl-net@users.noreply.github.com>

* small formatting fixes

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

---------

Signed-off-by: Lars Lehmann <33843261+larsl-net@users.noreply.github.com>
Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>
---
 .../services/hashicorp-vault/index.md         |   2 +-
 website/integrations/services/netbox/index.md | 223 ++++++++++++++++++
 .../integrations/services/nextcloud/index.md  |   2 +-
 .../integrations/services/node-red/index.md   |   2 +-
 website/sidebarsIntegrations.js               |   1 +
 5 files changed, 227 insertions(+), 3 deletions(-)
 create mode 100644 website/integrations/services/netbox/index.md

diff --git a/website/integrations/services/hashicorp-vault/index.md b/website/integrations/services/hashicorp-vault/index.md
index 1da157f19..e778bbddf 100644
--- a/website/integrations/services/hashicorp-vault/index.md
+++ b/website/integrations/services/hashicorp-vault/index.md
@@ -25,7 +25,7 @@ The following placeholders will be used:
 
 ### Step 1
 
-In authentik, create an _OAuth2/OpenID Provider_ (under _Resources/Providers_) with these settings:
+In authentik, create an _OAuth2/OpenID Provider_ (under _Applications/Providers_) with these settings:
 
 :::note
 Only settings that have been modified from default have been listed.
diff --git a/website/integrations/services/netbox/index.md b/website/integrations/services/netbox/index.md
new file mode 100644
index 000000000..38af02816
--- /dev/null
+++ b/website/integrations/services/netbox/index.md
@@ -0,0 +1,223 @@
+---
+title: NetBox
+---
+
+<span class="badge badge--secondary">Support level: Community</span>
+
+## What is NetBox
+
+From https://github.com/netbox-community/netbox
+
+:::note
+NetBox is the leading solution for modeling and documenting modern networks.
+:::
+
+## Preparation
+
+The following placeholders will be used:
+
+-   `netbox.company` is the FQDN of the NetBox install.
+-   `authentik.company` is the FQDN of the authentik install.
+
+Create an application in authentik and note the slug you choose, as this will be used later. In the Admin Interface, go to _Applications_ -> _Providers_. Create a _OAuth2/OpenID provider_ with the following parameters:
+
+-   Client Type: `Confidential`
+-   Redirect URIs: `https://netbox.company/oauth/complete/oidc/`
+-   Scopes: OpenID, Email and Profile
+-   Signing Key: Select any available key
+
+Note the Client ID and Client Secret values. Create an application, using the provider you've created above.
+
+## NetBox
+
+:::info
+This setup was tested and developed with NetBox Docker. For a non-Docker installation, the Docker part must be disabled and the non-docker part must be used.
+:::
+
+The following Docker env vars are required for the configuration.
+
+```env
+# Enable python-social-auth
+REMOTE_AUTH_ENABLED='true'
+REMOTE_AUTH_BACKEND='social_core.backends.open_id_connect.OpenIdConnectAuth'
+
+# python-social-auth config
+SOCIAL_AUTH_OIDC_ENDPOINT='https://authentik.company/application/o/<Application slug>/'
+SOCIAL_AUTH_OIDC_KEY='<Client ID>'
+SOCIAL_AUTH_OIDC_SECRET='<Client Secret>'
+LOGOUT_REDIRECT_URL='https://authentik.company/application/o/<Application slug>/end-session/'
+```
+
+The Netbox configuration needs to be extended, for this you can create a new file in the configuration folder, for example `authentik.py`.
+
+```py
+from os import environ
+
+#############
+# Docker
+#############
+
+# python-social-auth configuration
+SOCIAL_AUTH_OIDC_ENDPOINT = environ.get('SOCIAL_AUTH_OIDC_ENDPOINT')
+SOCIAL_AUTH_OIDC_KEY = environ.get('SOCIAL_AUTH_OIDC_KEY')
+SOCIAL_AUTH_OIDC_SECRET = environ.get('SOCIAL_AUTH_OIDC_SECRET')
+LOGOUT_REDIRECT_URL = environ.get('LOGOUT_REDIRECT_URL')
+
+
+#############
+# non Docker
+#############
+
+# NetBox settings
+#REMOTE_AUTH_ENABLED = True
+#REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth'
+
+# python-social-auth configuration
+#SOCIAL_AUTH_OIDC_ENDPOINT = 'https://authentik.company/application/o/<Application
+#SOCIAL_AUTH_OIDC_KEY = '<Client ID>'
+#SOCIAL_AUTH_OIDC_SECRET = '<Client Secret>'
+#LOGOUT_REDIRECT_URL = 'https://authentik.company/application/o/<Application slug>/end-session/
+```
+
+### Groups
+
+To manage groups in NetBox custom social auth pipelines are required. To create them you have to create the `custom_pipeline.py` file in the NetBox directory with the following content.
+
+```python
+from django.contrib.auth.models import Group
+
+class AuthFailed(Exception):
+    pass
+
+def add_groups(response, user, backend, *args, **kwargs):
+    try:
+        groups = response['groups']
+    except KeyError:
+        pass
+
+    # Add all groups from oAuth token
+    for group in groups:
+        group, created = Group.objects.get_or_create(name=group)
+        group.user_set.add(user)
+
+def remove_groups(response, user, backend, *args, **kwargs):
+    try:
+        groups = response['groups']
+    except KeyError:
+        # Remove all groups if no groups in oAuth token
+        user.groups.clear()
+        pass
+
+    # Get all groups of user
+    user_groups = [item.name for item in user.groups.all()]
+    # Get groups of user which are not part of oAuth token
+    delete_groups = list(set(user_groups) - set(groups))
+
+    # Delete non oAuth token groups
+    for delete_group in delete_groups:
+        group = Group.objects.get(name=delete_group)
+        group.user_set.remove(user)
+
+
+def set_roles(response, user, backend, *args, **kwargs):
+    # Remove Roles temporary
+    user.is_superuser = False
+    user.is_staff = False
+    try:
+        groups = response['groups']
+    except KeyError:
+        # When no groups are set
+        # save the user without Roles
+        user.save()
+        pass
+
+    # Set roles is role (superuser or staff) is in groups
+    user.is_superuser = True if 'superusers' in groups else False
+    user.is_staff = True if 'staff' in groups else False
+    user.save()
+```
+
+The path of the file in the Official Docker image is: `/opt/netbox/netbox/netbox/custom_pipeline.py`
+
+To enable the pipelines, add the pipelines section to the netbox configuration file from above
+
+```python
+SOCIAL_AUTH_PIPELINE = (
+    ###################
+    # Default pipelines
+    ###################
+
+    # Get the information we can about the user and return it in a simple
+    # format to create the user instance later. In some cases the details are
+    # already part of the auth response from the provider, but sometimes this
+    # could hit a provider API.
+    'social_core.pipeline.social_auth.social_details',
+
+    # Get the social uid from whichever service we're authing thru. The uid is
+    # the unique identifier of the given user in the provider.
+    'social_core.pipeline.social_auth.social_uid',
+
+    # Verifies that the current auth process is valid within the current
+    # project, this is where emails and domains whitelists are applied (if
+    # defined).
+    'social_core.pipeline.social_auth.auth_allowed',
+
+    # Checks if the current social-account is already associated in the site.
+    'social_core.pipeline.social_auth.social_user',
+
+    # Make up a username for this person, appends a random string at the end if
+    # there's any collision.
+    'social_core.pipeline.user.get_username',
+
+    # Send a validation email to the user to verify its email address.
+    # Disabled by default.
+    # 'social_core.pipeline.mail.mail_validation',
+
+    # Associates the current social details with another user account with
+    # a similar email address. Disabled by default.
+    # 'social_core.pipeline.social_auth.associate_by_email',
+
+    # Create a user account if we haven't found one yet.
+    'social_core.pipeline.user.create_user',
+
+    # Create the record that associates the social account with the user.
+    'social_core.pipeline.social_auth.associate_user',
+
+    # Populate the extra_data field in the social record with the values
+    # specified by settings (and the default ones like access_token, etc).
+    'social_core.pipeline.social_auth.load_extra_data',
+
+    # Update the user record with any changed info from the auth service.
+    'social_core.pipeline.user.user_details',
+
+
+    ###################
+    # Custom pipelines
+    ###################
+    # Set authentik Groups
+    'netbox.custom_pipeline.add_groups',
+    'netbox.custom_pipeline.remove_groups',
+    # Set Roles
+    'netbox.custom_pipeline.set_roles'
+)
+
+```
+
+### Roles
+
+In netbox, there are two special user roles `superuser` and `staff`. To set them, add your users to the `superusers` or `staff` group in authentik.
+
+To use custom group names, the following scope mapping example can be used. In the example, the group `netbox_admins` is used for the `superusers` and the group `netbox_staff` for the `staff` users.
+
+Name: `Netbox roles`
+Scope name: `roles`
+
+Expression:
+
+```python
+return {
+  "groups": ["superusers" if group.name == "netbox_admin" else "staff" if group.name == "netbox_staff" else group.name for group in request.user.ak_groups.all()],
+}
+```
+
+This scope mapping must also be selected in the _OAuth2/OpenID Provider_ created above.
diff --git a/website/integrations/services/nextcloud/index.md b/website/integrations/services/nextcloud/index.md
index 302656929..a5674a251 100644
--- a/website/integrations/services/nextcloud/index.md
+++ b/website/integrations/services/nextcloud/index.md
@@ -27,7 +27,7 @@ The following placeholders will be used:
 -   `nextcloud.company` is the FQDN of the Nextcloud install.
 -   `authentik.company` is the FQDN of the authentik install.
 
-Create an application in authentik and note the slug you choose, as this will be used later. In the Admin Interface, go to Applications->Providers. Create a SAML provider with the following parameters:
+Create an application in authentik and note the slug you choose, as this will be used later. In the Admin Interface, go to _Applications_ -> _Providers_. Create a _SAML provider_ with the following parameters:
 
 -   ACS URL: `https://nextcloud.company/apps/user_saml/saml/acs`
 -   Issuer: `https://authentik.company`
diff --git a/website/integrations/services/node-red/index.md b/website/integrations/services/node-red/index.md
index aa6650dbc..7dc02cf96 100644
--- a/website/integrations/services/node-red/index.md
+++ b/website/integrations/services/node-red/index.md
@@ -27,7 +27,7 @@ The following placeholders will be used:
 
 ### Step 1
 
-In authentik, create an _OAuth2/OpenID Provider_ (under _Resources/Providers_) with these settings:
+In authentik, create an _OAuth2/OpenID Provider_ (under _Applications/Providers_) with these settings:
 
 :::note
 Only settings that have been modified from default have been listed.
diff --git a/website/sidebarsIntegrations.js b/website/sidebarsIntegrations.js
index 97036a808..36a691d04 100644
--- a/website/sidebarsIntegrations.js
+++ b/website/sidebarsIntegrations.js
@@ -68,6 +68,7 @@ module.exports = {
                         "services/harbor/index",
                         "services/hashicorp-vault/index",
                         "services/minio/index",
+                        "services/netbox/index",
                         "services/opnsense/index",
                         "services/pfsense/index",
                         "services/pgadmin/index",