Credential Provider Extender
開発者用資料
1. この製品について
Credential Provider Extender は Windows の認証を柔軟かつ容易に拡張するための開発用ミドルウェアです。
本製品は Credential Provider の複雑な仕様を隠蔽し、Windows Vista・Windows 7・Windows 8 の各 Edition や 32bit・64bit の違いによる相違点を全て吸収するため、一般的なアプリケーション開発と同程度に平易に認証拡張モジュールを開発できるようになります。
製品の概要や動作イメージについての詳細は インストールマニュアル をご覧ください。
2. モジュール
2.1 概要
本製品(以下、CPE) を導入すると、「モジュール」と呼ばれる実行ファイルを開発することで認証をカスタマイズできるようになります。
モジュールは、ログオン時、ロック時、パスワード変更時に CPE のアイコンが選択されたときに起動されます。起動後、モジュールは資格情報を入力するためのウインドウを表示し、ユーザーからの入力を待機します。
ユーザーからの入力があると、その結果としてどのような処理を行うかを決定し、標準出力を使って CPE に伝えます。例えば、ログオンを行う場合には次のように出力します。
action=logon MsUsername=yamada MsPassword=P4ssw0rD MsDomain=
このように、モジュールと CPE の間のやりとりは標準入力を使うため、モジュールの開発言語にたいする制約はほとんどありません。C++、Visual Basic、C#、MFC、Delphi、Perl など、使い慣れた言語を選択できます。また、モジュールは単独で実行できるため、動作検証のたびにログアウトする必要がありません。統合開発環境(IDE)でのデバッグも可能です。
モジュールからデバイスやネットワークへのアクセスも問題なく行えます。例えば、IC カードから PIN 番号を取得した上で、LDAP サーバーと認証連携を行う、といった複雑になりがちな処理でも、通常のアプリケーションと同じように開発することができます。
2.2 モジュールの設定
モジュールの設定は cpe-config.exe で行います。cpe-config.exe を起動すると、次のような画面が表示されます。
例えば、ログオン画面にアイコンを表示するには、[画面の種類] で「ログオン画面」を選択し、[アイコンを表示する] にチェックをします。次に、[パス] にモジュールのパスを入力します。
[他のアイコンを非表示にする] を選択すると、ログオン画面の表示時に他のアイコンが表示されないようになり、CPE のアイコンが選択された状態で画面表示が行われます。つまり、画面表示時に必ずモジュールが起動します。
[テスト起動] ボタンを押すと、[パス] で設定したモジュールをテスト実行することができます。
設定ツールの詳しい使い方は、3章をご覧ください。
2.3 モジュールの出力
モジュールは標準出力を用いて、「○○というユーザーでログオンする」や「シャットダウンする」といった情報を CPE に伝えます。出力は ini ファイルの形式（名前=値）で行います。
モジュールの終了後、CPE はモジュールの出力を解析して、要求された動作を行います。
出力のうち、一番重要なパラメータが action です。action には次のような種類があります。
| logon | ログオン画面ではログオンする。ロック画面では、ロック解除する（パスワード変更画面では利用できない）。 加えて、次のパラメータも指定する必要がある。
|
|---|---|
| chpwd | パスワードの変更を行う（パスワード変更画面でのみ利用可能）。 加えて、次のパラメータも指定する必要がある。
|
| shutdown | 端末をシャットダウンする。 |
| poweroff | shutdown と同じ。 |
| reboot | 端末を再起動する。 |
| cancel | ようこそ画面に戻る (他のアイコンを表示している場合のみ)。 |
| none | cancel と同じ |
例えば、ログオン画面で起動されたモジュールが、CO-CONV ドメインの tanaka というユーザーでログオンさせるには次のように出力します。
action=logon MsUsername=tanaka MsPassword=P4ssw0rD MsDomain=CO-CONV
この資格情報が正しければ、tanaka というユーザーでログオンします。資格情報に不正だった場合には、Windows 標準のエラーメッセージが表示され、再度、ログオン モジュールが起動されます。
シャットダウンするには次のように出力します。
action=poweroff
2.4 サンプル モジュール
サンプル モジュールは module フォルダーに格納されています。 サンプル モジュールのソースコードは module/source フォルダーに格納されています。 サンプル モジュールの詳細については module/readme.txt を参照してください。
3. Credential Provider Extender の設定
本製品の設定はインストールフォルダに入っている cpe-config.exe を用いて行います。cpe-config.exe を起動すると、「ユーザーアカウント制御」の警告が表示されます。[許可]ボタンを押して起動するようにしてください。
設定が完了したら、[OK] ボタンを押します。設定は直ちに反映され、次回のログオン・ロック・パスワード変更から有効となります。
3.1 モジュール タブ
アイコンを表示するかどうかや、選択時に起動するモジュールのパスなどを指定します。
設定できる項目は次のとおりです。
- 画面の種類
- 設定を行う画面を選びます。「ログオン画面」「ロック画面」「パスワード変更画面」の３種類があります。
- アイコンを表示する
- [画面の種類] で選んだ画面で、アイコンを表示するかどうかを選びます。アイコンが選択されたタイミングで、モジュールが起動されます。
- 他のアイコンを非表示にする
- Windows 標準のアイコンを含め、CPE が表示するアイコン以外を非表示にします。この項目をオンにすると、画面が表示されたタイミングで、モジュールが起動されるようになります。
- パス
- 実行ファイルのパスを指定します。[参照] ボタンを押すと、ファイル選択ダイアログから選ぶことができます。
[相対パスで指定] をチェックすると、実行ファイルのパスを、CPE のインストールフォルダからの相対パスで指定することができます。ご利用の製品で、インストール先のフォルダが状況によって変わる場合にはチェックしておくと便利です。
絶対パスで指定する場合には、環境変数 (%ProgramData%や%SystemDrive%など) を利用できます。 - コマンドライン引数
- 実行ファイルを起動する際のコマンドライン引数を指定します。後述の特殊変数を利用できます。
- テスト起動ボタン
- [パス] で指定した実行ファイルを [コマンドライン引数] をつけて起動します。
特殊変数には次のようなものがあります。
| %s | モジュールが起動されたタイミングを表す文字列に置き換わります。ログオン画面では logon、ロック画面では lock、パスワード変更画面では chpwd となります。 |
|---|---|
| %u | ロック画面・パスワード変更画面で、ログオン中のアカウントのユーザー名に置き換わります。 |
| %d | ロック画面・パスワード変更画面で、ログオン中のアカウントのドメイン名に置き換わります。 |
3.2 表示 タブ
表示タブではアイコンの表示方法の設定を行います。
- アイコンの画像
- アイコンの中に表示する画像を指定します。画像はビットマップ形式でなければなりません。画像のサイズは 128ピクセル×128ピクセルのサイズを指定します。
[相対パスで指定] をチェックすると、画像のパスを、CPE のインストールフォルダからの相対パスで指定することができます。
絶対パスで指定する場合には、環境変数 (%ProgramData%や%SystemDrive%など) を利用できます。 - タイトル文字
- アイコンの下に表示する文字列を指定します。
- 説明用のテキスト
- [タイトル文字]の下に小さく表示される文字列を指定します。
3.3 ログ タブ
ログタブでは CPE が出力するログの設定を行います。
- パス
- ログを出力するパスを指定します。
[相対パスで指定] をチェックすると、出力先のパスを、CPE のインストールフォルダからの相対パスで指定することができます。
絶対パスで指定する場合には、環境変数 (%ProgramData%や%SystemDrive%など) を利用できます。 - ログレベル
- ログを出力する細かさを指定します。ここで指定した数字以下のログがログファイルに出力されます。
ログレベルは以下のものが利用できます。- 1 : error （処理を継続できないような重大なエラーが発生した）
- 2 : warn （処理は継続できるが、問題がある）
- 3 : info （内部動作の情報）
- 4 : debug （デバッグ用のメッセージ）
- ファイルの最大サイズ
- ログの最大サイズを KBbyte(キロバイト) 単位で指定します。0 の場合はログのサイズ制限はありません。0 より大きい場合は、ログのファイルサイズが最大サイズを超えたときには、[保存するファイル数] で指定している世代の数だけログのローテートが行われます。
- 保存するファイル数
- ログのバックアップを行うファイルの数を指定します。バックアップされたファイルは、"ファイル名.<0から始まる番号>" という形式でログと同じフォルダに保存されます。
CPE の動作検証を行うときには、レベル3もしくはレベル4で検証することをお勧めします。モジュールの出力はレベル4で出力されます。ただし、モジュールが出力するパスワード文字列も含まれてしまうため、セキュリティ上の問題が発生する可能性があります。レベル4 は、あくまでデバッグ用にご利用ください。
ログファイルは「<時刻> : <ログレベル> : <ログメッセージ>」が列挙された形で出力されます。
4. モジュール開発上の注意点
ログオンできなくなった場合
他のアイコンを非表示にして検証を行っていると、モジュールの実装ミスによって端末にログオンできなくなってしまうことがあります。ログオンできなくなった場合は、セーフモードで起動し、ログオンの上、cpe-config.exe で設定を変更してください。
ウインドウ表示時の注意
モジュールでウインドウを表示する場合、[常に最前面に表示] というオプションを指定してください。そのようにしなければ、モジュールの表示がログオン画面やロック画面の背後に隠れてしまうことがあります。[常に最前面に表示] オプションの表示名は開発言語や開発環境によって異なるのでご注意ください。
終了条件について
利用者が「ユーザー切り替え」などを行うと、モジュールは CPE によって終了させられます。
このときの処理の流れは次のようになります。
- モジュールのウインドウに WM_CLOSE メッセージを送る
- 5 秒以内にモジュールが終了しなければ、強制終了する
この流れは、タスクマネージャ から [タスクの終了] を行ったときと同等です。 デバイスとの通信やネットワーク通信を行うモジュールの場合、WM_CLOSE メッセージをハンドリングし、適切に終了処理を行うようお願いします。
セキュリティにご注意ください
モジュールは SYSTEM 権限で起動され、ローカルコンピュータへのフルアクセス権限を持ちます。利用者が任意のファイルにアクセスできたり、任意のプロセスを起動できると、ローカルコンピュータを乗っ取られてしまうことになります。
ファイルを扱う場合や、第３者が作成したコンポーネント(IEコンポーネントなど)を利用する際には、十分注意をしてください。
ネットワーク利用上の注意
Windows Vista 以降では電源起動直後の一定時間はネットワークが利用できません。これを回避するためには次のような方法があります。
- グループポリシーで「コンピュータの構成→管理用テンプレート→システム→ログオン」にある「コンピュータの起動およびログオンで常にネットワークを待つ」を有効にする
- モジュールの中で、ネットワークが利用できるかどうか判断する。
モジュールの 64 ビット OS での動作について
32 ビット OS 用に開発したモジュールは、 64 ビット OS 上では WOW64 環境下で動作します。ファイルシステムやレジストリがリダイレクトされるなどの WOW64 の制限にご注意ください。これらの制限を回避するには 64 ビット OS にネイティブ対応するようにモジュールを作成してください。
