SAML Group Mapping

Group mapping lets you manage NetBox Enterprise permissions centrally in your identity provider instead of assigning them user by user. When you update group membership in the IdP, those changes sync to NetBox the next time the user logs in, so access stays consistent as employees join, change roles, or leave.

If you already use SAML for your NetBox Enterprise deployment, you can set up group mapping by creating groups and permissions in NetBox, then configuring your IdP to send group membership in the SAML assertion.

Prerequisites

Before you begin, set up SAML SSO for your NetBox Enterprise deployment.

You must have:

• NetBox Enterprise v1.10 or later
• Admin console access in NetBox Enterprise
• Permission to edit the SAML application in your identity provider
• NetBox groups created with the permissions you want to assign

Group mapping does not create NetBox groups. Every group named in your configuration must already exist in NetBox. See Create NetBox groups and assign permissions.

Identity provider configuration

SAML group mapping matches on group names. Your IdP sends those names as the values of a groups attribute in the assertion, and NetBox maps each name to a NetBox group. Names are case-sensitive and must match your configuration exactly.

Add a groups attribute to your SAML application. NetBox expects this exact attribute name.

Okta

1. Navigate to Applications and Resources > [App] > SAML Settings.
2. Under Group Attribute Statements, add a statement:
   • Name: groups
   • Name format: Unspecified
   • Filter: Matches regex: .* to send every group the user belongs to, or something narrower such as Contains: NetBox to send only the groups relevant to NetBox

Microsoft Entra ID

1. Navigate to Enterprise apps > [App] > Single sign-on > Attributes & Claims.
2. Add a group claim and set its name to groups.
3. Set the source attribute so the claim emits group names rather than object IDs. Which options are available depends on whether your groups are cloud-only or synced from on-premises Active Directory. See Configure group claims for applications by using Microsoft Entra ID.

OneLogin

1. Navigate to Applications > [App] > Parameters.
2. Add a parameter named groups.
3. Check Include in SAML assertion.
4. Set the value to User Roles.

Auth0

1. Navigate to Applications > [App] > Addons > SAML2 Web App > Settings.

2. Add groups to the mappings:

   {
     "mappings": {
       "email": "email",
       "given_name": "first_name",
       "family_name": "last_name",
       "groups": "groups"
     }
   }

   Each key is a property on the Auth0 user profile and each value is the attribute name Auth0 emits in the assertion, so the values are what NetBox matches against your attr_* settings.

3. If your users' group membership does not already appear on their Auth0 profile, add a post-login Action to put it there. The mapping above only renames an existing top-level groups property, which AD/LDAP and enterprise connections provide but RBAC roles, Organizations, and database or social connections do not:

   exports.onExecutePostLogin = async (event, api) => {
     api.samlResponse.setAttribute('groups', event.authorization?.roles ?? []);
   };

Verify the assertion

Before configuring NetBox, confirm your IdP is actually sending the attribute. Capture a test login with a SAML tracer browser extension and look for a groups attribute in the response:

<saml:Attribute Name="groups">
  <saml:AttributeValue>Network Administrators</saml:AttributeValue>
  <saml:AttributeValue>Network Engineers</saml:AttributeValue>
</saml:Attribute>

Note the exact spelling of each value. These are the strings you will use as keys in your NetBox configuration.

NetBox Enterprise configuration

Add Python configuration overrides

Open your admin console at https://<your-cluster-host-or-ip>:30000/ and select the Config tab.

Enable Show Advanced Settings and locate the NetBox Python Configuration Overrides section.

Add the following configuration, which includes both the base SAML settings from SAML Single Sign-On and the group mapping additions:

REMOTE_AUTH_BACKEND = 'social_core.backends.saml.SAMLAuth'

# Force HTTPS for SSO redirects; set False only for localhost testing
SOCIAL_AUTH_REDIRECT_IS_HTTPS = True

# Service provider (NetBox) identity
SOCIAL_AUTH_SAML_SP_ENTITY_ID = 'https://<your-netbox-domain>'
SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = """-----BEGIN CERTIFICATE-----
<contents of saml_cert.pem>
-----END CERTIFICATE-----"""
SOCIAL_AUTH_SAML_SP_PRIVATE_KEY = """-----BEGIN PRIVATE KEY-----
<contents of saml_private_key.pem>
-----END PRIVATE KEY-----"""

