Freigeben über


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/jsonlauten.
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.