GitOps & API design: Add multiple Apple Business Manager and Volume Purchasing Program connections #21043
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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) | ||
| - [Add ABM token](#add-abm-token) | ||
| - [Turn off Apple MDM](#turn-off-apple-mdm) | ||
| - [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` | ||
|
|
||
| ### Add ABM token | ||
|
|
||
| `POST /api/v1/fleet/abm_tokens` | ||
|
|
||
| #### Parameters | ||
|
|
||
|
|
@@ -632,7 +638,7 @@ Content-Type: application/octet-stream | |
|
|
||
| #### Example | ||
|
|
||
| `POST /api/v1/fleet/abm_tokens` | ||
|
|
||
| ##### Request header | ||
|
|
||
|
|
@@ -653,11 +659,23 @@ Content-Type: application/octet-stream | |
| --------------------------f02md47480und42y | ||
| ``` | ||
|
|
||
| ##### Default response | ||
mna marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| `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": "", | ||
| "ios_team": "", | ||
| "ipados_team": "" | ||
rachaelshaw marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| ``` | ||
|
|
||
| ### 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` | ||
|
|
||
| #### Parameters | ||
|
|
||
| | 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 | ||
|
|
||
| `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` | ||
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
Sorry, something went wrong. |
||
|
|
||
| #### 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` | ||
jahzielv marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ```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 | ||
|
There was a problem hiding this comment. Dev noteThis is not a whole new endpoint. We added an upload VPP token endpoint as part of #18867: https://github.com/fleetdm/fleet/pull/19291/files#diff-831a63ebb3cab9b4e6b82d803d9ffcdc3722b12d486dcd7b13e9576643bb50b0R874 |
||
|
|
||
| `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 | ||
|
There was a problem hiding this comment. @noahtalerman as for the Add ABM token, I'd suggest returning a payload of the newly created VPP token here (similar to how it gets represented in If that sounds good to you I can push that update. There was a problem hiding this comment. That looks good! Please feel free to push that update. cc @dantecatalfamo @marko-lisica There was a problem hiding this comment. @mna I updated PR to include a payload. I did the same for:
They now include payload (vpp_token details after upload/update). I realized we do this in other endpoints, such as create/update policy or create/update query. |
||
|
|
||
| `Status: 200` | ||
|
|
||
|
There was a problem hiding this comment. Dev noteIf the user hits
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
Sorry, something went wrong. |
||
| ```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. | | ||
|
There was a problem hiding this comment. Note for whoever will work on the VPP API ticket - we decided to limit 1 VPP token to a single team (or "no team" or "all teams") for this release: https://fleetdm.slack.com/archives/C03C41L5YEL/p1723561317435649 There was a problem hiding this comment. update: this is incorrect, a VPP token can be assigned to multiple teams but a team can only have 1 VPP token |
||
|
|
||
| #### Example | ||
|
|
||
| `PATCH /api/v1/fleet/vpp_tokens/1/teams` | ||
|
|
||
| ##### Request body | ||
|
|
||
| ```json | ||
| { | ||
| "team_ids": [1, 2, 3] | ||
|
There was a problem hiding this comment. @noahtalerman to patch it back to 'all teams' I think it should be [] thoughts? There was a problem hiding this comment. Nice catch. I forgot about all teams. How do we solve this in existing API endpoints? I think let's be consistent with what we do in other API endpoints. If that's There was a problem hiding this comment. Instead of adding another key, can we introduce the convention that passing an empty array for teams means "All teams"? Does that conflict with any of the other endpoints? There was a problem hiding this comment. @noahtalerman In the current iteration we only support one team per VPP token, should we be passing in an array and validating that it only has one element or making a top level There was a problem hiding this comment. Moving forward with:
|
||
| } | ||
| ``` | ||
|
|
||
| ##### 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 | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dev note
We can break this endpoint and others because they're in the contributor docs.