Authentication & SSO
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and Single Sign-On (SSO) in Fleet provide secure access control for both the Fleet management console and the endpoints it manages. The system leverages industry-standard protocols such as SAML 2.0 and SCIM to integrate with external Identity Providers (IdPs), ensuring that user identities are verified centrally.
The primary scope includes securing the Fleet server via SSO settings, managing two-factor authentication (2FA) for privileged access, and mapping IdP identities (usernames, groups, and departments) to specific hosts during the enrollment process. This integration allows for infrastructure-as-code workflows and granular policy enforcement based on identity metadata.
Sources: tools/fleet-slackbot/system-prompt.js:335-340, articles/foreign-vitals-map-idp-users-to-hosts.md:1-10, articles/tales-from-fleet-security-securing-google-workspace.md:10-15
SSO Architecture and Configuration
Fleet's SSO implementation focuses on SAML 2.0 integration for user authentication. The global organization settings define the connection parameters required to communicate with an IdP.
Core SSO Settings
The configuration for SSO is managed within the global default.yml or the Fleet UI settings. These settings enable the server to delegate authentication to providers like Okta, Microsoft Entra ID (formerly Azure AD), or Google Workspace.
| Setting | Type | Description |
|---|---|---|
enable_sso | boolean | Globally enables or disables SSO for the Fleet server. |
entity_id | string | The Service Provider (SP) Entity ID recognized by the IdP. |
metadata | string | The XML metadata provided by the IdP. |
metadata_url | string | The URL where IdP metadata can be fetched. |
Sources: tools/fleet-slackbot/system-prompt.js:335-340, articles/tales-from-fleet-security-securing-google-workspace.md:20-25
Authentication Flow
The following diagram illustrates the high-level flow when a user attempts to authenticate via SSO:
The Fleet server acts as the Service Provider, validating SAML assertions from the Identity Provider to establish user sessions.
Sources: tools/fleet-slackbot/system-prompt.js:335-340, articles/tales-from-fleet-security-securing-google-workspace.md:55-60
Identity Provider (IdP) Integrations
Fleet Premium allows mapping IdP metadata directly to hosts. This is achieved through SCIM (System for Cross-domain Identity Management) and specific enrollment authentication hooks.
SCIM Integration
SCIM is used to provision and sync user attributes from IdPs to Fleet. This ensures that when a user is assigned to a host, Fleet knows their full name, department, and groups.
- Okta SCIM: Uses a SCIM connector base URL (
/api/v1/fleet/scim) and requires an API-only user with admin permissions. - Microsoft Entra ID: Requires a Tenant URL formatted as
https://<fleet_url>/api/v1/fleet/scim?aadOptscim062020. - Google Workspace: Since Google does not natively support SCIM, Fleet utilizes
authentikas a bridge, syncing Google LDAP data to authentik and then pushing to Fleet via SCIM.
Sources: articles/foreign-vitals-map-idp-users-to-hosts.md:27-35, articles/foreign-vitals-map-idp-users-to-hosts.md:79-85, articles/foreign-vitals-map-idp-users-to-hosts.md:120-130
Host Mapping via Enrollment
Fleet captures IdP vitals during endpoint enrollment. If require_idp_authentication is enabled, the user must authenticate with the IdP before the host is fully enrolled.
This mapping enables the use of IdP attributes as variables in configuration profiles and criteria for automated labels.
Sources: articles/foreign-vitals-map-idp-users-to-hosts.md:7-15, tools/mdm/apple/glossary-and-protocols.md:5-15
Authentication Security & MFA
Fleet emphasizes strong authentication for privileged accounts to mitigate phishing and credential theft.
Multi-Factor Authentication (MFA)
For Google Workspace and other critical tool integrations, Fleet implements the following:
- Hardware Security Keys: Promotion of FIDO U2F/Yubico hardware keys for all privileged access.
- Method Disabling: Phasing out unsafe methods like SMS and voice-based 2FA.
- Onboarding: standardizing hardware key distribution during employee onboarding.
API Authentication
For automated systems, Slackbots, and GitOps workflows, Fleet uses API-only users. These users are authenticated via API tokens and restricted to specific endpoints, such as /scim/* for identity sync or /api/v1/fleet/gitops for configuration changes.
Sources: articles/tales-from-fleet-security-securing-google-workspace.md:55-65, tools/fleet-slackbot/system-prompt.js:10-20, articles/foreign-vitals-map-idp-users-to-hosts.md:38-42
Summary
Authentication and SSO in Fleet are designed to bridge the gap between central identity management and endpoint security. By integrating SAML for user logins and SCIM for host-to-user mapping, Fleet allows administrators to manage their entire fleet using the same identity context found in their IdP. This facilitates secure enrollment, automated policy application, and strict access controls for privileged administrative actions.