mirror of
https://github.com/fleetdm/fleet
synced 2026-05-22 00:18:27 +00:00
0d8c099cf9
Documentation changes for 4.71.0 --------- Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Co-authored-by: Jordan Montgomery <elijah.jordan.montgomery@gmail.com> Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com> Co-authored-by: Lucas Manuel Rodriguez <lucas@fleetdm.com> Co-authored-by: Ian Littman <iansltx@gmail.com>
127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
# SCIM (System for Cross-domain Identity Management) integration
|
|
|
|
## Reference docs
|
|
|
|
- [scim.cloud](https://scim.cloud/)
|
|
- [SCIM: Core Schema (RFC7643)](https://datatracker.ietf.org/doc/html/rfc7643)
|
|
- [SCIM: Protocol (RFC7644)](https://datatracker.ietf.org/doc/html/rfc7644)
|
|
- [scim Go library](https://github.com/elimity-com/scim)
|
|
|
|
## Okta integration
|
|
|
|
- https://developer.okta.com/docs/guides/scim-provisioning-integration-prepare/main/
|
|
|
|
Sample provisioning settings that work. Capabilities can be disabled and attributes can be removed as needed.
|
|
|
|
|
|
|
|
From our testing with Okta, we see the following behavior that is worth noting:
|
|
- Okta does not use PATCH endpoint
|
|
- Okta does not DELETE users; if a new user needs to be created with the same username as a "deleted" user, then it overwrites the old user
|
|
|
|
### Automated test for Okta integration
|
|
|
|
First, create at least one SCIM user:
|
|
|
|
```
|
|
POST https://localhost:8080/api/latest/fleet/scim/Users
|
|
Authorization: Bearer <API key>
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
|
|
"userName": "test.user@okta.local",
|
|
"name": {
|
|
"givenName": "Test",
|
|
"familyName": "User"
|
|
},
|
|
"emails": [{
|
|
"primary": true,
|
|
"value": "test.user@okta.local",
|
|
"type": "work"
|
|
}],
|
|
"active": true
|
|
}
|
|
```
|
|
|
|
Run test using [Runscope](https://www.runscope.com/). See [instructions](https://developer.okta.com/docs/guides/scim-provisioning-integration-prepare/main/#test-your-scim-api).
|
|
|
|
## Entra ID integration
|
|
|
|
- [SCIM guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups)
|
|
- [SCIM validator](https://scimvalidator.microsoft.com/)
|
|
- Note: only test attributes implemented by Fleet
|
|
|
|
By default, Entra ID SCIM client is not fully SCIM 2.0 compliant. [See details](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility). Fleet server does not support Entra ID's non-SCIM compliant client. To use the SCIM compliant Entra ID client, you must append the following URL parameter to the Fleet server's path: `aadOptscim062020`. This parameter is processed by Entra ID, not by Fleet. So, the Fleet URL should look like this:
|
|
|
|
```
|
|
https://<server_url>/api/v1/fleet/scim?aadOptscim062020
|
|
```
|
|
|
|
### Testing Entra ID integration
|
|
|
|
Use [scimvalidator.microsoft.com](https://scimvalidator.microsoft.com/). Only test the attributes that we have implemented.
|
|
|
|
We support the `emails` attribute, even though it is not called out in our customer-facing guide.
|
|
|
|
|
|
|
|
|
|
To see our supported attributes, check the schema:
|
|
```
|
|
GET https://localhost:8080/api/latest/fleet/scim/Schemas
|
|
```
|
|
|
|
Results (2025/05/06)
|
|
|
|
|
|
|
|
## Authentication
|
|
|
|
We use same authentication as API. HTTP header: `Authorization: Bearer xyz`
|
|
|
|
## Diagrams
|
|
|
|
```mermaid
|
|
---
|
|
title: Initial DB schema (not kept up to date)
|
|
---
|
|
erDiagram
|
|
HOST_SCIM_USER {
|
|
host_id uint PK
|
|
scim_user_id uint PK "FK"
|
|
}
|
|
SCIM_USERS {
|
|
id uint PK
|
|
external_id *string "Index"
|
|
user_name string "Unique"
|
|
given_name *string
|
|
family_name *string
|
|
active *bool
|
|
}
|
|
SCIM_USER_EMAILS {
|
|
id uint PK
|
|
scim_user_id uint FK
|
|
type *string "Index"
|
|
email string "Index"
|
|
primary *bool
|
|
}
|
|
SCIM_USER_GROUP {
|
|
scim_user_id string PK "FK"
|
|
group_id uint PK "FK"
|
|
}
|
|
SCIM_GROUPS {
|
|
id uint PK
|
|
external_id *string "Index"
|
|
display_name string "Index"
|
|
}
|
|
HOST_SCIM_USER }o--|| SCIM_USERS : "multiple hosts can have the same SCIM user"
|
|
SCIM_USERS ||--o{ SCIM_USER_GROUP: "zero-to-many"
|
|
SCIM_USER_GROUP }o--|| SCIM_GROUPS: "zero-to-many"
|
|
SCIM_USERS ||--o{ SCIM_USER_EMAILS: "zero-to-many"
|
|
COMMENT {
|
|
_ _ "created_at and updated_at columns not shown"
|
|
}
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Okta and Entra ID do not support nested groups
|