証明書管理 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 要求には、次のヘッダーを含める必要があります (この一覧は完全ではありません)。

Header	説明
承認	必須です。内容は認証方法によって異なります。この方法は構成可能であり、Windows 統合認証 (WIA) またはActive Directory フェデレーションサービス (AD FS) (ADFS) に基づいて行うことができます。
Content-Type	要求本文が含まれる場合は必須。 `application/json`である必要があります。
Content-Length	要求本文が含まれる場合は必須。
クッキー	セッションの Cookie。認証方法によって必要な場合があります。

HTTP 応答には、次のヘッダーが含まれます (この一覧は完全ではありません)。

Header	説明
Content-Type	API は常にを返します `application/json`。
Content-Length	要求本文がある場合は、その長さ (バイト)。

API のバージョン管理

CM REST API の現在のバージョンは 1.0 です。バージョンは、URI: /api/v1.0 の /api セグメントのすぐ後ろのセグメントで指定されています。 API インターフェイスに大きな変更が加えられると、バージョン番号が変更されます。

API を有効にする

Web.config ファイルの <ClmConfiguration> セクションは、次の新しいキーで拡張されています。

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

このキーは、CM REST API がクライアントに公開されているかどうかを判断します。キーが "false" に設定されていると、アプリケーションの起動時に、API のルートマッピングが実行されません。 API エンドポイントに対する後続の要求では、HTTP 404 エラーコードが返されます。既定ではキーは「無効」に設定されています。

Note

この値を "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 でイベントログを検索して、エラーの詳細を確認できます。

Note

MIM CM REST API を使用した結果として生成されるエラーに対応するスタックトレースは、クライアントに送り返されません。セキュリティ上の問題のため、トレースはクライアントに送り返されません。

次の方法で共有