🆕API REST de administración

Solo para SCEPman Enterprise Edition

Aplicable a la versión 3.1 y superiores

La API de administración proporciona acceso administrativo a los certificados emitidos en SCEPman. Está pensada para flujos de trabajo de administración y operativos, como localizar certificados y revocarlos cuando sea necesario.

Estos endpoints están disponibles bajo /api/manage y requieren un usuario autenticado con el Manage.All rol en SCEPman-api.

Si actualiza desde una versión anterior de SCEPman, puede que aún no tenga el rol Manage.All. Ejecute Complete-SCEPmanInstallation de nuevo en una cloud shell para agregarlo automáticamente a su aplicación SCEPman-api.

Autenticación

La API usa autenticación de Entra. La forma más sencilla de autenticar suele ser la Microsoft Authentication Library (MSAL).

Una forma de obtener un token portador para la API de administración es con Azure CLI. El valor requerido para el parámetro `--resource` es el URI del ID de aplicación de su registro de aplicación SCEPman-api (normalmente su ID de aplicación con el prefijo api://).

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

Por ejemplo:

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

Luego puede usar ese token en las llamadas a la 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 búsqueda

GET /api/manage/search

Busca certificados emitidos y devuelve un conjunto de resultados paginado.

Parámetros de búsqueda

searchText

Término de búsqueda de texto libre usado para encontrar certificados coincidentes. Normalmente se usa para búsquedas por subcadena, por ejemplo, coincidiendo con el solicitante u otros metadatos del certificado que se puedan buscar.

pageSize

Número máximo de certificados devueltos en una sola página de respuesta.

• Predeterminado: 50

continuationToken

Token de paginación opcional usado para solicitar la siguiente página de resultados. Devuelva el continuationToken devuelto por una respuesta de búsqueda anterior para continuar obteniendo más certificados.

certValidity

Filtra los certificados por estado de validez.

• Predeterminado: Any

Los valores válidos son Any, Active, Expired, Revoked.

certType

Filtra los certificados por tipo de certificado.

• Predeterminado: Any

Esto puede usarse para restringir el conjunto de resultados a categorías específicas de certificados. Los valores válidos son Static, DC, User, Device, y Any.

Fuentes

Filtra los certificados por el endpoint a través del cual se han emitido. Puede especificar este filtro varias veces, una por fuente.

• Predeterminado: Sin restricción

Los valores válidos se muestran en la tabla siguiente; debe especificar la fuente usando sus valores enteros:

Fuente	Valor
CertificateMaster	0
Intune	1 o 9 (use ambos para asegurarse de encontrar todos)
Static	3
StaticAAD	4
Jamf	5
DomainController	6
API	7
RadiusAPI	8
Active Directory	10

La respuesta es una lista paginada de registros de certificados más un token de continuación para obtener la siguiente página.

Ejemplo

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"

Ejemplo de respuesta

{
  "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 revocación

PATCH /api/manage/revoke/{serialNumber}

Revoca un certificado identificado por su número de serie.

El cuerpo de la solicitud contiene:

• revocationReason - un entero para el motivo de la revocación. Consulte la tabla siguiente para conocer los posibles valores
• revoker (opcional) - un identificador en texto libre de la persona o sistema que solicita la revocación

Si se especifica, recomendamos usar el UPN para el campo revoker. Si no se especifica, se usará el UPN del usuario que ha iniciado sesión. Incluso si se especifica, el UPN del usuario que ha iniciado sesión sigue añadiéndose en la forma "{revoker} through API user ${logged on user}".

Este valor se usa para auditoría y en búsquedas.

Ejemplo

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]"
  }'

Respuesta exitosa

HTTP/1.1 200 OK

Certificado no encontrado

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

{
  "errorMessage": "Certificado no encontrado.",
  "errorCode": 7012
}

Ya revocado

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

{
  "errorMessage": "El certificado ya está revocado.",
  "errorCode": 5013
}

Motivos de revocación admitidos

La API admite los motivos de revocación especificados en RFC 5280:

Valor	Motivo de revocación
0	Unspecified
1	KeyCompromise
2	CACompromise
3	AffiliationChanged
4	Superseded
5	CessationOfOperation
6	CertificateHold
8	RemoveFromCrl
9	PrivilegeWithdrawn
10	AACompromise