Set up SSO with Microsoft Windows SSPI

How to set up a complete SSO system consisting of an Active Directory Server, censhare Client (running on Microsoft Windows), and a censhare Server (running on Mac OS X). The authentication is based on SSPI.

Target group

The audience for this article are developers and support people who want to set up a test system using the Microsoft Windows SSPI technology.

Introduction

The Microsoft Active Directory and Single-Sign-On technology are based on the Kerberos protocol. This section describes how the communication of the Kerberos protocol works in the context of the censhare system.

1.1 Kerberos

The complete SSO system is composed of

A censhare Client running on a Microsoft Windows OS .

A Domain-User signed in on the OS (e.g. by username & password or Smart-Card).

An Active Directory Server, called TGS (Ticket Granting System), providing the Windows Domain.

A censhare Server that the user wants to access without typing in its credentials again.

1.1.1 Client Authentication

At the very first step, the Domain-User (Client) has to authenticate itself at the TGS (MS Active Directory server).

Therefore the user logs into Microsoft Windows OS by entering its User-ID and password. The OS hashes the entered password and creates the Client Key (green key) out of it. For the authentication, the OS transfers the User-ID as plain-text to the TGS (no password or password-hash is transferred).

The TGS searches for the User-ID within its internal database and if the key is found, it creates a Client-TGS Session-Key (blue key) for the upcoming communication between the Client and the TGS.

Because the TGS has the password of the corresponding User-ID within its internal Database, it creates - like the Client itself - a Client Key out of the hashed password. Now the TGS transfers the Client-TGS Session-Key to the Client, encrypted by the Client Key. Besides, a TGT (Ticket Granting Ticket) is transferred to the Client. This TGT contains the Client-ID, the Client-Network Address, a validity period and the Client-TGS Session-Key. The complete TGT is encrypted by the private TGS key (red key).

After the client has received those two tickets, it decrypts the Client-TGS Session-Key with its generated Client Key. If the user has entered the correct password, the encryption will pass otherwise it fails. After that step, the Client is authenticated successfully against the TGS. The TGT can't be and doesn't need to be encrypted by the Client because only the TGS knows the secret key.

1.1.2 Service Authorization

Within the next step, the domain user starts the censhare Client on its Windows OS and wants to access the censhare Server. Before the Client can request the service censhare Server, it has to authorize itself for the usage of the service at the TGS.

Therefore the Client sends two tickets to the TGS. The first is composed out of the TGT - received at the end of the authentication process - and the Service-ID of the Service it wants to access (e.g. cs-srv13\CENSHARE.COM). The second ticket is an Authenticator containing the Client-ID and a timestamp encrypted by the Client-TGS Session-Key.

The TGS receives those two tickets and first decrypts the TGT with its private TGS key. The decrypted TGT contains the Client-TGS Session-key which is used to decrypt the second ticket (Authenticator). With all the information contained in those two tickets, the TGS can decide to accept or decline client requests to the service. If it accepts the request, a Client-Service Session-Key (orange key) is generated for the upcoming communication between the Client and the Service (censhare Server). The new session key is transferred to the Client, encrypted by the Client-TGS Session-Key. Besides, a Client-To-Service Ticket (C2s) is transferred to the Client, encrypted by the Service Key (purple key). The C2s contain the Client-ID, the Client-Network Address, a validity period, and the Client-Service session key.

After the Client has received those two tickets, it decrypts the Client-Service Session-Key and is prepared to request access to the censhare Server. The C2s can't be and don't need to be encrypted by the Client because only the censhare Server (and the TGS) knows the secret key.

1.1.3 Service Request

Now the Client and the censhare Client have enough information to request the Service itself (access to censhare Server).

Therefore the Client sends two tickets to the censhare Server. First of all the C2s ticket, received from the TGS in the prior step, is forwarded to the censhare Server. Besides, the second ticket is an Authenticator containing the Client-ID and a timestamp, encrypted by the Client-Service Session-Key.

The censhare Server receives the two tickets and decrypts the C2s with its Service Key. The Service Key is a shared secret between the TGS and the censhare Server (both servers have the same key file for this service). The decrypted C2s contain the Client-Service Session-key which is used to decrypt the second ticket (Authenticator). With all the information contained in those two tickets, the censhare-Server has enough information to accept or decline the request of the Client.

