Package: netbox-plugin-azuread
netbox-plugin-azureadA plugin for theIPAMtoolNetboxto support OAuth2 authentication viaAzure Active Directory.netbox-plugin-azureadis effectively a light wrapper around Microsoft's ownmsallibrary with the added ability to map AzureAD groups to Django permissions.InstallationBefore installing any plugins, it's worth familiarising yourself with theNetbox 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 metalIf you're using a non-containerised deployment of Netbox, you'll want to first activate the virtual environment asreferenced in the Netbox setup process.cd/opt/netboxsourcevenv/bin/activateOnce activated, you'll be able to use pip installnetbox-plugin-azureadby way of its hostedPyPIdistribution. We'll also be installingmsalas a dependency. Once done, you'll need to restart Netbox to see your changes.pipinstallmsalnetbox_plugin_azuread
systemctlrestartnetboxIf you prefer to install this package manually, both a.tar.gzand.whldistribution are available under under thereleasessection of this Github repository.Once installed, don't forget to add these changes to yourrequirements.txtor better yet, store them in their own distinct requirements file from the Netbox base requirements.ContainerisationIf you're looking to use this plugin in conjunction with your own dockerised version of Netbox, or one of the availablenetbox-dockerimages, 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:FROMnetboxcommunity/netbox:v2.11.12RUN/opt/netbox/venv/bin/pipinstallnetbox_plugin_azureadmsalAs above,msalis a dependency of this plugin so we need to install it as well. Despite this container being extremely small, the rest of thenetbox-dockerbuild scripts will implicitly execute as we haven't overridden the entrypoint or any other commands.UsageIn order to use this plugin, you'll need to add it to thePLUGINS_CONFIGportion of yourNetbox 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=TrueREMOTE_AUTH_BACKEND='netbox_plugin_azuread.backends.AzureADRemoteUserBackend'REMOTE_AUTH_ENABLED=TrueHere is a basic breakdown of each one:NameExampleNotesRequiredCLIENT_IDabc123Theclient idfor your Azure AD service principleYesCLIENT_SECRETabc123Theclient secretfor your Azure AD service principleYesAUTHORITYhttps://login.microsoftonline.com/abc123Theauthorityfor your Azure AD service principleYesLOGIN_URL/plugins/azuread/login/Thelogin URLto display the custom login page underNoREPLY_URL/plugins/azuread/complete/Thereply URLto receive Azure AD OAuth callbacks onNoSCOPES['https://graph.microsoft.com/.default']The scopes to use.The default Graph scopeshould be fine as it passes through all pre-configured permissionsNoAD_GROUP_MAP{'SUPERUSER: ['abc123']}A dictionary where keys are privileges and values are lists of groups to inherit those privilegesNoAD_GROUP_FILTER['abc123']A list of groups to beexplicitlyincluded so you don't import hundreds of irrelevant AD groups. Leaving it blank will import all groups.NoAs depicted above, onlyCLIENT_ID,CLIENT_SECRETandAUTHORITYare explicitly required.LOGIN_URL,REPLY_URLandSCOPESwill default to the above URLs. You'll probably want to make use of theAD_GROUP_MAPandAD_GROUP_FILTERbut they are also optional.Setting up group claimsGetting 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 theDirectory.Read.Allpermission of typeApplication.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 inissue #3.Redirecting the login pageOut of the box, you'll notice thathttp://netbox.blah/loginstill 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/azureadand 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 annginxinstance to write/login/to point to/plugins/azuread/login/instead.Here's an example of how your configuration could look:worker_processes1;pid/tmp/nginx.pid;error_log/dev/stderrinfo;events{worker_connections1024;}http{include/etc/nginx/mime.types;default_typeapplication/octet-stream;server_tokensoff;client_max_body_size25m;access_log/dev/stdout;server{listen8000;server_name_;access_logoff;location/{proxy_passhttp://localhost:8080/;}location/login/{proxy_passhttp://localhost:8080/plugins/azuread/login/;}location/complete/{proxy_passhttp://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-dockerhas since updated to use nginx unit under the hood so this is no longer relevant to my knowledge.QuestionsWhile 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