[API] Enhance REST API documentation for profiles - #49768
Merged
Conversation
Added activation criteria and updated profile parameters for Fleet Premium features.
Updated the request body example to use 'DDM.json' instead of 'Passcode.json'.
49 tasks
Added activation field to profile JSON structure and updated documentation for activation criteria.
Added activation field to the response example.
Changed the type of 'activation' from file to string and specified that it should be Base64 encoded.
rachaelshaw
approved these changes
Aug 3, 2026
raju249
added a commit
that referenced
this pull request
Aug 5, 2026
…es (#50280) **Related issue:** Resolves #49970 Adds custom activations to the single-profile paths for declaration (DDM) profiles — create, edit, delete and read — and unblocks management declarations. Part of #48222. Batch/GitOps is #49972; serving the custom activation to devices is #49971. ### Custom activations - `POST /configuration_profiles` and `PATCH /configuration_profiles/{uuid}` accept an optional `activation` file part, rejected for any profile type other than an Apple declaration. - Validation requires an activation `Type` (any `com.apple.activation.*`, so future Apple types need no Fleet change), an `Identifier`, and exactly one `StandardConfigurations` entry naming the configuration it ships with. `Predicate` and every other key are stored and served verbatim for the device to evaluate. - Premium-only, unconditionally. `parseAndValidateAppleDeclaration` requires premium only when a fleet or labels are involved, so an unassigned unlabeled DDM profile is free today; the activation carries its own gate. - The activation's Fleet variables are validated against `fleetVarsSupportedInDDMDeclarations` — already exactly the set specified for activations — and associated via `mdm_configuration_profile_variables.apple_ddm_activation_uuid`. - Returned base64-encoded on both the list and single-profile endpoints, per the API reference draft (#49768), and omitted entirely when absent. What an edit does to a stored activation: | Request | Result | | --- | --- | | activation supplied | replaces the stored one | | new profile content, no activation | stored one is cleared — this is how it's removed | | labels-only edit | stored one is carried forward | The third row matters: the datastore clears the activation of any declaration written without one, so a labels-only edit rebuilding the declaration from the existing row would otherwise silently wipe it. `GetMDMAppleDeclaration` loads the activation so it can be carried forward, and there's a test asserting it. ### Management declarations `com.apple.management.*` uploads are unblocked via a prefix check, so future management declarations work without a product change. Types to block go in the existing `ForbiddenDeclTypes` deny list, which is already evaluated ahead of the prefix. An activation supplied alongside a management declaration is rejected — those are never activated. Routing them to the manifest's Management section is #49971's work. ### Notes for review **Where the non-declaration guard lives differs by path, deliberately.** Create resolves the profile type in the endpoint from the uploaded file; edit resolves it in the service from the UUID prefix. The check sits wherever the type becomes known. Both use the same message so the mistake reads identically. **Endpoint-level errors must be returned from behind an authz check.** The create-path guard originally returned the error straight from the endpoint, which skips authorization and surfaces to the client as a bare `forbidden` rather than the validation message. It now goes through `NewMDMActivationUnsupportedProfile`, alongside the existing `NewMDMUnsupportedConfigProfile` and `NewMDMInvalidJSONConfigProfile`, which exist for the same reason. This was caught by the integration tests, not the unit tests — service-level tests bypass the authz middleware. **Activation rows are keyed on `declaration_uuid`, not inserted fresh.** An edit reuses the row, so the Fleet variable associations hanging off it survive. The UUID is read back after the upsert rather than reusing the generated one, since `ON DUPLICATE KEY UPDATE` keeps the existing row. **Secrets are expanded for validation but stored unexpanded**, so validation runs against the document the device receives without persisting secret values. `MDMAppleCustomActivation` is the storage type; `MDMAppleDDMActivation` was already taken by Apple's wire format. # Checklist for submitter - [x] Input data is properly validated, `SELECT *` is avoided, SQL injection is prevented (using placeholders for values in statements), JS inline code is prevented especially for url redirects, and untrusted data interpolated into shell scripts/commands is validated against shell metacharacters. No changes file: the feature isn't reachable by users until the DDM sync work in #49971 lands. ## Testing - [x] Added/updated automated tests - [ ] QA'd all new/changed functionality manually **Unit** (`server/fleet`): `GetRawActivationValues` and `ValidateUserProvided` — valid activation, unknown type under the activation prefix, missing `Type`, a configuration type supplied as an activation, missing `Identifier`, zero/multiple/mismatched `StandardConfigurations`, all problems reported at once, plus `IsManagementDeclaration`. **Service** (`server/service`): activation accepted, mismatched configuration rejected, malformed JSON rejected, rejected on a management declaration, supported Fleet variables recorded, unsupported rejected, premium required even where the declaration is free. On edit: activation-only edit keeps content, labels-only edit preserves the activation, new content without an activation clears it, and exactly one `edited_declaration_profile` activity fires. **Datastore** (`server/datastore/mysql`): write, read-back through list and single get, edit reusing the row, Fleet variable association, and removal cascading to the variable rows. **Integration** (`integration_mdm_ddm_test.go`): multipart upload with an activation, read back and asserted base64-decoded against the raw response body; the key omitted entirely for a declaration without one; two management declarations uploaded and coexisting; activation on a `.mobileconfig` rejected on both create and edit; activation-only `PATCH` replacing the activation while leaving the declaration untouched. The multipart test helper now supports more than one file part — nothing could build that request before, which is why the decode path was previously untested. Single-file callers are unchanged. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added optional custom activations for Apple DDM configuration declarations. - Activations support secrets, Fleet variables, and custom host vitals. - Activation data appears when viewing or downloading applicable profiles. - Activation files can be added, updated, preserved during label-only edits, or removed during content replacement. - Management declarations can coexist with supported configuration declarations. - **Validation** - Added checks for declaration matching, supported profile types, file limits, and Premium licensing. - Clear errors are provided when activations are used with management declarations or non-DDM profiles. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Added activation criteria and updated profile parameters for Fleet Premium features.
Related issue: Resolves #48222