# Published in NetBox's SAML metadata
SOCIAL_AUTH_SAML_ORG_INFO = {
    'en-US': {
        'name': '<organization-name>',
        'displayname': '<organization-display-name>',
        'url': '<organization-website>',
    }
}
SOCIAL_AUTH_SAML_TECHNICAL_CONTACT = {
    'givenName': 'Technical Support',
    'emailAddress': '<technical-contact-email>',
}
SOCIAL_AUTH_SAML_SUPPORT_CONTACT = {
    'givenName': 'Support Team',
    'emailAddress': '<support-contact-email>',
}

# Identity provider
SOCIAL_AUTH_SAML_ENABLED_IDPS = {
    'default': {
        'entity_id': '<idp-entity-id>',
        'url': '<idp-sso-url>',
        'x509cert': '<idp-certificate>',
        'attr_user_permanent_id': 'email',
        'attr_username': 'email',
        'attr_email': 'email',
        'attr_first_name': 'first_name',
        'attr_last_name': 'last_name',
    }
}

# Authentication pipeline with group mapping
SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.user.get_username',
    'social_core.pipeline.social_auth.associate_by_email',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'netbox.authentication.user_default_groups_handler',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
    'nbc_auth_extensions.saml_authentication.saml_map_groups',
)

# Group mapping configuration
SOCIAL_AUTH_PIPELINE_CONFIG = {
    'SAML_USER_FLAGS_BY_GROUP': {
        'is_staff': ['<idp-group-name-for-staff>'],
        'is_superuser': ['<idp-group-name-for-superusers>'],
    },
    'SAML_GROUP_MAP': {
        '<idp-group-name-1>': '<netbox-group-name-1>',
        '<idp-group-name-2>': '<netbox-group-name-2>',
    }
}

Deploy your configuration

1. Scroll to the bottom of the Config page
2. Click Save config
3. Click Go to updated version when prompted
4. Click Deploy to apply changes
5. Wait for NetBox Enterprise to reach Ready state

Configuration changes require restarting the application. Existing user sessions remain active during deployment.

Configuration parameters

Staff and Superuser groups

Optionally, you can grant members of specific IdP groups the NetBox built-in Staff or Superuser designations:

• Staff: Allows access to the NetBox admin interface.
• Superuser: Has all permissions without explicitly assigning them.

Configuration example

A practical example for a typical deployment:

SOCIAL_AUTH_PIPELINE_CONFIG = {
    'SAML_USER_FLAGS_BY_GROUP': {
        'is_staff': ['NetBox Admins', 'NetBox Superusers'],
        'is_superuser': ['NetBox Superusers'],
    },
    'SAML_GROUP_MAP': {
        'NetBox Admins': 'Network Admins',
        'NetBox Engineers': 'Network Engineers',
        'NetBox Viewers': 'Read Only Users',
    }
}

In this example:

• Members of the "NetBox Admins" or "NetBox Superusers" IdP groups can access the admin interface
• Members of the "NetBox Superusers" IdP group become NetBox superusers
• Three IdP groups are mapped to corresponding NetBox groups

Keys are IdP group names and values are NetBox group names. The two do not have to match, but each value must match an existing NetBox group exactly.

How group mapping works

When a user authenticates via SAML, NetBox reads the groups attribute from the assertion and maps the names it contains to NetBox groups based on your configuration.

On each login:

1. The user authenticates with the IdP.
2. The IdP returns a signed assertion containing a groups attribute.
3. NetBox validates the assertion.
4. NetBox removes all existing group memberships for the user.
5. NetBox maps IdP group names to NetBox groups based on your configuration.
6. User flags for Staff and Superuser groups are updated based on current groups.
7. The user receives permissions from their assigned groups.

Note the following:

• Adding a user to a mapped IdP group grants access the next time they log in.

• Removing a user from a mapped IdP group revokes their NetBox access the next time they log in. However, existing sessions aren't immediately affected, so users may retain access until their session expires. Consider forcing re-authentication for terminated employees.

• IdP groups that don't appear in SAML_GROUP_MAP are ignored. Users are not added to NetBox groups for them.

• A user in several mapped groups is added to all of the corresponding NetBox groups, and their permissions are the union of those groups. User flags take the highest privilege level, so membership in any is_superuser group makes the user a superuser.

• NetBox only sees the names present in the assertion, so whether nested groups are included is determined entirely by your IdP's claim configuration.

Create NetBox groups and assign permissions

Before group mapping can function, you must create NetBox groups and assign appropriate permissions.

1. Create object-based permissions in NetBox (Admin > Authentication > Permissions).
2. Ensure those permissions are mapped to a group (Admin > Authentication > Groups).