To decide if the connection will be accepted, the censhare Server requests more information about the Client from the TGS. Therefore an LDAP query with the Client-ID is sent to the TGS and on the basis of the returned values, the acceptance of the Client is decided.

If the censhare Server accepts the user, it returns an ACK ticket to the Client which contains the timestamp of the received Authenticator plus 1 encrypted by the Client-Service Session-Key.

Now the censhare Client can decide if it trusts the censhare Server or not. If it does, the connection was established successfully.

2 System Setup

With the knowledge of the Kerberos protocol (section 1) and its participants, a test system can be set up. This is described step-by-step within this section.

2.1 Prerequisites

This section describes the setup on the basis of the following elements which are the prerequisite for a successful running system.

macOS-based machine, running the censhare Server with static IP or registered host-name. The host-name must be accessible for the AD as well as for the censhare Client
A Microsoft Windows Professional (7 or higher) based machine or higher (Ultimate) running the censhare Client. The Windows OS might run as a Virtual Machine.
Access to the censahre Active Directory Test Server (dc01.censhare.com) from censhare Server and censhare Client.
All participants have to be in the same IP Subnet or at least reachable for each other. Please note: If you run the censhare Client within a Virtual Machine, it must not use "internet sharing" but "bridged network". As a prerequisite for "bridged network" your Ethernet connection must support "multiple authentications" (see Multiple Authentication ).

2.2 Setup TGS (AD Server)

At the AD server, we have to register a service user for our service "censhare Server", create a shared secret "Service key" (purple key) for secure communication, and create one or many users who should get access to the censhare Server using SSO. Therefore we need to open a remote desktop connection (RDP) to the Active-Directory Test Server (dc01.censhare.com).

Open RDP connection.
- Username: CENSHARE\Administrator
- Password: the well-known default password
Hint: you can add a drive from your local machine to the RDP. This makes the transfer of the Service Key (created in step 7) much easier. Therefore select in the login screen of the remote desktop connection: Options -> Local Resources -> Local devices: "More..." -> select a shared drive (e.g. C:)
Open Server Manager -> Active Directory Administrative Center
Select (1) censhare (local) > Users in the left pane and (2) Users > New > User in the right pane.

Before you create a new service user for your "censhare Server", please make sure you haven't already one registered within the AD. If you already have a service user, either delete it and continue with the following steps or reuse it if it fits your server IP or server hostname.
Create the service user for the "censhare Server". Enter at least the following values. Please use for <YOUR-SERVICE-NAME> a short name like "cs-sso-abc" wherby abc is your shorten name (e.g. "cs-sso-kkl" in my case) and replace <YOUR-SERVER-IP-OR-HOSTNAME> with the IP or Hostname of the machine your censhare-Server is running on.
- First name: <YOUR-SERVICE-NAME>
- Full name: <YOUR-SERVICE-NAME>
- User UPN login: host/<YOUR-SERVER-IP-OR-HOSTNAME>@ censhare.com
- User SamAccountName: censhare\<YOUR-SERVICE-NAME>
- Password: a password of your choice
- Account expires: Never
- Other password options: Select "Password never expires" and "User cannot change password".
Repeat Step 4 for one or many "real user(s)" who should authenticate themselves on the Windows machine running the censhare Client.
- First name: Your first name (e.g.: Kai)
- Last name: Your last name (e.g.: Klimke)
- Full name: Your full name (e.g.: Kai Klimke)
- User UPN logon: <shortend name>@ censhare.com (e.g. kkl@censhare.com)
- User SamAccountName: censhare\<shortend name> (e.g. censhare\kkl)
- Password: a password of your choice
- Account expires: Never
- Other password options: Select "Password never expires"
Now register your censhare Server machine as a service within the AD. Therefore open a terminal shell (cmd.exe) and execute the following command. Be sure you're using the exact same values you've used while you created the service user in step 4.
```
setspn -A host/<YOUR-SERVER-IP-OR-HOSTNAME> <YOUR-SERVICE-NAME>
      
```
Create Service Key (shared secret) and transfer generated "sharedSecret.keytab" to your machine running the censhare Server. Ensure you're using the exact values you've used while you created the service user in step 4.
```
ktpass -princ host/<YOUR-SERVER-IP-OR-HOSTNAME>@CENSHARE.COM -mapuser <YOUR-SERVICE-NAME>@CENSHARE.COM -pass * -out sharedSecret.keytab -pType KRB5_NT_PRINCIPAL
```

