netbox-plugin-auth-saml2 2.1

Netbox plugin for SAML2 auth

Netbox Plugin for SSO using SAML2

Netbox 2.8 provides enhancements to support remote user authentication uses specific variables defined in the configuration.py file, as described here:

https://netbox.readthedocs.io/en/stable/configuration/optional-settings/

This repository provides a Netbox plugin that can be used to integrate with a SAML SSO system, such as Okta.

NOTE: This approach uses a reverse-proxy URL rewrite so that the standard Netbox Login will redirect the User to the SSO system. Please refer to the example nginx.conf file.

NOTE: Netbox plugin for SSO, v2.0+, supports Netbox version 2.9, 2.10.

System Requirements

You will need to install the django3-auth-saml2 into your Netbox environment.

Netbox Configuration

In the configuration.py you will need to enable and configure these REMOTE_AUTH_xxx options at a minimum:

REMOTE_AUTH_ENABLED = True
REMOTE_AUTH_BACKEND = 'utilities.auth_backends.RemoteUserBackend'
REMOTE_AUTH_AUTO_CREATE_USER = True

You can also create the other options REMOTE_AUTH_DEFAULT_GROUPS and REMOTE_AUTH_DEFAULT_PERMISSIONS as described in the online docs.

Next you will need to configure this plugin, provding your specific configuraiton values as described in django3-okta-saml2 repo, for example:

PLUGINS = ['django3_saml2_nbplugin']

PLUGINS_CONFIG = {
    'django3_saml2_nbplugin': {

        # Use the Netbox default remote backend
        'AUTHENTICATION_BACKEND': REMOTE_AUTH_BACKEND,

        # Custom URL to validate incoming SAML requests against
        'ASSERTION_URL': 'https://netbox.company.com',

        # Populates the Issuer element in authn reques e.g defined as "Audience URI (SP Entity ID)" in SSO
        'ENTITY_ID': 'https://netbox.conpany.com/',

        # Metadata is required, choose either remote url or local file path
        'METADATA_AUTO_CONF_URL': "https://mycorp.okta.com/app/sadjfalkdsflkads/sso/saml/metadata"
    }
}

New Plugin URLs

This plugin will provide two new URLs to Netbox:

/plugins/sso/login/
This URLs redirects the User login to the SSO system (Okta) for authentication. This is the URL that needs to be used in the reverse-proxy redirect, for examlple see nginx.conf.

/sso/acs/
This URLs should be configured into your SSO system as the route to use to single-sign-on/redirection URL the User into Netbox after the User has authenticated with the SSO system.

Customizing on Create New User Configuration

If you want to customize the way a User is created, beyond what is provided by the Netbox REMOTE_AUTH variables, you can create a custom RemoteBackend class. See the samples in backends.py.

Using A Reverse Proxy Redirect

The use of this plugin requires a reverse-proxy URL redirect to override the default Netbox /login/ URL. There are two notes in this process:

1. You MAY need to disable port in redirect depending on your Netbox installation. If your Netbox server URL does not include a port, then you must disable port redirect. For example see nginx.conf.
2. You MUST add the ULR rewrite for the /login/ URL to use /plugins/sso/login/, for example nginx.conf.