Use SAML authentication in Pleasanter

Limitations¶

1. SAML authentication is not available in the Pleasanter.net shared environment.
2. Pleasanter does not have the capability to issue metadata from the SP (Pleasanter) side. You cannot register the SP (Pleasanter) metadata with the IdP to establish integration.
3. We recommend using HTTPS for production environments. Please limit the use of HTTP to local testing and development purposes only.
4. In a Linux environment, the procedure for placing the certificate specified by SigningCertificate in the store may differ depending on the distribution and the OS version. If placing the certificate is difficult, only when the IdP provides a metadata URL, you can use the method with LoadMetadata: true and MetadataLocation as an alternative (for details, see "Automatic Metadata Retrieval Using MetadataLocation").

Overview¶

This manual describes the settings for using SAML authentication.

1. Configure Authentication.json for SAML Authentication¶

Edit Authentication.json and configure it for SAML authentication.

Authentication.json Configuration Example (Excerpt of Items Related to SAML Authentication)¶

{
    "Provider": "SAML",
    // ～Omitted～
    "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
                }
            }
        ]
    }
}

SAML Authentication Items in Authentication.json¶

SamlParameters.Attributes Item List¶

Match Pleasanter's user columns with the attribute names that can be obtained from the SAML response. The left side of the parameter (key) is Pleasanter's user column. Write the corresponding SAML response attribute name on the right side.

About Synchronizing User Columns¶

After a successful login with SAML authentication, the Pleasanter user is created or updated based on the user data passed in the SAML response.

1. The ID set in the NameID element of the SAML response is registered as the login ID.
2. If the login ID is unregistered, a new user is created with that login ID.
3. If the login ID is already registered, the user information for that login ID is updated.
4. The user information to be synchronized is searched for by the attribute name of the SAML response specified in SamlParameters.Attributes in Authentication.json. Only if the corresponding attribute name exists in the SAML response is its value set in the user column.

If you do not know the attribute name of the SAML response to be synchronized with the user column, you can check it from the response data received when logging in with SAML. See the link below for the confirmation procedure.
I want to check the SAML response attribute name to be set in Authentication.json in SAML authentication settings

SamlParameters.SPOptions Item List¶

In this section, you set the information on the service provider (= Pleasanter) side.
Replace {ServerName} in the Description column according to your environment.

SamlParameters.IdentityProviders Item List¶

In this section, you set the information on the ID provider side.

Automatic Metadata Retrieval Using MetadataLocation¶

By combining LoadMetadata: true with MetadataLocation, you can automatically retrieve the signing certificate and endpoint information from the metadata provided by the IdP. Because SigningCertificate is set to null in this method, you do not need to install the IdP's certificate on the server.

When This Method Is Useful¶

1. When it is difficult to place the certificate in the .NET certificate store in a Linux environment
2. When the IdP provides a federation metadata URL (such as Microsoft Entra ID)
3. When you want to use metadata that is updated automatically when the certificate expires

Notes on Setting MetadataLocation¶

1. For MetadataLocation, specify a URL or file path that can be accessed from the Internet or locally on the server.
2. If access from Pleasanter to the MetadataLocation URL is blocked (by a firewall, for example), retrieving the metadata fails. In that case, download the metadata XML file to the server and specify its file path.
3. Verify the configuration in your own environment in advance before deciding to use it. For the configuration we have confirmed to work, see the configuration example below.

SamlParameters.IdentityProviders.SigningCertificate Item List¶

In this section, you set the information of the certificate that the identity provider uses to sign messages.

How to Check the Search Value (Thumbprint) of the Certificate to Set in FindValue¶

You can check it with the following steps. For more detailed information, see the Sustainsys.Saml2 documentation.

1. Press the R key while holding down the Windows key.
2. Enter "certlm.msc" in the "Run" dialog box and click the "OK" button.
3. In the "Management console", go to "Personal" - "Certificates" and double-click the target certificate.
4. Check the string displayed in the "Value" of the "Thumbprint" field on the "Details" tab of the "Certificate Information" screen.

Configuration Example: Microsoft Entra ID (MetadataLocation Method)¶

When Microsoft Entra ID is used as the IdP, you can use a configuration with LoadMetadata: true and MetadataLocation as shown below.

Checking in the Microsoft Entra Admin Center (Getting the Metadata URL)¶

1. Sign in to the Microsoft Entra admin center.
2. Open Enterprise applications > the target application > Single sign-on.
3. Copy the App Federation Metadata Url in the SAML Certificates section.

Authentication.json Configuration Example (Excerpt of IdentityProviders)¶

In the following configuration example, replace [Tenant ID] and [App ID] with the actual values of your Entra ID tenant.

JSON¶

"IdentityProviders": [
    {
        "EntityId": "https://sts.windows.net/[Tenant ID]/",
        "SignOnUrl": "https://login.microsoftonline.com/[Tenant ID]/saml2",
        "LogoutUrl": null,
        "AllowUnsolicitedAuthnResponse": true,
        "Binding": "HttpPost",
        "WantAuthnRequestsSigned": false,
        "DisableOutboundLogoutRequests": true,
        "LoadMetadata": true,
        "MetadataLocation": "https://login.microsoftonline.com/[Tenant ID]/FederationMetadata/2007-06/FederationMetadata.xml?appid=[App ID]",
        "SigningCertificate": null
    }
]

Supplement: EntityId and SignOnUrl may be overwritten when the metadata is retrieved from MetadataLocation. For Entra ID, there is no problem as long as they match the values included in the metadata.

Note: The EntityId (e.g. https://{ServerName}/Saml2) and ReturnUrl in SPOptions must match the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) set when registering the enterprise application in Entra ID.

2. ID Provider Settings¶

Set up the ID provider side according to the documentation of each ID provider.
The information on the Pleasanter side that is likely to be required on the ID provider side is as follows.
Replace {ServerName} in the Value column according to your environment.

3. Execute SAML Login¶

After you finish editing Authentication.json, restart IIS.
After restarting, when you access from a browser, a login button for SAML authentication ("SSO Login" button) is displayed on the login screen. Click this button and check the operation of SAML authentication.

Supported Versions¶

Related Information¶

• Authentication.json
• I want to specify the user column by combining "givenName" and "surname" instead of "Name" with SAML authentication
• The dept is not reflected when synchronizing user information with SAML authentication
• I want to check the SAML response attribute name to be set in Authentication.json in SAML authentication settings