Cisco Clean Access (NAC アプライアンス) Manager インストレーション アドミニストレーション ガイド Release 4.1(1)
API サポート
API サポート
発行日;2012/01/11 | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 7MB) | フィードバック

目次

API サポート

概要

認証要件

管理者の操作

adminlogin

adminlogout

MAC の操作

addmac

removemac

addcleanmac

removecleanmac

証明済みデバイス リストの操作

ユーザの操作

kickuser

kickuserbymac

kickoobuser

queryuserstime

renewuserstime

changeuserrole

changeloggedinuserrole

ゲスト アクセスの操作

getlocaluserlist

addlocaluser

deletelocaluser

レポートの操作

getuserinfo

getoobuserinfo

getcleanuserinfo

getreports

API サポート

この章では、Clean Access Manager(CAM)の API サポートについて説明します。この章の内容は以下のとおりです。

「概要」

「認証要件」

「MAC の操作」

「証明済みデバイス リストの操作」

「ユーザの操作」

「ゲスト アクセスの操作」

「レポートの操作」

概要

Cisco NAC アプライアンスは、HTTPS POST を使用して特定の操作を実行できる cisco_api.jsp という名前のユーティリティ スクリプトがあります。CAM の Clean Access API には、Web ブラウザから次の URL でアクセスできます。 https://<ip-or-name>/admin/cisco_api.jsp

この API を使用する場合は、次の点に注意してください。

企業内に Perl などのスクリプト言語に精通している担当者が必要です。

管理ユーザ認証のみをサポートします。HTTP、GET、および「認証を行わない」API はサポートされません。

これらのスクリプトを実行するマシンには、Perl または同様のソフトウェアをインストールする必要があります。

Cisco TAC は Perl またはその他のスクリプト パッケージのデバッグをサポートしません。

CAM から Cisco API ページを表示できます( https://<ccam-ip-or-name>/admin/cisco_api.jsp )。また、次の URL にある cisco_api.jsp ページで、Cisco NAC アプライアンスの情報を確認できます。

http://www.cisco.com/warp/customer/707/ca-mgr-faq2.html#q8

CAM Web コンソール インターフェイスを介してデバイスを免除する方法については、 「デバイスおよびサブネットのグローバル フィルタリング」 を参照してください。

認証要件

API にアクセスするには、SSL を介した認証が必要です。2 つの認証方式がサポートされています。

セッションによる認証

管理者は adminlogin および adminlogout 関数を使用して認証シェル スクリプトを作成し、このスクリプトを使用して、管理セッションの残りの部分でアクセスするセッション ID をクッキーに設定します。セッション ID クッキーが設定されていないと、Invalid User エラーが表示されます。 adminlogin (管理者ログイン)関数は、セッション ID を返します。 adminlogout 関数は、セッションを終了します。ただし、 adminlogout 関数を使用しなかった場合は、CAM が設定されたか、またはデフォルトの管理セッション タイムアウトに従ってセッションを終了します。

関数による認証

クッキーを使用するシェル スクリプトを作成しない場合は、関数が使用されるたびに認証することができます。関数による認証の場合、ユーザは既存スクリプトで使用しているすべての関数に admin および password パラメータを追加する必要があります。この場合は、 adminlogin および adminlogout 関数は使用しません。

管理者の操作

クッキーを使用してセッション ID による認証を実行する場合は、 adminlogin および adminlogout 関数を使用してシェル スクリプトを作成します。これらの関数を使用しない場合は、各関数に管理者のユーザ名およびパスワードのパラメータを含める必要があります。

adminlogin

adminlogin 関数はセッション ID を返します。セッション ID は、別の API で使用するためにクッキーとして設定する必要があります。

必須入力パラメータ:

op:adminlogin

admin:管理者のユーザ名を指定します。

passwd:管理者のパスワードを指定します。

出力パラメータ:<!--error=mesg--> コメント

Success:次の 2 番めのコメントに、メッセージ値 0 とセッション ID が示されます。<!--session_id=SESSION_ID_STRING-->

Failure:エラー文字列

adminlogout

adminlogout 関数は、クッキー内のセッション ID を使用して管理者をログアウトします。

必須入力パラメータ:

op:adminlogout

出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

MAC の操作

ここでは、次の項目について説明します。

「addmac」

「removemac」

「addcleanmac」

「removecleanmac」

addmac

addmac 関数は、1 つまたは複数の MAC アドレスを証明済みデバイス リストに追加します。

必須入力パラメータ:

op:addmac

mac:正確な MAC アドレスまたは範囲を指定します。
サポートされる形式:00:01:12:23:34:45、00:01:12:*、または 00:01:12:23:34:45-11:22:33:44:55:66

任意の入力パラメータ:

ip:正確な MAC アドレスの IPv4 アドレスを指定します。ワイルドカードまたは範囲を指定して、MAC アドレス範囲を指定する場合は、[ip] パラメータは使用しないでください。サポートされる形式:192.168.0.10

type:次の文字列のいずれかを指定します:deny(デフォルト)、allow、userole、check、または ignore

role:ロール名を指定します。role パラメータは、Unauthenticated ロール(デフォルト)の場合は必須ではありませんが、[userole] または [check] の場合は必須です。

desc:説明を入力します。

ssip:Clean Access Server(CAS)を CAM に設定するために使用した IP アドレスを指定します。デフォルトは global です。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

removemac

removemac 関数は、1 つまたは複数の MAC アドレスをデバイス フィルタ リストから削除します。

必須入力パラメータ:

op:removemac

mac:デバイス フィルタ リストから削除する 1 つまたは複数の MAC アドレスを指定します。MAC アドレスは、ワイルドカードを含む表示形式に完全に一致している必要があります。カンマで区切って複数の MAC アドレスを指定できます。

任意の入力パラメータ:

ssip:CAS を CAM に設定するために使用した IP アドレスを指定します。デフォルトは global です。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

addcleanmac

addcleanmac 関数は、1 つまたは複数の MAC アドレスを証明済みデバイス リストに免除デバイスとして追加します。

必須入力パラメータ:

op:addcleanmac

mac:追加する MAC アドレスを指定します。サポートされる形式:00:01:12:23:34:45、00-01-12-23-34-45、または 000112233445

任意の入力パラメータ:

ssip:デフォルトは global です。CAS を CAM に設定するために使用した IP アドレスを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

removecleanmac

removecleanmac 関数は、1 つまたは複数の MAC アドレスを証明済みデバイス リストから削除します。

必須入力パラメータ:

op:removecleanmac

mac:削除する 1 つまたは複数の MAC アドレスを指定します。サポートされる形式:00:01:12:23:34:45、00-01-12-23-34-45、または 000112233445

任意の入力パラメータ:

ssip:デフォルトは global です。CAS を CAM に設定するために使用した IP アドレスを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:ssip が指定されていない場合、または複数の CAS から MAC アドレスを削除できない場合は、1 つまたは複数のエラー文字列が表示されることがあります。

証明済みデバイス リストの操作

clearcertified 関数は、Clean Access 証明済みデバイス リストから既存のエントリをすべて削除します。

必須入力パラメータ:

op:clearcertified


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

ユーザの操作

ここでは、次のユーザ管理関数について説明します。

「kickuser」

「kickuserbymac」

「kickoobuser」

「queryuserstime」

「renewuserstime」

「changeuserrole」

「changeloggedinuserrole」

「getlocaluserlist」

「addlocaluser」

「deletelocaluser」

kickuser

kickuser 関数は、1 つまたは複数の現在ログインしている in-band(IB; インバンド)ユーザのアクティブ セッションを終了します。

必須入力パラメータ:

op:kickuser

ip:1 つの IP アドレスまたはカンマ区切りの IP アドレスのリストを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

kickuserbymac

kickuserbymac 関数は、1 つまたは複数のログインしている IB ユーザのアクティブ セッションを MAC アドレスによって終了します。

必須入力パラメータ:

op:kickuserbymac

mac:1 つの MAC アドレスまたはカンマ区切りの MAC アドレスのリストを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

kickoobuser

kickoobuser 関数は、1 人または複数の out-of-band(OOB; アウトオブバンド)ユーザのアクティブ セッションを終了します。

必須入力パラメータ:

op:kickoobuser

mac:1 つの MAC アドレスまたはカンマ区切りの MAC アドレスのリストを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

queryuserstime

queryuserstime 関数は、ログインしているユーザの残りのセッション時間を照会します。この関数は、セッション タイムアウトが設定されたロールのログイン ユーザのリストを返します。

必須入力パラメータ:

op:queryuserstime


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0。もう 1 つの <!--list=iplist--> コメントには、IP リストと、各 IP エントリのセッションの残り時間が示されます。

Failure:エラー文字列

renewuserstime

ログインしたユーザのセッション タイムアウトを、セッションを使用して更新します。

必須入力パラメータ:

op:renewuserstime

list:カンマ区切りの IP アドレスのリストを指定します。サポートされる形式:10.1.10.10, 10.1.10.11, 10.1.10.12


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

changeuserrole

changeuserrole 関数は、IB ユーザをオンライン ユーザ ロールから削除し、そのユーザの MAC アドレスを新しいロールでデバイス フィルタ リストに追加することで、IB ユーザがログインする前にそのユーザのアクセス権を変更します。

必須入力パラメータ:

op:changeuserrole

ip:ログインしているユーザの IP アドレスを指定します。

role:ユーザの移動先のロールを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

changeloggedinuserrole

changeloggedinuserrole 関数は、ログインしている IB ユーザの現在のロールを新しいロールに変更することで、そのユーザのアクセス権を変更します。

必須入力パラメータ:

op:changeloggedinuserrole

ip:ログインしているユーザの IP アドレスを指定します。複数のユーザを指定するには、カンマ区切りの IP リストを使用します。

role:ユーザの新しいロールを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

ゲスト アクセスの操作

ここでは、次の関数について説明します。

「getlocaluserlist」

「addlocaluser」

「deletelocaluser」

これらの API 関数を使用して、管理者は CAM 上でローカル ユーザ アカウントを作成、削除、および表示できます(ローカル ユーザは、外部認証サーバではなく、CAM によって内部的に検証されるユーザです)。これらの API は、ダイナミック トークン ユーザ アクセスを生成するためのゲスト アクセスのサポートを目的としています。そのため、次の機能を備えています。

Web ページを使用して Cisco NAC アプライアンス API にアクセスし、ビジターのユーザ名/パスワードの組み合せ(jdoe@visitor.com/jdoe112805 など)を挿入し、ロールを割り当てます( guest1day など)。

該当日にゲスト アクセス ロールに関連付けられたゲスト ユーザをすべて削除します。

ゲスト アクセス ロールに関連付けられたすべてのユーザ名をリストします。

これらの API は、ゲスト ユーザ アクセス用のダイナミック トークン/パスワード生成をほとんどサポートし、ゲストロールに対応するゲスト ユーザの削除を許可します。

フロントエンド生成パスワード/トークンを作成する必要があります。Cisco NAC アプライアンスに備わっているアカウンティング機能は、RADIUS のみです。

getlocaluserlist

getlocaluserlist 関数は、ローカル ユーザ アカウントとそれらのユーザ名およびロール名のリストを返します。

必須入力パラメータ:

op:getlocaluserlist


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0。<!--count=10--> に返されたユーザ数が示され、続いて、<!--NAME=jdoe,ROLE=Student--> の形式で同じ数のコメントが表示されます。

Failure:エラー文字列

addlocaluser

addlocaluser 関数は、新しいローカル ユーザ アカウントを追加します。

必須入力パラメータ:

op:addlocaluser

username:新しいローカル ユーザ アカウントのユーザ名を指定します。

userpass:新しいローカル ユーザ アカウントのユーザ パスワードを指定します。

userrole:新しいローカル ユーザ アカウントのロールを指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

deletelocaluser

deletelocaluser 関数は、1 つまたはすべてのローカル ユーザ アカウントを削除します。

必須入力パラメータ:

op:deletelocaluser

qtype:name または all のいずれかのデータ タイプを指定します。

qval:一重引用符で囲んだ正確なユーザ名を指定するか、または [all] を示す空の文字列 ‘' を指定します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0

Failure:エラー文字列

レポートの操作

スクリプトを作成して情報のリストを編集したり、次のレポート関数を使用してレポートしたりできます。

「getuserinfo」

「getoobuserinfo」

「getcleanuserinfo」

「getreports」

getuserinfo

特定の IP アドレス、MAC アドレス、またはユーザ名について、 getuserinfo 関数は次のユーザ情報を取得します。

IPv4 形式の IP

MAC アドレス

Name はユーザ名です。

Provider は、LDAP サーバの場合があります。

Role は、ユーザに割り当てられている現在のロールです。

Origrole は、ユーザに割り当てられた本来のロールです。

VLAN は、本来の VLAN タグです。

NEWVLAN は、現在の VLAN タグです。

ユーザのシステムのオペレーティング システム

複数のユーザが条件に一致する場合、システムはユーザのリストを返します。qtype パラメータとして [all] を入力した場合は、すべてのユーザのすべての情報が取得されます。

必須入力パラメータ:

op:getuserinfo

qtype:次の文字列のいずれかを指定します:ip、mac、name、または all

qval:qtype パラメータに応じて IP アドレス、MAC アドレス、またはユーザ名を指定します。[all] を指定した場合は、空の文字列(‘')を入力します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0。<!--count=10--> に返されたユーザ数が示され、続いて、対応する数のコメント <!--IP=10.1.10.12,MAC=0A:13:07:9B:82:60,NAME=jdoe,PROVIDER=LDAP Server,ROLE=Student,ORIGROLE=Student,VLAN=1024,NEWVLAN=1024,OS=Windows XP--> が表示されます。

Failure:エラー文字列

getoobuserinfo

特定の IP アドレス、MAC アドレス、またはユーザ名について、 getoobuserinfo 関数は、ログインしている OOB ユーザに関する情報を取得します。または、qtype パラメータに [all] を指定した場合は、システムはログインしているすべての OOB ユーザに関するすべての情報のリストを生成します。複数のユーザが条件に一致する場合、システムはユーザのリストを生成します。

必須入力パラメータ:

op:getoobuserinfo

qtype:1 人または複数のユーザを識別する方式を指定します。ip、mac、name、または all

qval:IP アドレス、MAC アドレス、またはユーザ名を指定します。[all] を指定する場合は、空の文字列(‘')を入力します。


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0。<!--count=10--> に返されたユーザ数が示され、続いて、相当する数のコメント <!--IP=10.1.10.12,MAC=0A:13:07:9B:82:60,NAME=jdoe,PROVIDER=LDAP Server,ROLE=Student,AUTHVLAN=10,ACCESSVLAN=1024,OS=Windows XP,SWITCHIP=10.1.10.1,PORTNUM=18--> が表示されます。

Failure:エラー文字列

getcleanuserinfo

特定の MAC アドレスまたはユーザ名について、 getcleanuserinfo 関数は認証済みユーザに関する情報を返します。複数のユーザが条件に一致する場合、システムは認証済みユーザのリストを生成します。

必須入力パラメータ:

op:getcleanuserinfo

qtype:1 人または複数のユーザを識別する方式を指定します。mac、name、または all

qval:MAC アドレスまたはユーザ名を指定します。[all] を指定する場合は、空の文字列(‘')を入力します。

出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0。<!--count=10--> に返されたユーザ数が示され、続いて、相当する数のコメントが <!--MAC=0A:13:07:9B:82:60,NAME=jdoe,PROVIDER=LDAP Server,ROLE=Student,VLAN=10--> の形式で表示されます。

Failure:エラー文字列

getreports

getreports 関数は、カスタマイズされた内容を含むレポートを返します。また、この関数を使用して、特定のソフトウェアがインストールされているユーザのリストを編集できます。

必須入力パラメータ:

op:getreports


) セッション ID による認証を使用しない場合は、admin および passwd 関数は必須です。「認証要件」を参照してください。


任意のクエリ パラメータ:

表B-1 に、 getreports 関数のクエリ パラメータを示します。

 

表B-1 getreports 関数のクエリ パラメータ

パラメータ名
有効な値
説明

status

次の値のいずれか:

any(デフォルト)

success

failure

指定されたステータスの情報だけをレポートします。

user

文字列。デフォルトは、一重引用符で囲んだ空の文字列です。

指定されたユーザに関する情報をレポートします。

userKey

文字列。デフォルトは、一重引用符で囲んだ空の文字列です。

このユーザの鍵を含む情報をレポートします。

ip

1 つの有効な IPv4 アドレス(10.20.30.40 など)。デフォルトは一重引用符で囲まれた空の値です。

指定された IP アドレスに関する情報をレポートします。

mac

1 つの有効な MAC アドレス(00:01:12:23:34:45 など)。デフォルトは、一重引用符で囲んだ空の値です。

指定された MAC アドレスに関する情報をレポートします。

os

次の値のいずれか:

任意の OS を指定するには、一重引用符で囲んだ空の値('')を入力します(デフォルト)。

WINDOWS_VISTA_ALL(Windows Vista)

WINDOWS_VISTA_HOME_BASIC(Windows Vista Home Basic)

WINDOWS_VISTA_BUSINESS(Windows Vista Business)

WINDOWS_VISTA_ULTIMATE(Windows Vista Ultimate)

WINDOWS_VISTA_ENTERPRISE(Windows Vista Enterprise)

WINDOWS_XP(Windows XP)

WINDOWS_PRO_XP(Windows XP Pro/Home)

WINDOWS_TPC_XP(Windows XP Tablet PC Edition)

WINDOWS_MCE_XP (Windows XP Media Center Edition)

WINDOWS_2K(Windows 2000)

WINDOWS_ME(Windows ME)

WINDOWS_98(Windows 98)

指定された OS に関する情報をレポートします。

timeRange

timeFrom、timeTo

timeFrom は、次の値のいずれかになります。

タイムスタンプ(形式:yyyy-mm-dd hh:mm:ss)

現在より何時間前かを示す負の整数

past

timeTo は、次の値のいずれかになります。

タイムスタンプ(形式:yyyy-mm-dd hh:mm:ss)

現在より何時間前かを示す負の整数

now

-48, -24(昨日)

-24, now(当該日)

2007-01-01 00:00:00, 2007-02-28 23:59:59(1 月 1 日から 2 月 28 日までの間)

デフォルト:past, now(時間を問わず、すべての可能なレポート)

指定した時間範囲内に収集した情報をレポートします。

showText

次の値のいずれか:

true ― テキストを返します。

false ― テキストを返しません(デフォルト)。

レポート テキストを返すかどうかを指定します。

orderBy

次の値のいずれか:

user

userKey

ip

mac

os

time(デフォルト)

レポートの編成方法を指定します。

orderDir

次の値のいずれか:

asc ― 昇順を指定します(デフォルト)。

desc ― 降順を指定します。

データの昇順または降順を指定します。

instSoft

次の値のいずれか:

一重引用符で囲んだ空の値(‘’)は、[any] を示しています(デフォルト)。

AV ― AntiVirus(AV; アンチウイルス)がインストール済み

AS ― AntiSpyware(AS; アンチスパイウェア)がインストール済み

UNKNOWN AV/AS ― 不明の AV/AS

このタイプのインストール済みソフトウェアを含むレポートのみに制限します。

reqName

AV または AS ソフトウェア名の要件。一重引用符で囲んだ空の値は [any] を示します(デフォルト)。

このソフトウェア要件を満たすレポートだけに制限します。

reqStatus

次の値のいずれか:

any(デフォルト)

success

failure

ソフトウェア要件を満たし、ステータスが条件に一致するレポートだけに制限します(reqName が使用されている場合のみ)。

出力パラメータ:<!--error=mesg--> コメント

Success:メッセージ値 0。<!--count=count--> に返されたレポート数が示されます。レポート数に続き、同じ数のコメントが、
<!--status=status,user=user,userKey=userKey,ip=ip,mac=mac,os=os,time=time,text=text--> の形式で表示されます。

Failure:エラー文字列