인증서 관리 REST API 서비스 세부 정보

아티클
09/14/2023

다음 섹션에서는 MIM(Microsoft Identity Manager) 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 요청에는 다음 헤더가 포함되어야 합니다(이 목록은 완전하지 않음).

헤더	Description
권한 부여	필수 요소. 콘텐츠는 인증 방법에 따라 달라집니다. 메서드는 구성 가능하며 WIA(Windows 통합 인증) 또는 ADFS(Active Directory Federation Services)를 기반으로 할 수 있습니다.
콘텐츠 형식	요청에 본문이 있는 경우 필수 사항입니다. `application/json`이어야 합니다.
Content-Length	요청에 본문이 있는 경우 필수 사항입니다.
쿠키	세션 쿠키입니다. 인증 방법에 따라 필요할 수 있습니다.

HTTP 응답에는 다음 헤더가 포함됩니다(이 목록은 완전하지 않음).

헤더	Description
콘텐츠 형식	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 오류 코드를 반환합니다. 키는 기본적으로 "disabled"으로 설정됩니다.

참고

이 값을 "true"로 변경한 후 서버 에서 iisreset 을 실행해야 합니다.

추적 및 로깅 사용

MIM CM REST API는 전송된 각 HTTP 요청에 대한 추적 데이터를 내보냅니다. 다음 구성 값을 설정하여 내보낸 추적 정보의 세부 정보 표시 수준을 설정할 수 있습니다.

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

오류 처리 및 문제 해결

요청을 처리하는 동안 예외가 발생하면 MIM CM REST API가 HTTP 상태 코드를 웹 클라이언트로 반환합니다. 일반적인 오류의 경우 API가 적절한 HTTP 상태 코드 및 오류 코드를 반환합니다.

처리되지 않은 예외는 HTTP 상태 코드 500("내부 오류")과 함께 HttpResponseException 으로 변환되고 이벤트 로그와 MIM CM 추적 파일에서 모두 추적됩니다. 처리되지 않은 각 예외는 해당 상관 관계 ID와 함께 이벤트 로그에 기록됩니다. 또한 상관 관계 ID는 오류 메시지로 API 소비자에게도 전송됩니다. 오류를 해결하기 위해 관리자가 해당 상관 관계 ID 및 오류 세부 정보에 대해 이벤트 로그를 검색할 수 있습니다.

참고

MIM CM REST API를 사용한 결과로 생성된 오류에 해당하는 스택 추적은 클라이언트로 다시 전송되지 않습니다. 추적은 보안 문제로 인해 클라이언트로 다시 전송되지 않습니다.

다음을 통해 공유