Detalhes do serviço da API REST de Gerenciamento de Certificados
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.
Observação
Rastreamentos de pilha que correspondem a erros, que são gerados como resultado do consumo da API REST do MIM CM, não são enviados de volta para o cliente. Os rastreamentos não são enviados de volta ao cliente devido a preocupações de segurança.