Detalhes do serviço da API REST da Gestão de Certificados

Artigo
09/14/2023

As secções seguintes descrevem os detalhes da API REST de Gestão de Certificados (CM) Microsoft Identity Manager (MIM).

Arquitetura

As chamadas à API REST do CM do MIM são processadas por controladores. A tabela seguinte mostra a lista completa de controladores e exemplos do contexto em que podem ser utilizados.

Controlador	Rota de exemplo
CertificateDataController	/api/v1.0/requests/{requestid}/certificatedata/
CertificateRequestGenerationOptionsController	/api/v1.0/requests/{requestid}
CertificatesController	/api/v1.0/smartcards/{smartcardid}/certificates /api/v1.0/profiles/{profileid}/certificates
OperationsController	/api/v1.0/smartcards/{smartcardid}/operations /api/v1.0/profiles/{profileid}/operations
PoliciesController	/api/v1.0/profiletemplates/{profiletemplateid}/policies/{id}
ProfilesController	/api/v1.0/profiles/{id}
ProfileTemplatesController	/api/v1.0/profiletemplates/{id} /api/v1.0/profiletemplates /api/v1.0/profiletemplates/{profiletemplateid}/policies/{id}
RequestsController	/api/v1.0/requests/{id} /api/v1.0/requests
SmartcardsController	/api/v1.0/requests/{requestid}/smartcards/{id}/diversifiedkey /api/v1.0/requests/{requestid}/smartcards/{id}/serverproposedpin /api/v1.0/requests/{requestid}/smartcards/{id}/authenticationresponse /api/v1.0/requests/{requestid}/smartcards/{id} /api/v1.0/smartcards/{id} /api/v1.0/smartcards
SmartcardsConfigurationController	/api/v1.0/profiletemplates/{profiletemplateid}/configuration/smartcards

Cabeçalhos de pedidos e respostas HTTP

Os pedidos HTTP enviados para a API devem incluir os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho	Description
Autorização	Obrigatório. Os conteúdos dependem do método de autenticação. O método é configurável e pode basear-se na Autenticação Integrada do Windows (WIA)) ou Serviços de Federação do Active Directory (AD FS) (ADFS).
Content-Type	Necessário se o pedido tiver um corpo. Tem de ser `application/json`.
Comprimento do Conteúdo	Necessário se o pedido tiver um corpo.
Cookie	O cookie da sessão. Pode ser necessário consoante o método de autenticação.

As respostas HTTP incluem os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho	Description
Content-Type	A API devolve `application/json`sempre .
Comprimento do Conteúdo	O comprimento do corpo do pedido, se estiver presente, em bytes.

Controlo de versões da API

A versão atual da API REST do CM é 1.0. A versão é especificada no segmento diretamente a seguir ao /api segmento no URI: /api/v1.0. O número da versão é alterado quando são efetuadas modificações importantes na interface de API.

Ativar a API

A <ClmConfiguration> secção do ficheiro Web.config foi expandida com uma nova chave:

<add key="Clm.WebApi.Enabled" value="false" />

Esta chave determina se a API REST do CM está exposta aos clientes. Se a chave estiver definida como "false", o mapeamento de rotas para a API não é efetuado no arranque da aplicação. Os pedidos subsequentes aos pontos finais da API devolvem um código de erro HTTP 404. A chave está definida como "desativada" por predefinição.

Nota

Depois de alterar este valor para "verdadeiro", lembre-se de executar iisreset no servidor.

Ativar o rastreio e o registo

A API REST do CM do MIM emite dados de rastreio para cada pedido HTTP enviado para o mesmo. Pode definir o nível de verbosidade das informações de rastreio emitidas ao definir o seguinte valor de configuração:

<add name="Microsoft.Clm.Web.API" value="0" />

Resolução de problemas e processamento de erros

Quando ocorrem exceções durante o processamento de um pedido, a API REST do CM do MIM devolve um código de estado HTTP ao cliente Web. Para erros comuns, a API devolve um código de estado HTTP adequado e um código de erro.

As exceções não processadas são convertidas num HttpResponseException com o Código de Estado HTTP 500 ("Erro Interno") e rastreadas no registo de eventos e no ficheiro de rastreio CM do MIM. Cada exceção não processada é escrita no registo de eventos com um ID de correlação correspondente. O ID de correlação também é enviado ao consumidor da API na mensagem de erro. Para resolver o erro, um administrador pode procurar no registo de eventos o ID de correlação correspondente e os detalhes do erro.