🆕API REST de gestão

apenas na Edição Enterprise do SCEPman

Aplicável à versão 3.1 e superior

A Management API 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 Manage.All função no SCEPman-api.

Se você atualizar a partir de uma versão anterior do SCEPman, talvez ainda não tenha a função Manage.All. Execute Complete-SCEPmanInstallation novamente em um shell de nuvem para adicioná-la automaticamente à sua aplicação SCEPman-api.

Autenticação

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

Uma forma de obter um token bearer para a Management API é com o Azure CLI. O valor necessário para o parâmetro `--resource` é o URI do ID da aplicação do seu registo de aplicação SCEPman-api (normalmente o seu ID da aplicação precedido de 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 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. Isto é normalmente usado para pesquisas baseadas em subcadeias, por exemplo, correspondendo ao requisitante ou a outros metadados de certificado pesquisáveis.

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 solicitar a página seguinte de resultados. Passe de volta 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, Expirado, Revoked.

certType

Filtra certificados por 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, Usuário, Dispositivo, e Any.

Sources

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

• Padrão: Sem restrição

Os valores válidos são mostrados na tabela abaixo; deve especificar a fonte usando os seus valores inteiros:

Fonte	Valor
CertificateMaster	0
Intune	1 ou 9 (use ambos para garantir encontrar 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"

Exemplo de resposta

{
  "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. Veja a tabela abaixo para possíveis valores
• 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 com sessão iniciada. Mesmo que seja especificado, o UPN do utilizador com sessão iniciada continua a ser adicionado na forma "{revoker} por meio do utilizador da API ${logged on user}".

Este valor é usado para auditoria e em 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 de revogação
0	Não especificado
1	Compromisso da chave
2	Compromisso da AC
3	Mudança de afiliação
4	Substituído
5	Cessação da operação
6	Retenção do certificado
8	Remover do CRL
9	Retirada do privilégio
10	Compromisso da AA