diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index 937408ec2c52..f66c79f1e751 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -585,16 +585,44 @@ Can only be configured for all teams (`org_settings`). #### mdm -The `mdm` section lets you enable MDM features in Fleet. +##### apple_business_manager -- `apple_bm_default_team` - is name of the team that macOS hosts in Apple Business Manager automatically enroll to when they're first set up. If empty, hosts will enroll to "No team" (default: `""`). +- `organization_name` is the organization name associated with the Apple Business Manager account. +- `macos_team` is the team where macOS hosts are automatically added when they appear in Apple Business Manager. +- `ios_team` is the the team where iOS hosts are automatically added when they appear in Apple Business Manager. +- `ipados_team` is the team where iPadOS hosts are automatically added when they appear in Apple Business Manager. ##### Example ```yaml org_settings: mdm: - apple_bm_default_team: "Workstations" # Available in Fleet Premium + apple_business_manager: # Available in Fleet Premium + - organization_name: Fleet Device Management Inc. + macos_team: "💻 Workstations" + ios_team: "📱🏢 Company-owned iPhones" + ipados_team: "🔳🏢 Company-owned iPads" +``` + +> Apple Business Manager settings can only be configured for all teams (`org_settings`). + +##### volume_purchasing_program + +- `location` is the name of the location in the Apple Business Manager account. +- `teams` is a list of team names. If you choose specific teams, App Store apps in this VPP account will only be available to install on hosts in these teams. If not specified, App Store apps are available to install on hosts in all teams. + +##### Example + +```yaml +org_settings: + mdm: + volume_purchasing_program: # Available in Fleet Premium + - location: Fleet Device Management Inc. + teams: + - "💻 Workstations" + - "💻🐣 Workstations (canary)" + - "📱🏢 Company-owned iPhones" + - "🔳🏢 Company-owned iPads" ``` Can only be configured for all teams (`org_settings`). diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index 3e75c98e58c4..ec39149199a1 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -531,9 +531,15 @@ The MDM endpoints exist to support the related command-line interface sub-comman - [Generate Apple Business Manager public key (ADE)](#generate-apple-business-manager-public-key-ade) - [Request Certificate Signing Request (CSR)](#request-certificate-signing-request-csr) - [Upload APNS certificate](#upload-apns-certificate) -- [Upload ABM Token](#upload-abm-token) +- [Add ABM token](#add-abm-token) - [Turn off Apple MDM](#turn-off-apple-mdm) -- [Disable automatic enrollment (ADE)](#disable-automatic-enrollment-ade) +- [Update ABM token's teams](#update-abm-tokens-teams) +- [Renew ABM token](#renew-abm-token) +- [Delete ABM token](#delete-abm-token) +- [Add VPP token](#add-VPP-token) +- [Update VPP token's teams](#update-vpp-tokens-teams) +- [Renew VPP token](#renew-vpp-token) +- [Delete VPP token](#delete-vpp-token) - [Batch-apply MDM custom settings](#batch-apply-mdm-custom-settings) - [Initiate SSO during DEP enrollment](#initiate-sso-during-dep-enrollment) - [Complete SSO during DEP enrollment](#complete-sso-during-dep-enrollment) @@ -620,9 +626,9 @@ Content-Type: application/octet-stream `Status: 200` -### Upload ABM Token +### Add ABM token -`POST /api/v1/fleet/mdm/apple/abm_token` +`POST /api/v1/fleet/abm_tokens` #### Parameters @@ -632,7 +638,7 @@ Content-Type: application/octet-stream #### Example -`POST /api/v1/fleet/mdm/apple/abm_token` +`POST /api/v1/fleet/abm_tokens` ##### Request header @@ -653,11 +659,23 @@ Content-Type: application/octet-stream --------------------------f02md47480und42y ``` - ##### Default response `Status: 200` +```json +"abm_token": { + "id": 1, + "apple_id": "apple@example.com", + "org_name": "Fleet Device Management Inc.", + "mdm_server_url": "https://example.com/mdm/apple/mdm", + "renew_date": "2024-10-20T00:00:00Z", + "terms_expired": false, + "macos_team": null, + "ios_team": null, + "ipados_team": null +} +``` ### Turn off Apple MDM @@ -671,19 +689,265 @@ Content-Type: application/octet-stream `Status: 204` +### Update ABM token's teams + +`PATCH /api/v1/fleet/abm_tokens/:id/teams` -### Disable automatic enrollment (ADE) +#### Parameters -`DELETE /api/v1/fleet/mdm/apple/abm_token` +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| id | integer | path | *Required* The ABM token's ID | +| macos_team_id | integer | body | macOS hosts are automatically added to this team in Fleet when they appear in Apple Business Manager. If not specified, defaults to "No team" | +| ios_team_id | integer | body | iOS hosts are automatically added to this team in Fleet when they appear in Apple Business Manager. If not specified, defaults to "No team" | +| ipados_team_id | integer | body | iPadOS hosts are automatically added to this team in Fleet when they appear in Apple Business Manager. If not specified, defaults to "No team" | #### Example -`DELETE /api/v1/fleet/mdm/apple/abm_token` +`PATCH /api/v1/fleet/abm_tokens/1/teams` + +##### Request body + +```json +{ + "macos_team_id": 1, + "ios_team_id": 2, + "ipados_team_id": 3 +} +``` + +##### Default response + +`Status: 200` + +```json +"abm_token": { + "id": 1, + "apple_id": "apple@example.com", + "org_name": "Fleet Device Management Inc.", + "mdm_server_url": "https://example.com/mdm/apple/mdm", + "renew_date": "2024-11-29T00:00:00Z", + "terms_expired": false, + "macos_team": 1, + "ios_team": 2, + "ipados_team": 3 +} +``` + +### Renew ABM token + +`PATCH /api/v1/fleet/abm_tokens/:id/renew` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| id | integer | path | *Required* The ABM token's ID | + +#### Example + +`PATCH /api/v1/fleet/abm_tokens/1/renew` + +##### Request header + +```http +Content-Length: 850 +Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y +``` + +##### Request body + +```http +--------------------------f02md47480und42y +Content-Disposition: form-data; name="token"; filename="server_token_abm.p7m" +Content-Type: application/octet-stream + + + +--------------------------f02md47480und42y +``` + +##### Default response + +`Status: 200` + +```json +"abm_token": { + "id": 1, + "apple_id": "apple@example.com", + "org_name": "Fleet Device Management Inc.", + "mdm_server_url": "https://example.com/mdm/apple/mdm", + "renew_date": "2025-10-20T00:00:00Z", + "terms_expired": false, + "macos_team": null, + "ios_team": null, + "ipados_team": null +} +``` + +### Delete ABM token + +`DELETE /api/v1/fleet/abm_tokens/:id` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| id | integer | path | *Required* The ABM token's ID | + +#### Example + +`DELETE /api/v1/fleet/abm_tokens/1` ##### Default response `Status: 204` +### Add VPP token + +`POST /api/v1/fleet/vpp_tokens` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| token | file | form | *Required* The file containing the content token (.vpptoken) from Apple Business Manager | + +#### Example + +`POST /api/v1/fleet/vpp_tokens` + +##### Request header + +```http +Content-Length: 850 +Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y +``` + +##### Request body + +```http +--------------------------f02md47480und42y +Content-Disposition: form-data; name="token"; filename="sToken_for_Acme.vpptoken" +Content-Type: application/octet-stream + +--------------------------f02md47480und42y +``` + +##### Default response + +`Status: 200` + +```json +"vpp_token": { + "id": 1, + "org_name": "Fleet Device Management Inc.", + "location": "https://example.com/mdm/apple/mdm", + "renew_date": "2024-10-20T00:00:00Z", + "terms_expired": false, + "teams": null +} +``` + +### Update VPP token's teams + +`PATCH /api/v1/fleet/vpp_tokens/:id/teams` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| id | integer | path | *Required* The ABM token's ID | +| team_ids | list | body | If you choose specific teams, App Store apps in this VPP account will only be available to install on hosts in these teams. If not specified, defaults to all teams. | + +#### Example + +`PATCH /api/v1/fleet/vpp_tokens/1/teams` + +##### Request body + +```json +{ + "team_ids": [1, 2, 3] +} +``` + +##### Default response + +`Status: 200` + +```json +"vpp_token": { + "id": 1, + "org_name": "Fleet Device Management Inc.", + "location": "https://example.com/mdm/apple/mdm", + "renew_date": "2024-10-20T00:00:00Z", + "terms_expired": false, + "teams": [1, 2, 3] +} +``` + +### Renew VPP token + +`PATCH /api/v1/fleet/vpp_tokens/:id/renew` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| id | integer | path | *Required* The VPP token's ID | + +##### Request header + +```http +Content-Length: 850 +Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y +``` + +##### Request body + +```http +--------------------------f02md47480und42y +Content-Disposition: form-data; name="token"; filename="sToken_for_Acme.vpptoken" +Content-Type: application/octet-stream + + + +--------------------------f02md47480und42y +``` + +##### Default response + +`Status: 200` + +```json +"vpp_token": { + "id": 1, + "org_name": "Fleet Device Management Inc.", + "location": "https://example.com/mdm/apple/mdm", + "renew_date": "2025-10-20T00:00:00Z", + "terms_expired": false, + "teams": [1, 2, 3] +} +``` + +### Delete VPP token + +`DELETE /api/v1/fleet/vpp_token/:id` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| id | integer | path | *Required* The VPP token's ID | + +#### Example + +`DELETE /api/v1/fleet/vpp_tokens/1` + +##### Default response + +`Status: 204` ### Batch-apply MDM custom settings diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index e31703b6fb6d..c160aac679ff 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -878,9 +878,6 @@ None. "additional_queries": null }, "mdm": { - "apple_bm_default_team": "", - "apple_bm_terms_expired": false, - "enabled_and_configured": true, "windows_enabled_and_configured": true, "enable_disk_encryption": true, "macos_updates": { @@ -1170,9 +1167,6 @@ Modifies the Fleet's configuration with the supplied information. "expiration": "0001-01-01T00:00:00Z" }, "mdm": { - "apple_bm_default_team": "", - "apple_bm_terms_expired": false, - "apple_bm_enabled_and_configured": false, "enabled_and_configured": false, "windows_enabled_and_configured": false, "enable_disk_encryption": true, @@ -1694,7 +1688,6 @@ _Available in Fleet Premium._ | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| apple_bm_default_team | string | _Available in Fleet Premium._ The default team to use with Apple Business Manager. | | windows_enabled_and_configured | boolean | Enables Windows MDM support. | | enable_disk_encryption | boolean | _Available in Fleet Premium._ Hosts that belong to no team will have disk encryption enabled if set to true. | | macos_updates | object | See [`mdm.macos_updates`](#mdm-macos-updates). | @@ -1811,7 +1804,6 @@ _Available in Fleet Premium._ ```json { "mdm": { - "apple_bm_default_team": "", "windows_enabled_and_configured": false, "enable_disk_encryption": true, "macos_updates": { @@ -6261,8 +6253,8 @@ This endpoint returns the list of custom MDM commands that have been executed. ## Integrations - [Get Apple Push Notification service (APNs)](#get-apple-push-notification-service-apns) -- [Get Apple Business Manager (ABM)](#get-apple-business-manager-abm) -- [Get Volume Purchasing Program (VPP)](#get-volume-purchasing-program-vpp) +- [List Apple Business Manager (ABM) tokens](#list-apple-business-manager-abm-tokens) +- [List Volume Purchasing Program (VPP) tokens](#list-volume-purchasing-program-vpp-tokens) ### Get Apple Push Notification service (APNs) @@ -6289,11 +6281,11 @@ None. } ``` -### Get Apple Business Manager (ABM) +### List Apple Business Manager (ABM) tokens _Available in Fleet Premium_ -`GET /api/v1/fleet/abm` +`GET /api/v1/fleet/abm_tokens` #### Parameters @@ -6301,20 +6293,82 @@ None. #### Example -`GET /api/v1/fleet/abm` +`GET /api/v1/fleet/abm_tokens` ##### Default response `Status: 200` ```json -{ - "apple_id": "apple@example.com", - "org_name": "Fleet Device Management", - "mdm_server_url": "https://example.com/mdm/apple/mdm", - "renew_date": "2023-11-29T00:00:00Z", - "default_team": "" -} +"abm_tokens": [ + { + "id": 1, + "apple_id": "apple@example.com", + "org_name": "Fleet Device Management Inc.", + "mdm_server_url": "https://example.com/mdm/apple/mdm", + "renew_date": "2023-11-29T00:00:00Z", + "terms_expired": false, + "macos_team": { + "name": "💻 Workstations", + "id" 1 + }, + "ios_team": { + "name": "📱🏢 Company-owned iPhones", + "id": 2 + }, + "ipados_team": { + "name": "🔳🏢 Company-owned iPads", + "id": 3 + } + } +] +``` + +### List Volume Purchasing Program (VPP) tokens + +_Available in Fleet Premium_ + +`GET /api/v1/fleet/vpp_tokens` + +#### Parameters + +None. + +#### Example + +`GET /api/v1/fleet/vpp_tokens` + +##### Default response + +`Status: 200` + +```json +"vpp_tokens": [ + { + "id": 1, + "org_name": "Fleet Device Management Inc.", + "location": "https://example.com/mdm/apple/mdm", + "renew_date": "2023-11-29T00:00:00Z", + "teams": [ + { + "name": "💻 Workstations", + "id": 1 + }, + { + "name": "💻🐣 Workstations (canary)", + "id": 2 + }, + { + "name": "📱🏢 Company-owned iPhones", + "id": 3 + }, + { + "name": "🔳🏢 Company-owned iPads", + "id" 4 + } + ], + } +] ``` Get Volume Purchasing Program (VPP) diff --git a/website/config/routes.js b/website/config/routes.js index 2252a7072945..8c9991200f3a 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -559,6 +559,9 @@ module.exports.routes = { 'GET /learn-more-about/host-identifiers': '/docs/rest-api/rest-api#get-host-by-identifier', 'GET /learn-more-about/uninstall-fleetd': '/docs/using-fleet/faq#how-can-i-uninstall-fleetd', 'GET /learn-more-about/vulnerability-processing': '/docs/using-fleet/vulnerability-processing', + 'GET /learn-more-about/apple-business-manager-tokens-api': '/docs/rest-api/rest-api#list-apple-business-manager-abm-tokens', + 'GET /learn-more-about/apple-business-manager-teams-api': 'https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#update-abm-tokens-teams', + 'GET /learn-more-about/apple-business-manager-gitops': '/docs/using-fleet/gitops#apple-business-manager', 'GET /learn-more-about/s3-bootstrap-package': '/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket', // Sitemap