📘

Perforce Helix Core に Azure AD SSO でサインインする

2022/10/13に公開

出てくるサービス

  • Perforce Helix Core (Core サーバ, p4d)
  • Helix Authentication Service (HAS)
  • Azure AD

作るもの

architecture_diagram

  • AWS 環境に HAS, p4d を起動する ※1
  • HAS の HTTPS 通信のために ALB を配置する
  • HAS と Azure AD を連携させる
  • p4d に authentication-extension を導入する

※1 図上は HAS と p4d を別インスタンスで書いているが、同一インスタンスでも問題ない

準備

  • Azure AD の利用環境
  • Helix Core サーバ(p4d)は動いているものとする
  • HAS のドメインを決める
  • 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/
  • 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 が表示される。
SS Login Sccessful

Azure AD ログイン成功しているにも関わらず HAS の Login Succressful ではなく通常トップが表示されてしまう場合, TRUST_PROXY 設定が誤っている可能性がある。
https://www.perforce.com/manuals/helix-auth-svc/Content/HAS/troubleshooting.htmlChrome does not allow login と同根の問題なので IP レンジを確認。

関連資料

GitHubで編集を提案

Discussion