# 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 Eliona 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 Eliona v13.2 or later. If you are installing Eliona for the first time, you can skip this section. Before Eliona v13.2, the "ADFS" app was used for single sign-on (SSO) with Azure. From v13.2 onward, Eliona supports a broader 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 Eliona 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. Update in your **Azure**configuration the Reply URL to:\ `https://{your-eliona-domain.com}/apps-public/saml-sso/saml/acs` 4. Make sure that 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 works properly. After successful verification, you can safely remove the **ADFS**app. ### Configuration The SAML 2.0 Service Provider is configured by defining one or more authentication records: | Attribute | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Configuration ID. Can only be 1 | | `enable` | Whether the configuration is enabled or not | | `serviceProviderCertificate` | The certificate of this SAML Service Provider (SP). Can be a self-signed x509 certificate. | | `serviceProviderPrivateKey` | The private key corresponding to 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 metadataXml to provide the IdP metadata directly and leave this field empty | | `idpMetadataXml` | Provide the IdP metadata XML directly if you do not have access to idpMetadataUrl | | `ownUrl` | The own URL of this Eliona instance | | `userToArchive` | If enabled, the newly created user will be archived and will not be able to log in until an administrator activates 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 at 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 redirect to if login fails. If this value is null, the default /noLogin page is shown | Configuration is done using a corresponding JSON structure. As an 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", "idpMetadataXml": null, "ownUrl": "https://customer.eliona.cloud", "userToArchive": false, "allowInitializationByIdp": false, "signedRequest": true, "forceAuthn": false, "entityId": "{ownUrl}/saml/metadata", "loginFailedUrl": "{ownUrl}/logout" } ``` Configurations can be created in Eliona with this structure 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 your SSO provider's documentation. #### Attribute mapping The default attribute mapping (suitable for Azure AD) can be changed using the `/configuration/attribute-mapping` endpoint. ```json { "uuid": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email", "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstName", "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastName", "phone": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/phoneNumber" } ``` If you want to use email as the identifier (recommended), leave the uuid field empty. 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 assigning user roles during user creation. Example setup of project roles: First create the project roles “Project user” and “Project guest” in the Eliona Engineering module, and then configure the endpoint `/configuration/permission-mapping` with the following configuration: ```json { "defaultSystemRole": "System user", "defaultProjRole": "Project user", "defaultLanguage": "en", "projRoleSamlAttribute": "MemberOf", // SAML attribute name with role names "projRoleMap": [ { "elionaRole": "Project user", "samlValue": "Manager" }, { "elionaRole": "Project guest", "samlValue": "Guest" } ] } ``` #### Azure AD as a 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** the option **Single Sign-On**. * Select **SAML** as the single sign-on method. 3. **Set up basic SAML configuration** * Click on **Edit** in the section **Basic SAML configuration**. * **Identifier (Entity ID)**: Set this to a unique URI, usually based on your tenant's domain or another verified domain. Example: `yourtenant.onmicrosoft.com/your-app-id`. Does not have to match the actual Eliona 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 section **SAML Signing Certificate** download the file **Federation Metadata XML** or copy the provided metadata URL: ``` 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 the users or groups that are allowed to authenticate with Eliona via SAML. 6. **Configure SAML SSO settings in Eliona** * **MS login**: Enable the login button "via Microsoft" by setting the configuration to "Enabled". * **Metadata URL**: Enter the metadata URL copied from Azure AD (see step 4). * **Own URL**: Enter the URL of your Eliona instance (e.g. `https://customer.eliona.cloud`). * **Entity ID**: Set the Entity ID from step 3. * **certificate**: Optionally, you can use a self-created certificate to secure the 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).