はじめに
Cisco Catalyst SD-WAN Manager（旧 vManage）の管理画面へのログインを、Casdoor の SAML 認証と連携させてみました。
Casdoor を Identity Provider（IdP）、SD-WAN Manager を Service Provider（SP）として設定し、Manager から SSO を開始して、Casdoor の Password 認証後に管理画面へ入るところまで確認しています。
設定で特に重要だったのは、次の3点です。
- Manager の metadata にある SP Entity ID と ACS URL を、そのまま Casdoor に設定する。
- SAML 属性として、大文字小文字を含めて
UsernameとGroupsを返す。 - Casdoor の HTTP-POST binding 用 metadata を Manager に登録する。
本稿は、Casdoor の SAML 実装を修正しない Password 認証での連携手順です。WebAuthn では別の問題があったため、末尾で GitHub Issue を紹介します。
検証構成と前提
| 項目 | 検証した構成 |
|---|---|
| SD-WAN Manager | 26.2.1、単体構成 |
| Casdoor | v4.26.0、Docker、SQLite |
| 認証の開始点 | SD-WAN Manager の SSO（SP initiated） |
| Casdoor で選ぶ認証方法 | Password。MFA が有効なユーザーは追加認証も実施 |
| ブラウザー | Microsoft Edge |
| 確認範囲 | SAML 認証、netadmin の受理、対象ユーザーでの Monitor / Overview 表示 |
検証日は2026年11月11日 JST です。以下の FQDN・Organization 名・メールアドレスは記事用の例に置き換えています。
| 用途 | 記事内の値 |
|---|---|
| Casdoor の URL | https://id.example.com |
| SD-WAN Manager の URL | https://vmanage.example.com |
| Casdoor の Organization | example.com |
| Casdoor の Application | sdwan |
| テストユーザーのメールアドレス | alice@example.com |
Casdoor の構築と HTTPS 化は済んでいるものとします。ブラウザーから両方の URL にアクセスでき、証明書を正常に検証できる状態にしておきます。両サーバーの時刻も同期させます。
また、Casdoor には通常の Password ログインができる Organization とユーザーを用意し、ユーザーの Email に alice@example.com を設定しておきます。SAML 用の署名証明書と、サイトの HTTPS 証明書は用途が異なります。
Cisco の26.x設定ガイドでは、Okta、ADFS、PingID、Microsoft Entra ID が検証済み IdP として挙げられています。本稿は Casdoor を組み合わせた実機検証例です。
ログインの流れ
本稿では、SD-WAN Manager からログインを開始します。SAML の要求と応答は、いずれもブラウザーを介して受け渡します。
RelayState は、SP が送ったログイン処理の状態を応答へ引き継ぐための値です。ログイン後のダッシュボード URL を推測して固定するのではなく、SP が送った値を保持します。
1. SD-WAN Manager の SP metadata を取得する
普段使う FQDN、ここでは https://vmanage.example.com で Manager にログインします。
Administration > Settings > Identity provider settings を開き、Installed certificate details にある SAML metadata の Download から SP metadata を保存します。バージョンによって画面の階層やラベルが異なるため、Cisco の設定例も参照してください。
metadata で確認する値は次の3つです。
| XML の項目 | 役割 | 本稿の設定例 |
|---|---|---|
EntityDescriptor の entityID
|
SP の識別子。SAML の Audience と照合する | vmanage.example.com |
AssertionConsumerService の Location
|
SAML 応答を受け取る ACS URL | https://vmanage.example.com:443/samlLoginResponse |
SingleLogoutService の Location
|
SAML ログアウトの受信先 | https://vmanage.example.com:443/samlLogoutResponse |
SP Entity ID は、ブラウザーで開く URL と同じ表記とは限りません。 この検証ではホスト名だけの値でした。自分の metadata が vmanage.example.com なら、独自に https:// を足さず、その値を使います。逆に metadata にスキームが含まれていれば、それを保持します。
ACS やログアウト URL の :443、パス、末尾のスラッシュも、取得した metadata を基準にします。上表をそのまま実環境へコピーするのではなく、実際の値と置き換えてください。
2. Casdoor に Manager 用の Application を作る
Casdoor では、Organization がユーザーの所属先、Application が接続先ごとの認証設定です。ユーザーは既存の Organization に所属させたまま、SD-WAN Manager 用に Application sdwan を追加します。
Casdoor の管理画面から Applications を開き、次の内容で作成します。
| 項目 | 設定例 |
|---|---|
| Name | sdwan |
| Organization | example.com |
| Type |
All（今回の実機設定） |
| Signin methods |
Password を利用できるようにする |
| Enable signup | 無効。ユーザーは管理者が登録する |
通常のアカウント画面用 Application と分けておくと、Manager 向けの属性・証明書・許可先を個別に管理できます。
Authentication タブでは Enable signup を無効にしています。
Redirect URLs を設定する
Casdoor の Redirect URLs には、SP の Entity ID を登録します。Casdoor の SAML 設定説明でも、SP が示す識別子と同じ値を設定するよう案内されています。
検証時にログイン成功を確認した登録値は、次の2件です。
vmanage.example.com
https://vmanage.example.com
1行目が SP metadata の Entity ID に対応します。2行目は検証過程で併記し、その状態で成功を確認した値です。URL 形式の2行目も必須なのかは切り分けていません。 別の環境で設定する場合も、まず実際の SP Entity ID との一致を確認してください。
SAML タブの設定
Application の SAML タブを、次のように設定します。
| 項目 | 設定値 |
|---|---|
| SAML reply URL（Consumer URL / ACS） | https://vmanage.example.com:443/samlLoginResponse |
| SAML single logout URL | https://vmanage.example.com:443/samlLogoutResponse |
| SAML hash algorithm | SHA256 |
| Enable SAML assertion signature | 有効 |
| Enable SAML C14N10 | 有効 |
| SAML C14N10 prefix | 空欄 |
| Use Email as NameID | 有効 |
| Disable SAML attributes | 無効 |
| Enable SAML POST binding | 無効（今回の保存済み設定。POST 用 metadata は手順3の URL で取得） |
Application に SAML 署名用の証明書を割り当て、その公開証明書を含む metadata を後で Manager に登録します。設定項目の説明は Casdoor の Application settings referenceを参照してください。
検証では、Response と Assertion の署名に RSA-SHA256、正規化に Exclusive C14N 1.0 が使われることを確認しました。署名のハッシュ方式と XML の正規化方式は別の設定なので、SHA256 を選んだことだけで署名検証が通るとは限りません。
Username と Groups を返す
SAML attributes に次の2項目を追加します。
| Name | Name format | Value |
|---|---|---|
Username |
Basic |
$user.email |
Groups |
Basic |
netadmin |
Username と Groups は大文字小文字を含めてこの名前にします。Cisco の Okta 設定例でも、この2つの属性名が指定されています。
$user.email は Casdoor ユーザーの Email を参照する式です。ここでは alice@example.com が渡されます。ユーザーの Email が未登録なら、先にユーザー設定を修正します。
Groups は Manager が解釈するグループ名です。今回の例では固定文字列 netadmin を返します。Casdoor 内に同じ名前の Group を作るだけでは、この SAML 属性の設定をしたことにはなりません。
Groups を固定値 netadmin にすると、この Application で認証できるユーザーには、その権限が渡ります。検証対象の利用者にアクセスを限定してください。複数の権限を使い分ける運用では、所属と権限に応じた属性の割当を別途設計します。
3. Casdoor の HTTP-POST 用 metadata を取得する
Application を保存したら、SAML metadata を取得します。今回の設定で Casdoor が通常出力した metadata を、そのまま Manager に登録する方法ではログインできませんでした。 そこで、Casdoor 標準の取得オプション enablePostBinding=true を指定し、HTTP-POST 用 metadata を生成し直して登録しました。XML の手編集や、metadata 生成処理への独自コード追加は行っていません。
取得する metadata の違いは次のとおりです。いずれも Casdoor の既存 API が生成する XML です。
| 取得オプション | SSO binding | SSO endpoint のパス | 今回の結果 |
|---|---|---|---|
enablePostBinding を省略 |
HTTP-Redirect |
/login/saml/authorize/admin/sdwan |
IdP 検証で失敗 |
enablePostBinding=true を指定 |
HTTP-POST |
/api/saml/redirect/admin/sdwan |
Password 認証で成功 |
このオプションの読取りは Casdoor の metadata 取得 API の実装でも確認できます。
HTTP-POST binding 用の URL は、次の形です。
https://id.example.com/api/saml/metadata?application=admin/sdwan&enablePostBinding=true
admin/sdwan の admin は Application の owner、sdwan は Application 名です。Organization 名の example.com をこの部分に入れるわけではありません。実際の owner・Application 名に合わせてください。
今回の実機では、画面の Enable SAML POST binding スイッチは無効のまま、上記 URL の enablePostBinding=true を明示して POST 用 metadata を取得しました。画面に表示される metadata をそのまま使うのではなく、この URL をブラウザーで開き、XML をファイルへ保存します。Copy SAML metadata URL で取得した URL を使う場合も、このパラメーターが付いていることを確認してください。
保存した XML の SingleSignOnService は、次の組合せになっている必要があります。以下は該当要素だけの抜粋例です。
<md:SingleSignOnService
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://id.example.com/api/saml/redirect/admin/sdwan" />
あわせて、IdP の entityID が https://id.example.com であることと、Application に割り当てた署名証明書が含まれることを確認します。
「応答を POST すること」と区別する
この設定は SP から Casdoor へ送る AuthnRequest の binding に関わります。Casdoor から Manager の ACS へ SAMLResponse を POST することとは別です。
| 向き | 本稿の設定 |
|---|---|
| Manager → Casdoor：AuthnRequest | HTTP-POST 用 IdP metadata を登録する |
| Casdoor → Manager：SAMLResponse | SAML reply URL に ACS を設定し、HTTP-POST で返す |
検証当初は、SAMLResponse 自体は ACS へ POST されていましたが、IdP metadata の SSO は HTTP-Redirect のみでした。この状態では Manager 側の IdP 検証で idpUrl is null の例外が発生しました。
POST 用 metadata に差し替えた後、Password 認証で管理画面へ到達しました。 Casdoor の認証コードや Cisco のコードを修正する必要はありませんでした。
4. Casdoor の metadata を Manager に登録する
Manager の Administration > Settings > Identity provider settings から Add IdP を開き、次の内容を設定します。既に作成している場合は対象 IdP の編集画面を使います。
| 項目 | 設定例 |
|---|---|
| Enable identity provider settings | 有効 |
| IdP Name | casdoor |
| Domain | example.com |
| Identity provider metadata | 手順3で取得した HTTP-POST 用 XML |
IdP Name は Manager 内で設定を識別する名前です。
Domain は、今回のユーザー名 alice@example.com のドメインに対応させます。Casdoor サーバーのホスト名 id.example.com を入れる欄ではありません。
保存後に編集画面をもう一度開き、次の3点を読み取って確認します。
- IdP の設定が有効で、Domain が
example.comになっている。 -
手順3で生成し直して登録した metadata の
SingleSignOnServiceがHTTP-POSTになっている。Casdoor の通常出力をそのまま使った状態とは区別する。 - SSO の Location が
https://id.example.com/api/saml/redirect/admin/sdwanになっている。
Casdoor の署名証明書や SSO endpoint を変更した場合は、Manager に登録した metadata も更新します。画面側の設定変更だけで、既に読み込んだ XML の内容が更新されるわけではありません。
5. Password 認証でログインを確認する
既存セッションの影響を避けるため、検証用のブラウザーセッションを分けて操作します。
-
https://vmanage.example.comを開き、SSO のログインから開始します。 - ユーザー名として
alice@example.comを指定します。 - Casdoor に移動したら Password タブを選び、対象ユーザーの認証を行います。
- MFA を有効にしている場合は、続けて追加認証を完了します。
- Manager に戻り、対象ユーザーで
Monitor / Overviewが表示されることを確認します。
Casdoor のログイン成功だけでは、Manager 側の権限まで確認したことにはなりません。Manager の表示ユーザーとデータ表示も確認します。
Manager 側のログを確認する
SSO の確認には /var/log/nms/vmanage-sso.log を使います。Cisco の設定ガイドにも、SSO 専用ログとして記載されています。
Manager の vshell から、たとえば次のように確認します。
tail -n 100 /var/log/nms/vmanage-sso.log
以下は成功時に採取したログのメッセージ部分の抜粋です。ログの prefix と Assertion ID は省略・匿名化し、URL を記事用の値へ置き換えています。
Signature validation using candidate credential was successful
Validation of authentication statement in assertion <assertion-id> was successful
SAMLAuthenticationProvider::authenticate::roles check [netadmin]
Redirecting to https://vmanage.example.com:443/#/banner
署名、認証、netadmin の受理と、ブラウザーでの管理画面表示を合わせて成功と判断しました。今回の確認範囲はここまでで、すべての管理操作や SAML Single Logout の受入試験まで行ったわけではありません。
ログやブラウザーの通信履歴を共有する場合は、SAMLResponse、Cookie、認証コード、秘密鍵などを含めないようにします。
うまくいかないときの確認点
画面に Wrong username/password or user is not authorized to access SD-WAN Manager. と表示されても、それだけで Casdoor のパスワードが間違っているとは判断できません。今回も、設定や IdP 検証の問題が同じ画面エラーになりました。
| 観測した状態・エラー | 確認する項目 |
|---|---|
IdP 検証で idpUrl is null
|
登録した XML が POST 用か。enablePostBinding=true と SingleSignOnService の Binding / Location を確認する |
| Audience の不一致 | SP metadata の entityID と Casdoor の Redirect URLs を照合する。スキームや末尾のスラッシュを推測で変えない |
Signature contained an invalid transform |
SHA256 に加え、Enable SAML C14N10 と prefix の設定を確認する |
| 認証後に権限エラーになる |
Username / Groups の名前、実際の属性値、ユーザーの Email を確認する |
unifiedsamllogin.html?...&idpInitLogin=true から認証が再開する |
SP から開始した認証か、元の AuthnRequest が引き継がれているかを確認する。WebAuthn の問題は次節を参照 |
設定を直した後は、Manager の SSO から新しい要求で試します。古い AuthnRequest の画面をそのまま使い続けると、設定変更前の状態やセッション期限の影響が混ざります。
WebAuthn では別の問題があった
同じ Application で WebAuthn を選ぶと、認証後に Manager から Casdoor のログイン画面へ戻る現象がありました。
Casdoor v4.26.0 の該当実装では、WebAuthn の finish API と、その後の AuthForm へ元の SAML AuthnRequest を引き継ぐ処理が欠けていました。これにより、SP から開始した認証でも、要求に対応付かない IdP initiated の応答を生成する経路に入っていました。
この件は、再現条件と修正コード案を添えて Casdoor に報告しています。
Casdoor Issue #6070: WebAuthn drops SAML AuthnRequest during SP-initiated sign-in
本稿の設定手順と成功確認は Password 認証が前提です。WebAuthn を使う場合は、上記 Issue と利用するバージョンへの修正取り込み状況を別途確認してください。
おわりに
SD-WAN Manager 26.2.1 と Casdoor v4.26.0 では、SP metadata に基づく識別子・ACS、Username / Groups、HTTP-POST 用 IdP metadata をそろえることで、Password 認証から管理画面へログインできました。
特に今回の切り分けでは、「SAMLResponse を POST しているから、IdP metadata も POST 用になっている」とは限らないことがポイントでした。送信方向ごとに、metadata と実際の要求・応答を確認すると整理しやすくなります。