SCIM

The System for Cross-domain Identity Management (SCIM) specification is designed to simplify the management of user identities in cloud-based applications and services.

Setup

Prerequisites

• A Netdata Cloud account
• Admin access to the Space
• The Space must be on a paid plan
• OIDC/SSO integration must already be enabled in one of your Spaces

Supported Features

This integration adheres to SCIM v2 specifications. Supported features include:

• User Resource Management (urn:ietf:params:scim:schemas:core:2.0:User)
• Group Resource Management (urn:ietf:params:scim:schemas:core:2.0:Group)
• Create users
• Import users
• Update user attributes
• Deactivate users
• Create groups
• Nested groups supported
• Patch operations: Supported
• Filtering: Supported (max results: 200)
• Authentication schemes: OAuth Bearer Token
• Import groups: Not supported
• Bulk operations: Not supported
• Password synchronization: Not supported, as we rely on SSO/OIDC authentication
• Push Now: Not supported
• eTag: Not supported

Netdata Configuration Steps

1. Click on the Space settings cog (located above your profile icon).
2. Click on the User Management section and access Authentication and Authorization tab.
3. In the SCIM card, click on Activate.
4. Depending on your situation:
   • If OIDC/SSO integration is already enabled in your Space, click Activate.
   • If you already have a SCIM integration in another Space and want to create a linked integration here, enter the SCIM token from the original integration and click Activate.
5. If the setup is successful, you will receive two parameters:
   • Base URL: Use this URL as the base URL for your SCIM client.
   • Token: Use this token for Bearer Authentication with your SCIM client.

Client Configuration Steps

Okta

If you’re configuring SCIM in Okta, and you already have the Token from the previous section, follow these steps:

1. Go to the Applications menu on the left-hand panel and select the Netdata application.
2. In the Netdata application, navigate to the Provisioning tab.
3. Click on Configure API Integration and check the box for Enable API Integration.
4. Enter the Token (obtained in the Netdata Configuration Steps section) into the API Token field, then click Test API Credentials to ensure the connection is successful.
5. If the test is successful, click Save to apply the configuration.

Setting Up Membership Rules

1. Click on the Space settings cog (located above your profile icon).
2. Navigate to the User Management section and select the Groups tab.
3. Once your SCIM client has provisioned groups to Netdata, you’ll see a Create a new rule button.
4. Click this button to open the membership rule configuration panel.
5. For each rule, configure the following three components:

• SCIM Group: Select the SCIM group that should be mapped
• Netdata Role: Choose the role that members of this group should have in the space
• Space Rooms: (Optional) Select specific rooms that these users should be members of

6. Click Save to activate the configuration.
7. Repeat steps 4-6 to create additional rules as needed.

How Membership Rules Work

• When a user in your identity provider is assigned to a SCIM group, they will automatically be added to your Netdata Space with the role and room access defined in your rules.
• If a user is removed from a SCIM group, their access will be adjusted according to your rules.
• When users match multiple rules, they are granted the highest permission level from all their matching rules.
• Changes to membership rules take effect immediately for new and existing users.

Important Considerations

• If you had previously manually invited users who are now being provisioned through SCIM, their existing roles and room access will be updated to match your rules.
• You must create at least one rule that assigns the Admin role to a SCIM group. If no admin role is defined in your rules, Netdata will not implement any user membership changes and will display a warning in the workspace.

Troubleshoot

Rotating the SCIM Token

You can rotate the token provided during SCIM integration setup if needed.

Steps to rotate the token:

1. Click on the Space settings cog (located above your profile icon).
2. Click on the User Management section and access Authentication and Authorization tab.
3. In the already configured SCIM card, click Configure.
4. Click Regenerate Token.
5. If successful, you will receive a new token for Bearer Authentication with your SCIM client.

User Keying Between SCIM and OIDC

Our SCIM (System for Cross-domain Identity Management) integration utilizes OIDC (OpenID Connect) to authenticate users. To ensure users are correctly identified and authenticated between SCIM and OIDC, we use the following mapping:

• SCIM externalID ↔ OIDC sub

This mapping ensures that the identity of users remains consistent and secure across both systems.

Important: Ensure that your OIDC and SCIM systems follow this mapping strictly. The externalID in SCIM must correspond to the subfield in OIDC. Any deviation from this mapping may result in incorrect user identification and authentication failures.

Supported SCIM User properties

Our SCIM server supports the following User attributes:

• userName (required)
• externalId (required)
• name.formatted
• name.familyName
• name.givenName
• active
• emails (we only store the primary email)

Important Considerations

• Configure supported attributes only: Your SCIM client must be configured to send only the attributes listed above. Requests containing unsupported attributes will fail with a 400 Bad Request error.
• Okta users: No additional setup needed. The Netdata integration includes the correct attribute configuration automatically.

FAQ

Why aren’t users automatically added to Netdata spaces when they’re created through SCIM?

Users created through SCIM are not automatically assigned to spaces. You need to configure Membership Rules to control space assignments.

See Setting Up Membership Rules section above for setup instructions.

Reference

SCIM Specification