--- locale: "en" updated_at: "2026-03-02T16:30:27.566Z" canonical: "https://www.isdecisions.com/en/userlock/docs/guides/sso/configure-the-applications/configure-non-supported-saas-application" --- # Configure a non-supported SaaS application Generic SAML setup, manual configuration, metadata exchange. ## Overview UserLock SSO lets you integrate any SaaS application that supports the **SAML** protocol, even if it is not natively available in the interface. This integration is achieved by creating a **custom configuration file** that defines how UserLock should issue SAML assertions and handle application-specific parameters. Each custom configuration is saved in the following file: `%ProgramData%\ISDecisions\UserLock\SSO\CustomSamlManagers.json` You can include multiple configurations in this file, one for each application. Once your custom configuration has been created, you must also set up the corresponding application profile in UserLock SSO, just as you would for other SaaS providers. 🚩 **Before starting:** - Ensure you have access to the SaaS application’s SAML configuration **guide or documentation.** - Verify the required **attributes, endpoints, and NameID formats** expected by the application. - Prepare the **SAML certificate** used by the SaaS application, if it requires signed authentication requests. - **UserLock SSO** must already be [installed and configured](/userlock/docs/guides/sso/install-configure-sso). > **Note** > > Custom configurations using the **OpenID Connect** protocol are not currently supported. ## Step 1 – Create the configuration file The configuration file must be in **JSON format** and structured as an array of configuration objects — one for each SaaS application. ```json [ { "ProfileTypeId": "Contoso", "Assertion": { "NameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "NameIdType": "Email", "Attributes": { "MyAttribute": [ "FirstName", "LastName" ] } }, "Configuration": { "MultiConfigAllowed": true, "EditableInputs": { "EmailDomain": "" }, "LogoFilePath": "C:\\Images\\logo.png", "IssuerFormat": "https://{0}.contoso.com", "AssertionConsumerServicesUriFormat": "https://{0}.contoso.com/sso" } } ] ``` ## Step 2 – Choose your configuration type UserLock supports two configuration approaches depending on your needs: | **Type** | **Description** | **Typical Use Case** | | --- | --- | --- | | **Single Configuration** | Fixed configuration that works for one environment, with all values defined directly in the JSON file. | When your SaaS app uses a single domain or instance (e.g., one company tenant). | | **Flexible Configuration** | Dynamic configuration that allows several profiles for the same app. | When your SaaS app uses multiple domains or tenants (e.g., one per department or client). | ## Step 3 – Define the unique identifier The `ProfileTypeId` serves as a unique identifier for your SaaS application configuration within UserLock. ```json "ProfileTypeId": "Contoso" ``` Each SaaS application requires a distinct `ProfileTypeId` to avoid any configuration conflict. ## Step 4 – Configure the SAML assertion This step explains how UserLock constructs the SAML assertion that is transmitted to the SaaS application during the authentication process. ```json "Assertion": { "NameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "NameIdType": "Email", "Attributes": { "MyAttribute": [ "FirstName", "LastName" ] } } ``` ### Define the NameIdFormat This parameter specifies the format of the NameID (subject) used in the SAML response. It must correspond exactly to the format expected by the SaaS application for authentication. Example: ```json "NameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" ``` Commonly used formats: - `"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"` (most commonly used) - `"urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"` - `"urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos"` - `"urn:oasis:names:tc:SAML:2.0:nameid-format:transient"` ### Define the NameIdType This parameter defines which Active Directory user attribute UserLock will use as the **NameID** in the SAML response. ```json "NameIdType": "Email" ``` Supported values: - **Email** — selects the first email address matching the expected domain from the user’s UPN, Email, or ProxyAddresses attributes (requires the `EmailDomain` editable input). - **ImmutableId** - **UserPrincipalName** (UPN) - **SamAccountName** Values not listed above are not supported. ### Define attributes Attributes represent additional user information included in the SAML response. They correspond to user properties retrieved from Active Directory. **Example:** ```json "Attributes": { "MyAttribute": [ "FirstName", "LastName" ] } ``` You can define multiple attributes: ```json "Attributes": { "MyAttribute": [ "FirstName", "LastName" ], "MySecondAttribute": [ "DisplayName" ] } ``` Supported values: - Email - ImmutableId - FirstName - LastName - DisplayName - UserPrincipalName > **Note** > > If you need additional attributes that are not listed here, please contact the **IS Decisions Support Team** for assistance. ## Step 5 – Define the Configuration section The configuration section specifies which parameters the administrator can customize in the UserLock SSO console, as well as how the SaaS application will be displayed and managed within it. ```json "Configuration": { "MultiConfigAllowed": true, "EditableInputs": { "EmailDomain": "" }, "LogoFilePath": "C:\\Images\\logo.png", "IssuerFormat": "https://{0}.contoso.com", "AssertionConsumerServicesUriFormat": "https://{0}.contoso.com/sso" } ``` ### MultiConfigAllowed Specifies whether multiple configurations for this app can coexist. ```json "MultiConfigAllowed": true ``` - **true** – allows several profiles (use for flexible configurations). - **false** – restricts to one static configuration. ### Editable Inputs Defines the fields that will appear in the UserLock SSO console for this SaaS app. ```json "EditableInputs": { "EmailDomain": "", "MandatoryCertificate": "", "OptionalCertificate": "" } ``` Supported editable inputs: - **EmailDomain** — required if using the `Email` NameIdType or attribute. - **MandatoryCertificate** — for SaaS applications that *require* the SAML request to be signed. The user will be prompted to upload the corresponding certificate. - **OptionalCertificate** — for SaaS applications that *support* signed requests but do not require them. Uploading the certificate is optional. - **CustomAppDomain** — required when using a **Flexible Configuration**, as it is used to populate the placeholder in both the **Issuer Format** and the **ACS URI Format**. ### Issuer Format Defines how UserLock generates the *issuer* value in the SAML request. **Static issuer:** ```json "IssuerFormat": "https://contoso.com" ``` If you want your configuration to be flexible, leave the value empty or include a placeholder pattern. In both cases, you’ll define the actual value later in the UserLock SSO interface when creating the application profile. **Flexible issuer:** ```json "IssuerFormat": "https://{0}.contoso.com" ``` ### Assertion Consumer Services URI Format Defines the endpoint that receives the SAML response from UserLock. **Static endpoint:** ```json "AssertionConsumerServicesUriFormat": "https://contoso.com/sso" ``` The same logic applies here, for flexible configurations leave the value empty or include a placeholder pattern. **Flexible endpoint** ```json "AssertionConsumerServicesUriFormat": "https://{0}.contoso.com/sso" ``` ## Step 6 – Create and validate the SSO profile Once your JSON configuration is complete: 1. In the UserLock console, go to ⚙ **Server settings▸ Single Sign-On**. 2. In the application list, select **your custom application**. 3. Fill in any editable inputs (e.g., email domain, certificate uploads). 4. Save the configuration and test authentication with the SaaS application.