🆕API REST de gestion

SCEPman Enterprise Edition uniquement

Applicable à la version 3.1 et aux versions ultérieures

L’API de gestion fournit un accès administratif aux certificats émis dans SCEPman. Elle est destinée aux flux de travail de gestion et d’exploitation, tels que la localisation des certificats et მათი révocation lorsque cela est nécessaire.

Ces points de terminaison sont disponibles sous /api/manage et nécessitent un utilisateur authentifié ayant le Manage.All rôle dans SCEPman-api.

Si vous effectuez une mise à jour depuis une version antérieure de SCEPman, il se peut que vous n’ayez pas encore le rôle Manage.All. Exécutez Complete-SCEPmanInstallation à nouveau dans un cloud shell pour l’ajouter automatiquement à votre application SCEPman-api.

Authentification

L’API utilise l’authentification Entra. Le moyen le plus simple de s’authentifier est souvent la bibliothèque Microsoft Authentication Library (MSAL).

Une façon d’obtenir un jeton porteur pour l’API de gestion est d’utiliser Azure CLI. La valeur requise pour le paramètre `--resource` est l’URI d’ID d’application de votre inscription d’application SCEPman-api (généralement son ID d’application préfixé par api://).

az account get-access-token --resource api://[APPLICATION-ID] --query accessToken --output tsv

Par exemple :

TOKEN=$(az account get-access-token \\
  --resource api://16b6a4d1-0a20-4b41-bf58-12783034cad3 \\
  --query accessToken \\
  --output tsv)

Vous pouvez ensuite utiliser ce jeton dans les appels à l’API :

curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=ABC123&pageSize=10&certValidity=Any&certType=Any" \\
  -H "Authorization: Bearer $TOKEN" \\
  -H "Accept: application/json"

API de recherche

GET /api/manage/search

Recherche les certificats émis et renvoie un ensemble de résultats paginé.

Paramètres de recherche

searchText

Terme de recherche en texte libre utilisé pour trouver les certificats correspondants. Il est généralement utilisé pour des recherches par sous-chaîne, par exemple pour faire correspondre le demandeur ou d’autres métadonnées de certificat consultables.

pageSize

Nombre maximal de certificats renvoyés dans une seule page de réponse.

• Par défaut : 50

continuationToken

Jeton de pagination facultatif utilisé pour demander la page suivante de résultats. Renvoyez le continuationToken renvoyé par une réponse de recherche précédente pour continuer à récupérer davantage de certificats.

certValidity

Filtre les certificats par état de validité.

• Par défaut : Any

Les valeurs valides sont Any, Active, Expiré, Revoked.

certType

Filtre les certificats par type de certificat.

• Par défaut : Any

Cela peut être utilisé pour restreindre l’ensemble des résultats à des catégories de certificats spécifiques. Les valeurs valides sont Static, DC, Utilisateur, Appareil, et Any.

Sources

Filtre les certificats par le point de terminaison par lequel ils ont été émis. Vous pouvez spécifier ce filtre plusieurs fois, une fois par source.

• Par défaut : aucune restriction

Les valeurs valides sont indiquées dans le tableau ci-dessous, vous devez spécifier la source à l’aide de leurs valeurs entières :

Source	Valeur
CertificateMaster	0
Intune	1 ou 9 (utilisez les deux pour vous assurer de tout trouver)
Static	3
StaticAAD	4
Jamf	5
DomainController	6
API	7
RadiusAPI	8
Active Directory	10

La réponse est une liste paginée d’enregistrements de certificats, plus un jeton de continuation pour récupérer la page suivante.

Exemple

curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=507AEAC03CCEF83F106914418D9222E466A629C1&pageSize=10&certValidity=Any&certType=Any" \\
  -H "Authorization: Bearer <token>" \\
  -H "Accept: application/json"

Exemple de réponse

{
  "items": [
    {
    "serialNumber":  "507AEAC03CCEF83F106914418D9222E466A629C1",
    "subject":  "CN=device01.contoso.local",
    "sans":  null,
    "upn":  null,
    "issuanceDate":  "2026-05-28T10:57:22Z",
    "expirationDate":  "2028-05-28T10:57:22Z",
    "revocationDate":  null,
    "revocationReason":  null,
    "revokedBy":  null,
    "requester":  "[e-mail]",
    "source":  "CertificateMaster",
    "certificateType":  "Static"
    }
  ],
  "continuationToken": "..."
}

API de révocation

PATCH /api/manage/revoke/{serialNumber}

Révoque un certificat identifié par son numéro de série.

Le corps de la requête contient :

• revocationReason - un entier indiquant la raison de la révocation. Voir le tableau ci-dessous pour les valeurs possibles
• revoker (facultatif) - un identifiant en texte libre pour la personne ou le système demandant la révocation

Si elle est spécifiée, nous recommandons d’utiliser l’UPN pour le champ revoker. Si elle n’est pas spécifiée, l’UPN de l’utilisateur connecté sera utilisé. Même si elle est spécifiée, l’UPN de l’utilisateur connecté est tout de même ajouté sous la forme "{revoker} via l’utilisateur API ${logged on user}".

Cette valeur est utilisée pour l’audit et dans les recherches.

Exemple

curl -X PATCH "https://scepman.contoso.com/api/manage/revoke/ABC123" \\
  -H "Authorization: Bearer <token>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "revocationReason": 4,
    "revoker": "[e-mail]"
  }'

Réponse réussie

HTTP/1.1 200 OK

Certificat introuvable

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorMessage": "Certificate not found.",
  "errorCode": 7012
}

Déjà révoqué

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "errorMessage": "The certificate is already revoked.",
  "errorCode": 5013
}

Raisons de révocation prises en charge

L’API prend en charge les raisons de révocation spécifiées dans RFC 5280:

Valeur	Raison de révocation
0	Non spécifiée
1	Compromission de clé
2	Compromission de l’AC
3	Changement d’affiliation
4	Remplacé
5	Cessation d’activité
6	Mise en attente du certificat
8	Retirer de la CRL
9	Privilège retiré
10	Compromission de l’AA