[ACSv2] Powershell で ACS を管理する

久しぶりのポストとなってしまいました。

以前 OpenID Provider を ACSv2 に登録するための GUI クライアントを公開しました。
http://idmlab.eidentity.jp/2011/03/acsv2openid-provider.html
http://idmlab.eidentity.jp/2011/04/acsv2-openid.html

その後 ACSv2 が正式にリリースされたことを受けてラボ版とは別に正式リリース版の ACSv2 用の GUI を含め以下のURLで公開をしました。（5月の初めにリリースしましたが blog に書くのを忘れてました）
http://sourceforge.net/projects/acsv2management/files/

ラボ用：ACSv2_Config.ZIP
正式リリース用：ACSv2_Config_for_Prod.zip


そんな中、これも少し前になりますが Vittorio が CodePlex に PowerShell のコマンドレットを公開しています。
http://blogs.msdn.com/b/vbertocci/archive/2011/05/17/announcing-sample-acs-cmdlets-for-the-windows-azure-appfabric-access-control-service.aspx
http://wappowershell.codeplex.com/releases/view/66308#DownloadId=240649



ACSv2 が正式にリリースされた時にも書きましたが結局 OpenID Provider をサポートした、と言っても Web の管理画面から管理をすることが出来ないので、上記 GUI や Powershell を使って ACS の Management Service を直接操作するしか方法がありません。

GUI の操作は以前紹介したので、今回は PowerShell のコマンドレットを使って ACS を操作する方法を紹介します。


■ ACS の Management Service の基本概念
その前にまずは ACS の Management Service を操作するときの基本的な考え方を整理しておきます。

基本は WCF Data Services を使って ACS Management Service を操作するので、サービス参照をしてクライアントを生成して用意された API を実行していく、というスタイルです。

また、サービスを使う際は ACS の Management Service 用のユーザとパスワードで事前に認証を受けておきます。
流れは、
１．認証：[マネージメントサービスのエンドポイント]/v2/OAuth2-13 へユーザ名とパスワードを POST し、 SWT(Simple Web Token)を取得する
２．認可：取得した SWT を HTTP の Authorization ヘッダに Bearer トークンとして付加してアクセス
です。

その後は実際のメソッドを実行して各種操作（例えば作成した IdP に RP を紐付ける場合であれば AddToRelyingPartyIdentityProviders ）を行う、という形です。


■ Powershell コマンドレットのセットアップ
ただ、毎回これを実行するのはかなり面倒なので、上述の GUI や Powershell が活躍するわけです。今回は Powershell 版の使い方です。

まずは CodePlex からダウンロードしたモジュールをセットアップしますが、前提となるソフトウェアは、
・Powershell
・.NET Framework 3.5 SP1
・Windows Identity Foundation Runtime
・ADO.NET Data Services Update for .NET Framework 3.5 SP1
です。

これらがインストールされているマシンにダウンロードしたモジュールを解凍、セットアップファイルを実行するとコマンドレッドが組み込まれます。

（セットアップ画面）

■ 用意されているコマンドレッド
以下のコマンドレットが用意されています。Web 画面を知っていれば各パラメータが何を指しているのかは理解できると思います。
利用するときは Add-PSSnapin ACSManagementToolsSnapIn を実行してスナップインを組み込みます。

