netbox-plugin-azuread - Forked

This repo is a forked repo of Marcus's great work with netbox-plugin-azuread

I have taken the fix from from cpajr and applied it to this repo.

This was because many of our Azure AD users have 100+ groups assigned. The fix has been tested and working.

What is 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 with Kubernetes

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

How to get his plugin working with Kubernetes - High Level Overview:

• Build this repository with the setup.py creating a .whl file in a repository
• Build the container with the below docker file picking up the module from the repository
• Include the following plugins config in your netbox plugin helmchart

Here's the simplest possible Dockerfile you could write:

FROM netboxcommunity/netbox:v3.2.8

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

# Example url with -i 
RUN /opt/netbox/venv/bin/pip install -i http://user:[email protected]/artifactory/api/pypi/py-it/simple netbox_plugin_azuread==1.2.3 --trusted-host localrepository.domain

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
    },
    'AD_GROUP_FILTER': [ # Only import those groups listsm otherwise if empty, import all Azure groups
        'abc123',
        'blahblah',
        'blahadmin'
    ]
  }
}
REMOTE_AUTH_AUTO_CREATE_USER = True
REMOTE_AUTH_BACKEND = 'netbox_plugin_azuread.backends.AzureADRemoteUserBackend'
REMOTE_AUTH_ENABLED = True

Here is a basic breakdown of each one:

Name	Example	Notes	Required
CLIENT_ID	abc123	The client id for your Azure AD service principle	Yes
CLIENT_SECRET	abc123	The client secret for your Azure AD service principle	Yes
AUTHORITY	https://login.microsoftonline.com/abc123	The authority for your Azure AD service principle	Yes
LOGIN_URL	/plugins/azuread/login/	The login URL to display the custom login page under	No
REPLY_URL	/plugins/azuread/complete/	The reply URL to receive Azure AD OAuth callbacks on	No
SCOPES	['https://graph.microsoft.com/.default']	The scopes to use. The default Graph scope should be fine as it passes through all pre-configured permissions	No
AD_GROUP_MAP	{'SUPERUSER: ['abc123']}	A dictionary where keys are privileges and values are lists of groups to inherit those privileges	No
AD_GROUP_FILTER	['abc123']	A list of groups to be explicitly included so you don't import hundreds of irrelevant AD groups. Leaving it blank will import all groups.	No

As depicted above, only CLIENT_ID, CLIENT_SECRET and AUTHORITY are explicitly required. LOGIN_URL, REPLY_URL and SCOPES will default to the above URLs. You'll probably want to make use of the AD_GROUP_MAP and AD_GROUP_FILTER but they are also optional.

Setting up group claims

Getting groups flowing through can trip up some users so it's important that the Azure Service Principal you're using has the correct permissions.

At present, the bare minimum configuration is a service principal with the Directory.Read.All permission of type Application.

Either yourself or someone authorised to view Azure Active Directory should be able to verify this under Enterprise Applications -> your sp -> API Permissions tab. It should look like the following:

You can also read a bit more about this in 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