Tanúsítványkezelés REST API-szolgáltatás részletei

Cikk
09/14/2023

Az alábbi szakaszok a Microsoft Identity Manager (MIM) Tanúsítványkezelés (CM) REST API részleteit ismertetik.

Architektúra

A MIM CM REST API-hívásokat vezérlők kezelik. Az alábbi táblázat azoknak a vezérlőknek és mintáknak a teljes listáját mutatja be, amelyekben használhatók.

Vezérlő	Mintaútvonal
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-kérés- és válaszfejlécek

Az API-nak küldött HTTP-kéréseknek a következő fejléceket kell tartalmazniuk (ez a lista nem teljes):

Fejléc	Description
Engedélyezés	Kötelező. A tartalom a hitelesítési módszertől függ. A metódus konfigurálható, és a Windows integrált hitelesítésén (WIA) vagy Active Directory összevonási szolgáltatások (AD FS) (ADFS) alapulhat.
Content-Type	Kötelező, ha a kérelem törzse van. A fájlnak kell lennie `application/json`.
Tartalom hossza	Kötelező, ha a kérelem törzse van.
Cookie	A munkamenet cookie-ja. A hitelesítési módszertől függően szükség lehet rá.

A HTTP-válaszok a következő fejléceket tartalmazzák (ez a lista nem teljes):

Fejléc	Description
Content-Type	Az API mindig a következőt adja `application/json`vissza: .
Tartalom hossza	A kérelem törzsének hossza(ha van) bájtban.

API-verziószámozás

A CM REST API jelenlegi verziója 1.0. A verzió a szegmensben van megadva, közvetlenül a /api szegmenst követve az URI-ban: /api/v1.0. A verziószám megváltozik, amikor jelentős módosításokat hajtanak végre az API-felületen.

Az API engedélyezése

A <ClmConfiguration> Web.config fájl szakasza egy új kulccsal bővült:

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

Ez a kulcs határozza meg, hogy a CM REST API elérhető-e az ügyfelek számára. Ha a kulcs értéke "false", az API útvonal-leképezése nem történik meg az alkalmazás indításakor. Az API-végpontokra irányuló későbbi kérések HTTP 404-hibakódot adnak vissza. A kulcs alapértelmezés szerint "letiltva" értékre van állítva.

Megjegyzés

Miután ezt az értéket "true" értékre módosította, ne felejtse el futtatni az iisreset parancsot a kiszolgálón.

Nyomkövetés és naplózás engedélyezése

A MIM CM REST API minden neki küldött HTTP-kérelemhez nyomkövetési adatokat bocsát ki. A kibocsátott nyomkövetési információk részletességi szintjét a következő konfigurációs érték beállításával állíthatja be:

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

Hibakezelés és hibaelhárítás

Ha a kérés feldolgozása során kivételek történnek, a MIM CM REST API EGY HTTP-állapotkódot ad vissza a webes ügyfélnek. Gyakori hibák esetén az API egy megfelelő HTTP-állapotkódot és egy hibakódot ad vissza.

A kezeletlen kivételeket a rendszer 500-os HTTP-állapotkóddal ("belső hiba") konvertálja HttpResponseException , és az eseménynaplóban és a MIM CM-nyomkövetési fájlban is nyomon követi. A rendszer minden nem kezelt kivételt az eseménynaplóba ír egy megfelelő korrelációs azonosítóval. A korrelációs azonosítót a rendszer a hibaüzenetben elküldi az API felhasználójának is. A hiba elhárításához a rendszergazda megkeresheti az eseménynaplóban a megfelelő korrelációs azonosítót és hibaadatokat.