種別	コマンドレット名	概要	引数	説明
共通	Get-AcsManagementToken	ManagementServiceへアクセスするためのトークンを取得する	-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
IdP	Add-IdentityProvider	Identity Providerを追加する	-type	定義済みかカスタムか
			-PreconfiguredIpType	定義済みの場合のタイプ
			-Name	IdP名
			-AllowedRelyingParties	紐付けるRP
			-LoginLinkText	ホームレルムディスカバリ時のリンク文字列
			-FbAppId	Facebookの場合のApplicationID
			-FbAppSecret	Facebookの場合のApplicationSecret
			-WsFederationMetadata	ws-federationのmetadata
			-Protocol	プロトコル
			-SignInAddress	サインインアドレス
			-SigningCertificate	トークン署名の証明書
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-IdentityProvider	Identity Provider情報を取得する	-Name	取得対象のIdP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-IdentityProviders	登録されている全Identity Provider情報を取得する	-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Remove-IdentityProvider	Identity Providerを削除する	-Name	削除対象のIdP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
RP	Add-RelyingParty	Relying Partyを追加する	-Name	RP名
			-Realm	ACSがトークンを発行する先のURI
			-ReturnUrl	ACSがトークンを返却する先のURI
			-ErrorUrl	エラーが発生した時のリダイレクト先URI
			-TokenFormat	ACSが発行するトークンのフォーマット（種類）
			-TokenLifetime	トークンの有効期間
			-AllowedIdentityProviders	紐付けるIdP
			-RuleGroupName	紐付けるRuleGroup名
			-SigningSymmetricKey	トークン署名の対象鍵
			-SigningCert	トークン署名の証明書
			-EncryptionCert	トークン暗号化の証明書
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-RelyingParty	Relying Party情報を取得する	-Name	取得対象のRP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-RelyingParties	登録されている全Relying Party情報を取得する	-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Remove-RelyingParty	Relying Partyを削除する	-Name	削除対象のRP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
Rule	Add-DefaultPassThroughRules	デフォルトのパススルールールを追加する	-GroupName	対象のグループ名
			-IdentityProviderName	対象のIdP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Add-Rule	ルールを追加する	-GroupName	対象のグループ名
			-Description	説明
			-IdentityProviderName	対象のIdP名
			-InputClaimType	入力クレームのタイプ
			-InputClaimValue	入力クレームの値
			-OutputClaimType	出力クレームのタイプ
			-OutputClaimValue	出力クレームの値
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-Rule	ルール情報を取得する	-Id	取得対象ルールのID
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-Rules	登録されている全ルール情報を取得する	-GroupName	対象のグループ名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Remove-Rule	ルールを削除する	-Rule	削除対象のルール名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
Rule Group	Add-RuleGroup	ルールグループを追加する	-Name	ルールグループ名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-RuleGroup	ルールグループ情報を取得する	-Name	取得対象のルールグループ名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-RuleGroups	登録されている全ルールグループ情報を取得する	-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Remove-RuleGroup	ルールグループを削除する	-Name	削除対象のルールグループ名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
Crypto	Add-TokenEncryptionKey	トークン暗号化キーの追加	-Name	キー名
			-Certificate	証明書
			-RelyingPartyName	RP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Add-TokenSigningKey	トークン署名キーの追加	-Name	キー名
			-Key	証明書パスワード
			-EffectiveDate	開始日
			-ExpirationDate	有効期限
			-Certificate	証明書
			-MakePrimary	プライマリ設定
			-RelyingPartyName	RP名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-ServiceKey	サービスキー情報を取得する	-Name	キー名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Get-ServiceKeys	登録されている全サービスキー情報を取得する	-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン
	Remove-ServiceKey	サービスキーを削除する	-Name	キー名
			-NameSpace	ACSv2のネームスペース名
			-ManagementKey	Management Service用のパスワード
			-MgmtToken	Get-AcsManagementTokenで取得したトークン

■ 利用例
登録されている IdP 一覧を取得してみます。

SnapInの組み込み	PS C:\Windows\system32> Add-PSSnapin ACSManagementToolsSnapIn;
定数（ネームスペース、パスワード）の登録	PS C:\Windows\system32> $acsNamespace = "sso-test";
	PS C:\Windows\system32> $mgmtKey = "xxxx";
アクセストークンの取得	PS C:\Windows\system32> $mgmtToken = Get-AcsManagementToken -namespace $acsNamespace -managementKey $mgmtKey;
IdP一覧の取得	PS C:\Windows\system32> Get-IdentityProviders -MgmtToken $mgmtToken
結果	Id : 10000009 Name : Windows Live ID Realm : https://accesscontrol.windows.net/ WebSSOProtocolType : WsFederation LoginLinkName : Windows Live? ID IssuerName : uri:WindowsLiveID SignInEndpoint : https://login.live.com/login.srf SignOutEndpoint : EmailDomain : ImageUrl : FedMetadataUrl : https://nexus.passport.com/federationmetadata/2007-06/federationmetadata.xml ClaimTypes : {} Keys : {Windows Live ID Signing Key, Windows Live ID Signing Key} RelyingParties : {} MgmtToken : http%253a%252f%252fschemas.microsoft.com%252fws%252f2008%252f06%252fidentity%252fclaims%252frole%3 dAdministrator%26http%253a%252f%252fschemas.microsoft.com%252faccesscontrolservice%252f2010%252f07 %252fclaims%252fidentityprovider%3dhttps%253a%252f%252fsso-test.accesscontrol.windows.net%252f%26A udience%3dhttps%253a%252f%252fsso-test.accesscontrol.windows.net%252fv2%252fmgmt%252fservice%252f% 26ExpiresOn%3d1310076551%26Issuer%3dhttps%253a%252f%252fsso-test.accesscontrol.windows.net%252f%26 HMACSHA256%3dBKS2yqeR11sE%252fBj5wzoxSUY41mwMhMwfUb7ThCZ9bO4%253d SystemReserved : True

いかがでしょうか？
一括登録や Web の管理画面では登録できないようなカスタムプロバイダを登録する場合など、コマンドラインで操作できると非常に楽ですね。