前回の記事では、Swagger UI を使用して SPP ローカルユーザーを作成する手順を紹介しました。
今回は、SPP API を PowerShell から操作する safeguard-ps モジュール の使用方法を紹介します。
safeguard-ps モジュールは、One Identity のオープンソースプロジェクトでサポートされます。
※参照：OneIdentity/safeguard-ps（https://github.com/OneIdentity/safeguard-ps）
safeguard-ps モジュールとは
safeguard-ps モジュールは、One Identity Safeguard Web API と対話するためのスクリプトツールです。Microsoft がサポートする PowerShell Gallery で公開されています。
Web ブラウザーを開いて powershellgallery.com にアクセスし、safeguard-ps を検索してみてください。safeguard-ps モジュールが見つかります。
PowerShell は Windows プラットフォームのスクリプト言語ですが、macOS や Linux でも使用できます。
safeguard-ps モジュールは、PowerShell がサポートするすべてのプラットフォームをサポートされるべきですが、Windows 以外のプラットフォームでサポートされていないコマンドレットまたはコマンドレットパラメーターが存在する場合があります（使用した場合、サポートされていないことを示すメッセージが表示されます）。Windows 以外のプラットフォームで問題が発生した場合は、ご連絡ください。
safeguard-ps モジュールのインストール
はじめに、お使いのコンピューターに safeguard-ps モジュールをインストールする必要があります。次のいずれかの手順で、safeguard-ps をインストールしてください。
PowerShell Gallery からインストールする
ここでは、Windows マシンに PowerShell Gallery から safeguard-ps モジュールをインストールする手順を紹介します。
Windows PowerShell を 管理者として実行 します。
次のコマンドを実行します。
Install-Module safeguard-ps –RequiredVersion 7.0.68972
ここでは、-RequiredVersion オプションを使用することで、インストールするモジュールのバージョンを指定しています。ご利用中の SPP アプライアンスバージョンの先頭の 2つの数字が等しいモジュールバージョンを使用してください（例えば、ver 7.0.4 をお使いの場合は、7.0.x を指定してください）。３つ目の数字は異なっていて構いません。モジュールバージョンは PowerShell Gallery で確認してください。）
Install-Module コマンドレットは、PowerShell Gallery で safeguard-ps を見つけ、すべてのユーザーに対してインストールします。これは、すべてのユーザーに対してソフトウェアをインストールできる管理者として PowerShell を実行する必要があることを意味します。
管理者として PowerShell を実行することができない場合は、通常の PowerShell プロンプトを開き、次のように入力してください。現在のユーザーに対してのみ safeguard-ps モジュールをインストールすることができます。Install-Module safeguard-ps -Scope CurrentUser
Y を入力して Enter キーを押します。
デフォルトでは、信頼されていないリポジトリのため、インストール時に信頼するかどうか確認されます。
次のコマンドを実行し、safeguard-ps モジュールがインストールされたことを確認します。
Get-Module safeguard-ps -ListAvailable
この例の場合は、C:\Program Files\WindowsPowerShell\Modules にインストールされたことがわかります。
GitHub から zip をダウンロードしてインストールする
Install-Module を使用して safeguard-ps モジュールをインストールできない場合は、GitHub から zip ファイルをダウンロードして手動でインストールしてください。
Web ブラウザーを開き、github.com/oneidentity/safeguard-ps にアクセスします。
master ボタンをクリックし、 Branches から release-7.0 を選択します。
ご利用中の SPP バージョンと同じバージョンを選択してください。
Code ボタンをクリックし、Download ZIP をクリックします。
zip ファイルを保存し、任意の場所に展開します。
Windows PowerShell を 管理者として実行 します。
cd コマンドで展開したフォルダの場所に移動（この例の場合は、safeguard-ps-release-7.0 フォルダ）に移動し、次のコマンドを実行します。
./install-local.ps1
「このシステムではスクリプトの実行が無効になっているため、ファイル xxxxxxx\safeguard-ps-release-7.0\install-local.ps1 を読み込むことができません。」というメッセージが表示された場合は、次のコマンドを実行して実行ポリシー(ExecutionPolicy)を変更したあとで、上記のコマンドを再度実行してください。
Set-ExecutionPolicy Bypass -Scope Process
この例の場合は、’C:\Users\<現在のログインユーザー>\Documents\WindowsPowerShell\Modules\safeguard-ps にインストールされました。
safeguard-ps モジュールのインポート
インストールが完了したら、次のコマンドを実行し safeguard-ps モジュールをインポートします。
Import-Module safeguard-ps
「このシステムではスクリプトの実行が無効になっているため、ファイル C:\Program Files\WindowsPowerShell\Modules\safeguard-ps\xxxxxx\xxxxx.psm1 を読み込むことができません。」というメッセージが表示された場合は、次のコマンドを実行して実行ポリシー(ExecutionPolicy)を変更したあとで、上記のコマンドを再度実行してください。
Set-ExecutionPolicy Bypass -Scope Process
次のコマンドを実行し、safeguard-ps モジュールがインポートされたことを確認します。
Get-Module safeguard-ps
下のような応答があれば、safeguard-ps モジュールがインポートされています。次に進んでください。
SPP API への接続
safeguard-ps モジュールのインストールとインポートが完了したら、SPP API に接続することができます。SPP API への接続には、Connect-Safeguard コマンドレットを使用します。
Connect-Safeguard コマンドレットは、SPP アプライアンスからアクセストークンを安全に取得し、グローバル変数として保存するのに役立ちます。オプションを指定することで、トークンを標準出力に返し、セッションに保存しないようにすることもできます。
アクセストークンをセッションに保存する場合
Connect-Safeguard コマンドレットは、アクセストークンと接続情報を含むセッション変数を作成します。これにより、コマンド間でセッションを持続させ safeguard-ps モジュールが提供する他のコマンドレットを簡単に呼び出すことができます。
次のコマンドを実行します。
Connect-Safeguard -Insecure
-Insecure オプションは、safeguard-ps に SSL 証明書の検証を無視するように指示します。SPP に証明書を正しく設定している場合は必要ありません。
safeguard-ps は 接続先の SPP アプライアンスを問うプロンプト（Appliance: ）を表示します。
接続先の SPP アプライアンスの DNS 名または IP アドレスを入力し、Enter キーを押します。
safeguard-ps は 認証プロバイダーを問うプロンプト（Provider: ）を表示します。
SPP では、複数の ID および認証プロバイダーを使用できます。SPP 内部のユーザーで認証する場合は local、クライアント証明書で認証する場合は certificate と入力します。上の ad14 [demo.s-test.local] は、この SPP に追加されている Active Directoryドメインです。ad14 または demo.s-test.local のいずれかを入力すると、このプロバイダーを使用できます（表示内容はご利用環境によって異なります）。
ここでは、SPP 内部のユーザーで認証します。local と入力し、Enter キーを押します。
ユーザー名を問うプロンプト（Username: ）に SPP ユーザー名を入力し、Enter キーを押します。
パスワードを問うプロンプト（Password: ）にパスワードを入力し、Enter キーを押します。
Password: の入力値はマスクされます。
ログインセッションが作成されました。これ以降は、他の safeguard-ps コマンドレットを呼び出す際に、認証情報を提供する必要はありません。
ターミナルウィンドウの上部に接続情報（SPP アプライアンス名、認証プロバイダ、Username: プロンプトで入力した SPP ユーザー名）が表示されます。
次のコマンドを実行してみてください。
Get-SafeguardLoggedInUser
safeguard-ps はセッションを再利用して、GET service/core/v4/Me に HTTP リクエストを送信します。Authorization ヘッダーは自動的に受け渡されます。
次のような結果が表示されます。
結果は JSON 形式ではありません。PowerShell から HTTP リクエストを実行すると、結果は自動的に PowerShell オブジェクトに変換されます。これにより、safeguard-ps コマンドレットの出力に対して PowerShell スクリプト構文を簡単に使用することができます。
たとえば、次のコマンドを実行してみてください。
(Get-SafeguardLoggedInUser).AdminRoles
今回は、HTTP リクエストのすべての出力ではなく、ログインしているユーザーの AdminRoles リストのみが表示されました。
アクセストークンをセッションに保存しない場合
SPP API を呼び出したいが、コマンド間で持続するセッションを作成したくないという状況があるかもしれません。これは、-NoSessionVariable パラメーターを使用することで実現できます。
次に進む前に（セッションが継続している場合は）一旦、セッションを切断します。
次のコマンドを実行してください。
Disconnect-Safeguard
出力から、ログアウトに成功し、セッション変数が削除されたことが分かります。
今回は、いくつかのパラメーターをコマンドラインで渡してみます。
次のコマンドを実行してください。
Connect-Safeguard -Insecure -Appliance <SPP サーバー名または IP アドレス> -IdentityProvider local -Username <ユーザー名> -NoSessionVariable
SPP は SPP API トークンを含む長い文字列を返します。この SPP API トークンを（セッションに保存せず）変数に取り込んで利用します。
次のように入力して実行してください。
$tok = (Connect-Safeguard -Insecure <SPP サーバー名または IP アドレス> local <ユーザー名> -NoSessionVariable)
Get-SafeguardLoggedInUser -Appliance <SPP サーバー名または IP アドレス> -AccessToken $tok –Insecure
ここでは、変数 $tok に SPP API トークンを格納し、-AccessToken パラメーターの引数として使用しています。
-AccessToken パラメーターを使用して変数を渡す場合、-Appliance パラメーターと –Insecure パラメーターを指定する必要があります。通常、これらの値は SPP API トークンとともにセッションに保存されます。セッションがない場合、safeguard-ps はこれらの値に対して何を使用すればよいかわかりません。
変数（この例の場合は $tok）に格納されているトークンを無効にするには、次のようなコマンドを実行します。
Disconnect-Safeguard -Appliance <SPP サーバー名または IP アドレス> -AccessToken $tok -Insecure
利用可能な safeguard-ps コマンドレットの見つけ方
ここまでで、SPP API への接続方法が分かりました。
次に、どのコマンドレットを呼び出せるかを知る必要があります。
safeguard-ps で呼び出すことができるコマンドレットを知るには、次のコマンドを実行します。
Get-SafeguardCommand
結果から、非常に多くのコマンドレットが存在することが分かります。
Get-SafeguardCommand コマンドレットでは、必要なコマンドレットを正確に絞り込むために、最大3つのパラメーターを使用することができます。
例えば、アクセスリクエストの作成を処理するコマンドレットを探したいとします。
この場合、次のように実行します：
Get-SafeguardCommand new request
結果から、新しいアクセスリクエストを作成するためのコマンドレットが、
New-SafeguardAccessRequest という名前であることがわかります。
safeguard-ps コマンドレットの命名形式
safeguard-ps モジュールに含まれるコマンドレットの名前は、すべて <動詞>-Safeguard<名詞> の形式で命名されています。コマンドレットで使用される<動詞>については、PowerShell コマンドに承認されている動詞（Microsoft ドキュメントページ） を参照してください。
safeguard-ps コマンドレットの使用方法の確認
目的のコマンドレットが見つかったら、Get-Help Powershell コマンドレットを使用して、そのコマンドレットの使用方法を確認します。
例えば、次のコマンドを実行してみてください。
Get-Help New-SafeguardAccessRequest -Full
次のような結果が表示されます。
PowerShell はタブ補完をサポートしているため、コマンドレットの完全な名前を入力する必要はありません。名前の一部を入力してタブキーを押すだけで、PowerShell は入力されたものと一致するコマンドレットを表示します。
目的のコマンドレットが見つからない場合
Get-SafeguardCommand を使用して、探している機能のコマンドレットが見つからなかったとしても、safeguard-ps モジュールを使用できないわけではありません。Invoke-SafeguardMethod コマンドレットを使用することで SPP API を呼び出すことができます。
現在、safeguard-ps には約 390のコマンドレットがありますが、SPP API のエンドポイントは 約 800あります。
これは、safeguard-ps でサポートされていない SPP API エンドポイントが数多く存在することを意味します。
safeguard-ps モジュールのすべてのコマンドレットは、Invoke-SafeguardMethod という Core safeguard-ps コマンドレットをベースに記述されています。
次のコマンドを実行して、出力結果を確認してください。
Get-Help Invoke-SafeguardMethod -Full
Get-Help の出力からわかるように、リクエストをカスタマイズするための多くのパラメーターが用意されています。重要なパラメーターは以下の通りです。
| パラメーター | 説明 | パラメーター値 |
|---|---|---|
| -Accept | HTTP の Accept ヘッダーに渡す内容を指定します。 | application/json text/csv |
| -ContentType | HTTP の Content-Type ヘッダーに渡す内容を指定します。 | application/json |
| -Body | URL に PUT または POST するオブジェクトを含むハッシュテーブル | PowerShell オブジェクト |
| -JsonBody | URL に PUT または POST するための事前にフォーマットされた JSON 文字列。 -Body も指定した場合、これは無視されます。 | JSON 文字列 |
| -Parameters | URL に追加する HTTP クエリパラメーターを含むハッシュテーブル | ハッシュテーブル |
| -OutFile | Web API のレスポンスを保存するファイル | ファイルへのパス |
（Connect-Safeguard でセッションを使用している場合）Invoke-SafeguardMethod を呼び出すための基本構文は次のようになります。
Invoke-SafeguardMethod <サービス> <httpメソッド> <相対URL>
例えば、core サービスの Users エンドポイントに対して GET リクエストを送信する場合は、次のコマンドを実行します。
Invoke-SafeguardMethod core GET Users
いくつかの例を試してみてください。
セッションを切断している場合は、Connect-Safeguard –Insecure コマンドを再度実行してセッションを作成してください。適切なアクセス許可権限を持つ SPP 管理ユーザーを使用してください。
使用例：-Parameters の指定
ここでは、-Parameters パラメーターを使用して、特定の文字列（下の例の場合は、admin）を名前に含むユーザーを検索してみます。
次のコマンドを実行してみてください。
Invoke-SafeguardMethod core GET Users -Parameters @{ filter = “Name icontains ‘admin'”; fields = “Name,AdminRoles” }
PowerShell では、ハッシュテーブルのプロパティを区切るために、カンマ（,）ではなくセミコロン（;）を使用します。
Name に admin を含むユーザー(NameとAdminRoles)が出力されます。
使用例：-Body の指定
ここでは、-Body パラメーターを使用して新しい SPP 標準ユーザーを作成してみます。
次のコマンドを実行してみてください。
Invoke-SafeguardMethod core POST Users -Body @{
Name = "NewUser"
PrimaryAuthenticationProvider = @{Id = -1}
}
- -Body パラメーター値は、ハッシュテーブルで定義します。複数行で記述しても構いません。
- PrimaryAuthenticationProvider で認証プロバイダ Idを指定します（-1 は SPP のローカルプロバイダ）。
- PrimaryAuthenticationProvider は必須項目です。
NewUser という名前の SPP 標準ユーザーが作成されました。
使用例：-JsonBody の指定
ここでは、-JsonBody パラメーターを使用して、新しい SPP 管理ユーザーを作成してみます。
-JsonBody パラメーターを使用する方が簡単な場合があります：
(1) Body が既に JSON 文字列で保存されている場合
(2) ハッシュテーブルのショートカットを使用してオブジェクトを作成する場合、PowerShell でオブジェクトを適切に作成するのが難しい場合
次のコマンドを実行してみてください。
Invoke-SafeguardMethod core POST Users -JsonBody "{
`"Name`": `"AnotherNewUser`",
`"AdminRoles`": [`"UserAdmin`",`"AssetAdmin`",`"PolicyAdmin`"],
`"PrimaryAuthenticationProvider`": {`"Id`": `"-1`"}
}"
- -JsonBody パラメーター値は、JSON 文字列で定義します。
- -JsonBody を使用する場合、ダブルクォート（”）のエスケープ文字はバッククォート文字（`）であるということに注意してください。
AnotherNewUser という名前の SPP 管理ユーザーが作成されました。
セッションの切断
作業が完了したら、Disconnect-Safeguard コマンドレットを実行してアクセストークンを無効化し、セッションを削除します。
次のコマンドを実行します。
Disconnect-Safeguard
さいごに
safeguard-ps モジュールは、自動化のためのスクリプト言語であると同時に、SPP への対話的なコマンドラインインターフェースでもあります。safeguard-ps コマンドレットは、不足している情報の入力を促すプロンプトを表示してくれるため、Swagger UI より使いやすいです。
OneIdentity 社の GitHub ページには、safeguard-ps モジュールの学習に役立つ サンプルスクリプトも用意されていますので、ぜひ評価版でお試しください。
SPP 製品紹介ページ
SPP には、この記事で紹介した以外にも機能があります。
その他の特長や機能については、それぞれの製品紹介ページをご参照ください。
SPP 評価版
SPP の評価版は、仮想アプライアンス（OVAまたはVHDXファイル）で提供いたします。
SPP の評価版では、すべての機能を 90日間無料でご利用いただけます。
評価版の利用をご希望いただく場合は、下記お問い合わせフォームから評価ライセンスをお申し込みください。
お問い合わせ
購入前の SPP に関するお問い合わせは、下記お問い合わせフォームからお問い合わせください。
