SAML認証を利用する

制限事項¶

1. Pleasanter.net共有環境ではSAML認証は利用できません。
2. PleasanterにSP（Pleasanter）側のメタデータを発行する機能はありません。SP（Pleasanter）のメタデータをIdPに登録して連携することはできません。
3. 運用時のプロトコルとしてはhttpsを推奨します。httpはローカル検証用途・開発用途などに限って使用してください。
4. Linux環境では、SigningCertificateで指定する証明書のストア配置手順が、ディストリビューションやOSバージョンにより異なる場合があります。証明書配置に困難が生じる場合は、IdPがメタデータURLを提供している場合に限り、LoadMetadata: trueとMetadataLocationを使用した方式を代替として利用できます（詳細は「MetadataLocationを利用したメタデータ自動取得」を参照してください）。

概要¶

SAML認証を利用するための設定手順を記載します。

1. Authentication.jsonをSAML認証向けに構成¶

Authentication.jsonを編集し、SAML認証向けに構成します。

Authentication.json設定例（SAML認証に関連する項目のみを抜粋）¶

{
    "Provider": SAML,
    // ～中略～
    "SamlParameters": {
        "Attributes": {
            "Name": "Name",
            "UserCode": "UserCode",
            "Birthday": "Birthday",
            "Gender": "Gender",
            "Language": "Language",
            "TimeZone": "TimeZone",
            "TenantManager": "TenantManager",
            "DeptCode": "DeptCode",
            "Dept": "Dept",
            "Body": "Body",
            "MailAddress": "{NameId}"
        },
        "SamlTenantId": 1,
        "DisableOverwriteName": false,
        "NotCreatePersistentCookie": false,
        "SPOptions": {
            "EntityId": "https://localhost:59802/Saml2",
            "ReturnUrl": "https://localhost:59802/Users/SamlLogin",
            "AuthenticateRequestSigningBehavior": "IfIdpWantAuthnRequestsSigned",
            "OutboundSigningAlgorithm": "https://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
            "MinIncomingSigningAlgorithm": "https://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
            "IgnoreMissingInResponseTo": false,
            "PublicOrigin": null,
            "ServiceCertificates": []
        },
        "IdentityProviders": [
            {
                "EntityId": null,
                "SignOnUrl": null,
                "LogoutUrl": null,
                "AllowUnsolicitedAuthnResponse": true,
                "Binding": "HttpPost",
                "WantAuthnRequestsSigned": false,
                "DisableOutboundLogoutRequests": true,
                "LoadMetadata": false,
                "MetadataLocation": null,
                "SigningCertificate": {
                    "StoreName": "My",
                    "StoreLocation": "CurrentUser",
                    "X509FindType": "FindByThumbprint",
                    "FindValue": null
                }
            }
        ]
    }
}

Authentication.jsonのSAML認証項目¶

SamlParameters.Attributes項目一覧¶

プリザンターのユーザ項目とSAMLレスポンスから取得可能な属性名との対応付けを行います。パラメータの左側（キー）がプリザンターのユーザ項目です。対応するSAMLレスポンスの属性名を右側に記載します。

ユーザ項目の同期について¶

SAML認証でのログインが成功すると、SAMLレスポンスから渡されるユーザデータを基に、プリザンターのユーザを作成・更新します。

1. SAMLレスポンスのNameID要素に設定されているIDを「ログインID」として登録します。
2. 未登録の「ログインID」であった場合、その「ログインID」でユーザが新規に作成されます。
3. 登録済みの「ログインID」であった場合、その「ログインID」のユーザ情報が更新されます。
4. 同期するユーザ情報はAuthentication.jsonの__SamlParameters.Attributes__ で指定したSAMLレスポンスの属性名で検索します。SAMLレスポンスの該当する属性名が存在したのみ、その値をユーザ項目に設定します。

ユーザ項目と同期するSAMLレスポンスの属性名が不明の場合、SAMLログイン時に受け取ったレスポンスデータから確認する方法があります。確認手順は下記のリンク先を確認してください。
SAML認証設定でAuthentication.json に設定するSAMLレスポンスの属性名を確認したい

SamlParameters.SPOptions項目一覧¶

このセクションでは、サービスプロバイダ（＝プリザンター）側の情報を設定します。
説明列の文字列【サーバ名】は環境に応じて読み替えてください。

SamlParameters.IdentityProviders項目一覧¶

このセクションでは、IDプロバイダ側の情報を設定します。

MetadataLocationを利用したメタデータ自動取得¶

