GitOps & API design: Add multiple Apple Business Manager and Volume P…

…urchasing Program connections (#21043) GitOps and API changes for the following story: - #9956 DONE: - ~~Contributor API endpoints to support best practice GitOps (`fleetctl gitops`) and backwards compatibility GitOps (`fleetctl apply`)~~ - #21043 (comment) --------- Co-authored-by: Martin Angers <martin.n.angers@gmail.com> Co-authored-by: Dante Catalfamo <43040593+dantecatalfamo@users.noreply.github.com> Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com> Co-authored-by: George Karr <georgekarrv@users.noreply.github.com> Co-authored-by: Gabriel Hernandez <ghernandez345@gmail.com> Co-authored-by: Rachael Shaw <r@rachael.wtf>
fleetdm · Sep 20, 2024 · 1677783 · 1677783
1 parent eeb0579
commit 1677783
Show file tree

Hide file tree

Showing 4 changed files with 381 additions and 32 deletions.
diff --git 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
@@ -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
+
+<TOKEN_DATA>
+
+--------------------------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
+<TOKEN_DATA>
+--------------------------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
+
+<TOKEN_DATA>
+
+--------------------------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