[YAML/API] Deploy certificates on Android hosts via GitOps #35270
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -16,6 +16,7 @@ These API endpoints in this document are only used when contributing to Fleet. T | |||||
| - [Setup](#setup) | ||||||
| - [Scripts](#scripts) | ||||||
| - [Software](#software) | ||||||
| - [Certificates](#certificates) | ||||||
| - [Users](#users) | ||||||
| - [Conditional access](#conditional-access) | ||||||
| - [Host identity](#host-identity) | ||||||
|
|
@@ -4878,6 +4879,76 @@ Body: <blob> | |||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Certificates | ||||||
|
|
||||||
| ### Apply certificate templates | ||||||
|
|
||||||
| _Available in Fleet Premium_ | ||||||
|
|
||||||
| `POST /api/latest/fleet/spec/certificates` | ||||||
|
|
||||||
| #### Parameters | ||||||
|
|
||||||
| | Name | Type | In | Description | | ||||||
| | --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||||||
| | specs | array | body | **Required**. An array of objects with the certificate templates. Each item must contain `name` with the certificate template name, a `team` with a team name, `certificate_authority_id` with the certificate authority id, and `subject_name` with the certificate's subject name. | | ||||||
|
|
||||||
| > Any existing certificate template that is not included in the list will be removed, and existing templates with the same name as the new template will be edited. Providing an empty list of certificate templates will remove existing scripts. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
I think "scripts" might have been a typo? Or are there scripts involved? cc @marko-lisica (Will approve anyway since this is a contributor endpoint) |
||||||
|
|
||||||
| #### Example | ||||||
|
|
||||||
| `POST /api/latest/fleet/spec/certificates` | ||||||
|
|
||||||
| ##### Request body | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "specs": [ | ||||||
| { | ||||||
| "name": "WIFI_CERTIFICATE", | ||||||
| "team": "workstations", | ||||||
| "certificate_authority_id": 1, | ||||||
| "subject_name": "/CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME/OU=$FLEET_VAR_HOST_UUID/ST=$FLEET_VAR_HOST_HARDWARE_SERIAL" | ||||||
| }, | ||||||
| { | ||||||
| "name": "WIFI_CERTIFICATE_TEST", | ||||||
| "team": "workstations-canary", | ||||||
| "certificate_authority_id": 1, | ||||||
| "subject_name": "/CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME/OU=$FLEET_VAR_HOST_UUID/ST=$FLEET_VAR_HOST_HARDWARE_SERIAL" | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ##### Default response | ||||||
|
|
||||||
| `Status: 200` | ||||||
|
|
||||||
| ### Delete certificate templates | ||||||
|
|
||||||
| `DELETE /api/latest/fleet/spec/certificates` | ||||||
|
|
||||||
| #### Parameters | ||||||
|
|
||||||
| | Name | Type | In | Description | | ||||||
| |-----------|---------|-------|----------------------------------------------------------------------------------------| | ||||||
| | ids | array | body | **Required**. An array of certificate template ids to be deleted | | ||||||
| | team_id | integer | body | **Required**. The team_id which the certificate templates you want to delete belong to | | ||||||
|
|
||||||
| #### Example | ||||||
|
|
||||||
| `DELETE /api/latest/fleet/spec/certificates` | ||||||
| ```json | ||||||
| { | ||||||
| "ids": [1, 2, 3, 4], | ||||||
| "team_id": 1 | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ##### Default response | ||||||
|
|
||||||
| `Status: 200` | ||||||
|
|
||||||
| ## Users | ||||||
|
|
||||||
| ### Update user-specific UI settings | ||||||
|
|
||||||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -594,6 +594,8 @@ Returns a list of the activities that have been performed in Fleet. For a compre | |
| - [Update certificate authority (CA)](#update-certificate-authority-ca) | ||
| - [List certificate authorities (CAs)](#list-certificate-authorities-cas) | ||
| - [Get certificate authority (CA)](#get-certificate-authority-ca) | ||
| - [List certificate templates](#list-certificate-templates) | ||
| - [Get certificate template](#get-certificate-template) | ||
| - [Delete certificate authority (CA)](#delete-certificate-authority-ca) | ||
| - [Request certificate](#request-certificate) | ||
|
|
||
|
|
@@ -854,6 +856,119 @@ Get details of the certificate authority. | |
| } | ||
| ``` | ||
|
|
||
| ### List certificate templates | ||
|
|
||
| List certificate added to Fleet. Currently, they can only be added via GitOps. | ||
|
|
||
| `GET /api/v1/fleet/certificates` | ||
|
|
||
| #### Parameters | ||
|
|
||
| | Name | Type | In | Description | | ||
| | ----------| ------- | ---- | -------------------------------------------------------------- | | ||
| | team | string | query | _Available in Fleet Premium_. The team ID to filter profiles. | | ||
| | page | integer | query | Page number of the results to fetch. | | ||
| | per_page | integer | query | Results per page. | | ||
|
|
||
| #### Request headers | ||
|
|
||
| This endpoint accepts the node key from Fleet's Android agent for authentication in addition to [default authentication](#retrieve-your-api-token) with a Bearer token. | ||
|
|
||
| The `Authorization` header must be formatted as follows: | ||
|
|
||
| ``` | ||
| Authorization: Node key <node_key> | ||
| ``` | ||
|
Comment on lines
+873
to
+881
Member
Author
There was a problem hiding this comment. @ksykulev, do we need this? Does the agent call this endpoint? If I remember correctly, we added a new contributor endpoint (
Member
There was a problem hiding this comment. @marko-lisica, the parameter for the team should be
Member
Author
There was a problem hiding this comment. @AndreyKizimenko, that's righ,t it should be
@ksykulev can you confirm if the agent is using this endpoint and if we support node key authentication for this endpoint? |
||
|
|
||
| #### Example | ||
|
|
||
| `GET /api/v1/fleet/certificates/` | ||
|
|
||
| ##### Request headers | ||
|
|
||
| ```http | ||
| Authorization: Node key 24dd9ebf-02cd-4d4c-888a-5caa441ee5d5 | ||
| ``` | ||
|
|
||
| ##### Default response | ||
|
|
||
| `Status: 200` | ||
|
|
||
| ```json | ||
| { | ||
| "certificates": [ | ||
| { | ||
| "id": 1, | ||
| "name": "wifi-certificate", | ||
| "certificate_authority_id": "1", | ||
| "certificate_authority_name": "PRODUCTION_SCEP_SERVER", | ||
| "subject_name": "/CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME/OU=$FLEET_VAR_HOST_UUID/ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", | ||
| "created_at": "2025-11-04T00:00:00Z", | ||
| }, | ||
| { | ||
| "id": 2, | ||
| "name": "vpn-certificate", | ||
| "certificate_authority_id": "1", | ||
| "certificate_authority_name": "PRODUCTION_SCEP_SERVER", | ||
| "subject_name": "/CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME/OU=$FLEET_VAR_HOST_UUID", | ||
| "created_at": "2025-11-04T00:00:00Z", | ||
| } | ||
| ], | ||
| "meta": { | ||
| "has_next_results": false, | ||
| "has_previous_results": false | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Get certificate template | ||
|
|
||
| Get details of the certificate added to Fleet. | ||
|
|
||
| `GET /api/v1/fleet/certificates/:id` | ||
|
Member
Author
There was a problem hiding this comment. @ksykulev, is this one used by GitOps? Did we end up implementing this one? Now, when we return |
||
|
|
||
| #### Parameters | ||
|
|
||
| | Name | Type | In | Description | | ||
| |---------------- |-------- |------|-------------------------------------------------------------| | ||
| | id | integer | path | **Required**. The ID of the certificate. | | ||
| | host_id | integer | query | ID of the host. If included, variables in `subject_name` will be replaced with host's values. | | ||
|
|
||
| #### Request headers | ||
|
|
||
| This endpoint accepts the node key from Fleet's Android agent for authentication in addition to [default authentication](#retrieve-your-api-token) with a Bearer token. | ||
|
|
||
| The `Authorization` header must be formatted as follows: | ||
|
|
||
| ``` | ||
| Authorization: Node key <node_key> | ||
| ``` | ||
|
|
||
| #### Example | ||
|
|
||
| `GET /api/v1/fleet/certificates/1` | ||
|
|
||
| ##### Request headers | ||
|
|
||
| ```http | ||
| Authorization: Node key 24dd9ebf-02cd-4d4c-888a-5caa441ee5d5 | ||
| ``` | ||
|
|
||
| ##### Default response | ||
|
|
||
| `Status: 200` | ||
|
|
||
| ```json | ||
| { | ||
| "certificate_authority_id": 2, | ||
| "certificate_authority_name": "PRODUCTION_SCEP_SERVER", | ||
| "created_at": "2025-11-04T00:00:00Z", | ||
| "id": 1, | ||
| "name": "wifi-certificate", | ||
| "subject_name": "/CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME/OU=$FLEET_VAR_HOST_UUID/ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", | ||
|
marko-lisica marked this conversation as resolved.
|
||
| } | ||
| ``` | ||
|
|
||
| ### Delete certificate authority (CA) | ||
|
|
||
| > **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows. | ||
|
|
||
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.
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:
Errors:
namethat is already taken by another certificate:namewith characters that are not supported: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.
@marko-lisica If user specified invalid Fleet variable, like $FLEET_VAR_BOZO?
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.
@marko-lisica If user specified $FLEET_SECRET_SOMETHING?
Uh oh!
There was an error while loading. Please reload this page.
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.
@getvictor If IdP variable is empty, we should return an error on the host details on the OS settings modal. I think we should be consistent with any invalid variable and secret.
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.
If user specify CA other than custom SCEP proxy, throw an error:
Couldn't edit "<file_name>" at "<full_path>": Currently, only thecustom_scep_proxy` certificate authority is supported.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.
@marko-lisica What about these:
Uh oh!
There was an error while loading. Please reload this page.
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.
@getvictor What do we do for configuration profiles in that case? We should do the same.
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.
@marko-lisica configuration profiles support secrets, while the Android certificates do not (we do not have secrets support coded).
configuration profiles return an error on unsupported Fleet variables.
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.
Let's show this error message if variable is not supported or doesn't exist:
For secrets: