Skip to content

Add OIN instructions to SSO configuration documentation #34861

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
tux234 wants to merge 11 commits into
base: main
Choose a base branch
from
+240 −20
Draft

Add OIN instructions to SSO configuration documentation #34861

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
98a453a
Add OIN instructions to SSO configuration documentation
tux234 Oct 28, 2025
256d5f3
Remove help section from SSO documentation
tux234 Nov 25, 2025
88dddf9
Update single-sign-on-sso.md
tux234 Dec 1, 2025
5b95ca3
Update foreign-vitals-map-idp-users-to-hosts.md
tux234 Dec 2, 2025
e786edd
Update single-sign-on-sso.md
tux234 Dec 2, 2025
d504a72
Update single-sign-on-sso.md
tux234 Dec 2, 2025
dcc6ca4
Update single-sign-on-sso.md
tux234 Dec 5, 2025
44bcee6
Update single-sign-on-sso.md
tux234 Dec 5, 2025
3680386
Update single-sign-on-sso.md
tux234 Dec 5, 2025
b654bc6
Update SSO API integration steps in documentation
tux234 Dec 10, 2025
8f1ed24
Add 'End users' step for SSO configuration in Fleet
tux234 Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 56 additions & 12 deletions articles/foreign-vitals-map-idp-users-to-hosts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,29 @@ Learn how to enforce authentication in the [setup experience guide](https://flee

## Okta

Fleet's Okta integration supports the following SCIM features:

**Provisioning to Fleet (Push):**
- Push New Users - Create new users in Fleet from Okta
- Push Profile Updates - Update existing user attributes in Fleet when changed in Okta
- Push Groups - Provision Okta groups to Fleet and maintain group memberships
- Deactivate Users - Remove user access when deactivated in Okta

**Provisioning from Fleet (Import):**
- Import New Users - Not supported (Fleet does not create users in Okta)
- Import Profile Updates - Not supported (Fleet does not modify Okta user profiles)

To map users from Okta to hosts in Fleet, we'll do the following steps:

1. [Create application in Okta](#step-1-create-application-in-okta)
2. [Connect Okta to Fleet](#step-2-connect-okta-to-fleet)
3. [Map users and groups to hosts in Fleet](#step-3-map-users-and-groups-to-hosts-in-fleet)
3. [Enable provisioning to Fleet](#step-3-enable-provisioning-to-fleet)
4. [Assign users to the application](#step-4-assign-users-to-the-application)
5. [Configure push groups](#step-5-configure-push-groups)

#### Step 1: Create application in Okta
#### Step 1: Create an application in Okta

1. Head to Okta admin dashboard.
1. Head to the Okta admin dashboard.
2. In the main menu, select **Applications > Applications**, then select **Create App Integration**.
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**.
Expand All @@ -45,20 +59,50 @@ To map users from Okta to hosts in Fleet, we'll do the following steps:
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.
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.

#### Step 3: Enable provisioning to Fleet

1. Under the **Provisioning** tab, select **To App** and then select **Edit** in the **Provisioning to App** section.
2. Enable **Create Users**, **Update User Attributes**, and **Deactivate Users**, then select **Save**.
3. On the same page, verify that `givenName` and `familyName` have Okta values assigned to them. Currently, Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Fleet also supports the `department` attribute (optional). Delete the rest of the attributes.
![Okta SCIM attributes mapping](../website/assets/images/articles/okta-scim-attributes-mapping-402x181@2x.png)

#### Step 3: Map users and groups to hosts in Fleet
#### Step 4: Assign users to the application

To send users and groups information to Fleet, you have to assign them to your new SCIM app.
To send user information to Fleet, assign users to your SCIM app. You can assign users individually or by group.

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.
**Option A: Assign by group (recommended)**
1. In Okta's main menu, select **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.
![Okta group rule](../website/assets/images/articles/okta-scim-group-rules-1000x522@2x.png)
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. In the main menu, select **Applications > Applications** and select your 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. Select **Done**.

**Option B: Assign individual users**
1. In the main menu, select **Applications > Applications** and select your SCIM app.
2. Select the **Assignments** tab, then **Assign > Assign to People**.
3. Select **Assign** next to each user you want to provision to Fleet, then select **Done**.

#### Step 5: Configure push groups

Group Push provisions Okta groups to Fleet and maintains group memberships. For a user's group memberships to appear in Fleet:
- The user must be assigned to the Fleet SCIM application (see Step 4)
- The user must be a member of the group in Okta
- The group must be configured for Push in the application

To enable Group Push:

1. In your Fleet SCIM app, select the **Push Groups** tab.
2. Select **Push Groups > Find groups by name**.
3. Search for and add the groups you want to provision to Fleet (e.g., "Fleet human-device mapping" and any other groups assigned to the app).
4. Ensure **Push group memberships immediately** is selected for each group.
5. Select **Save**.

**Important notes about Group Push:**
- Only users who are both assigned to the app AND members of pushed groups will have group data in Fleet
- If you remove a user from a pushed group in Okta, the group membership will be removed from Fleet
- If you unassign a user from the app, all their group memberships will be removed from Fleet
- Group push happens immediately, but can take a few minutes to reflect in Fleet

## Microsoft Entra ID

Expand Down
192 changes: 184 additions & 8 deletions docs/Deploy/single-sign-on-sso.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,177 @@ To configure SSO, follow steps for your IdP and then complete [Fleet configurati

> JIT? SAML implementation supports just-in-time (JIT) user provisioning, as well as both IdP-initiated login and service-initiated (SP) login.

**Using Fleet MDM?** If you're using automatic enrollment (ADE/DEP), you'll need two separate SSO apps in your IdP - one for your admin console and one for end user authentication during device setup. See [End user authentication for MDM](#end-user-authentication-for-mdm) after you've configured your IdP.

## Okta

Create a new SAML app in Okta:
Fleet offers two ways to set up Okta:

1. **[Okta Integration Network (OIN)](#okta-integration-network-oin)** - Use the pre-configured Fleet app from Okta's catalog (recommended)
2. **[Custom SAML app](#okta-custom-saml-app)** - Manually create a SAML app in Okta (for testing or advanced configs)

### Okta Integration Network (OIN)

The Fleet app is available in Okta's catalog. This is the fastest way to set up SAML SSO and SCIM provisioning for your Fleet admin console.

**Note:** The OIN app is for Fleet admin/user access only. If you're using MDM with automatic enrollment, you'll need a separate custom SAML app for end user authentication during device setup. See [End user authentication for MDM](#end-user-authentication-for-mdm).

**What you'll need:**
- Fleet Premium license
- Fleet admin access
- Okta admin access

#### Supported features

**SAML 2.0 Single Sign-On:**
- SP-initiated SSO
- IdP-initiated SSO
- Just-In-Time (JIT) provisioning

**SCIM 2.0 Provisioning:**
- Create users
- Update user attributes
- Deactivate users
- Reactivate users
- Push groups

**Note:** Fleet doesn't support importing users or profile updates from Fleet back to Okta (one-way sync only).

#### Set up SAML SSO

1. Sign in to your Okta Admin Console
2. Go to **Applications** > **Applications** > **Browse App Catalog**
3. Search for "Fleet" and select it
4. Click **Add Integration**
5. Configure the basics:
- **Application Label**: Name for your Fleet instance (e.g., "Fleet Production")
- **Entity ID**: Must match exactly what you set in Fleet under **Settings > Integrations > Single sign-on (SSO)** (e.g., `fleet`)
- **Fleet instance base URL**: Your Fleet URL from **Settings > Organization settings > Fleet web address** (e.g., `fleetprod.cloud.fleetdm.com`)
> Note: Be sure to omit `https://` as it will be added automatically when the app is created in Okta.

6. Assign users:
- Go to the **Assignments** tab
- Click **Assign** and choose **Assign to People** or **Assign to Groups**
- Select users or groups, then click **Done**

7. Complete the Fleet side:
- In Okta, go to your Fleet app's **Sign On** tab
- Under **SAML 2.0** > **Metadata details**, copy the **Metadata URL**
- In Fleet, go to **Settings** > **Integrations** > **Single sign-on (SSO)** > **End users**
- Check **Enable single sign-on**
- **Identity provider name**: `Okta` (or whatever you want)
- **Entity ID**: Must match Okta exactly (e.g., `fleet`)
- **Metadata URL**: Paste the URL from Okta
- Click **Save**

Fleet's SAML implementation requires the following attributes to be populated in Okta:
- `username`
- `displayName`

Fleet also has [optional](#customization-of-user-roles) attributes that can be used for Just-In-Time (JIT) provisioning to assign administrative roles to Fleet globally or to a specific team.

**Important:** The Entity ID must match exactly between Okta and Fleet or SSO won't work.

Once SAML is configured, users can sign in directly from your Fleet instance login page by clicking **Login with Okta**. No need to go through the Okta dashboard.

#### Set up SCIM provisioning (optional)

SCIM lets you automatically provision users and groups from Okta to Fleet. This is separate from SAML SSO - you can use SAML without SCIM, but SCIM requires SAML to be configured first.

**What SCIM does:**
- Automatically creates Fleet users when assigned in Okta
- Syncs user profile changes (name, email, department)
- Deactivates users when unassigned
- Syncs group memberships

**Step 1: Connect Okta to Fleet**

1. In your Fleet Okta app, go to the **Provisioning** tab
2. Click **Configure API Integration**
3. Check **Enable API integration**
4. Generate your Fleet API token:
- [Create a Fleet API-only user](https://fleetdm.com/guides/fleetctl#create-api-only-user) with maintainer permissions
- Copy the API token and paste it in Okta's **Authorization** field
5. Click **Test API Credentials** - you should see a success message
6. In Fleet, go to **Settings > Integrations > Identity provider (IdP)** and verify Fleet received the test request
7. Back in Okta, click **Save**

**Step 2: Enable provisioning**

1. Under the **Provisioning** tab, select **To App**
2. Click **Edit** in the **Provisioning to App** section
3. Enable:
- **Create Users**
- **Update User Attributes**
- **Deactivate Users**
4. Click **Save**
5. Verify attributes are mapped correctly:
- Required: `userName`, `givenName`, `familyName`
- Optional: `department`
- Delete any other attributes

**Step 3: Configure push groups**

Group Push syncs Okta groups to Fleet. For group memberships to work, users must:
- Be assigned to the Fleet app in Okta
- Be members of the group in Okta
- Have the group configured for Push

To enable Group Push:

1. Go to the **Push Groups** tab
2. Click **Push Groups** > **Find groups by name**
3. Search for and add groups you want to sync to Fleet
4. Make sure **Push group memberships immediately** is checked
5. Click **Save**

**Important:** Only users who are both assigned to the app AND members of pushed groups will have group data in Fleet. If you remove a user from a group or unassign them from the app, their group memberships in Fleet will be removed.

#### Verify everything works

1. Sign in to Fleet as an admin
2. Go to **Settings** > **Integrations** > **Identity provider (IdP)**
3. Check that Fleet's receiving requests from Okta
4. Verify users and groups are showing up correctly

#### Troubleshooting

**SAML authentication issues:**
- Verify your Fleet Server URL doesn't have a trailing slash
- Confirm users are assigned to the Fleet app in Okta
- Check that the Entity ID matches exactly in both Okta and Fleet
- If you're not using SCIM, verify JIT provisioning is enabled in Fleet

**Users not provisioning via SCIM:**
- Check your API token is valid and has maintainer permissions
- Look for errors in Okta's **Provisioning** tab under **View Logs**
- Verify required attributes (userName, givenName, familyName) are mapped
- Double-check your Base URL format: `https://your-fleet-instance.com/api/v1/fleet/scim`

**Group membership not syncing:**
- Confirm groups are added in the **Push Groups** tab
- Check that **Push group memberships immediately** is enabled
- Verify users are actually members of the pushed groups in Okta
- Remember: users must be assigned to the app to see group data

### Okta custom SAML app

Create a custom SAML app in Okta if you're testing configurations or setting up [end user authentication for MDM](#end-user-authentication-for-mdm).

![Example Okta IdP Configuration](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/okta-idp-setup.png)

If you're configuring [end user authentication](https://fleetdm.com/guides/macos-setup-experience#end-user-authentication-and-end-user-license-agreement-eula), use `https://<your_fleet_url>/api/v1/fleet/mdm/sso/callback` for the **Single sign on URL** instead.
**For MDM end user authentication**, use `https://<your_fleet_url>/api/v1/fleet/mdm/sso/callback` as the **Single sign on URL** instead of the regular callback.

Once configured, you will need to retrieve the issuer URI from **View Setup Instructions** and metadata URL from the **Identity Provider metadata** link within the application **Sign on** settings. See below for where to find them:
Once configured, you'll need:
- **Issuer URI** from **View Setup Instructions**
- **Metadata URL** from the **Identity Provider metadata** link in the app's **Sign on** settings

![Where to find SSO links for Fleet](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/okta-retrieve-links.png)

> The Provider Sign-on URL within **View Setup Instructions** has a similar format as the Provider SAML Metadata URL, but this link provides a redirect to _sign into_ the application, not the metadata necessary for dynamic configuration.
> **Note:** The Provider Sign-on URL has a similar format to the metadata URL, but it's for signing into the app, not for metadata configuration. Make sure you grab the metadata URL.

## Google Workspace

If you're configuring [end user authentication](https://fleetdm.com/guides/macos-setup-experience#end-user-authentication-and-end-user-license-agreement-eula), use `https://<your_fleet_url>/api/v1/fleet/mdm/sso/callback` for the **Single sign on URL** instead.

Create a new SAML app in Google Workspace:

1. Navigate to the [Web and Mobile Apps](https://admin.google.com/ac/apps/unified) section of the Google Workspace dashboard. Click **Add App -> Add custom SAML app**.
Expand Down Expand Up @@ -65,7 +217,6 @@ Create a new SAML app in Google Workspace:
8. Enable SSO for a test user and try logging in. Note that Google sometimes takes a long time to propagate the SSO configuration, and it can help to try logging in to Fleet with an Incognito/Private window in the browser.

## Entra

Create a new SAML app in Microsoft Entra Admin Center:
1. From the left sidebar, navigate to **Applications > Enterprise Applications**.
2. At the top of the page, click **+ New Application**.
Expand Down Expand Up @@ -102,7 +253,7 @@ Fleet can be configured to use authentik as an identity provider. To continue, y

1. Log in to authentik and click **Admin interface**.

2. Navigate to **Applications -> Applications** and click **Create with Provider** to create an application and provider pair.
2. Navigate to **Applications -> Applications** and click **Create with Provider** to create an application and provider pair.

3. Enter "Fleet" for the **App name** and click **Next**.

Expand Down Expand Up @@ -140,6 +291,31 @@ IdPs generally requires the following information:

After supplying the above information, your IdP will generate an issuer URI and metadata that will be used to configure Fleet as a service provider.

## End user authentication for MDM

If you're using Fleet MDM with automatic enrollment (ADE/DEP), you need **two separate SSO apps** in your IdP - one for the Fleet admin console and one for end user authentication during device setup.

**Why two apps?**

Having separate apps gives you flexibility with security:
- **Admin console app**: Fleet admins and users sign into Fleet's web UI (`/api/v1/fleet/sso/callback`)
- **End user auth app**: Employees authenticate during out-of-box macOS setup (`/api/v1/fleet/mdm/sso/callback`)

With two apps, you can apply different conditional access policies or security controls. Maybe you want MFA required for admins but not during device setup. Or stricter device compliance checks for the admin portal. Separate apps let you tailor security to each use case.

**Setting up the end user authentication app:**

You'll need to create a custom SAML app for end user authentication. The OIN app doesn't support the MDM callback URL yet.

1. Create a new custom SAML app in your IdP (follow the [Okta custom SAML app](#okta-custom-saml-app) instructions if using Okta)
2. Use `https://<your_fleet_url>/api/v1/fleet/mdm/sso/callback` for the SSO callback URL
3. Set **Name ID** to email (required) - Fleet uses this to populate the macOS account name
4. Assign users who'll be setting up new Macs
5. In Fleet, go to **Settings** > **Integrations** > **Mobile device management (MDM)** > **End user authentication** and configure the connection
6. Enable it at **Controls** > **Setup experience** > **End user authentication**

For complete setup instructions, see the [macOS setup experience guide](https://fleetdm.com/guides/macos-setup-experience#end-user-authentication-and-end-user-license-agreement-eula).

## Fleet configuration

To configure SSO in Fleet head to **Settings > Integrations > Single sign-on (SSO)**.
Expand Down