证书管理 REST API 服务详细信息

项目
09/14/2023

以下部分介绍MICROSOFT IDENTITY MANAGER (MIM) 证书管理 (CM) REST API 的详细信息。

体系结构

MIM CM REST API 调用由控制器处理。下表显示控制器的完整列表以及可在其中使用它们的上下文的示例。

控制器	示例路由
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

HTTP 请求和响应标头

发送到 API 的 HTTP 请求应包含以下标头， (此列表并不详尽) ：

标头	说明
授权	必需。内容取决于身份验证方法。方法可配置，可以基于 Windows 集成身份验证 (WIA) ) 或 Active Directory 联合身份验证服务 (ADFS) 。
Content-Type	如果请求具有正文则为必需。必须是 `application/json`。
Content-Length	如果请求具有正文则为必需。
Cookie	会话 Cookie。根据身份验证方法，可能为必需。

HTTP 响应包括以下标头， (此列表并不详尽) ：

标头	说明
Content-Type	API 始终返回 `application/json`。
Content-Length	请求正文的长度（如果存在），以字节为单位。

API 版本控制

CM REST API 的当前版本为 1.0。在紧接在 URI 中的 /api 段后的段中指定版本： /api/v1.0。对 API 接口进行重大修改时，版本号会更改。

启用 API

Web.config 文件的 <ClmConfiguration> 部分已由新键扩展：

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

此键决定是否向客户端公开 CM REST API。如果此键设置为“false”，则不在应用程序启动时执行 API 的路由映射。对 API 终结点的后续请求将返回 HTTP 404 错误代码。此键默认设置为“已禁用”。

注意

将此值更改为“true”后，请记住在服务器上运行 iisreset 。

启用跟踪和日志记录

MIM CM REST API 为发送到它的每个 HTTP 请求发射跟踪数据。你可以通过设置以下配置值来设置所发射的跟踪信息的详细级别：

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

错误处理和故障排除

如果在处理请求时发生异常，MIM CM REST API 会将 HTTP 状态代码返回到 Web 客户端。对于常见错误，API 将返回相应的 HTTP 状态代码和错误代码。

未处理的异常转换为带有 HTTP 状态代码 500 的（“内部错误”） HttpResponseException ，并且在事件日志和 MIM CM 跟踪文件中跟踪该异常。每个未处理的异常都将写入事件日志，并带有相应的相关 ID。相关 ID 也会在错误消息中发送给 API 的使用者。若要解决此错误，管理员可以搜索事件日志以查找相应的关联 ID 和错误详细信息。

注意

与使用 MIM CM REST API 生成的错误对应的堆栈跟踪不会发送回客户端。出于安全考虑，跟踪不会发送回客户端。

通过