WINAP additional information - SSO

Owned by John Jellema
2023-05-05
6 min read

web.config Configuration Details

The main configuration of the Windows AP resides in the ASP.NET configuration file located at the path %PROGRAMFILES%\Ubisecure\Ubisecure.Ubilogin.UAP\uapsso\web.config. In the example below is the default configuration for Ubisecure Windows Authentication Provider.

Listing 1. ASP.NET configuration file (web.config) with default settings for Windows AP
<?xml version="1.0"?>
<configuration>
  <system.diagnostics>
    <switches>
      <!-- 0 = Off, 1 = Error, 2 = Warning, 3 = Info, 4 = Verbose -->
      <add name="Ubisecure.Ubilogin.UAP" value="0"/>
    </switches>
<!--
    <trace autoflush="true" indentsize="2">
      <listeners>
        <add name="output.log" type="System.Diagnostics.TextWriterTraceListener" initializeData="c:\temp\output.log"/>
      </listeners>
    </trace>
-->
  </system.diagnostics>
  <system.web>
    <trust level="Full" originUrl=""/>
    <globalization requestEncoding="utf-8" responseEncoding="utf-8"/>
 
    <compilation debug="true">
      <assemblies>
        <add assembly="System.DirectoryServices, Version=2.0.0.0, Culture=neutral, PublicKeyToken=B03F5F7F11D50A3A"/>
        <add assembly="Ubisecure.Ubilogin, Version=3.0.1.0, Culture=neutral, PublicKeyToken=e76714ff33c956b5"/>
        <add assembly="Ubisecure.Ubilogin.UAP, Version=3.2.0.0, Culture=neutral, PublicKeyToken=e76714ff33c956b5"/>
      </assemblies>
    </compilation>
 
    <authentication mode="Windows"/>
    <identity impersonate="true"/>
    <httpHandlers>
      <clear/>
      <add verb="*" path="login.aspx" type="My.LoginServlet"/>
      <add verb="*" path="*" type="System.Web.HttpForbiddenHandler"/>
    </httpHandlers>
    <httpModules>
      <clear/>
      <add name="WindowsAuthentication" type="System.Web.Security.WindowsAuthenticationModule"/>
    </httpModules>
  </system.web>
 
  <appSettings>
    <!-- format of the username value, one of the following
    urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
    urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
    urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
    -->
    <add key="Ubisecure.Ubilogin.UAP.NameFormat" value="urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName"/>
    <!-- transform username with: ToUpper/ToLower/None -->
    <add key="Ubisecure.Ubilogin.UAP.NameTransform" value="ToLower"/>
    <!-- crack username components to username.name/username.domain/username.realm -->
    <add key="Ubisecure.Ubilogin.UAP.CrackName" value="false"/>
    <!-- add ldap and dn attributes for domain users -->
    <add key="Ubisecure.Ubilogin.UAP.LDAP.DN" value="true"/>
    <!-- enable test page -->
    <add key="Ubisecure.Ubilogin.UAP.EnableTest" value="true"/>
  </appSettings>
 
</configuration>

Within the configuration files, there are blocks that contain the configuration information for the Windows AP. These are the <system.diagnostics /> and <appSettings /> -elements.

Configuration Options for the system.diagnostics Element

The system.diagnostics element itself contains two child elements; <switches/> and <trace/>. These control the logging output of the Windows AP and modifications are mainly used for troubleshooting.

The switches element contains name-value mappings defined by the <add/> –element. This definition maps the Ubisecure.Ubilogin.UAP key with the value representing the current log level. Only the number indicating the log level should be modified here.

The log levels are as follows:
0: No logging at all
1: Log only error conditions
2: Log errors and warnings
3: Log information about logon events, errors and warnings
4: Verbosely output logon information, errors and warnings

Logging affects the software speed marginally. The higher the log level is set, the slower the performance will be.
The <trace /> element is a special debugging configuration for outputting more detailed information in the specified log file. This element should only be uncommented for troubleshooting. By default this will output information in the c:\temp\output.log file. Note that the temp –folder will not be created automatically. If the folder does not exist, no logfile will be generated.

Configuration Options for the appSettings Element

The <appSettings/> element contains a key-value map where mappings are defined in the <add /> element. The key is defined with the name attribute and the value is defined with the value attribute.

Ubisecure.Ubilogin.UAP.NameFormat

This configuration option defines the format of the subject which should be added in the response message. Possible values are:

urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName (this is the default value)
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos

Ubisecure.Ubilogin.UAP.NameTransform

This configuration option defines if the name should be transposed to uppercase or lowercase or sent as it is. Possible values are:
ToLower (this is the default value)
ToUpper
None

Ubisecure.Ubilogin.UAP.CrackName

This option defines if the username should be split into components. Possible values are:
true
false (this is the default value)

Note that this configuration is tied to the Ubisecure Ubilogin.UAP.NameFormat option and the name is split according to its format. The behavior is, as follows:

urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName: the name is split into the username.name and username.domain attributes.
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName: this format can not be split.
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos: this format is split into the username.realm and username.name –attributes.

Ubisecure.Ubilogin.UAP.LDAP.DN

This option defines whether Windows AP will include the URL of Active Directory and the Distinguished Name of the user in the authentication response. Possible values are:
true (this is the default value)
false

Ubisecure.Ubilogin.UAP.RoleNames

This optional configuration enables the sending of additional user role information to the Ubisecure SSO Server. This value references an external XML file which contains a mapping of what role names will be sent to the Ubisecure SSO Server based on what their group membership is in the Active Directory. An application service provider could distribute the external XML file to their customer organizations to allow existing group memberships to be used in third party applications.

<add key="Ubisecure.Ubilogin.UAP.RoleNames" value="~/App_Data/RoleNames.xml" />
If value starts with "~/" then path is resolved relative to web application folder, otherwise the path is resolved relative to %CommonApplicationData%\Ubisecure\Ubisecure.Ubilogin.UAP
The syntax of RoleNames.xml file is shown in the following example:
<roles xmlns="http://schema.ubisecure.com/uapsso/roles">
<role name="admins">builtin\Administrators</role>
<role name="users">builtin\users</role>
<role name="staff">example\staff</role>
</roles>

In this case, if the user is in the staff group of the example domain, the role staff will be sent to Ubisecure SSO Server and available as a method attribute name roles. The role format is checked with WindowsPrincipal.IsInRole. See Microsoft documentation for more information http://msdn.microsoft.com/en-us/library/fs485fwh.aspx

Ubisecure.Ubilogin.UAP.EnableTest

This configuration option defines if the test page is enabled. The test page makes it possible to verify if the Web Application and the Domain Computer hosting IIS are configured correctly in respect to the Domain Configuration and that Windows Integrated Authentication is possible. Additionally the page will output the format of the attributes that the Windows AP is going to return according to the configuration. Possible values for this configuration option are:

true (default)
false

The test page can be accessed at https://<servername>/uapsso/login.aspx, where <servername> represents the fully qualified domain name of the server where Windows AP is installed. An example is shown below in Figure 1.

Figure 1. Test page after successful installation, showing all attributes.

Additional Information

For information about ASP.NET configuration files, refer to documentation at Microsoft Developer Network. https://msdn.microsoft.com/en-us/library/ms178683.aspx

Determining the Instance Number of an Internet Information Services (IIS) Virtual Server

In certain phases of the installation, it is required to supply the instance number of the IIS virtual server where the windows authentication provider is desired to be installed. The instance number of the Default Web Site is usually 1. The instance number can be determined by following procedure on Internet Information Services (IIS) Manager:

Open the Internet Information Services (IIS) Manager –application
Expand the selection [your computer name]
Select “Web Sites”
From the Identifier field you can pick up the instance number of the web site.

Related Web Resources

Microsoft TechNet: Integrated Windows Authentication in IIS 6.0

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/9b619620-4f88-488b-8243-e6bc7caf61ad.mspx

Configuring ADAM to Ignore Windows Domain Password Policy Settings

The Windows Domain Password Policy settings are not used by Ubisecure Server to enforce password requirements, therefore this option can be disabled on a server which offers ADAM services only to Ubisecure Server.
In order to disable this feature, you have to log on with an account with administrative privileges for ADAM (i.e., the user account that installed the ADAM instance in the first place in a default scenario), then open a commandprompt window and issue the following commands.

  1. %WINDIR%\ADAM\dsmgmt.exe
  2. Configurable Settings
  3. Connections
  4. connect to server localhost:389
  5. quit
  6. set ADAMDisablePasswordPolicies to 1
  7. Commit Changes
  8. Show Values
  9. quit
  10. quit


Figure 2. Disabling Windows Password Policy on ADAM

Using Internet Explorer with Windows AP

Windows SSO use with Internet Explorer is enabled by default, no changes are typically necessary. To confirm if it is enabled:

  1. Choose Tools… then Options menu in Internet Explorer
  2. Choose Advanced Options

  3. Confirm that Enable Integrated Windows Authentication is selected. Enabling this option requires the browser to be restarted.

    Figure 3. Configuring Integrated Windows Authentication in Internet Explorer

Using Mozilla Firefox with Windows AP

To use Windows SSO in Mozilla Firefox, you must add the hostnames of the Windows AP servers in Firefox configuration. Use the following steps to configure Mozilla Firefox:

  1. Navigate to special URI about:config in Mozilla Firefox
  2. Write ntlm in the Filter and double click the network.automatic-ntlm-auth.trusted-uris configuration key

  3. Enter the hostname of your Windows AP server, e.g. uap.example.com. If you need multiple hosts, use comma as the separator.

    Figure 4. Configuring trusted Windows AP hostnames in Mozilla Firefox


Ubisecure Privacy Policy & Cookie Statement