Group Mapping For SAML Single Sign-On (SSO)

Group mapping lets you manage NetBox Cloud permissions centrally in your identity provider (IdP) instead of assigning them user by user. When you update group membership in your IdP, that change takes effect in NetBox Cloud the next time the user logs in, so access stays consistent as employees join, change roles, or leave.

If you already use SAML for NetBox Cloud SSO, you can set up group mapping by creating your groups and permissions in NetBox Cloud, configuring your IdP to send group membership in the assertion, and then sharing the mapping details with NetBox Labs support.

Before you begin, set up SAML SSO for your NetBox Cloud instance.

Identity provider configuration

Group mappings are based on the name of the group in your IdP. NetBox Cloud maps each name your IdP sends to a NetBox Cloud group, and that group carries the permissions. Names are case-sensitive and must match your mapping exactly.

Add a groups attribute to your SAML application. NetBox Cloud expects this exact attribute name, so if your IdP sends group information under a different name, such as MemberOf, update its configuration to use groups.

Where you add the attribute depends on the provider:

• Okta: A group attribute statement under SAML Settings, filtered to the groups NetBox Cloud should see.
• Microsoft Entra ID: A group claim under Single sign-on > Attributes & Claims. Set the source attribute so the claim emits group names rather than object IDs.
• OneLogin: A parameter under Parameters, with Include in SAML assertion checked.

Before contacting support, confirm your IdP is sending the attribute. Capture a test login with a SAML tracer browser extension, look for a groups attribute in the response, and note the exact spelling of each value. Those strings are what you send us.

NetBox Cloud configuration

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

Provide the group mapping information to NetBox

Send the following information to NetBox Labs support:

• IdP group name
• NetBox group name
• Optionally, whether the group should also map to the Staff or Superuser groups

The support team will enable group mapping on your NetBox Cloud instance, configure the mappings, and confirm when this is ready for testing.

How mapping works

On each login:

1. NetBox reads the group names in the groups attribute of the assertion.
2. NetBox removes all existing group memberships for the user.
3. NetBox adds new group memberships based on the current IdP groups.
4. User flags for Staff and Superuser groups are updated based on current groups.

Note the following:

• Adding a user to a mapped IdP group grants access on next login.

• Removing a user from a mapped IdP group revokes their NetBox access on next login. So users may retain access until their session expires if removed from groups. Consider forcing re-authentication for terminated employees.

• IdP groups that aren't part of your mapping are ignored. Users are not added to NetBox Cloud groups for them.

• A user in several mapped groups is added to all of the corresponding NetBox Cloud groups, and their permissions are the union of those groups.

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

Staff and Superuser groups

Optionally, members of the IdP groups can also be members of the NetBox built-in groups:

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

The NetBox Labs support team will map your IdP groups to your NetBox Cloud groups, for example: