Cisco Identity Services Engine Release 1.1.x API リファレンス ガイド
Monitoring REST API の概要
Monitoring REST API の概要
発行日;2012/09/25 | 英語版ドキュメント(2012/03/30 版) | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 1MB) | フィードバック

目次

Monitoring REST API の概要

Cisco Monitoring ISE ノードの確認

サポートされる API コール

HTTP PUT を使用したサポート対象の API コール

Monitoring REST API の概要

Cisco Identity Services Engine API リファレンス ガイド 』には、サポート対象の 3 つのカテゴリの Representational State Transfer(REST)API および関連 API コール使用のガイドラインと使用例が記載されています。REST API とコールでは、ネットワークで Cisco Monitoring ISE ノードを使用することにより、セッションおよびノード固有の情報を収集することができます。セッションは、目的のノードへのアクセスの開始から情報の収集に必要なタスクまたは操作のセットの完了までの期間として定義されます。

Cisco ISE Release 1.1.1 でユーザが使用できる、サポート対象の Monitoring REST API のカテゴリは、次のとおりです。

クエリー

セッション管理

トラブルシューティング

認可変更(CoA)


) Monitoring ペルソナによって監視されているエンドポイントに関する情報を収集するためには、これらのサポート対象の REST API カテゴリだけを使用できます。Monitoring は、ISE のノード タイプが Cisco ISE リリース 1.1 の展開で実行できる、サポート対象の 3 つのペルソナの 1 つです。このガイドの残りの部分では、Cisco ISE ノードの Monitoring ペルソナを説明するため、「Monitoring ISE ノード」を使用します。


これらの API を Cisco ISE 展開における Cisco ISE アプライアンスの Policy service ペルソナに関する情報の収集に使用しようとすると、エラーが発生します。Cisco ISE ノードおよびペルソナに関する詳細については、『Cisco Identity Services Engine User Guide, Release 1.1.1』を参照してください。

REST API コールは、ユーザが Cisco Monitoring ISE ノードを通じてアクセスできるネットワークで、個々のエンド ポイントに格納されている重要なリアルタイムのセッション ベースの情報を検索、監視、収集する手段を提供します。

ユーザが収集するリアルタイムのセッション ベースの情報は、Cisco ISE 操作の理解、状態や問題の診断の支援に役立ちます。また、モニタリング業務に影響を与える可能性のあるエラー状態、アクティビティ、動作などのトラブルシューティングに使用することもできます。REST API が Cisco ISE 分散展開で果たす役割を図 1-1 に示します。

図 1-1 に示すように、REST(HTTPS)API コールは、サポートされているクライアントのタイプ(リモート Java、ブラウザ ベース、または PHP(ハイパーテキスト プリプロセッサ))によって使用され、Cisco Monitoring ISE ノードにアクセスして Cisco ISE 展開のエンド ポイントに格納されている重要なセッション ベースの情報を取得する目的で使用されます。

図 1-1 Cisco ISE の分散展開および REST API

Cisco Monitoring ISE ノードの確認

API コールを Cisco Monitoring ISE ノードで正常に呼び出す前に、監視するノードが有効な Cisco Monitoring ISE ノードであることを確認しておく必要があります。これを確認するには、正常にログインして、Cisco ISE ネットワークによって認証を受ける必要があります。


) パブリック REST API を使用できるようにするには、サポート対象の Cisco ISE 管理ロール(Helpdesk Admin、Identity Admin、Monitoring Admin、Network Device Admin、Policy Admin、RBAC Admin、Super Admin、System Admin)の有効なクレデンシャルを使用して、最初に Cisco ISE で認証を受ける必要があります。


ログインして認証を受けるには、次の手順を実行します。


ステップ 1 有効なログイン クレデンシャル(ユーザ名とパスワード)を [Cisco ISE ログイン(Cisco ISE Login)] ウィンドウに入力し、[ログイン(Login)] をクリックします。

Cisco ISE ダッシュボードとユーザ インターフェイスが表示されます。

ステップ 2 [許可(Authorization)] > [システム(System)] > [展開(Deployment)] の順に選択します。

展開されたすべての設定済みノードがリストされた [展開ノード(Deployment Nodes)] ページが表示されます。

ステップ 3 [展開ノード(Deployment Nodes)] ページの [ロール(Roles)] カラムに、監視するターゲット ノードのロールが Cisco Monitoring ISE ノード タイプとして表示されていることを確認します。


 

サポートされる API コール

ここでは、ノード固有またはセッション固有の情報を取得して表示するコールをプログラムで発行するためのインターフェイスを提供する REST API の概要を説明します。次の表に、API カテゴリと API コールのタイプ、API コールの形式の簡単な説明および例を示します。

表 1-1:セッション管理用のクエリー API コールを定義します。

表 1-2:トラブルシューティング用のクエリー API コールを定義します。

表 1-3:CoA API コールを定義します。


) このマニュアルで説明する API コールを実行するには、最初に Cisco ISE ネットワークにログインして認証を受けておく必要があります。パブリック REST API を使用するための認証要件については、「Cisco Monitoring ISE ノードの確認」を参照してください。


Cisco ISE でサポートされる REST API を使用して認証を受けるため、汎用プログラマチック インターフェイスを使用する計画の場合、Cisco ISE と使用するツールとの間を接続する REST ベースのクライアントを最初に作成する必要があります。次に、この REST クライアントを使用して Cisco ISE REST API での認証を実行し、API 要求を変換して Monitoring ISE ノードに送信します。そして、API 応答を再変換し、これらの応答を指定されたツールに引き渡します。

表 1-1 Cisco ISE クエリー API コール:セッション管理

Cisco ISE API コール カテゴリ
Cisco ISE API コールの説明と例

セッション管理

セッション カウンタ

アクティブ セッション カウンタ

現在アクティブなセッションの数をリストします。

https://<ISEhost>/ise/mnt/api/Session/ActiveCount

ポスチャ セッション カウンタ

現在アクティブなポスチャ サービス セッションの数をリストします。

https://<ISEhost>/ise/mnt/api/Session/PostureCount

(注) ポスチャとは、Cisco ISE ネットワークに接続しているすべてのエンドポイントの状態(またはポスチャ)の確認を支援するサービスです。

プロファイラ セッション カウンタ

現在アクティブなプロファイラ サービス セッションの数をリストします。

https://<ISEhost>/ise/mnt/api/Session/ProfilerCount

(注) プロファイラとは、Cisco ISE ネットワークにあるすべての接続エンドポイントの機能の識別、検索、確認を支援するサービスです。

単純なセッションのリスト

(注) 単純なセッション リストには、MAC アドレス、ネットワーク アクセス スイッチ(NAS)の IP アドレス、ユーザ名、セッションに関連付けられているセッション ID 情報が含まれます。Cisco Identity Services Engine Release 1.1.1 は、IPv6 に準拠していません。

(注) Cisco ISE における IPv6 のサポートの度合いは、IPv6 ネットワーク(IPv6 ステートレス自動設定および DHPv6 など)でアドレス指定されたノードに関係している場合だけです。ただし、Cisco ISE Release 1.1.1 プロトコル スタック(ランタイムや mgmt など)のいずれも IPv6 をサポートしません。

アクティブなセッション リスト

現在アクティブなすべてのセッションをリストします。

https://<ISEhost>/ise/mnt/api/Session/ActiveList

(注) Cisco ISE のこのリリースでは、アクティブな認証済みエンドポイント セッションの表示可能な最大数は、100,000 に制限されています。

認証済みセッション
リスト

現在アクティブなすべての認証済みセッションをリストします。

https://<ISEhost>/ise/mnt/api/Session/AuthList/<parameteroptions>

(注) starttime/endtime の形式は、yyyy-mm-dd hh24:MM:ss(例:2010-12-10 16:30:00)です。

(注) 異なる値を返す次のパラメータ オプションを指定できます。

null/null が指定されると、現在アクティブなすべての認証済みセッションがリストされます。

