netbox-plugin-azuread

A plugin for the IPAM tool Netbox to support OAuth2 authentication via Azure Active Directory.

netbox-plugin-azuread is effectively a light wrapper around Microsoft's own msal library with the added ability to map AzureAD groups to Django permissions.

Installation

Before installing any plugins, it's worth familiarising yourself with the Netbox documentation.

Regardless of environment, it's always a good idea to pin your dependencies. I haven't done it explicitly in this README but I recommend doing it for your own deployments eg; pip install msal==1.2.3 netbox_plugin_azuread==1.0.0.

Bare metal

If you're using a non-containerised deployment of Netbox, you'll want to first activate the virtual environment as referenced in the Netbox setup process.

cd /opt/netbox
source venv/bin/activate

Once activated, you'll be able to use pip install netbox-plugin-azuread by way of its hosted PyPI distribution. We'll also be installing msal as a dependency. Once done, you'll need to restart Netbox to see your changes.

pip install msal netbox_plugin_azuread
systemctl restart netbox

If you prefer to install this package manually, both a .tar.gz and .whl distribution are available under under the releases section of this Github repository.

Once installed, don't forget to add these changes to your requirements.txt or better yet, store them in their own distinct requirements file from the Netbox base requirements.

Containerisation

If you're looking to use this plugin in conjunction with your own dockerised version of Netbox, or one of the available netbox-docker images, it's a little bit more involved.

At work, we run this plugin within a build of Netbox deployed via Kubernetes but the steps are the same for any Docker deployment.

Here's the simplest possible Dockerfile you could write:

FROM netboxcommunity/netbox:v2.11.12

RUN /opt/netbox/venv/bin/pip install netbox_plugin_azuread msal

As above, msal is a dependency of this plugin so we need to install it as well. Despite this container being extremely small, the rest of the netbox-docker build scripts will implicitly execute as we haven't overridden the entrypoint or any other commands.

Usage

In order to use this plugin, you'll need to add it to the PLUGINS_CONFIG portion of your Netbox configuration.

Here's a sample of all of the possible settings you can configure:

PLUGINS = [
  'netbox_plugin_azuread'  # Note that we use underscores for the plugin internally but the name has dashes
]
PLUGINS_CONFIG = {
  'netbox_plugin_azuread': {
    'CLIENT_ID': '<YOUR-CLIENT-ID-HERE>',  # Available for viewing in the Azure Portal under Azure Active Directory
    'CLIENT_SECRET': '<YOUR-CLIENT-SECRET-HERE>',
    'AUTHORITY': '<YOUR-CLIENT-AUTHORITY-HERE>',
    'LOGIN_URL': '<LOGIN-URL>',  # Should be /plugins/azuread/login/ unless you remap it using eg; nginx
    'REPLY_URL': '<REPLY_URL>',  # Should be /plugins/azuread/complete/ unless you remap it using eg; nginx
    'SCOPES': ['https://graph.microsoft.com/.default'],
    'AD_GROUP_MAP': {
      'STAFF': ['abc123', 'blahblah'],
      'SUPERUSER': ['blahadmin']  # Set one or more Azure AD groups and users with this group will receive the superuser or staff flag
    }
  }
}
REMOTE_AUTH_AUTO_CREATE_USER = True
REMOTE_AUTH_BACKEND = 'netbox_plugin_azuread.backends.AzureADRemoteUserBackend'
REMOTE_AUTH_ENABLED = True

Realistically, they're all required except for the AD_GROUP_MAP which is totally optional.

Setting up group claims

This section is intended to be fleshed out in future but for now, if you're having trouble with configuring group claims, check out Issue #3.

Redirecting the login page

Out of the box, you'll notice that http://netbox.blah/login still shows the usual login page. Due to the nature of this being a plugin and not a core part of Netbox, it lives under /plugins/azuread and can't overwrite Netbox URLs.

One possible solution is to request that Netbox allows updating which route is considered the login page via configuration but in lieu of that, we can work around this. To be clear, you can always just ask users to manually visit /plugins/azuread/login/ each time but that's a pain to remember.

In my own case, I use an nginx instance to write /login/ to point to /plugins/azuread/login/ instead.

Here's an example of how your configuration could look:

worker_processes 1;
pid /tmp/nginx.pid;

error_log /dev/stderr info;

events {
    worker_connections 1024;
}

http {
    include              /etc/nginx/mime.types;
    default_type         application/octet-stream;
    server_tokens        off;
    client_max_body_size 25m;
    access_log           /dev/stdout;

    server {
        listen      8000;
        server_name _;
        access_log  off;

        location / {
            proxy_pass http://localhost:8080/;
        }

        location /login/ {
            proxy_pass http://localhost:8080/plugins/azuread/login/;
        }

        location /complete/ {
            proxy_pass http://localhost:8080/plugins/azuread/complete/;
        }
    }
}

This may seem a bit overkill just for one plugin but originally, nginx was required regardless to serve static assets. In our case, netbox-docker has since updated to use nginx unit under the hood so this is no longer relevant to my knowledge.

Questions

While this project is open sourced with no guarantees, feel free to open an issue and I'll attempt to provide support as I can.

Screenshots