Configure a non-supported SaaS application

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.

The configuration file must be in JSON format and structured as an array of configuration objects — one for each SaaS application.

[
  {
    "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",
      "AssertionConsumerServicesUri": "https://{0}.contoso.com/sso"
    }
  }
]

UserLock supports two configuration approaches depending on your needs:

The ProfileTypeId serves as a unique identifier for your SaaS application configuration within UserLock.

"ProfileTypeId": "Contoso"

Each SaaS application requires a distinct ProfileTypeId to avoid any configuration conflict.

This step explains how UserLock constructs the SAML assertion that is transmitted to the SaaS application during the authentication process.

"Assertion": {
  "NameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "NameIdType": "Email",
  "Attributes": {
    "MyAttribute": [
      "FirstName",
      "LastName"
    ]
  }
}

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:

"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"

This parameter defines which Active Directory user attribute UserLock will use as the NameID in the SAML response.

"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.

Attributes represent additional user information included in the SAML response.
They correspond to user properties retrieved from Active Directory.

Example:

"Attributes": {
  "MyAttribute": [
    "FirstName",
    "LastName"
  ]
}

You can define multiple attributes:

"Attributes": {
  "MyAttribute": [
    "FirstName",
    "LastName"
  ],
  "MySecondAttribute": [
    "DisplayName"
  ]
}

Supported values:

• Email

• ImmutableId

• FirstName

• LastName

• DisplayName

• UserPrincipalName

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.

"Configuration": {
  "MultiConfigAllowed": true,
  "EditableInputs": {
    "EmailDomain": ""
  },
  "LogoFilePath": "C:\\Images\\logo.png",
  "IssuerFormat": "https://{0}.contoso.com",
  "AssertionConsumerServicesUri": "https://{0}.contoso.com/sso"
}

Specifies whether multiple configurations for this app can coexist.

"MultiConfigAllowed": true

• true – allows several profiles (use for flexible configurations).

• false – restricts to one static configuration.

Defines the fields that will appear in the UserLock SSO console for this SaaS app.

"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.

Defines how UserLock generates the issuer value in the SAML request.

Static issuer:

"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:

"IssuerFormat": "https://{0}.contoso.com"

Defines the endpoint that receives the SAML response from UserLock.

Static endpoint:

"AssertionConsumerServicesUri": "https://contoso.com/sso"

The same logic applies here, for flexible configurations leave the value empty or include a placeholder pattern.

Flexible endpoint

"AssertionConsumerServicesUri": "https://{0}.contoso.com/sso"

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.