null/endtime が指定されると、指定された endtime の後にアクティブなすべての認証済みセッションがリストされます。

starttime/null が指定されると、指定された starttime の前にアクティブなすべての認証済みセッションがリストされます。

starttime/endtime が指定されると、指定された starttime と endtime の間で認証されたすべてのセッションがリストされます。

4 つのパラメータ オプションをすべて示すサンプルについては、「AuthList API コールから返されるサンプル データ」を参照してください。

(注) Cisco ISE のこのリリースでは、アクティブな認証済みエンドポイント セッションの表示可能な最大数は、100,000 に制限されています。

詳細なセッション属性

(注) これは、指定された検索属性を含む最新のセッションのタイムスタンプに基づいた検索です。

MAC アドレス セッションの検索

指定した MAC アドレスを含む最新のセッションについてデータベースを検索します。

https://<ISEhost>/ise/mnt/api/Session/MACAddress/<macaddress>

(注) XX:XX:XX:XX:XX:XX は MAC アドレス形式です。大文字と小文字は区別されません(例:0a: 0B: 0c: 0D: 0e: 0F)。

(注) MAC アドレスは、監視対象の正しいセッションを検索する唯一の一意のキーとして機能します。MAC アドレスの検索のベースとすることが可能なアクティブなすべてのセッションと MAC アドレスをリストするには ActiveList API コールを使用します。

ユーザ名セッション
検索

指定したユーザ名を含む最新のセッションについてデータベースを検索します。

https://<ISEhost>/ise/mnt/api/Session/UserName/<username>

』の「User Password Policy」を参照してください。

NAS IP アドレス セッションの検索

指定した NAS IP アドレスを含む最新のセッションについてデータベースを検索します。

https://<ISEhost>/ise/mnt/api/Session/IPAddress/<nasipaddress>

(注) xxx.xxx.xxx.xxx は NAS IP アドレス形式(例:10.10.10.10)です。

セッション管理用の Cisco ISE クエリー API コールの詳細については、「セッション管理のためのクエリー API の使用」を参照してください。

表 1-2 Cisco ISE クエリー API コール:トラブルシューティング

Cisco ISE API コール カテゴリ
Cisco ISE API コールの説明と例

クエリー:トラブルシューティング

ノードのバージョンとタイプの取得

ノードのバージョンと
タイプ

ノードのバージョンおよびタイプをリストします。

https://<ISEhost>/ise/mnt/api/Version

ノードのタイプは、次の値(0 ~ 3)のいずれかです。
STAND_ALONE_MNT_NODE = 0
ACTIVE_MNT_NODE = 1
STAND_BY_MNT_NODE = 2
NOT_AN_MNT_NODE = 3

NOT_AN_MNT_NODE は、Cisco Monitoring ISE ノードではないことを意味します。サポート対象の ISE ノードおよびペルソナの詳細については、『Cisco Identity Services Engine User Guide, Release 1.1.1』を参照してください。

障害理由マッピングの取得

障害理由

障害の理由をリストします。

https://<ISEhost>/ise/mnt/api/FailureReasons

各障害理由は、次の例に示すように、エラーコード(failureReason id)、簡単な説明(code)、障害理由(cause)、および可能な対処(resolution)を表示します。

<failureReason id="100009">
<code> 100009 WEBAUTH_FAIL
<cause> This may or may not be indicating a violation.
<resolution> Please review and resolve this issue according to your organization's policy.

(注) FailureReasons API コールの設計用途は、Monitoring ISE ノードから情報を収集するために一度だけ呼び出す必要がある場合に対処するものです。使用しているファイル システムまたはデータベースに、返された障害理由の内容を保存する必要があります。これらの API コールの返信内容はあくまでも参照用に使用することを目的としています。認証中に問題が発生した場合、認証応答で提供される障害理由コードと、ユーザのファイル システムまたはデータベースに保存しているた障害理由のリストと比較する必要があります。

Cisco ISE 障害理由の完全なリストについては、 付録 A「Cisco ISE Failure Reasons Editor の使用」 を参照してください。

