# SAML SSO ### App for SAML Single Sign-On > The SAML SSO (Security Assertion Markup Language Single Sign-On) app allows users to log in to BuildingPro Suites with various SAML 2.0 SSO providers, including Microsoft ADFS. This setup simplifies authentication by using a single set of credentials.
#### Migration from ADFS to SAML SSO > **Note:** This section is only relevant if you previously used the ADFS app and are upgrading to BuildingPro Suites v13.2 or newer. If you are installing BuildingPro Suites for the first time, you can skip this section. Before BuildingPro Suites v13.2, the "ADFS" app was used for Single Sign-On (SSO) with Azure. As of v13.2, BuildingPro Suites supports a wider range of identity providers and implements the full SAML SSO protocol. Therefore, the "ADFS" app has been replaced by the new "SAML SSO" app. **Important:** After upgrading to BuildingPro Suites v13.2, the ADFS login will no longer work. To restore SSO functionality, follow these steps: 1. Install the **SAML SSO** app. 2. Check the configuration of the SAML SSO app. It should automatically detect and adopt the previous ADFS configuration. (The configurations of both apps should be similar.) 3. In your **Azure** configuration, update the Reply URL to: `https://{your-eliona-domain.com}/apps-public/saml-sso/saml/acs` 4. Make sure the **Entity ID** in your Azure configuration matches the one in the SAML SSO app. After you have completed these steps, test the login process to ensure that SSO is working correctly. After a successful check, you can safely remove the **ADFS** app. ### Configuration The SAML 2.0 Service Provider is configured by defining one or more authentication data records: | Attribute | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Configuration ID. Can only be 1 | | `enable` | Whether the configuration is active or not | | `serviceProviderCertificate` | The certificate of this SAML Service Provider (SP). Can be a self-signed x509 certificate. | | `serviceProviderPrivateKey` | The private key that matches the certificate of this SAML Service Provider (SP). DO NOT use an RSA key length below 2048 | | `idpMetadataUrl` | The metadata URL of the Identity Provider (IdP), if available. Otherwise, use the metadataXml to provide the IdP's metadata directly and leave this field blank | | `idpMetadataXml` | Specify the IdP metadata XML directly if you do not have access to the idpMetadataUrl | | `ownUrl` | The own URL of this BuildingPro Suites instance | | `userToArchive` | When activated, the newly created user is archived and cannot log in until an administrator has activated them | | `allowInitializationByIdp` | Allow IdP-initiated assertions. | | `signedRequest` | Whether the SP should make a signed SAML Authn request or not | | `forceAuthn` | Normally, this value is set to false for an SP. If set to true, the user must re-authenticate (log in to the IdP) even if they have a valid session with the IdP | | `entityId` | Service provider Entity ID. Unique identifier URI, usually based on the tenant's domain. Normally, the default value can remain unchanged | | `loginFailedUrl` | The URL to which it is redirected if the login fails. If this value is null, the default page /noLogin is displayed | The configuration is done via a corresponding JSON structure. For example, the following JSON structure can be used to define an endpoint for app permissions: ```json { "id": 1, "enable": true, "serviceProviderCertificate": "-----BEGIN CERTIFICATE-----***-----END CERTIFICATE-----", "serviceProviderPrivateKey": "-----BEGIN PRIVATE KEY-----***-----END PRIVATE KEY-----", "idpMetadataUrl": "[https://login.thirdparty-idp.example/federationmetadata/metadata.xml](https://login.thirdparty-idp.example/federationmetadata/metadata.xml)", "idpMetadataXml": null, "ownUrl": "[https://customer.eliona.cloud](https://customer.eliona.cloud)", "userToArchive": false, "allowInitializationByIdp": false, "signedRequest": true, "forceAuthn": false, "entityId": "{ownUrl}/saml/metadata", "loginFailedUrl": "{ownUrl}/logout" } ``` Configurations can be created with this structure in BuildingPro Suites under `Settings > Apps > System > SAML SSO app`. To do this, select the /configs endpoint with the POST method. Information on configuration on the provider side can be found in the documentation of your SSO provider. #### Attribute Mapping The default attribute mapping (suitable for Azure AD) can be changed using `/configuration/attribute-mapping`. ```json { "uuid": "[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn)", "email": "[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email)", "firstName": "[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstName](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstName)", "lastName": "[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastName](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastName)", "phone": "[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/phoneNumber](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/phoneNumber)" } ``` If you want to use email as the identifier (recommended), leave the uuid field blank. If you want to use another unique user identifier (e.g., UPN), fill the uuid field with the name of the SAML attribute. #### Permission Mapping To pass the access control list, the SAML SSO App allows the assignment of user roles during user creation. Example for setting up tenant roles: First, create the tenant roles "Tenant user" and "Tenant guest" in the BuildingPro Suites Engineering module and then configure the endpoint `/configuration/permission-mapping` with the following configuration: ```json { "defaultSystemRole": "System user", "defaultProjRole": "Tenant user", "defaultLanguage": "en", "projRoleSamlAttribute": "MemberOf", // SAML attribute name with role names "projRoleMap": [ { "elionaRole": "Tenant user", "samlValue": "Manager" }, { "elionaRole": "Tenant guest", "samlValue": "Guest" } ] } ``` #### Azure AD as SAML SSO Identity Provider To configure Azure Active Directory (Azure AD) specifically for SAML-based Single Sign-On (SSO), follow these steps: 1. Create an enterprise application in Azure AD * Go to the [Azure portal](https://portal.azure.com/). * Navigate to Azure Active Directory > Enterprise applications. (Note: App registrations are for the OAuth/OIDC workflow, while enterprise applications are for SAML.) * Click on New application and then select "Create your own application". * Enter the name of your application and select "Integrate any other application you don't find in the gallery". * Click on Create. 2. Configure Single Sign-On (SAML) * In your enterprise application, under Manage, select Single sign-on. * Select SAML as the single sign-on method. 3. Set up basic SAML configuration * Click on Edit in the Basic SAML Configuration section. * Identifier (Entity ID): Set this to a unique URI, typically based on your tenant's domain or another verified domain. Example: `yourtenant.onmicrosoft.com/your-app-id`. Does not have to match the actual BuildingPro Suites instance domain. Can also be set via the manifest field `"identifierUris"`. * Reply URL (Assertion Consumer Service URL): Enter the URL to which Azure AD sends SAML responses, e.g.: `https://customer.eliona.cloud/apps-public/saml-sso/saml/acs`. 4. Download Azure AD metadata * In the SAML Signing Certificate section, download the Federation Metadata XML file or copy the provided metadata URL: ``` [https://login.microsoftonline.com/](https://login.microsoftonline.com/){tenant-id}/federationmetadata/2007-06/federationmetadata.xml ``` * Replace `{tenant-id}` with your actual Azure AD tenant ID. 5. Assign users and groups * Under Users and groups, assign users or groups who are allowed to authenticate with BuildingPro Suites via SAML. 6. Configure SAML SSO settings in BuildingPro Suites * MS Login: Activate the "via Microsoft" login button by setting the configuration to "Active". * Metadata URL: Enter the metadata URL copied from Azure AD (see step 4). * Own URL: Enter the URL of your BuildingPro Suites instance (e.g., `https://customer.eliona.cloud`). * Entity ID: Set the Entity ID from step 3. * Certificate: Optional, you can use a self-created certificate to secure communication. For a more detailed guide, refer to the official [Microsoft Azure SAML documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications).