Details des REST-API-Diensts für die Zertifikatverwaltung
In den folgenden Abschnitten werden Details zur REST-API für die Microsoft Identity Manager (MIM) Certificate Management (CM) beschrieben.
Architektur
Die MIM CM REST-API-Aufrufe werden vom Controller behandelt. In der folgenden Tabelle wird die vollständige Liste der Controller und Beispiele für den Kontext angezeigt, in dem sie verwendet werden können.
Controller | Beispielroute |
---|---|
CertificateDataController | /api/v1.0/requests/{requestid}/certificatedata/ |
CertificateRequestGenerationOptionsController | /api/v1.0/requests/{requestid} |
CertificatesController | /api/v1.0/smartcards/{Smartcard-ID}/certificates /api/v1.0/profiles/{Profil-ID}/certificates |
OperationsController | /api/v1.0/smartcards/{Smartcard-ID}/operations /api/v1.0/profiles/{Profil-ID}/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/{Anforderungs-ID}/smartcards/{ID}/diversifiedkey /api/v1.0/requests/{Anforderungs-ID}/smartcards/{ID}/serverproposedpin /api/v1.0/requests/{Anforderungs-ID}/smartcards/{ID}/authenticationresponse /api/v1.0/requests/{Anforderungs-ID}/smartcards/{ID} /api/v1.0/smartcards/{ID} /api/v1.0/smartcards |
SmartcardsConfigurationController | /api/v1.0/profiletemplates/{profiletemplateid}/configuration/smartcards |
HTTP-Anforderungs- und Antwortheader
HTTP-Anforderungen, die an die API gesendet werden, sollten die folgenden Header enthalten (diese Liste ist nicht vollständig):
Header | BESCHREIBUNG |
---|---|
Authorization | Erforderlich. Der Inhalt hängt von der Authentifizierungsmethode ab. Die Methode ist konfigurierbar und kann auf Windows Integrated Authentication (WIA)) oder Active Directory-Verbunddienste (AD FS) (AD FS) basieren. |
Content-Type | Erforderlich, wenn die Anforderung Text enthält. Muss application/json lauten. |
Content-Length | Erforderlich, wenn die Anforderung Text enthält. |
Cookie | Das Sitzungscookie. Möglicherweise je nach Authentifizierungsmethode erforderlich. |
HTTP-Antworten enthalten die folgenden Header (diese Liste ist nicht vollständig):
Header | BESCHREIBUNG |
---|---|
Content-Type | Die API gibt immer zurück application/json . |
Content-Length | Die Länge des Anforderungstexts, falls vorhanden, in Bytes. |
API-Versionsverwaltung
Die aktuelle Version der CM REST-API ist 1.0. Die Version wird in dem Segment angegeben, das im URI direkt auf das Segment /api
folgt: /api/v1.0
. Die Versionsnummer ändert sich, wenn wichtige Änderungen an der API-Schnittstelle vorgenommen werden.
Aktivieren der API
Der Abschnitt <ClmConfiguration>
der Datei „Web.config“ wurde durch einen neuen Schlüssel erweitert:
<add key="Clm.WebApi.Enabled" value="false" />
Dieser Schlüssel bestimmt, ob die CM REST-API für Clients zur Verfügung gestellt wird. Wenn der Schlüssel auf „False“ festgelegt ist, wird die Routenzuordnung für die API nicht beim Start der Anwendung ausgeführt. Nachfolgende Anforderungen an API-Endpunkte geben einen HTTP 404-Fehlercode zurück. Der Schlüssel ist standardmäßig auf „Deaktiviert“ festgelegt.
Hinweis
Nachdem Sie diesen Wert in "true" geändert haben, denken Sie daran , iisreset auf dem Server auszuführen.
Aktivieren der Ablaufverfolgung und Protokollierung
Die MIM CM REST-API gibt für jede an sie gesendete HTTP-Anforderung Ablaufverfolgungsdaten aus. Sie können den Ausführlichkeitsgrad für die ausgegebenen Ablaufverfolgungsinformationen einstellen, indem Sie den folgenden Konfigurationswert festlegen:
<add name="Microsoft.Clm.Web.API" value="0" />
Fehlerbehandlung und Problembehandlung
Wenn beim Verarbeiten einer Anforderung Ausnahmen auftreten, gibt die MIM CM REST-API einen HTTP-Statuscode an den Webclient zurück. Für allgemeine Fehler gibt die API einen entsprechenden HTTP-Statuscode und einen Fehlercode zurück.
Nicht behandelte Ausnahmen werden in ein HttpResponseException
mit HTTP-Statuscode 500 („Interner Fehler“) konvertiert und sowohl im Ereignisprotokoll als auch in der MIM CM-Ablaufverfolgungsdatei verfolgt. Jede nicht behandelte Ausnahme wird mit einer entsprechenden Korrelations-ID im Ereignisprotokoll eingetragen. Die Korrelations-ID wird auch an den Consumer der API in der Fehlermeldung gesendet. Ein Administrator kann das Ereignisprotokoll nach der entsprechenden Korrelations-ID und den Fehlerdetails durchsuchen, um den Fehler zu beheben.
Hinweis
Stapelablaufverfolgungen, die Fehlern entsprechen, die als Folge der Nutzung der MIM CM-REST-API generiert werden, werden nicht an den Client zurückgesendet. Die Ablaufverfolgungen werden aufgrund von Sicherheitsbedenken nicht an den Client zurückgesendet.