Each group name must match the corresponding value in SAML_GROUP_MAP exactly, including capitalization and spacing.

Test group mapping

After configuring group mapping, verify that it works end-to-end using a test user who belongs to one or more mapped IdP groups:

1. Log in to NetBox via SAML as the test user.
2. In Admin > Authentication > Users, open the test user and confirm Staff status and Superuser status match their SAML_USER_FLAGS_BY_GROUP mapping, and that Groups matches their SAML_GROUP_MAP mapping.
3. Confirm permissions behave as expected (for example, read-only users can view but not edit, admins can reach the admin interface).
4. To confirm updates sync correctly, add the user to a new mapped IdP group, log out and back in, and verify the corresponding NetBox group now appears.

Troubleshooting

Groups not syncing

Symptoms:

• User logs in successfully via SAML
• NetBox groups do not match IdP groups
• User has no group memberships after login

Resolution:

1. Confirm the assertion contains groups. Capture a test login with a SAML tracer and verify a groups attribute is present with the expected values.

2. Check the pipeline configuration:

   • Verify 'nbc_auth_extensions.saml_authentication.saml_map_groups' is included in SOCIAL_AUTH_PIPELINE
   • Verify it is the last step in the pipeline

3. Check NetBox logs for errors:

   kubectl logs <netbox-pod> -n kotsadm | grep -i "saml.*group"

Groups attribute missing or misnamed

Symptoms:

• Group claims are configured in the IdP but nothing syncs
• The assertion contains group values under a different attribute name, such as MemberOf, memberOf, roles, or group

Resolution:

NetBox reads group membership from an attribute named exactly groups. Reconfigure your IdP to use that name.

NetBox groups not found

Symptoms:

• NetBox logs show "group not found locally"
• User logs in successfully but is not added to any groups
• Some groups work but others do not

Resolution:

1. Verify NetBox groups exist:

   • Navigate to Admin > Authentication > Groups in NetBox
   • Verify each group referenced as a value in SAML_GROUP_MAP exists

2. Check for name mismatches. Group names are case-sensitive and whitespace matters, on both sides of the mapping:

   'SAML_GROUP_MAP': {
       'network admins': 'Network_Admins',  # will not match
       'Network Admins': 'Network Admins',  # exact match
   }

   Check the logs for the group names your IdP actually sent and update the keys to match.

3. Create missing groups. For each group referenced in the configuration, create a corresponding NetBox group and assign it permissions.

Permissions not applied

Symptoms:

• User is added to NetBox groups successfully
• User does not have expected permissions
• "You do not have permission to access this page" errors

Resolution:

1. Verify group permissions:

   • Navigate to Admin > Authentication > Groups
   • Click each group name and verify permissions are assigned to it
   • Empty groups grant no permissions

2. Check user flags:

   • Navigate to Admin > Authentication > Users and locate the user
   • Verify Active is checked (required for all access)
   • Verify Staff status is checked if the user needs admin access

3. Review permission requirements. Different NetBox features require different permissions, and some actions require more than one (for example, both view and change).

Configuration not taking effect

Symptoms:

• Configuration updated but behavior unchanged
• Old group mappings still in effect

Resolution:

1. Verify the configuration was deployed. Confirm you clicked Save config and Deploy, and that NetBox Enterprise reached Ready state afterward.

2. Check for Python syntax errors. A syntax error in the overrides can prevent the whole configuration from loading.

3. Force a re-login. Group mappings are applied at login time, so log out of NetBox completely, clear cookies for the NetBox domain, and log in again.

Security considerations

Superuser assignment

Exercise extreme caution with is_superuser groups. Superusers have unrestricted access to NetBox and can modify any data, including configuration, and elevate other users. Limit is_superuser to a single small, well-controlled IdP group and audit its membership regularly.

Group membership synchronization

Group memberships are synchronized on each login:

• Removing a user from a mapped IdP group revokes their NetBox access the next time they log in
• Adding a user to a mapped IdP group grants access the next time they log in
• Users may retain access until their session expires if removed from groups
• Consider forcing re-authentication for terminated employees

Audit logging

Group mapping operations are written to the NetBox application log, including the user, the groups added, and the user flags set. Review them during security audits and watch for unexpected group assignments.

kubectl logs <netbox-pod> -n kotsadm | grep "SAML group mapping"

Privileged access management

Consider implementing privileged access management:

• Use your IdP's access request workflow to grant temporary superuser access
• Require approval for adding users to superuser groups
• Implement just-in-time access for administrative operations
• Regularly review group memberships and access patterns