@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
yaml 240 lines 11.8 KB
Raw
1 # yamllint disable rule:line-length
2 ---
3 - id: 'okta-authentication'
4 meta:
5 name: 'Okta SSO'
6 link: 'https://netdata.cloud'
7 categories:
8 - auth
9 icon_filename: 'okta.png'
10 keywords:
11 - sso
12 - okta
13 - okta-sso
14 overview:
15 authentication_description: "Integrate your organization's Okta account with Netdata to better manage your team's access controls to Netdata Cloud."
16 authentication_limitations: ''
17 setup:
18 description: |
19 ### Prerequisites
20 - An Okta account
21 - A Netdata Cloud account
22 - Access to the Space as an **Admin**
23 - Space needs to be on a paid plan
24
25 ### Setting up Okta
26 Steps needed to be done on Okta Admin Portal:
27 1. Click on **Applications** tab and choose to **Browse App Catalogue**
28 2. Find Netdata's preconfigured app for easy setup and click **Add Integration**
29 3. Give the app, that will be in your apps dashboard, the preferred **Application label** and click **Next** to move to the Sign-On options tab
30 4. In the **Sign-On Options** all the values we expect are already filled and no additional data is required
31 5. Click **Done**. You are able to go back and edit any fields later if need be
32 6. Go to the **Assignments** tab and enter the People or Group assignments as per your organization’s policies
33
34 ### Netdata Configuration Steps
35 1. Click on the Space settings cog (located above your profile icon)
36 2. Click on the **User Management** section and access **Authentication and Authorization** tab.
37 3. On the Okta SSO card, click on **Configure**
38 4. Fill in the [required credentials](https://developer.okta.com/docs/guides/find-your-app-credentials/main/), you get them from **Okta Admin Portal**:
39 - **Issuer URL** you can get it from your profile icon on top, e.g. `https://company-name.okta.com`
40 - **Client ID** you can get it from **General** tab on application you configured on Okta
41 - **Client Secret** you can get it from **General** tab on application you configured on Okta
42
43 ### Supported features
44 * SP-initiated SSO (Single Sign-On)
45 * IdP-initiated SSO
46
47 ### SP-initiated SSO
48
49 If you start your authentication flow from Netdata sign-in page please check [these steps](/docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md).
50
51 - id: 'oidc-authentication'
52 meta:
53 name: 'OIDC'
54 link: 'https://netdata.cloud'
55 categories:
56 - auth
57 icon_filename: 'openid.svg'
58 keywords:
59 - sso
60 - oidc
61 overview:
62 authentication_description: "Integrate your organization's Authorization Servers with Netdata to better manage your team's access controls to Netdata Cloud."
63 authentication_limitations: ''
64 setup:
65 description: |
66 ### Prerequisites
67 - Authorization Server with OIDC protocol supported
68 - A Netdata Cloud account
69 - Access to the Space as an **Admin**
70 - Space needs to be on a paid plan
71
72 ### Setting up Authorization Server
73 Your server should follow the [full specification for OIDC](https://openid.net/specs/openid-connect-core-1_0.html).
74 In order to integrate your Authorization Server with Netdata the creation of a client is required. Clients are applications and services that can request authentication of a user.
75 The access settings for your client are the following:
76
77 | field | value |
78 | :-- | :-- |
79 | Root URL | `https://app.netdata.cloud/` |
80 | Home/Initiate login URL | `https://app.netdata.cloud/api/v2/auth/account/auth-server?id={netdata-space-id}&redirect_uri=https://app.netdata.cloud/sign-in&register_uri=https://app.netdata.cloud/sign-up/verify` |
81 | Redirect URL | `https://app.netdata.cloud/api/v2/auth/account/auth-server/callback` |
82
83 ### Netdata Configuration Steps
84 1. Click on the Space settings cog (located above your profile icon)
85 2. Click on the **User Management** section and access **Authentication and Authorization** tab.
86 3. On the OIDC card, click on **Configure**
87 4. Fill in the required credentials:
88 - **Issuer URL** the Authorization Server Issuer URL, e.g. `https://my-auth-server.com/`
89 - **Client ID** the Client ID from the created client
90 - **Client Secret** the Client Secret from the created client
91
92 ### Supported features
93 * SP-initiated SSO (Single Sign-On)
94 * IdP-initiated SSO
95
96 ### SP-initiated SSO
97
98 If you start your authentication flow from Netdata sign-in page please check [these steps](/docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md).
99
100
101 ### Reference
102 https://openid.net/developers/how-connect-works/
103
104 - id: 'scim'
105 meta:
106 name: 'SCIM'
107 link: 'https://netdata.cloud'
108 categories:
109 - auth
110 icon_filename: 'scim.svg'
111 keywords:
112 - scim
113 - identity-management
114 overview:
115 authentication_description: "The System for Cross-domain Identity Management (SCIM) specification is designed to simplify the management of user identities in cloud-based applications and services."
116 authentication_limitations: ''
117 setup:
118 description: |
119 ### Prerequisites
120 - A Netdata Cloud account
121 - Admin access to the Space
122 - The Space must be on a paid plan
123 - OIDC/SSO integration must already be enabled in one of your Spaces
124
125 ### Supported Features
126 This integration adheres to SCIM v2 specifications. Supported features include:
127
128 - User Resource Management (urn:ietf:params:scim:schemas:core:2.0:User)
129 - Group Resource Management (urn:ietf:params:scim:schemas:core:2.0:Group)
130 - Create users
131 - Import users
132 - Update user attributes
133 - Deactivate users
134 - Create groups
135 - Nested groups supported
136 - Patch operations: Supported
137 - Filtering: Supported (max results: 200)
138 - Authentication schemes: OAuth Bearer Token
139 - Import groups: Not supported
140 - Bulk operations: Not supported
141 - Password synchronization: Not supported, as we rely on SSO/OIDC authentication
142 - Push Now: Not supported
143 - eTag: Not supported
144
145 ### Netdata Configuration Steps
146 1. Click on the Space settings cog (located above your profile icon).
147 2. Click on the **User Management** section and access **Authentication and Authorization** tab.
148 3. In the SCIM card, click on **Activate**.
149 4. Depending on your situation:
150 - If OIDC/SSO integration is already enabled in your Space, click **Activate**.
151 - 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**.
152 5. If the setup is successful, you will receive two parameters:
153 - **Base URL**: Use this URL as the base URL for your SCIM client.
154 - **Token**: Use this token for Bearer Authentication with your SCIM client.
155
156 ## Client Configuration Steps
157
158 ### Okta
159 If you're configuring SCIM in Okta, and you already have the Token from the previous section, follow these steps:
160
161 1. Go to the **Applications** menu on the left-hand panel and select the **Netdata** application.
162 2. In the **Netdata** application, navigate to the **Provisioning** tab.
163 3. Click on **Configure API Integration** and check the box for **Enable API Integration**.
164 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.
165 5. If the test is successful, click **Save** to apply the configuration.
166
167 ## Setting Up Membership Rules
168
169 1. Click on the Space settings cog (located above your profile icon).
170 2. Navigate to the **User Management** section and select the **Groups** tab.
171 3. Once your SCIM client has provisioned groups to Netdata, you'll see a **Create a new rule** button.
172 4. Click this button to open the membership rule configuration panel.
173 5. For each rule, configure the following three components:
174 - **SCIM Group**: Select the SCIM group that should be mapped
175 - **Netdata Role**: Choose the role that members of this group should have in the space
176 - **Space Rooms**: (Optional) Select specific rooms that these users should be members of
177 6. Click **Save** to activate the configuration.
178 7. Repeat steps 4-6 to create additional rules as needed.
179
180 ### How Membership Rules Work
181
182 - 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.
183 - If a user is removed from a SCIM group, their access will be adjusted according to your rules.
184 - When users match multiple rules, they are granted the highest permission level from all their matching rules.
185 - Changes to membership rules take effect immediately for new and existing users.
186
187 **Important Considerations**
188 - 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.
189 - 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.
190
191 ## Troubleshoot
192
193 ### Rotating the SCIM Token
194 You can rotate the token provided during SCIM integration setup if needed.
195
196 Steps to rotate the token:
197 1. Click on the Space settings cog (located above your profile icon).
198 2. Click on the **User Management** section and access **Authentication and Authorization** tab.
199 3. In the already configured SCIM card, click **Configure**.
200 4. Click **Regenerate Token**.
201 5. If successful, you will receive a new token for Bearer Authentication with your SCIM client.
202
203 ### User Keying Between SCIM and OIDC
204 Our SCIM (System for Cross-domain Identity Management) integration utilizes OIDC (OpenID Connect) to authenticate users.
205 To ensure users are correctly identified and authenticated between SCIM and OIDC, we use the following mapping:
206
207 - SCIM externalID ↔ OIDC sub
208
209 This mapping ensures that the identity of users remains consistent and secure across both systems.
210
211 **Important**: Ensure that your OIDC and SCIM systems follow this mapping strictly.
212 The externalID in SCIM must correspond to the subfield in OIDC. Any deviation from this mapping may result
213 in incorrect user identification and authentication failures.
214
215 ## Supported SCIM User properties
216
217 Our SCIM server supports the following User attributes:
218
219 - userName (required)
220 - externalId (required)
221 - name.formatted
222 - name.familyName
223 - name.givenName
224 - active
225 - emails (we only store the primary email)
226
227 **Important Considerations**
228 - 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.
229 - Okta users: No additional setup needed. The Netdata integration includes the correct attribute configuration automatically.
230
231 ## FAQ
232
233 ### Why aren’t users automatically added to Netdata spaces when they’re created through SCIM?
234
235 Users created through SCIM are not automatically assigned to spaces. You need to configure Membership Rules to control space assignments.
236
237 See Setting Up Membership Rules section above for setup instructions.
238
239 ### Reference
240 [SCIM Specification](https://scim.org)