---
title: NetBox
---

<span class="badge badge--secondary">Support level: Community</span>

## What is NetBox

> NetBox is the leading solution for modeling and documenting modern networks.
>
> -- https://github.com/netbox-community/netbox

## 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>'
SOCIAL_AUTH_OIDC_SCOPE = ["openid", "profile", "email", "roles"]
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')
SOCIAL_AUTH_OIDC_SCOPE = ["openid", "profile", "email", "roles"]
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.

:::info
From Netbox version 4.0.0 Netbox add the custom `Group` models. The following code is compatible with Netbox 4.0.0 and above. For Netbox versions below 4.0.0, the import statement and group adding / deleting of user lines must be changed.
:::

```python
# from django.contrib.auth.models import Group # For Netbox < 4.0.0
from netbox.authentication import Group # For Netbox >= 4.0.0

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) # For Netbox < 4.0.0
        user.groups.add(group) # For Netbox >= 4.0.0

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) # For Netbox < 4.0.0
        user.groups.remove(group) # For Netbox >= 4.0.0


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.