LoadMetadata: trueとMetadataLocationを組み合わせることで、IdPが提供するメタデータから署名証明書・エンドポイント情報を自動取得できます。この方式では、SigningCertificateにnullを指定するため、IdPの証明書をサーバにインストールする作業が不要になります。

この方式が有効なケース¶

1. Linux環境で.NETの証明書ストアへの証明書配置が困難な場合
2. IdPがフェデレーションメタデータURLを提供している場合（Microsoft Entra IDなど）
3. 証明書の期限切れ時に自動更新されるメタデータを利用したい場合

MetadataLocation設定時の注意事項¶

1. MetadataLocationにはインターネットまたはサーバローカルからアクセス可能なURLまたはファイルパスを指定してください。
2. プリザンターからMetadataLocationのURLへのアクセスが遮断されている場合（ファイアウォールなど）はメタデータの取得に失敗します。その場合はメタデータXMLファイルをサーバにダウンロードし、ファイルパスで指定してください。
3. ユーザ環境において事前検証を実施したうえで判断・利用してください。弊社での動作確認実績については、以下の設定例を参照してください。

SamlParameters.IdentityProviders.SigningCertificate項目一覧¶

このセクションでは、IDプロバイダがメッセージの署名に使用する証明書の情報を設定します。

FindValueに設定する証明書の検索値（拇印）の確認方法¶

以下の手順で確認できます。より詳細な情報は、Sustainsys.Saml2のドキュメントを参照してください。

1. Windowsキーを押しながら、Rキーを押してください。
2. 「ファイル名を指定して実行」ダイアログに「certlm.msc」と入力し、「OK」ボタンをクリックしてください。
3. 「管理コンソール」の「個人」－「証明書」から対象の証明書をダブルクリックしてください。
4. 「証明書情報」画面の「詳細」タブ－「拇印」フィールドの「値」に表示される文字列を確認してください。

設定例: Microsoft Entra ID（MetadataLocation方式）¶

Microsoft Entra IDをIdPとする場合、以下のようにLoadMetadata: trueとMetadataLocationを使用する構成を利用できます。

Entra ID管理ポータルでの確認手順（メタデータURLの取得）¶

1. Microsoft Entra 管理センター にサインインしてください。
2. エンタープライズ アプリケーション > 対象アプリ > シングル サインオンを開いてください。
3. SAML 署名証明書セクションにある「アプリのフェデレーション メタデータ URL」 をコピーしてください。

Authentication.json設定例（IdentityProviders部分の抜粋）¶

以下の設定例において、【テナントID】と【アプリID】の部分は、Entra IDテナントの実際の値に置き換えてください。

JSON¶

"IdentityProviders": [
    {
        "EntityId": "https://sts.windows.net/【テナントID】/",
        "SignOnUrl": "https://login.microsoftonline.com/【テナントID】/saml2",
        "LogoutUrl": null,
        "AllowUnsolicitedAuthnResponse": true,
        "Binding": "HttpPost",
        "WantAuthnRequestsSigned": false,
        "DisableOutboundLogoutRequests": true,
        "LoadMetadata": true,
        "MetadataLocation": "https://login.microsoftonline.com/【テナントID】/FederationMetadata/2007-06/FederationMetadata.xml?appid=【アプリID】",
        "SigningCertificate": null
    }
]

補足: EntityIdおよびSignOnUrlはMetadataLocation取得時に上書きされる場合があります。Entra IDの場合、メタデータに含まれる値と一致していれば問題ありません。

注意: SPOptionsのEntityId（例: https://[サーバ名]/Saml2）およびReturnUrlは、Entra IDのエンタープライズアプリケーション登録時に設定した 識別子 (Entity ID)および応答 URL (ACS URL)と一致させる必要があります。

2. IDプロバイダ側の設定¶

IDプロバイダ側の設定は、各IDプロバイダのドキュメントに従い、設定してください。
IDプロバイダ側で必要と思われるプリザンター側の情報は以下の通りです。
値列の【サーバ名】は環境に応じて読み替えてください。

3. SAMLログインの実行¶

Authentication.jsonの編集が済んだら、IISを再起動してください。
再起動後、ブラウザからアクセスするとログイン画面にSAML認証用のログインボタン（「SSOログイン」ボタン）が表示されます。このボタンをクリックし、SAML認証の動作確認を行ってください。

対応バージョン¶

関連情報¶

・パラメータ設定：Authentication.json
・FAQ：SAML認証で、ユーザー項目を「Name」の代わりに「givenName」と「surname」を結合して指定したい
・FAQ：SAML認証で、ユーザー項目の「DeptCode」を指定せずに組織に反映したい
・FAQ：SAML認証設定でAuthentication.json に設定するSAMLレスポンスの属性名を確認したい