## Overview This manual describes the settings for using SAML authentication. ## Supported versions 1. Pleasanter 1.2.6.0 or later ## 1. Edit Authentication.json Configure Authentication.json for SAML integration. Authentication.json is located in the following directory in the standard configuration. ``` C:¥web¥pleasanter¥Implem.Pleasanter¥App_Data¥Parameters ``` - Setting example (Excerpts related to SAML certification only) ```json { "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, "SPOptions": { "EntityId": "https://sso-pleasanter.com/pleasanter/Saml2", "ReturnUrl": "https://sso-pleasanter.com/pleasanter/Users/SamlLogin", "AuthenticateRequestSigningBehavior": "IfIdpWantAuthnRequestsSigned", "OutboundSigningAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", "MinIncomingSigningAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", "IgnoreMissingInResponseTo": false, "PublicOrigin": null, "ServiceCertificates": [] }, "IdentityProviders": [ { "EntityId": "https://id-provider.com/saml", "SignOnUrl": "https://id-provider.com/saml/login", "LogoutUrl": null, "AllowUnsolicitedAuthnResponse": true, "Binding": "HttpPost", "WantAuthnRequestsSigned": false, "DisableOutboundLogoutRequests": true, "LoadMetadata": false, "MetadataLocation": null, "SigningCertificate": { "StoreName": "My", "StoreLocation": "LocalMachine", "X509FindType": "FindByThumbprint", "FindValue": "50B459426DE554010B35E9XXXXXXXXXXXXXXXXX" } } ] } } ``` #### Authentication.json SAML authentication column list |Column name|Setting example|Description| |-|-|-| |Provider|"SAML"|Fixed to "SAML"| |SamlParameters.Attributes|(See `SamlParameters.Attributes` column list)|Match Pleasanter's user columns with attribute names that can be obtained from the SAML response. The left side of the parameter (key) is Pleasanter's user column. The corresponding SAML response attribute name is written on the right side. | |SamlParameters.SamlTenantId|1|Fixed to 1| ### 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. - The ID set in the NameID element of the SAML response is registered as the login ID. - If the login ID is unregistered, a new user is created with that login ID. - If the login ID is already registered, the user information for that login ID is updated. - The user information to be synchronized is searched for by the attribute name of the SAML response specified in __SamlParameters.Attributes__ in Authentication.json. If the attribute name in the SAML response exists, its value is set in the user column. #### `SamlParameters.Attributes` Columns List |User column name|Default value|Description| |-|-|-| |Name|"Name"|Specify the attribute name to be set in "Name". If the FirstName and LastName columns are added, specifying null for Name will set the combined value of FirstName and LastName to Name. If the value cannot be obtained from the specified SAML attribute, the login ID will be set. | |UserCode|"UserCode"|Specify the attribute name to be set in "User code". | |Birthday|"Birthday"|Specify the attribute name to be set in "Date of birth". | |Gender|"Gender"|Specify the attribute name to be set in "Gender". | |Language|"Language"|Specify the attribute name to be set in "「Language」". | |TimeZone|"TimeZone"|Specify the attribute name to be set in "「TimeZone」". | |TenantManager|"TenantManager"|Specify the attribute name to be set in [Tenant Manager](https://pleasanter-cms-1112983746-staging-en.azurewebsites.net/ja/manual/user-management-tenant-manager). If the attribute value is "true", the user will be registered as a tenant manager. | |DeptCode|"DeptCode"|Specify the attribute name to be set in "Dept code". The [Dept](https://pleasanter-cms-1112983746-staging-en.azurewebsites.net/ja/manual/table-management-choices-text-depts) with the dept code obtained here will be assigned to this user. If the corresponding [Dept](https://pleasanter-cms-1112983746-staging-en.azurewebsites.net/ja/manual/table-management-choices-text-depts) does not exist, a new dept will be created. | |Dept|"Dept"|Specify the attribute name to be set in "Dept name". The dept name of the [Dept](https://pleasanter-cms-1112983746-staging-en.azurewebsites.net/ja/manual/table-management-choices-text-depts) derived from "DeptCode" will be updated. If the corresponding dept does not exist, a dept will be created with this "Dept name". | |Body|"Body"|Specify the attribute name to be set in [Description](https://pleasanter-cms-1112983746-staging-en.azurewebsites.net/ja/manual/table-management-column-description). | |MailAddress|"{NameId}"|Specify the attribute name to be set in "Email address". If the NameID element is an email address, you can register the NameID value as an "email address" by specifying "{NameId}". | * 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. Refer to the link below for the confirmation procedure. [ I want to check the SAML response attribute name set in Authentication.json in the SAML authentication setup](/manual/faq-saml-response) ### `SamlParameters.SPOptions` In this section, you will set the information on the service provider（=Pleasanter）side. |Element name|Setting example|Description| |-|-|-| |EntityId|https://sso-pleasanter.com/pleasanter/Saml2|Entity ID of the service provider. Specify "{ServerName}/Saml2". *1| |ReturnUrl|https://sso-pleasanter.com/pleasanter/Users/SamlLogin|Redirect destination after successful authentication. Specify "{ServerName}/Users/SamlLogin". *1| |AuthenticateRequestSigningBehavior|IfIdpWantAuthnRequestsSigned|| |OutboundSigningAlgorithm|http://www.w3.org/2001/04/xmldsig-more#rsa-sha256|| |MinIncomingSigningAlgorithm|http://www.w3.org/2001/04/xmldsig-more#rsa-sha256|| |DisableOverwriteName|false|Set to "true" if you do not want to overwrite the user's "name" with the value of the SAML response when logging in. | |IgnoreMissingInResponseTo|false|Set to "true" if you want to skip validation of the InResponseTo element included in the SAML response. | |PublicOrigin|null|Specify the base URL of the Saml2 endpoint. Use this when the URL within the server and the URL published externally are different, such as when using a reverse proxy or load balancer. | |ServiceCertificates|[]|| - *1 Replace {ServerName} according to your environment. ### `SamlParameters.IdentityProviders` In this section, you will set the information on the ID provider side. |Element name|Setting example|Description| |-|-|-| |EntityId|https://id-provider.com/saml|Specify the entity ID of the ID provider. | |SignOnUrl|https://id-provider.com/saml/login|Specify the login URL of the ID provider. | |LogoutUrl|null| |AllowUnsolicitedAuthnResponse|true|Allow unsolicited responses. Specify true if you are using IdP-Initiated. | |Binding|HttpPost|Binding used when sending a SAML request to the ID provider. The following values ​​can be set: HttpRedirect / HttpPost / Artifact| |WantAuthnRequestsSigned|false| |DisableOutboundLogoutRequests|true| |LoadMetadata|false| |MetadataLocation|null| ### `SamlParameters.IdentityProviders.SigningCertificate` This section sets the certificate information that the identity provider will use to sign messages. |Element name|Setting example|Description| |-|-|-| |StoreName|My|Name of the certificate store to search. See *2 for possible values.| |StoreLocation|LocalMachine|Certificate store to search. See *3 for possible values.| |X509FindType|FindByThumbprint|Field to search for a match with the findValue value. See *4 for possible values.| |FindValue|50B459426DE554010B35E9XXXXXXXXXXXXXXXXX|Search value when searching for a certificate. Search is performed in the field specified by x509FindType. See *5 for possible values.| - *2 https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.storename?view=net-8.0 - *3 https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.storelocation?view=net-8.0 - *4 https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509findtype?view=net-8.0 - *5 The search value (thumbprint) of the certificate to be set in FindValue can be checked by the following steps. 1. Press the [Windows] key + [R], enter "certlm.msc" in the Run dialog box, and click "OK". 2. In the management console, go to "Personal" - "Certificates" and double-click the target certificate (or right-click and "Open"). 3. The string displayed in the "Value" field of the "Thumbprint" field on the "Details" tab of the certificate information screen For more detailed information, please refer to the Sustainsys.Saml2 documentation. https://saml2.sustainsys.com/en/v2/configuration.html#sustainsys-saml2-section ## 2. ID provider settings Please follow the manuals of each ID provider to set up on the ID provider side. The following information of the Pleasanter side is required in the ID provider side. |Column name|Value| |-|-| |SP Entity ID|"{ServerName}/Saml2" *6| |Redirect URL to transition to after successful authentication|"{ServerName}/Users/SamlLogin" *6| |ACS URL|"{ServerName}/Saml2/Acs"| - *6 Replace and set {ServerName}according to the environment. (e.g. https://sso-pleasanter.com/pleasanter/Saml2) ## 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 will appear on the login screen. ("SSO Login" button). Click this button to check the operation of SAML authentication. ## Limitation Pleasanter does not have the function to issue metadata on the SP (Pleasanter) side. It is not possible to register SP (Pleasanter) metadata in the IdP and link it.