--- title: "Implementation > SAML Authentication" canonical: "https://technology.bytangram.com/space/TGKB/1598849025/Implementation%20%3E%20SAML%20Authentication" format: markdown --- SAML (Security Assertion Markup Language) is a standard commonly used to enable Single Sign-On (SSO). It allows you to configure WorkBook to authenticate users via an Identity Provider (IdP), so they can log in using their existing organisation credentials. Some of these identity providers are: - Azure AD / Office 365 - Okta - OneLogin - AD FS - Generic SAML 2.0 Identity Providers WorkBook expects the SAML assertion to include the claim `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, which must match the user's LoginName in WorkBook. > 📝 **Note: **that SAML authentication is used solely for validating user credentials; user accounts must still be created, managed, and deactivated manually within WorkBook. > ⚠️ **Important:** It is not currently possible to disable regular password authentication. As a workaround, you can enable LDAP authentication for the user—even if LDAP is not fully configured—to prevent login via password. | **ON THIS PAGE YOU WILL FIND:** | | --- | | > Macro (toc) | --- ## CONFIGURATION OF THE IDENTITY PROVIDER The following information is required to configure your Identity Provider (IdP) for SAML-based authentication with WorkBook. - **SAML Binding Endpoint:** `:///API/Auth/SAML` *(Replace *``* with *`https`* and *``* with your actual WorkBook domain.)* - **Supported SAML Bindings:** - `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect` - `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` --- ## CONFIGURATION IN WORKBOOK (SERVICE PROVIDER) SAML configuration in WorkBook is managed via system variables. To access these settings, navigate to: - **Settings** module > **global system settings** sub menu > **system variables** - Search for “SAML” in the **search field** You will find the following key configuration variables: | **SYSTEM VARIABLE** | **DETAILS** | | --- | --- | | **1002 – SAML Configuration**
![image-20250603-051529.png](media://d9205270-4805-4eea-8969-023e3cbd3c50) | Contains the main SAML configuration for the Service Provider (WorkBook). See below for configuration details. | | **1004 - SAML ServiceProvider Certificate** | The certificate that WorkBook should use for signing all requests (Optional) | | **1005 - SAML ServiceProvider Certificate Password** | The password for the Service Provider certificate | | **1006 - SAML IdentityProvider Certificate**
![image-20250603-052046.png](media://1f6a41b9-8f50-4dad-9b82-3dfc967207c5) | The public certificate for the IdentityProvider, used to validate all requests from the Identity Provider **(REQUIRED)**. The certificate should be base64 encoded and start with “—–BEGIN CERTIFICATE—–” and end with “—–END CERTIFICATE—–“ | | **1060 - SAML Error Response Redirect Address** | The URL that WorkBook should redirect to if SAML login fails. You can use #ErrorMessage# as a replacement token to display the specific error | | **1178 - SAML Use User Login**
![image-20250603-051556.png](media://ef98689f-fc0e-466e-9556-f3a8eb166789) | Must be enabled (checked). This ensures WorkBook uses the user's LoginName when matching the SAML assertion | --- ## SAML CONFIGURATION A typical SAML Configuration resembles the XML snippet below. This defines the Assertion Consumer Service (ACS) URL. If your Identity Provider requires a different configuration or does not support these options, please contact us — we’re happy to help you adjust the settings to meet your requirements. **Sample SAML Configuration XML** `` `    ` `    ` `        ` `    ` `` - Replace the placeholders: !!ServiceProvider Id!! and !!Url used for SAML!! - If a SAML ServiceProvider Certificate has been specified, change “UseEmbeddedCertificate” to false ### Configuring Microsoft Entra ID for SAML Authentication **Identifier (Entity ID):** - This can be set to whatever makes the most sense in the setup. **Note:** If the intent is to use Single Sign-On for other WorkBook systems, then it is recommended to use the URL for the system as the identifier. Entra ID doesn’t allow identical Identifier names. - **Reply URL (Assertion Consumer Service URL):** - `:///API/Auth/SAML` *(Replace *``* with *`https`* and *``* with your actual WorkBook domain.)* - **Sign On URL:** *Workbook URL* - **Relay State:** *Workbook URL* - **Logout URL:** *workbook URL* When using **Microsoft Entra ID** (formerly Azure Active Directory) as an authentication method, it’s essential to configure the **SAML assertion** correctly so that the required user attributes are passed from Entra ID to the target application during sign-in. You can refer to the following example setup when configuring the SAML attributes within Microsoft Entra ID: 1. Under **Attributes & Claims**, select **Edit**. 2. Add a new claim with the following details: - **Name:** `Name` - **Namespace:** `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/` - **Source attribute:** `user.mail` *(recommended)* ![image (36)-20251029-041918.png](media://421cd24d-d6f4-4f08-be9b-6163f4bf7886) ![image-20251029-044131.png](media://bafd2050-5391-4bda-a34b-77a670f2b5c8) This configuration ensures that the application receives the user’s email address as the unique identifier (**NameID**) during authentication. The `user.mail` attribute is generally preferred because it remains unique and consistent across Microsoft 365 and Entra ID environments. After adding the claim, save the configuration and verify the **SAML response** to confirm that the correct attribute values are being passed to the application. > **Note:** If your organization does not use the email field consistently, you can alternatively use the `user.userprincipalname` attribute instead. ### Google SAML Terminology If you're configuring WorkBook with **Google Workspace** as the IdP, note the terminology mapping: - ServiceProvider ID - is known as ‘Entity ID’ - SingleSignOnServiceUrl - is known as ‘SSO URL’ Under Service Provider Details: - ACS URL: Should be set to ‘https://[THE_URL_FOR_YOUR_WORKBOOK]/api/auth/saml’ - Entity ID: Always ‘workbook://app’ ### Additional Options and Configurations [SAMLConfiguration schema](http://update.workbook.net/saml-config-schema.xsd) --- ## DISABLING WORKBOOK USERNAME & PASSWORD Currently, there is no dedicated feature to completely disable WorkBook username and passwords. However, there is a workaround using LDAP settings to prevent users from logging in with their WorkBook credentials. ### Workaround: Use LDAP Authentication 1. Enable system variable: **844** - Allow the usage of Lightweight Directory Access Protocol for authentication of users 2. For each user you want to restrict: 1. Open the **employee card **> **login settings** 2. Check the “**Is LDAP User**” option ![image](media://e538c090-6389-457a-9b61-f8ee0bb1e5ec) This prevents the user from using WorkBook’s standard username/password mechanism, and forces them to use the Identity Provider. --- # TROUBLESHOOTING | **ISSUE** | **SOLUTION** | | --- | --- | | **The audience restriction * doesn’t match the expected audience restriction *** | - This is caused because the identity of the application on the IdentityProvider does not match the ServiceProvider. - We recommend that you change the identity on the IdentityProvider to match a non-existing address, the default sample is “workbook://app” | | **Login failed for the username: *** | - This error is issued by WorkBook when no username in WorkBook matches the username sent by the IdentityProvider. - On most IdentityProvider you can change what it sends as username, and alternatively you can “just” change the username of the individual users in WorkBook. - If the username displayed is a number, GUID or similar it is most likely because the system is not sending the claim “[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name”](#) as expected by WorkBook. | | **The SAML message doesn’t contain an InResponseTo attribute.** | - Some IdentityProvider will not send an “InReposenTo” when the login has been initiated by the IdentityService. - If you are unable to, enable this behavior on the IdentityProvider, you can disable it in WorkBook by adding **DisableInResponseToCheck=”True” **in the **PartnerIdentityProvider** section of the WorkBook configuration. | --- **Related articles ** > Macro (contentbylabel)