🆕API REST de gestão

Apenas para a SCEPman Enterprise Edition

Aplicável à versão 3.1 e superior

A API de Gestão fornece acesso administrativo aos certificados emitidos no SCEPman. Destina-se a fluxos de trabalho de gestão e operacionais, como localizar certificados e revogá-los quando necessário.

Estes endpoints estão disponíveis em /api/manage e requerem um utilizador autenticado com a função Manage.All no SCEPman-api.

Se atualizar a partir de uma versão anterior do SCEPman, é possível que ainda não tenha a função Manage.All. Execute Complete-SCEPmanInstallation novamente numa Cloud Shell para a adicionar automaticamente à sua aplicação SCEPman-api.

Autenticação

A API usa autenticação Entra. A forma mais fácil de autenticar é muitas vezes a Microsoft Authentication Library (MSAL).

Uma forma de obter um token bearer para a Management API é com a Azure CLI. O valor necessário para o parâmetro `--resource` é o URI do ID da aplicação do registo da sua SCEPman-api (normalmente o ID da aplicação precedido por api://).

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

Por exemplo:

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

Pode então usar esse token nas chamadas da 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 Pesquisa

GET /api/manage/search

Pesquisa os certificados emitidos e devolve um conjunto de resultados paginado.

Parâmetros de pesquisa

searchText

Termo de pesquisa em texto livre usado para encontrar certificados correspondentes. Normalmente é usado para pesquisas baseadas em substring, por exemplo, correspondência do requerente ou de outros metadados pesquisáveis do certificado.

pageSize

Número máximo de certificados devolvidos numa única página de resposta.

• Padrão: 50

continuationToken

Token de paginação opcional usado para pedir a página seguinte de resultados. Devolva o continuationToken devolvido por uma resposta de pesquisa anterior para continuar a obter mais certificados.

certValidity

Filtra certificados pelo estado de validade.

• Padrão: Any

Os valores válidos são Any, Active, Expired, Revoked.

certType

Filtra certificados pelo tipo de certificado.

• Padrão: Any

Isto pode ser usado para restringir o conjunto de resultados a categorias específicas de certificados. Os valores válidos são Static, DC, User, Device, e Any.

Sources

Filtra certificados pelo endpoint através do qual foram emitidos. Pode especificar este filtro várias vezes, uma vez por origem.

• Padrão: Sem restrição

Os valores válidos são apresentados na tabela abaixo, deve especificar a origem usando os respetivos valores inteiros:

Origem	Valor
CertificateMaster	0
Intune	1 ou 9 (use ambos para garantir que encontra todos)
Static	3
StaticAAD	4
Jamf	5
DomainController	6
API	7
RadiusAPI	8
Active Directory	10

A resposta é uma lista paginada de registos de certificados, mais um token de continuação para obter a página seguinte.

Exemplo

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"

Resposta de exemplo

{
  "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 Revogação

PATCH /api/manage/revoke/{serialNumber}

Revoga um certificado identificado pelo seu número de série.

O corpo do pedido contém:

• revocationReason - um inteiro para o motivo da revogação. Consulte a tabela abaixo para os valores possíveis
• revoker (opcional) - um identificador em texto livre para a pessoa ou sistema que solicita a revogação

Se especificado, recomendamos usar o UPN para o campo revoker. Se não for especificado, será usado o UPN do utilizador autenticado. Mesmo que seja especificado, o UPN do utilizador autenticado continua a ser adicionado na forma "{revoker} through API user ${logged on user}".

Este valor é usado para auditoria e nas pesquisas.

Exemplo

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

Resposta bem-sucedida

HTTP/1.1 200 OK

Certificado não encontrado

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

{
  "errorMessage": "Certificado não encontrado.",
  "errorCode": 7012
}

Já revogado

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

{
  "errorMessage": "O certificado já está revogado.",
  "errorCode": 5013
}

Motivos de revogação suportados

A API suporta os motivos de revogação especificados em RFC 5280:

Valor	Motivo da revogação
0	Unspecified
1	KeyCompromise
2	CACompromise
3	AffiliationChanged
4	Superseded
5	CessationOfOperation
6	CertificateHold
8	RemoveFromCrl
9	PrivilegeWithdrawn
10	AACompromise