Detalhes do serviço da API REST de Gerenciamento de Certificados

Artigo
09/14/2023

As seções a seguir descrevem os detalhes da API REST do GERENCIAMENTO de Certificados (CM) do MIM (Microsoft Identity Manager).

Arquitetura

As chamadas da API REST do MIM CM são manipuladas pelos controladores. A tabela a seguir mostra a lista completa de controladores e exemplos do contexto no qual eles podem ser usados.

Controller	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 solicitação e resposta HTTP

As solicitações HTTP enviadas à API devem incluir os seguintes cabeçalhos (essa lista não é exaustiva):

parâmetro	Descrição
Autorização	Obrigatórios. O conteúdo depende do método de autenticação. O método é configurável e pode ser baseado em WIA (Autenticação Integrada do Windows)) ou Serviços de Federação do Active Directory (AD FS) (ADFS).
Tipo de conteúdo	Obrigatório se a solicitação tiver um corpo. Deve ser `application/json`.
Content-Length	Obrigatório se a solicitação tiver um corpo.
Cookie	O cookie de sessão. Pode ser necessário, dependendo do método de autenticação.

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

parâmetro	Descrição
Tipo de conteúdo	A API sempre retorna `application/json`.
Content-Length	O comprimento do corpo da solicitação, se presente, em bytes.

Controle de versão de API

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

Habilitar a API

A seção <ClmConfiguration> do arquivo Web.config foi estendida com uma nova chave:

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

Essa chave determina se a API REST do CM é exposta aos clientes. Se a chave for definida como "false", o mapeamento de rota para a API não será executado na inicialização do aplicativo. Solicitações subsequentes para pontos de extremidade de API retornam um código de erro HTTP 404. Por padrão, a chave é definida como "desabilitada".

Observação

Depois de alterar esse valor para "true", lembre-se de executar iisreset no servidor.

Habilitar rastreamento e registro em log

A API de REST do MIM CM emite os dados de rastreamento para cada solicitação HTTP enviada a ela. Você pode definir o nível de detalhamento das informações de rastreamento emitidas ajustando o valor de configuração a seguir:

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

Tratamento de erros e solução de problemas

Quando ocorrerem exceções ao processar uma solicitação, a API REST do CM MIM retorna um código de status HTTP para o cliente web. Para erros comuns, a API retorna um código de status HTTP apropriado e um código de erro.

Exceções sem tratamento são convertidas para uma HttpResponseException com o Código de Status HTTP 500 ("Erro interno") e rastreadas no log de eventos e no arquivo de rastreamento do MIM CM. Cada exceção sem tratamento é gravada no log de eventos com uma ID de correlação correspondente. A ID de correlação também é enviada para o consumidor da API na mensagem de erro. Para solucionar o erro, o administrador pode pesquisar no log de eventos os detalhes da ID de correlação e do erro correspondentes.