セッションの認証ステータスの取得

セッションの認証
ステータス

すべてのセッションの認証ステータスをリストします。

https://<ISEhost>/ise/mnt/api/AuthStatus/MACAddress/<macaddress>/<numberofseconds>/<numberofrecordspermacaddress>/All

(注) seconds パラメータ <numberofseconds> は、最短 0 秒から最長 432000 秒(5 日)の範囲でユーザが設定できます。

(注) 認証ステータスは、すべてのデータ フィールドが RADIUS_AUTH テーブルで使用可能なときに定義されます。

セッション アカウンティング ステータスの取得

アカウンティング セッション
ステータス

特定の期間内のすべてのセッションのアカウンティング ステータスを示します。

https://<ISEhost>/ise/mnt/api/Session/AcctStatusTT/MACAddress/
<macaddress>/<numberof seconds>

(注) seconds パラメータ <numberofseconds> は、最短 0 秒から最長 432000 秒(5 日)の範囲でユーザが設定できます。

トラブルシューティング用の Cisco ISE クエリー API コールの詳細については、「セッション管理のためのクエリー API の使用」を参照してください。

表 1-3 Cisco ISE 認可変更 API コール

Cisco ISE API コール カテゴリ
Cisco ISE API コールの説明と例

CoA セッション管理

セッション再認証

セッション
再認証
タイプ

セッション再認証コマンドとタイプを送信します。

https://<ISEhost>/ise/mnt/api/CoA/Reauth/<serverhostname>/
<macaddress>/<reauthtype>/<nasipaddress>/
<destinationipaddress>

再認証タイプは次の値(0 ~ 2)のいずれかです。
REAUTH_TYPE_DEFAULT = 0
REAUTH_TYPE_LAST = 1
REAUTH_TYPE_RERUN = 2

(注) NAS IP アドレスが不明な場合は、この時点までに必要な値を入力できます。API はこれらの値を検索クエリーに使用します。ただし、この API コールを実行するには、MAC アドレスを知っている必要があります。

この API コールは、CoA をリモートで実行する要求を送信する Monitoring ISE ノードでしか実行できません。Administration ISE ノードは、これらの CoA API コールの実行には関係ないか、必要がありません。

セッション切断

セッション切断
タイプ

セッション切断コマンドおよびポート オプション タイプを送信します。

https://<ISEhost>/ise/mnt/api/CoA/Disconnect/<serverhostname>/
<macaddress>/<disconnecttype>/<nasipaddress>/
<destinationipaddress>

DYNAMIC_AUTHZ_PORT_SHUTDOWN = 2

(注) NAS IP アドレスが不明な場合は、この時点までに必要な値を入力します。API はこれらの値を検索クエリーに使用します。ただし、この API コールを実行するには、MAC アドレスを知っている必要があります。

Cisco ISE 認可変更 API コールに関する詳細については、「認可変更 REST API の使用」を参照してください。

HTTP PUT を使用したサポート対象の API コール

表 1-2 のセッションの認証ステータス取得 API コールと同様に、クライアントがアカウント ステータスを取得できるようにする REST API 実装の HTTP PUT バージョンがあります。REST API は、HTTP GET コールについて記述したこのマニュアルの例で示すように、HTTP PUT と HTTP GET の両方のコールをサポートします。HTTP PUT のバージョンは、パラメータの入力が必要な API の必要性に対処します。次のスキーマ ファイルの例は、アカウント ステータスの要求です。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
<xs:element name="acctRequest" type="mnTRESTAcctRequest"/>
 
<xs:complexType name="mnTRESTAcctRequest">
<xs:complexContent>
<xs:extension base="mnTRESTRequest">
<xs:sequence>
<xs:element name="duration" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
 
<xs:complexType name="mnTRESTRequest" abstract="true">
<xs:sequence>
<xs:element name="valueList">
<xs:complexType>
<xs:sequence>
<xs:element name="value" type="xs:string" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="searchCriteria" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>