netbox-plugin-auth-saml2 3.0

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 2.8, 2.9, 2.10, 2.11, 3.0.

*NOTE: Netbox plugin for SSO, v3.0+, supports Netbox 4.0.

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'
# For v2.8+:
# REMOTE_AUTH_BACKEND = 'netbox.authentication.RemoteUserBackend'
# For backends included with this plugin:
# REMOTE_AUTH_BACKEND = 'django3_saml2_nbplugin.backends.<Backend>'
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
        'METADATA_AUTO_CONF_URL': "https://mycorp.okta.com/app/sadjfalkdsflkads/sso/saml/metadata",
        # or local file path
        'METADATA_LOCAL_FILE_PATH': '/opt/netbox/saml2.xml',

        # Settings for SAML2CustomAttrUserBackend. Optional.
        'CUSTOM_ATTR_BACKEND': {
            # See the note below about SAML attributes

            # Attribute containing the username. Optional.
            'USERNAME_ATTR': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
            # Attribute containing the user's email. Optional.
            'MAIL_ATTR': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
            # Attribute containing the user's first name. Optional.
            'FIRST_NAME_ATTR': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname',
            # Attribute containing the user's last name. Optional.
            'LAST_NAME_ATTR': 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname',
            # Set to True to always update the user on logon
            # from SAML attributes on logon. Defaults to False.
            'ALWAYS_UPDATE_USER': False,
            # Attribute that contains groups. Optional.
            'GROUP_ATTR': 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups',
            # Dict of user flags to groups.
            # If the user is in the group then the flag will be set to True. Optional.
            'FLAGS_BY_GROUP': {
                'is_staff': 'saml-group1',
                'is_superuser': 'saml-group2'
            },
            # Dict of SAML groups to NetBox groups. Optional.
            # Groups must be created beforehand in NetBox.
            'GROUP_MAPPINGS': {
                'saml-group3': 'netbox-group'
            }
        }
    }
}

Please note that METADATA_AUTO_CONF_URL and METADATA_LOCAL_FILE_PATH are mutually exclusive. Don't use both settings at the same time.

Attributes

Newer versions of pysaml2 uses an attribute map. For example, instead of http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress in the configuration above, emailAddress should be used instead.

See here for details.

New Plugin URLs

This plugin will provide two new URLs to Netbox:

/api/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.

/api/plugins/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.

Adding a SSO Login Button

Instead of using a reverse proxy redirect, you can add a SSO login button above the NetBox login form. This has the added benefit of allowing both local and SAML login options.

Add the following to your configuration.py:

BANNER_LOGIN = '<a href="/api/plugins/sso/login" class="btn btn-primary btn-block">Login with SSO</a>'