PAM REST API サービスの詳細
次のセクションでは、Microsoft Identity Manager (MIM) Privileged Access Management (PAM) REST API の詳細について説明します。
HTTP 要求ヘッダー
API に送信される HTTP 要求には、次のヘッダーを含める必要があります (この一覧は網羅的ではありません)。
| Header | 説明 |
|---|---|
| 承認 | 必須です。 コンテンツは、構成可能な認証方法に依存し、WIA (Windows 統合認証) または ADFS に基づいて指定できます。 |
| Content-Type | 要求本文が含まれる場合は必須。
application/json に設定する必要があります。 |
| Content-Length | 要求本文が含まれる場合は必須。 |
| クッキー | セッションの Cookie。 認証方法によって必要な場合があります。 |
HTTP 応答ヘッダー
HTTP 応答には、次のヘッダーを含める必要があります (この一覧は完全ではありません)。
| Header | 説明 |
|---|---|
| Content-Type | API は常に を返します application/json。 |
| Content-Length | 要求本文がある場合は、その長さ (バイト)。 |
バージョン管理
API の現在のバージョンは 1 です。
API バージョンは、次の例のように、要求 URL でクエリ パラメーターを通じて指定できます: http://localhost:8086/api/pamresources/pamrequests?v=1。バージョンが要求で指定されていない場合、一番新しくリリースされたバージョンの API に対して要求が実行されます。
セキュリティ
API へのアクセスには、統合 Windows 認証 (IWA) が必要です。 これは Microsoft Identity Manager (MIM) をインストールする前に、IIS で手動で構成する必要があります。
HTTPS (TLS) はサポートされていますが、IIS で手動で構成する必要があります。 詳細については、「INSTALLing FIM 2010 R2 Test Lab Guide」の「手順 9: インストール後の FIM 2010 R2 タスクを実行する」の「FIM ポータルに Secure Sockets Layer (SSL) を実装する」を参照してください。
Visual Studio コマンド プロンプトで、次のコマンドを実行して、新しい SSL サーバー証明書を生成できます。
Makecert -r -pe -n CN="test.cwap.com" -b 05/10/2014 -e 12/22/2048 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localmachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12
コマンドは、URL test.cwap.comが である Web サーバーで SSL を使用する Web アプリケーションをテストするために使用できる自己署名証明書を作成します。 オプションで定義された -eku OID は、証明書を SSL サーバー証明書として識別します。 証明書は ストア に格納され、マシン レベルで使用できます。 証明書は、mmc.exeの [証明書] スナップインからエクスポートできます。
クロス ドメイン アクセス (CORS)
CORS はサポートされていますが、IIS で手動で構成する必要があります。 展開済みの API web.config ファイルに次の要素を追加して、クロス ドメインの呼び出しができるように API を構成します。
<system.webServer>
<httpProtocol>
<customHeaders>
<add name="Access-Control-Allow-Credentials" value="true" />
<add name="Access-Control-Allow-Headers" value="content-type" />
<add name="Access-Control-Allow-Origin" value="http://<hostname>:8090" />
</customHeaders>
</httpProtocol>
</system.webServer>
エラー処理
API は、エラー状態を示すために HTTP エラー応答を返します。 エラーは、OData 準拠です。 次の表は、クライアントに返される可能性があるエラー コードを示しています。
| HTTP 状態コード | 説明 |
|---|---|
| 401 | 権限がありません |
| 403 | Forbidden |
| 408 | 要求タイムアウト |
| 500 | 内部サーバー エラー |
| 503 | サービス利用不可 |
フィルター処理
PAM REST API 要求には、応答に含める必要があるプロパティを指定するフィルターを含めることができます。 フィルター構文は、OData の式に基づいています。
フィルターでは、PAM 要求、PAM ロール、 または保留中の PAM 要求の任意のプロパティを指定できます。 たとえば ExpirationTime や DisplayName ですが、その他にも PAM 要求、PAM ロール、保留中要求の有効なプロパティはどれでも指定できます。
フィルター式で使用できる演算子は、And、Equal、NotEqual、GreaterThan、LessThan、GreaterThenOrEqueal、LessThanOrEqual です。
次の要求例には、次のフィルターが含まれています。
この要求は、指定した期間のすべての PAM 要求を返します:
http://localhost:8086/api/pamresources/pamrequests?$filter=ExpirationTime gt datetime'2015-01-09T08:26:49.721Z' and ExpirationTime lt datetime'2015-02-10T08:26:49.722Z'この要求は、表示名が "SQL File Access" の PAM ロールが返されます:
http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'