mirror of
https://github.com/fleetdm/fleet
synced 2026-04-21 13:37:30 +00:00
Update host foreign vitals IdP guide + related tweaks (#35229)
Fixes #32072. Biggest changes are in the foreign vitals IdP (SCIM) guide: * Moved Android from "coming soon" to live (true as of 4.75) * Moved Okta-specific troubleshooting under the Okta section * Moved "Other IdPs" into its own top level section instead of partway through the Google section (looks like the result of a bad merge) * Added a link to the labels guide where relevant * Various minor clarity/grammar fixes based on running through the process end-to-end with Okta Additionally: * Clarity fixes on labels docs * Noted in contributing docs the existence of the Okta Integrator Free plan for E2E testing SSO/SCIM flows
This commit is contained in:
Ian Littman
GitHub
parent
8dca5fe5e5
commit
f1c3f02dac
3 changed files with 44 additions and 41 deletions
|
|
@ -4,13 +4,13 @@
|
|||
|
||||
_Available in Fleet Premium._
|
||||
|
||||
Fleet can map an end user's IdP username, groups, and department to their host(s) in Fleet. Then, you can use these IdP host vitals as [variables in configuration profiles](https://fleetdm.com/docs/configuration/yaml-files#variables) or criteria for labels.
|
||||
Fleet can map an end user's IdP username, groups, and department to their host(s) in Fleet. Then, you can use these IdP host vitals as [variables in configuration profiles](https://fleetdm.com/docs/configuration/yaml-files#variables) or criteria for [labels](https://fleetdm.com/guides/managing-labels-in-fleet).
|
||||
|
||||
Fleet supports [Okta](#okta), [Microsoft Active Directory (AD) / Entra ID](#microsoft-entra-id), [Google Workspace](#google-workspace), [authentik](#google-workspace), as well as any other IdP that supports the [SCIM (System for Cross-domain Identity Management) protocol](https://scim.cloud/).
|
||||
Fleet supports [Okta](#okta), [Microsoft Active Directory (AD) / Entra ID](#microsoft-entra-id), [Google Workspace](#google-workspace), [authentik](#google-workspace), as well as [any other IdP](#other-idps) that supports the [SCIM (System for Cross-domain Identity Management) protocol](https://scim.cloud/).
|
||||
|
||||
Fleet gathers IdP host vitals when an end user authenticates during these enrollment scenarios:
|
||||
- Automatic enrollment (ADE) for Apple (macOS, iOS, iPadOS) hosts.
|
||||
- Manual enrollment for personal (BYOD) iOS and iPadOS hosts (Android coming soon).
|
||||
- Manual enrollment for personal (BYOD) iOS, iPadOS, and Android hosts.
|
||||
|
||||
Learn how to enforce authentication in the [setup experience guide](https://fleetdm.com/guides/macos-setup-experience#end-user-authentication).
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ To map users from Okta to hosts in Fleet, we'll do the following steps:
|
|||
3. Select **SAML 2.0** option and select **Next**.
|
||||
4. On the **General Settings** page, add a friendly **App name** (e.g Fleet SCIM), and select **Next**.
|
||||
5. On the **SAML Settings** page, add any URL to the **Single sign-on URL** and **Audience URI (SP Entity ID)** fields, and select **Next**.
|
||||
> Okta requires us to setup SAML settings in order to setup a SCIM integration. Since we don't need SAML right now, you can set the URL to anything like "example.fleetdm.com".
|
||||
> Okta requires setting up SAML to set up SCIM. Since we don't need SAML right now, you can set the URL to something arbitrary, e.g "example.fleetdm.com".
|
||||
6. On the **Feedback** page, provide feedback if you want, and select **Finish**.
|
||||
7. Select the **General** tab in your newly created app and then select **Edit** in **App Settings**.
|
||||
8. For **Provisioning**, select **SCIM** and select **Save**.
|
||||
|
|
@ -42,11 +42,14 @@ To map users from Okta to hosts in Fleet, we'll do the following steps:
|
|||
4. For the **Supported provisioning actions**, select **Push New Users**, **Push Profile Updates**, and **Push Groups**.
|
||||
5. For the **Authentication Mode**, select **HTTP Header**.
|
||||
6. [Create a Fleet API-only user](https://fleetdm.com/guides/fleetctl#create-api-only-user) with maintainer permissions and copy API token for that user. Paste your API token in Okta's **Authorization** field.
|
||||
7. Select the **Test Connector Configuration** button. You should see success message in Okta.
|
||||
8. In Fleet, head to **Settings > Integrations > Identity provider (IdP)** and verify that Fleet successfully received the request from IdP.
|
||||
|
||||
> For example, `fleetctl user create --name 'SCIM User' --email 'scim@example.com' --password 'hunter2' --api-only --global-role maintainer`
|
||||
|
||||
7. Select the **Test Connector Configuration** button. You should see a success message pop up in Okta. You can close this message.
|
||||
8. In Fleet, head to **Settings > Integrations > Identity provider (IdP)** and verify that Fleet successfully received the request from Okta.
|
||||
9. Back in Okta, select **Save**.
|
||||
10. Under the **Provisioning** tab, select **To App** and then select **Edit** in the **Provisioning to App** section. Enable **Create Users**, **Update User Attributes**, **Deactivate Users**, and then select **Save**.
|
||||
11. On the same page, make sure that `givenName` and `familyName` have Okta values assigned to it. Currently, Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Fleet also supports the `department` attribute (optional). Delete the rest of the attributes.
|
||||
11. On the same page, make sure that `givenName` and `familyName` attributes have Okta values assigned to them. Currently, Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Fleet also supports the `department` attribute, but does not require it. Delete the rest of the attributes.
|
||||
|
||||
|
||||
#### Step 3: Map users and groups to hosts in Fleet
|
||||
|
|
@ -54,11 +57,20 @@ To map users from Okta to hosts in Fleet, we'll do the following steps:
|
|||
To send users and groups information to Fleet, you have to assign them to your new SCIM app.
|
||||
|
||||
1. In Okta's main menu **Directory > Groups** and then select **Add group**. Name it "Fleet human-device mapping".
|
||||
2. On the same page, select the **Rules** tab. Create a rule that will assign users to your "Fleet human-device mapping" group.
|
||||
2. On the same page, select the **Rules** tab. Select **Add Rule** to create a rule that will assign users to your "Fleet human-device mapping" group.
|
||||
|
||||
3. In the main menu, select **Applications > Applications** and select your new SCIM app. Then, select the **Assignments** tab.
|
||||
4. Select **Assign > Assign to Groups** and then select **Assign** next to the "Fleet human-device mapping" group. Then, select **Done**. Now all users that you assigned to the "Fleet human-device mapping" group will be provisioned to Fleet.
|
||||
5. On the same page, select **Push Groups** tab. Then, select **Push Groups > Find groups by name** and add all groups that you assigned to "Fleet human-device mapping" group previously (make sure that **Push group memberships immediately** is selected). All groups will be provisioned in Fleet, and Fleet will map those groups to users.
|
||||
3. After saving your new rule, select **Activate** from the **Actions** menu to populate users into the human-device mapping group.
|
||||
4. In the Okta main menu, select **Applications > Applications** and select your new SCIM app. Then, select the **Assignments** tab.
|
||||
5. Select **Assign > Assign to Groups** and then select **Assign** next to the "Fleet human-device mapping" group, then **Save and Go Back**, then **Done**. Now all users that you assigned to the "Fleet human-device mapping" group will be provisioned to Fleet.
|
||||
6. On the same page, select the **Push Groups** tab. Then, select **Push Groups > Find groups by name** and add all groups that you assigned to "Fleet human-device mapping" group previously (make sure that **Push group memberships immediately** is selected). All groups will be provisioned in Fleet, and Fleet will map those groups to users.
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
If you find that identity information (e.g full name or groups) is missing on the host, and the host has an IdP username assigned to it:
|
||||
|
||||
1. In Okta, select **Directory > People**, find the affected user, and make sure that it has all the fields required by Fleet (username, first name, and last name).
|
||||
2. If all required fields are present, then go to **Applications > Applications**, select your app, then go to the **Provisioning** tab and select **To App**. Scroll to the bottom of the page and make sure that `userName`, `givenName`, and `familyName` have a value assigned to them.
|
||||
3. Otherwise, make sure that all settings from the instructions above were set correctly.
|
||||
|
||||
## Microsoft Entra ID
|
||||
|
||||
|
|
@ -102,19 +114,6 @@ It might take up to 40 minutes until Microsoft Entra ID sends data to Fleet. To
|
|||
|
||||
Google Workspace doesn't natively support the [SCIM](https://scim.cloud/) standard. The best practice is to export users to [authentik](https://goauthentik.io/). Authentik then adds users to Fleet.
|
||||
|
||||
## Other IdPs
|
||||
|
||||
IdPs generally require a Fleet SCIM URL and API token:
|
||||
|
||||
- SCIM URL - `https://<your_fleet_server_url>/api/v1/fleet/scim`
|
||||
- API token - [Create a Fleet API-only user](https://fleetdm.com/guides/fleetctl#create-api-only-user) with maintainer permissions and copy API token for that user.
|
||||
|
||||
Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Make sure these attributes are correctly mapped in your IdP with `userName` as the unique identifier. Fleet uses the `userName` attribute to map to IdP groups and department.
|
||||
|
||||
Fleet also supports the `department` attribute. Delete all other attributes.
|
||||
|
||||
To map groups, configure your IdP to provision (push) them to Fleet.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Install](https://docs.goauthentik.io/docs/install-config/install/aws) and run authentik
|
||||
|
|
@ -264,25 +263,28 @@ To map users from Google Workspace to hosts in Fleet, we'll do the following ste
|
|||
9. Select **Create** to add the application.
|
||||
10. After a few minutes, you should see users mapped to hosts in Fleet.
|
||||
|
||||
## Other IdPs
|
||||
|
||||
IdPs generally require a Fleet SCIM URL and API token:
|
||||
|
||||
- SCIM URL - `https://<your_fleet_server_url>/api/v1/fleet/scim`
|
||||
- API token - [Create a Fleet API-only user](https://fleetdm.com/guides/fleetctl#create-api-only-user) with maintainer permissions and copy API token for that user.
|
||||
|
||||
Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Make sure these attributes are correctly mapped in your IdP with `userName` as the unique identifier. Fleet uses the `userName` attribute to map to IdP groups and department.
|
||||
|
||||
Fleet also supports the `department` attribute. Delete all other attributes.
|
||||
|
||||
To map groups, configure your IdP to provision (push) them to Fleet.
|
||||
|
||||
## Verify connection
|
||||
|
||||
After following the steps above, you should be able to see the latest requests from your IdP to Fleet if you navigate to **Settings > Integrations > Identity Provider (IdP)**.
|
||||
|
||||
To verify that user information is added to a host, go to the host that has IdP username assigned, and verify that **Full name (IdP)**, **Department (IdP)**, and **Groups (IdP)** are populated correctly.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If you find that information from IdP (e.g full name or groups) is missing on the host, and the host has IdP username assigned to it, follow the steps below to resolve.
|
||||
|
||||
1. Please first go to Okta, select **Directory > People**, find user that is
|
||||
missing information and make sure that it has all the fields required by Fleet (username, first name, and
|
||||
last name).
|
||||
2. If all required fields are present, then go to **Applications > Applications > fleet_scim_application > Provisioning > To App**, then scroll to the bottom of the page and make sure that `userName`, `givenName`, and `familyName` have a value assigned to them.
|
||||
3. Otherwise, make sure that all settings from the instructions above were set correctly.
|
||||
To verify that user information is added to a host, go to the host that has an IdP username assigned and verify that **Full name (IdP)**, **Department (IdP)**, and **Groups (IdP)** are populated correctly.
|
||||
|
||||
<meta name="authorGitHubUsername" value="marko-lisica">
|
||||
<meta name="authorFullName" value="Marko Lisica">
|
||||
<meta name="publishedOn" value="2025-04-11">
|
||||
<meta name="publishedOn" value="2025-11-05">
|
||||
<meta name="articleTitle" value="Foreign vitals: map IdP users to hosts">
|
||||
<meta name="articleImageUrl" value="../website/assets/images/articles/add-users-from-idp-cover-img-800x400@2x.png">
|
||||
<meta name="category" value="guides">
|
||||
|
|
|
|||
|
|
@ -5,16 +5,15 @@ In Fleet, you can use labels to scope [software](https://fleetdm.com/guides/depl
|
|||
|
||||
Labels can be one of the following types:
|
||||
- **Dynamic**: A query-based label applied to any host that returns a result for the label’s query.
|
||||
> If you want to change the query or platform on a dynamic label, you must delete the existing label and create a new one.
|
||||
- **Manual**: A manually assigned label used to filter selected hosts.
|
||||
- **Host vitals**: A Fleet-generated label applied to hosts that match a specific host vital.
|
||||
|
||||
>Host vitals are currently supported only for IdP host vitals (groups and department) on macOS, iOS, iPadOS, and Android.
|
||||
- **Host vitals**: A Fleet-generated label applied to hosts that match a specific host vital (currently IdP group and department on macOS, iOS, iPadOS, and Android).
|
||||
> If you want to change the target of a host vitals label, you must delete the existing label and create a new one.
|
||||
|
||||
To add or edit a label in Fleet, select the avatar on the right side of the top navigation and select **Labels**.
|
||||
|
||||
You can also manage labels via [Fleet's API](https://fleetdm.com/docs/rest-api/rest-api#labels) or [best practice GitOps](https://fleetdm.com/docs/configuration/yaml-files#labels).
|
||||
|
||||
> For dynamic labels, if you want to change the query or platform, you must delete the existing label and create a new one.
|
||||
|
||||
<meta name="articleTitle" value="Labels in Fleet">
|
||||
<meta name="authorFullName" value="Noah Talerman">
|
||||
|
|
|
|||
|
|
@ -362,7 +362,9 @@ docker-compose exec redis redis-cli
|
|||
|
||||
## Testing SSO
|
||||
|
||||
Fleet's `docker-compose` file includes a SAML identity provider (IdP) for testing SAML-based SSO locally.
|
||||
For end-to-end testing including advanced use cases (e.g. SCIM), [Okta](https://developer.okta.com/signup/) has an Integrator Free Plan available that you can develop against.
|
||||
|
||||
For simpler use cases, Fleet's `docker-compose` file includes a SAML identity provider (IdP) for testing SAML-based SSO locally.
|
||||
|
||||
### Configuration
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue