You are here: Use cases > Implement Single Sign-On > How to support a custom SaaS application

How to support a custom SaaS application

UserLock SSO allows you to configure a custom SaaS application using Saml protocol with a dedicated configuration file. This file is named "CustomSamlManagers.json" and is located at %ProgramData%\ISDecisions\UserLock\SSO\CustomSamlManagers.json

Note: it is not yet possible to configure unsupported SaaS applications using OpenID connect protocol.

This file can contain several custom configurations, one for each custom or non-supported SaaS application.

The file is composed of three parts detailed below:

The Unique Identifier ("ProfileTypeId"): UserLock SSO uses this to uniquely identify the SaaS application. There cannot be 2 identical ProfileTypeIds amongst all UserLock SSO profiles, custom or not.
The Assertion ("Assertion"): used at runtime to return a correct SAML assertion to the SaaS application provider
The Configuration ("Configuration"): these parameters are used to display the appropriate settings in UserLock -> Single Sign-On -> Configuration. When a custom plugin is properly written, a dedicated tile will appear in the Configuration tab, and the settings that will be displayed while configuring the SaaS application depend on the parameters set here.

Sample Configuration File


			[
{
"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": "",
"CustomAppDomain": "https://{0}.contoso.com"
},
"LogoFilePath": "C:\\Images\logo.png",
"IssuerFormat": "https://{0}.contoso.com",
"AssertionConsumerServicesUriFormat": "https://{0}.contoso.com/sso"
}
}
			]

The unique identifier

In our example, the unique identifier is Contoso

"ProfileTypeId": "Contoso",

This identifier allows to differentiate this configuration from other configured supported SaaS applications.

The Assertion

This section contains the settings used at runtime to return a valid Saml Assertion during a logon. Each SaaS application requires specific settings that are defined here.
This part must be written using the SaaS application documentation that is dedicated to the SSO using Saml protocol.

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

Define the NameIdFormat

The NameId format is specified by the SaaS application (or service provider). It defines the expected format of the NameId (or Subject) in the Saml Response.

"NameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

Here are the common formats :

Email Address (default) : "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
Encrypted : "urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted"
Persistent : "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
Entity : "urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
Kerberos : "urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos"
Windows Domain Qualified Name : "urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName"
X509SubjectName : "urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"
Unspecified : "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
Transient : "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"

Define the NameIdType

The NameIdType defines which data UserLock SSO will use as the NameId value.

"NameIdType": "Email"

Supported values are :

Email, the email of the connecting user (this will require you to add the EmailDomain Editable input in the Configuration part)
ImmutableId

Define Attributes

Attributes are additional data that will be sent in the Saml Response. Refer to the documentation of the SaaS application in question to verify whether or not they are required.

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

The "MyAttribute" key must be replaced by the name of your attribute.
"FirstName" and "LastName" mean this attribute will have the FirstName and the LastName as specified in the Active Directory user profile.

Here are the supported values :

Email
ImmutableId
FirstName
LastName
DisplayName

If you need more than one attribute, you can define multiple ones as follows :

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

If an attribute value that is not available for a specific SaaS application, please contact IS Decisions support team.

The Configuration

Each type of SaaS application works differently and has a specific configuration. Once you will have created this custom configuration, you will need to create the SSO profile in the UserLock SSO administration console.
This next section will define the steps to create a profile for this SaaS application in the administration console:

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

MultiConfigAllowed

"MultiConfigAllowed": true

This property is set to true by default. It means you can create multiple profiles of this SaaS application in the UserLock SSO administration console. This is possible when the ProfileTypeId allows to uniquely identify a SaaS application subscription.
You must set it to false if the ProfileTypeId does not allow to differentiate 2 subscriptions of the SaaS application.

Editable Inputs

This part defines the fields that will be displayed in the UserLock SSO administration console when configuring a SaaS application.

"EditableInputs": {
"EmailDomain": "",
"CustomAppDomain": "https://{0}.contoso.com"
			}

Each input is composed of two values.
For example, in "CustomAppDomain": "https://{0}.contoso.com", the key "CustomAppDomain" allows to define which type of input will be requested.
"https://{0}.contoso.com" is an example. The whole value will be displayed but only the {0} part will be editable in the user interface.

Here are all the supported editable inputs :

CustomAppDomain> Enterprise or personal domain of the SaaS app (ex: "https://{0}.contoso.com")
Issuer
AcsUrl
EmailDomain: domain of the emails your users will connect with (mandatory if using the Email Attribute value or NameId)
MandatoryCertificate: the Saml certificate to use if a SaaS application requires to sign the authentication assertions
OptionalCertificate: the Saml certificate to use if a SaaS application optionally allows to sign the authentication assertions. The field will be optional too.

Logo file path

This indicates the local path to the file containing the logo of the SaaS application (only used for display purposes). It is not mandatory, but makes it easier to use the administration console. You have to download the logo and create the file yourself.

"LogoFilePath": "C:\\Images\logo.png"

Issuer Format

The IssuerFormat value need to be defined when you don't use the Issuer editable input. It will show UserLock SSO how to define the issuer of this application.

If the issuer of your application is always the same, you can directly define the value, and it will be used as is.

"IssuerFormat": "https://contoso.com"

If the issuer is dependent on a variable subdomain, and you can have multiple configurations for this SaaS application, you can enable the CustomAppDomain editable input and define the IssuerFormat like this (where {0} is the part that will be replaced by the custom app domain)

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

AssertionConsumerServicesUri

The AssertionConsumerServicesUri value needs to be defined when you don't use the AcsUrl editable input. It will show UserLock SSO how to define the Assertion Consumer Services Uri of this application.

If the Assertion Consumer Services Uri of your application is always the same, you can directly define the value, and it will be used as is.

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

If the Assertion Consumer Services Uri is dependent on a variable subdomain and you can have multiple configurations for this SaaS application, you can enable the CustomAppDomain editable input and define the AssertionConsumerServicesUri like this (where {0} is the part that will be replaced by the custom app domain):

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