Skip to content

Commit 921a3e6

Browse files
GirlBossRushtanberry
GirlBossRush
and
tanberry
authored
website/docs: Add Fleet integration. (#13618)
* website/docs: Add Fleet integration. * Apply suggestions from code review Co-authored-by: Tana M Berry <[email protected]> Signed-off-by: Teffen Ellis <[email protected]> * Update website/integrations/services/fleet/index.md Signed-off-by: Teffen Ellis <[email protected]> * Apply suggestions from code review Co-authored-by: Tana M Berry <[email protected]> Signed-off-by: Teffen Ellis <[email protected]> * Update index.md Signed-off-by: Teffen Ellis <[email protected]> * website/docs: Reorder. --------- Signed-off-by: Teffen Ellis <[email protected]> Co-authored-by: Tana M Berry <[email protected]>
1 parent fd898be commit 921a3e6

File tree

3 files changed

+153
-1
lines changed

3 files changed

+153
-1
lines changed

‎website/integrations/services/apple/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ tags:
77
- apple
88
- ssf
99
- backchannel
10+
- device-management
1011
authentik_version: "2025.2.0"
1112
authentik_enterprise: true
1213
authentik_preview: true

‎website/integrations/services/fleet/index.md

+151
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Integrate with Fleet
3+
sidebar_label: Fleet
4+
support_level: authentik
5+
tags:
6+
- integration
7+
- device-management
8+
authentik_enterprise: true
9+
authentik_preview: true
10+
---
11+
12+
## What is Fleet
13+
14+
> Fleet is an open source device management (MDM) platform for vulnerability reporting, detection engineering, device health monitoring, posture-based access control, managing unused software licenses, and more.
15+
>
16+
> -- [Fleet](https://fleetdm.com/)
17+
18+
## Preparation
19+
20+
By the end of this integration, your users will be able to log into Fleet using their authentik credentials.
21+
22+
Your authentik and Fleet instances must both be running and accessible on an HTTPS domain.
23+
24+
### Placeholders
25+
26+
The following placeholders are used in this guide:
27+
28+
- `authentik.company`: The FQDN of the authentik installation.
29+
- `fleet.company`: The FQDN of the Fleet installation.
30+
31+
## authentik configuration
32+
33+
The workflow to configure authentik as a single sign-on for Fleet involves creating an application and SAML provider pair. Following this configuration process will generate the necessary metadata you will use to configure Fleet to trust authentik as an identity provider.
34+
35+
### Create an application and provider
36+
37+
1. From the authentik Admin interface, navigate to **Applications -> Applications** and click **Create with Provider** to create an application and provider pair.
38+
39+
2. For the **App name** enter `Fleet` and click **Next**.
40+
41+
3. For the **Provider Type** select **SAML**, click **Next**, and use the following values.
42+
43+
- **Name**: `Fleet`
44+
- **Authorization flow**: Select a flow that suits your organization's requirements.
45+
- **Protocol settings**:
46+
47+
- **Assertion Consumer Service URL**: `https://fleet.company/api/v1/fleet/sso/callback`
48+
49+
:::info Requiring an End User License Agreement
50+
51+
If you require end users to agree to an end user license agreement (EULA) before they can use their device, you will need to modify the **Assertion Consumer Service URL**.
52+
53+
```diff
54+
- https://fleet.company/api/v1/fleet/sso/callback
55+
+ https://fleet.company/api/v1/fleet/mdm/sso/callback
56+
```
57+
58+
You will also need to configure Fleet with additional settings to enable the EULA. For more information, refer to Fleet's [end user authentication guide](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula).
59+
:::
60+
61+
- **Issuer**: `authentik`
62+
This value is used to identify authentik as the identity provider to Fleet. It can be any string, but it must be unique and used consistently across both authentik and Fleet configurations.
63+
- **Service Provider Binding**: `Post`
64+
- **Audience**: `https://fleet.company`
65+
- **Advanced protocol settings**:
66+
(Any fields that can be left as their default values are omitted from the list below).
67+
68+
- **Signing Certificate**: Select a certificate enable **Sign assertions** and **Sign responses**.
69+
- **NameID Property Mapping**: `authentik default SAML Mapping: Email`
70+
71+
4. Click **Next**, review the configuration details, and click **Submit**.
72+
73+
### Retrieve provider metadata
74+
75+
1. From the authentik Admin interface, navigate to **Applications -> Providers** and click the Fleet SAML provider.
76+
77+
2. In the **Related Objects** section, click **Copy download URL** to copy the metadata URL to your clipboard. Paste this URL to a text editor as you will need it when configuring Fleet.
78+
79+
:::tip Downloading the metadata file
80+
81+
If you prefer to download the metadata file, clicking **Download** will save an XML file to your local machine. The choice to download or copy the metadata URL will have no impact on the configuration process in Fleet.
82+
83+
:::
84+
85+
## Fleet configuration
86+
87+
With these prerequisites in place, authentik is now configured to act as a single sign-on provider for Fleet. The next step is to configure Fleet to trust authentik as an identity provider.
88+
89+
1. From the Fleet dashboard, click your avatar in the page header and select **Settings**.
90+
91+
2. In the **Organization settings** tab, click **Single sign-on options**.
92+
93+
3. Check the box next to **Enable single sign-on** and use the following values:
94+
95+
- **Identity provider name**: `authentik`
96+
- **Entity ID**: `authentik`
97+
98+
- **Metadata/Metadata URL**
99+
100+
Fleet's SSO configuration form will include two fields: **Metadata URL** and **Metadata**.
101+
Only one of these fields is required, but you must provide at least one of them.
102+
103+
- If you copied the **Metadata URL** from authentik, paste the URL you copied earlier into the **Metadata URL** field.
104+
105+
- If you downloaded the metadata file from authentik, paste the contents of the XML file into the **Metadata** field.
106+
107+
- **Allow SSO login initiated by identity provider**: Check this box to allow users to log in to Fleet using the authentik login page.
108+
109+
4. Click **Save** to apply the changes.
110+
111+
## Configuration verification
112+
113+
To verify that authentik and Fleet are correctly configured, you can test the SSO flow with a user account.
114+
115+
### Create a test user
116+
117+
1. From the authentik Admin interface, navigate to **Directory -> Users** and click **Create**.
118+
2. Enter the following details for the test user. All other fields can be left as their default values.
119+
120+
- **Name**: `Jessie Lorem`
121+
- **Email**: `[email protected]`
122+
123+
3. Click **Create** and verify that the user is listed in the **Users** table.
124+
125+
4. From the Fleet Admin interface, navigate to **Settings -> Users** and click **Add user**.
126+
127+
5. Enter the following details for the test user. All other fields can be left as their default values.
128+
129+
- **Full Name**: `Jessie Lorem`
130+
- **Email**: `[email protected]`
131+
- **Authentication**: `Single sign-on`
132+
- **Role**: `Observer`
133+
134+
6. Click **Add** and verify that the user is listed in the **Users** table.
135+
136+
### Test the SSO flow
137+
138+
1. In a private browsing window, navigate to your Fleet instance and click **Sign on with authentik**.
139+
2. After being redirected to the authentik login page, enter the test user's email address and password.
140+
141+
After you are authenticated, you should be redirected back to the Fleet and logged in as the test user. This confirms that the SSO flow is working as expected.
142+
143+
#### Troubleshooting
144+
145+
If the SSO authentication fails, your configuration may be incorrect. Here are some common issues to check:
146+
147+
- [x] Verify that your authentik instance is accessible from the internet from an HTTPS domain.
148+
- [x] Verify that the Fleet instance is accessible from the internet from an HTTPS domain.
149+
- [x] Ensure that your test user is not the default super-admin user.
150+
- [x] Check that your test user has a matching email address in both authentik and Fleet.
151+
- [x] Check that the test user has Single sign-on authentication enabled in Fleet.

‎website/sidebarsIntegrations.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ module.exports = {
1616
{
1717
type: "category",
1818
label: "Device Management",
19-
items: ["services/apple/index"],
19+
items: ["services/apple/index", "services/fleet/index"],
2020
},
2121
{
2222
type: "category",

0 commit comments

Comments
 (0)