OIDC Group Mapping

Is a mechanism which allows the bridging of Identity Provider (IDP) roles or claims to Control Plane's internal authorization model.

By leveraging your IDP it is possible to assign or remove Control Plane roles programmatically. This negates the need to manually configure each user's level of access within Control Plane.

User privileges are granted or revoked from Control Plane on the next login event.

Let's create an example to explain this in more detail.

Example

Inside your IDP, in this case Microsoft Entra, we have a group called nats-admins and another group called nats-observers. Internally, these two groups contain users who should be granted different levels of access.

Leveraging Control Plane OIDC Group Mapping it is possible to programmatically grant or remove privileges based on the users group assignment.

We could ensure that any user in Control Plane with nats-admin group access gets a Team:Admin role and nats-observers are only granted Team:Observer.

How it works

Control Plane reads the claims from the OIDC token presented during login and extracts the role or group from it. That group can then be used to programmatically link to Control Plane roles.

To enable this the following must occur:

1. Your IDP must expose a custom claim
   • Each IDP does this slightly differently but the claim must be exposed during the login event
   • The role or group must be available as field on the token provided by the IDP to Control Plane
2. Control Plane must be aware of the claim using our Jsonnet mapper

Once the claim has been added via the IDP a mapping can be constructed which links any user with that claim in their id_token to Control Plane roles.

Inside Control Plane we can create a mapping that links resources such as Teams, Systems and Accounts to the custom claim.

Both the API and UI are available for creating the OIDC group role mapping.

Mapping

Login Flow

If a user presents a claim for a group in their token which matches what has been configured in Control Plane, the access controls will be applied or revoked for that user.

Configuration

For detailed configuration refer to the guide.