Important Note: If you change any kind of value of your service users (for the censhare Server) like the name or the password, the shared secret gets invalid. The safest way to prevent trouble is to delete the service user and to repeat steps (4), (6), and (7).

2.3 Setup Service (censhare Server)

The censhare Server has to be set up accordingly to be able to authenticate users registered within the TGS (AD Server). Therefore open your Mac machine and follow these steps:

Copy the sharedSecret.keytab from the AD (created in Step 7 of chapter 2.2) to a local directory of the censhare Server machine.

Create Kerberos configuration file "/etc/krb5.conf":

[logging]
  default = FILE:/var/log/krb5libs.log
  kdc = FILE:/var/log/krb5kdc.log
  admin_server = FILE:/var/log/kadmind.log

[libdefaults]
  default_realm = CENSHARE.COM
  dns_lookup_realm = false
  dns_lookup_kdc = false
  ticket_lifetime = 24h
  renew_lifetime = 7d
  forwardable = true

[realms]
  CENSHARE.COM = {
    kdc = dc01.censhare.com
    admin_server = dc01.censhare.com
  }

[domain_realm]
  .censhare.com = CENSHARE.COM
  censhare.com = CENSHARE.COM
Copy

XML

Checkout censhare-Server and censhare-Client from GIT. Compile both accordingly.

Open "<path-to-your-git-dir>/censhare-Server/app/config/jaas.conf" and modify it according the following values. Be sure you're using the exact same values you've used while you created the service user in section 2.2, Step 4.

RMIGSSHandler {
     com.sun.security.auth.module.Krb5LoginModule Required
     storeKey=true
     debug = false
     principal="host/
            
                <YOUR-SERVER-IP-OR-HOSTNAME>
            
        @CENSHARE.COM"
     useTicketCache=true
     debug=true
     doNotPrompt=true
     useKeyTab=true
     keyTab="/path/to/generated/sharedSecret.keytab"
     renewTGT=true;
 };

XML

Copy the modified configuration file "jaas.conf" to your censhare server customization directory (e.g. "<path-to-your-git-dir>/censhare-Custom/kkl/censhare-Server/app/config") and - if you've already had ran the server prior - copy it additionally into your runtime directory (e.g. "<path-to-your-git-dir>/censhare-Server/work/runtime.kkl/config/").
Start your censhare Server (censhare-Server/bin/StartServer.sh <serverId>) and wait until startup process has completed.
Open the censhare Admin-Client and connect to your censhare-Server.
Create one to may new users as they've been created in Section 2.2., Step 5. At least enter the following values
- Last name: Your last name (e.g.: Klimke)
- Login name: <shortend name>@CENSHARE.COM (e.g. kkl@CENSHARE.COM, as set as UPN name in the AD)
- Authentication: External, Data synchronization: Don't synchronize
- Default role: a role of your choice (e.g. Administrator)
Setup LDAP service: go to Configuration -> Services -> LDAP -> Configuration.
- Service enabled: Enable checkbox
- Default settings: simple
- java.naming.provider.url: ldap://dc01.censhare.com:389/
- java.naming.security.principal: censhare\Administrator (Note: DON'T DO THIS IN A PRODUCTIVE ENVIRONMENT! USE A READ-ONLY ACCESS INSTEAD!)
- java.naming.security.credentials: the well known default password

Setup LDAP synchronization: go to Configuration -> Modules -> LDAP -> Synchronize Party with LDAP Preferences

Select "Edit XML-File", search for the XML Element <search> and replace the value of the attribute dn with dn="cn=users,dc=censhare,dc=com".

Beside that search for the XML Element <principal> and move it just after the <search> element. Replace the value of the attribute name with value="@PRINCIPAL@".

<?xml version="1.0" ?>

  [...]
  
  <!-- LDAP query definition -->
  <search
    dn="cn=users,dc=censhare,dc=com"
    search-scope="subtree"
    time-limit="0"
    count-limit="0"
    deref-link="false"
    return-obj="false">
    <filter expr="(& (objectClass=person) (userPrincipalName={0}))">
      <arg value="@PRINCIPAL@"/>
    </filter>
  </search>

  <!-- delivered from logon -->
  <principal name="@PRINCIPAL@"/>

[...]
  
</cmd>

XML

Execute "Update Server Configuration"

2.4 Setup Client (Windows and censhare Client)

As the last step we have to setup the client machine accordingly to be able to join the SSO mechanism:

Connect to the Windows machine you want to run the censhare Client on.
Go to Control Panel\Network and Internet\Network Connections, double click on your network device.
Click "Properties", select "Internet Protocol Version 4 (TCP/IPv4)" and press "Properties".
Select "Use the following DNS server address" and add the value 192.168.211.29.
Go to Control Panel\System and Security\System and press change settings within the section Computer name, domain, and workgroup settings
Select Change... on the first Tab (Computer Name)
Select in section Member of: Domain and enter censhare.com. Press OK.
You'll be asked to enter a username and password. Enter censhare\<shortend name> and the password you have chosen in section 2.2, Step 5.
Afterward, restart the windows machine.
From now on you can use the user(s) you've created in section 2.2., Step 5, to sign on onto your Windows machine. Always use "censhare\<shortend name>" as username to login onto the censhare-domain.
Note: If you want to make any changes on your machine which require administrative access, you have to authenticate the request with the account "censhare\Administrator" and its corresponding password.
Add a new entry to the censhare-Server into your %homepath%\censhare\hosts.xml with authentication method "kerberos_win_sspi". Be sure to use the same value four <YOUR-SERVER-IP-OR-HOSTNAME> as you've selected in Section 2.2, Step 4.
```
 <host authentication-method="kerberos_win_sspi" name="my-sso" url="rmi://
          <YOUR-SERVER-IP-OR-HOSTNAME>
        /corpus.RMIServer" compressionlevel="1">   <censhare-vfs use="1"/> </host>
```
Copy the compiled censhare Client to the windows machine and start the application.

Now you should be able to connect to your configured server "my-sso" without typing in any credentials.

Possible pitfalls

There are various pitfalls on the way to a running SSO system. Here are some possible problems which might occur.

Error: Cannot locate KDC

Cause: Either the configuration file "/etc/krb5.conf" is missing or invalid. Create the file or correct its errors.

Error: The specified target is unknown or unreachable

Cause: The jaas.conf file is missing or wrong. Make sure the right jaas.conf file is loaded by the server (at least within your runtime directory "censhare-Server/work/runtime.<server-id>/config/").

Error: Access denied - ldap-sync-party-failed - NullPointerException

Cause: The ldap-search query to map the user is wrong. Admin Client : Go to Configuration -> Modules -> LDAP -> Synchronize Party with LDAP Preferences and make sure you've set the correct distinguished name (DN) to cn=users,dc=censhare,dc=com.

Error: Access denied - ldap-sync-party-failed - RollbackException

Cause (1): The ldap configuration for the XML element "principal" is wrong. Admin Client : Go to Configuration -> Modules -> LDAP -> Synchronize Party with LDAP Preferences and search for the XML Element <principal>. Move it just after the <search> element and replace the value for attribute name with "@PRINCIPAL@".

Cause (2): The mapping of the user to the censhare DB failed because the login name is misconfigured or the user isn't marked as "external". Go to the user preferences in the Admin-Client and check if the login-name is <shortened name>@CENSHARE.COM.

Error: NullPointerException at RMIServerServiceImpl.java

Cause: This might have several reasons. For a detailed solution, you'll need to have a look into the server logging. One possible error might be that the LDAP credentials are set up wrongly. Go to Configuration -> Services -> LDAP -> Configuration and correct the values. You can test the LDAP connectivity e.g. with the terminal tool "ldapsearch".

Error: Pre-authentication information was invalid

Cause: This is an indication that something has changed in the settings of the service user at the AD (e.g. the password). If you change any kind of value of your service users like the name or the password, the shared secret gets invalid. The safest way to prevent trouble is to delete the service user and to repeat steps (4), (6) and (7) explained in section 2.2.

There are several other pitfalls and solutions, listed in the following article: LDAP and Single-SingOn Troubleshooting