Group Mapping For Okta Single Sign-On (SSO)

Group mapping lets you manage NetBox Cloud permissions centrally in Okta instead of assigning them user by user. When you update group membership in Okta, 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 Okta for NetBox Cloud SSO, you can set up group mapping by creating your groups and permissions in NetBox Cloud, creating matching groups in Okta, and then sharing the mapping details with NetBox Labs support.

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

For more information, see Groups in the Okta documentation.

Okta configuration

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

Two separate settings in Okta are involved, and they do different jobs:

• The groups claim controls which group names Okta sends to NetBox Cloud. Group mapping requires this.
• Assignments controls who can log in to NetBox Cloud. This is recommended, but mapping works without it.

Assigning the app integration to a group is an access decision that stays inside Okta. It answers whether a user may log in, and Okta doesn't pass that reasoning on.

The token NetBox receives carries the user's identity and nothing about group membership unless you configure the groups claim. Assignment also can't express which of several groups a user belongs to, which is exactly what a name-based mapping needs.

Identify your group names

1. In the Okta Admin Console, select Directory > Groups in the left menu.
2. Create a group or identify an existing group you want to use.
3. Note the group's exact name. You will use this name to map the Okta group to the NetBox Cloud group.

Assign the app integration to your groups (recommended)

Group mapping doesn't require this, but group-based assignment is the only way to control which Okta users can log in to NetBox Cloud. Without it, any user in your Okta org who reaches your NetBox Cloud URL can authenticate, and NetBox creates a local account for them on first login. Those accounts have no permissions, but they accumulate.

The simplest path is to choose group assignment when you create the app integration. In the Assignments section of the creation wizard, under Controlled access, select Limit access to selected groups and enter the names of the groups you plan to map. See Okta SSO Setup.

To add more groups to an integration that already uses group assignment:

1. In the Okta Admin Console, select Applications and Resources > Applications and open your NetBox Cloud app integration.
2. Select the Assignments tab.
3. Click Assign and choose Assign to Groups.
4. Click Assign next to each group that should have access, then click Done.

For more information, see Assign an app integration to a group.

Set the groups claim filter

Assigning the app integration to a group does not, by itself, tell NetBox Cloud which groups a user belongs to. Okta only sends group names when the app integration has a groups claim configured.

NetBox Cloud expects that claim to be named groups, which means you configure it under Okta's legacy claims configuration. Okta's newer claims feature reserves the name groups and rejects it.

1. In the Okta Admin Console, select Applications and Resources > Applications and open your NetBox Cloud app integration.

2. Go to the Sign On tab and find the Token claims section.

3. Expand Show legacy configuration.

4. Set Groups claim type to Filter.

5. In Groups claim filter, leave the claim name as groups, then set the filter to match the groups you want NetBox Cloud to see:

   • To send every group the user belongs to, select Matches regex and enter .*
   • To send a subset, select Starts with and enter a literal prefix such as NetBox

6. Click Save.

For more information, see Configure custom claims for app integrations.

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).

For example, this group called CircuitManager in NetBox Cloud has permissions assigned to it that allow members of the group to manage all of the Circuit and Provider object types:

Provide the group mapping information to NetBox

Send the following information to NetBox Labs support:

• Okta 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 Okta returns for the user.
2. NetBox removes all existing group memberships for the user.
3. NetBox adds new group memberships based on the current Okta groups.
4. User flags for Staff and Superuser groups are updated based on current groups.

Note the following:

• Adding a user to an Okta group grants access on next login.

• Removing a user from an Okta 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.

• Okta 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.

Which groups Okta sends

NetBox Cloud only sees the group names your groups claim filter matches, so that filter determines whether built-in groups such as Everyone, and groups a user joined through a group rule, are included.

Staff and Superuser groups

Optionally, members of the Okta 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 Okta groups to your NetBox Cloud groups, for example: