Perforce Helix Core に Azure AD SSO でサインインする
出てくるサービス
- Perforce Helix Core (Core サーバ, p4d)
- Helix Authentication Service (HAS)
- Azure AD
作るもの
- AWS 環境に HAS, p4d を起動する ※1
- HAS の HTTPS 通信のために ALB を配置する
- HAS と Azure AD を連携させる
- p4d に authentication-extension を導入する
※1 図上は HAS と p4d を別インスタンスで書いているが、同一インスタンスでも問題ない
準備
- Azure AD の利用環境
- Helix Core サーバ(p4d)は動いているものとする
- HAS のドメインを決める
- ここでは https://my-has-svc.example.com を使うものとする。以降読み替えてください
- AWS 環境
- ALB
- Ubuntu 20.04 サーバインスタンス
Azure AD 側の設定
ギャラリーからのアプリ追加
公式チュートリアルの "ギャラリーからの Perforce Helix Core - Helix Authentication Service の追加" に書かれているように、ギャラリーから Perforce Helix Core - Helix Authentication Service を追加する。
要件によって Properties -> Assignment required? を変更する。
明示的に Azure AD 側で SSO するユーザを指定するならば Yes、サインインできるすべてのユーザで SSO を利用するならば No にする。
SAML の設定
公式チュートリアルの Azure AD SSO の構成 部分をやる。
具体的には、Single sign-on -> SAML より、以下のように入力する。
- Basic SAML Configuration
- Identifier (Entity ID) :
https://my-has-svc.example.com/saml
- Reply URL (Assertion Consumer Service URL) :
https://my-has-svc.example.com/saml/sso
- Sign on URL :
https://my-has-svc.example.com/
- Identifier (Entity ID) :
- SAML Certificates
-
App Federation Metadata Url
をコピーしておく。
-
Helix Authentication Service のセットアップ
今回は Ubuntu 20.04 のパッケージ版で進める。 https://www.perforce.com/manuals/p4sag/Content/P4SAG/install.linux.packages.install.html に従って進める。
HAS インストール
wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -
echo 'deb http://package.perforce.com/apt/ubuntu focal release' | sudo tee /etc/apt/sources.list.d/perforce.list
sudo apt-get update
sudo apt-get install helix-auth-svc
これで /opt/perforce/
以下に HAS がインストールされる。この Ubuntu パッケージ版の場合は systemd 管理下で起動される。
HAS セットアップ
簡単のため、HAS 同梱のセットアップスクリプト (bin/configure-auth-service.sh
) を使う。
sudo -E /opt/perforce/helix-auth-svc/bin/configure-auth-service.sh --allow-root
スクリプトのガイドにしたがって設定する。今回の場合は以下のようになる。実行例も参照
- Enter the URL for this service: https://my-has-svc.example.com/
- Please choose which features ...: 1 Authentication
- Please choose which protocols ...: 2 SAML
- Enter the URL for SAML IdP metadata: Azure AD 設定でコピーした
App Federation Metadata Url
- Enter the URL for SAML IdP SSO endpoint: (空白でよい)
実行例: https://gist.github.com/komazarari/b25ee8cd0bb959c3fab4373e853c0b42
このスクリプトによって設定ファイル /opt/perforce/helix-auth-svc/.env
が生成される。
今回の構成では ALB で HTTPS 終端させる想定なので、ALB から HAS への通信は http:3000 で通るように一部設定を変更する。
echo 'PORT=3000' | sudo tee -a /opt/perforce/helix-auth-svc/.env
echo 'PROTOCOL=http' | sudo tee -a /opt/perforce/helix-auth-svc/.env
echo 'TRUST_PROXY=(ALB のレンジ, VPC のサブネットレンジでよい)' | sudo tee -a /opt/perforce/helix-auth-svc/.env
sudo systemctl restart helix-auth.service
ALB -> HAS 疎通
以下のように設定する
-
https://my-has-svc.example.com/
が ALB に名前解決されていること - ALB に正しく証明書がプロビジョニングされていること
- ALB が HAS をセットアップしたインスタンスの 3000 ポートにトラフィックを流すこと
AWS 的な内容のみなので詳細は割愛。
HAS 動作確認
ここまでの内容で、HAS + Azure AD の連携がセットアップされていることを確認できる。以下のようになれば OK
- ブラウザで
https://my-has-svc.example.com/
にアクセスし HAS の Welcome ページが表示されること - Azure AD の SAML 設定ページで、Test のエラーが無いこと
Helix Core (p4d) のセットアップ
Helix Core サーバ (p4d) が動いており、適当なユーザ、グループがすでに登録されているとする。
※ Azure AD SSO を使う場合でも, p4d 側にユーザ, グループが必要
helix-authentication-extension のビルドとインストール
https://github.com/perforce/helix-authentication-extension を使う。最新情報については docs を参照ください
git clone https://github.com/perforce/helix-authentication-extension
extension をビルドする
cd helix-authentication-extension
p4 extension --package loginhook
loginhook.p4-extension
という ZIP が作成される。
Ubuntu の p4d パッケージのデフォルト状態では署名のない extension をインストールできないので、署名無しでもインストールできるよう設定を変更したうえでインストールする
p4 configure set server.extensions.allow.unsigned=1
p4 extension --install loginhook.p4-extension -y
(確認)
p4 extension --list --type=extensions
helix-authentication-extension の設定
現在のグローバル設定をダンプする
p4 extension --configure Auth::loginhook -o > /tmp/loginhook.conf.orig
グローバル設定を更新する。更新内容は次に示す diff を参照。
p4 extension --configure Auth::loginhook
p4 extension --configure Auth::loginhook -o > /tmp/loginhook.conf.updated
変更差分は以下, Auth-Protocol と Service-URL を設定する。super ユーザ等も環境にあわせ設定する。
@@ -37,20 +37,20 @@
ExtEnabled: true
-ExtP4USER: sampleExtensionsUser
+ExtP4USER: super
Name: loginhook
Owner: super
-Update: 2022/**/** **:**:**
+Update: 2022/**/** **:**:**
Description:
The description of your config.
ExtConfig:
Auth-Protocol:
- ... Authentication protocol, such as 'saml' or 'oidc'.
+ saml
Authority-Cert:
... Path to certificate authority public key, defaults to ./ca.crt
Client-Cert:
@@ -58,7 +58,7 @@
Client-Key:
... Path to client private key, defaults to ./client.key
Service-URL:
- ... The authentication service base URL.
+ https://my-has-svc.example.com
Verify-Host:
... Ensure service host name matches certificate, if 'true'.
Verify-Peer:
続いて、個別設定も更新する。今回この設定は loginhook-a1
という名前にしている。グローバルのときと同様に現在の設定をダンプする
p4 extension --configure Auth::loginhook --name loginhook-a1 -o > /tmp/loginhook-a1.conf.orig
loginhook-a1
を更新する。更新内容は次に示す diff を参照。
p4 extension --configure Auth::loginhook --name loginhook-a1
p4 extension --configure Auth::loginhook --name loginhook-a1 -o > /tmp/loginhook-a1.conf.updated
変更差分は以下,
@@ -40,7 +40,7 @@
Owner: super
-Update: 2022/**/** **:**:**
+Update: 2022/**/** **:**:**
Description:
The description of your config.
@@ -55,17 +55,17 @@
client-user-identifier:
... Trigger variable used as unique P4LOGINSSO user identifier.
enable-logging:
- ... Extension will write debug messages to a log if 'true'.
+ true
name-identifier:
- ... Field within IdP response containing unique user identifier.
+ nameID
non-sso-groups:
- ... Those groups whose members will not be using SSO.
+ admins
non-sso-users:
- ... Those users who will not be using SSO.
+ super
sso-groups:
- ... Those groups whose members must authenticate using SSO.
+ your-sso-group-1 (SSO を利用するグループを列挙)
+ your-sso-group-2
sso-users:
- ... Those users who must authenticate using SSO.
+ some-sso-user-1 (SSO を利用するユーザを列挙)
+ some-sso-user-2
user-identifier:
- ... Trigger variable used as unique user identifier.
+ email
正しく設定できれば、以下のように list で auth-check-sso
, auth-pre-sso
等が表示される
p4 extension --list --type configs
... config loginhook
... extension Auth::loginhook
... uuid 117E9283-732B-45A6-9993-AE64C354F1C5
... revision 1
... owner super
... type global-extcfg
... config loginhook-a1
... extension Auth::loginhook
... uuid 117E9283-732B-45A6-9993-AE64C354F1C5
... revision 1
... owner super
... type auth-check-sso
... arg auth
... debugStatus none
... config loginhook-a1
... extension Auth::loginhook
... uuid 117E9283-732B-45A6-9993-AE64C354F1C5
... revision 1
... owner super
... type auth-pre-sso
... arg auth
... debugStatus none
... config loginhook-a1
... extension Auth::loginhook
... uuid 117E9283-732B-45A6-9993-AE64C354F1C5
... revision 1
... owner super
... type extension-run
... arg unset
... debugStatus none
p4d を再起動して完了。
# Ubuntu (systemd) の場合
sudo systemctl restart helix-p4dctl.service
接続確認
p4v クライアントで Helix Core サーバ(p4d) に接続する。パスワード入力でなくブラウザで Azure AD ページのログインが行われて、HAS で Login Successful が表示される。
Azure AD ログイン成功しているにも関わらず HAS の Login Succressful ではなく通常トップが表示されてしまう場合, TRUST_PROXY 設定が誤っている可能性がある。
https://www.perforce.com/manuals/helix-auth-svc/Content/HAS/troubleshooting.html の Chrome does not allow login と同根の問題なので IP レンジを確認。
関連資料
- https://learn.microsoft.com/ja-jp/azure/active-directory/saas-apps/perforce-helix-core-tutorial
- https://www.perforce.com/manuals/helix-auth-svc/Content/HAS/Home-has.html
- https://github.com/perforce/helix-authentication-extension/blob/master/docs/Administrator-Guide-2022.1.md#manual-installation
- https://github.com/p4misc/p4memo/blob/master/helix-authentication-service.md
Discussion