IceWarp Server - SSO (Single Sign-On)

IceWarp Server - SSO (Single Sign-On) Probably the most difficult task for me is to explain the new SSO feature of IceWarp Server. The reason for this is that I have only little knowledge about it and the documentation we have available is not in english :). Anyhow, I will do my best and discuss with the developers if something is unclear. Soon a more complete document will follow. Let me start with the term SSO (Single Sign-On). In layman's terms the mechanism is easy. You authenticate with your user credentials (username and password) only once and from that point forward all applications supporting SSO will log you in automatically without any additional login. It is all automatic. A typical example is that you login to Windows (enter your user and pass) and after that you start Outlook, WebClient, Notifier and others and never ever have to enter additional user details nor supply your password. Sounds like a dream, huh? Getting it to work is quite complicated, though. You need to have some knowledge about Active Directory and Kerberos authentication. The process above seems simple but the security behind is top notch. There are other SSO proprietary solutions that do not integrate but our solution just builds on the technology and protocols that have been already developed. Let s look at the standard Kerberos, which has been used for a long time in recent versions of Windows and is the primary protocol for authentication. This protocol is very safe and its nature supports single sign-on. So SSO is what interests us. Kerberos is generally used (not only on Windows), but the description will be based on the implementation of the MS domain environment. Single Sign-On (SSO) is a method that allows us to use a single login to multiple applications (if tested at the same source, there is no need to go back to the same login). In Windows, it usually means that when you log into your computer and authenticate against your Active Directory (domain). When another authentication is required for another system that uses a domain account (or accounts used for mapping their domain), apps use the data that we already have in the system for authentication and log into these other applications (without having to enter anything). In Windows Integrated Windows Authentication (IWA) is used, which uses the SPNEGO, Kerberos, and NTLMSSP. Kerberos is a secure protocol that uses the method of Keys (tickets) and that we will talk about. Kerberos and Single Sign-On - how it works Kerberos is a network authentication protocol that uses strong cryptography for secure authentication between client and server over an insecure network. It works on the principle that the client does not validate against the server where you want to get some service, but the mediator to the KDC. The central element of authentication increases security and can provide

services to more applications. Brief description of the Kerberos protocol in Windows: User Authentication o the first login the user enters their login information (we will assume the name and password) the client sends a request to the Key Distribution Center (KDC) Obtaining Ticket-Granting Ticket o the AS verifies that the user exists and that he sends a unique key and ticketgranting ticket (TGT) o the TGT also serves to identify a user, includes the client's name, address, expiration date, o o the client cannot decrypt the TGT (it can only KDC) TGT has a limited lifetime (default 10 hours), but it can automatically reauthenticate, each login creates a new TGT obtain Service Ticket o when we want to subscribe to any service on the network, applications on the client uses the TGT to the KDC and requests a service ticket o the client sends a request for a service ticket to the KDC (the request contains the TGT) o o Decrypts the KDC client If the data is correct, the TGS sends back a reply that contains part of the client and server Verification of service (server) o the service ticket is then used to authenticate client to server o the service sends a ticket (on the server where you want to log in using the SSO) o server decrypts the service ticket and obtains reliable data about the client, if everything is fine the encrypted confirmation sent o Confirmation includes a time stamp from the client + 1 establish a session o the client decrypts a confirmation and compares the timestamp, if everything is ok we have a successful authentication

Simplified description of the SSO to Web applications Let s try to explain the whole process from a practical and simplified view. Log on to Windows (will check to AD and get TGT), now using a Web browser login to same page that supports SSO. The browser obtains (using the OS) from the AD (using their data and SPN service - type and address) service ticket (which contains user information), it is encrypted using the keys (the client does not alter it in any way). The clients sends it to the application, which knows who is the certified user and sets it up as logged in. The Key to encrypt the service ticket service knows only AD, so you cannot fake or intervene. This means that the authentication server does not have to communicate with AD, it is enough that it owns the key for decryption. Only the client that wants to authenticate to the server communicates with AD. It gets the encrypted data that the server decrypts and by this the server confirms the authenticity of the information contained. All safety lies in the encryption, a key is always used to decrypt the data by the good side and for authentication temporary tickets are used. A complete description can be found in this article. It is in Czech though but by far it has the best content out-there: http://www.samuraj-cz.com/clanek/kerberos-protokol-a-single-sign-on/

Browser setup All major browsers support SSO but they need to be configured to use it. In Internet Explorer you need to have the Integrated Windows Authentication turned on (on by default). You also need to add the trusted domain to Local Intranet (Sites - Advanced) in the Security section. In Mozilla Firefox Integrated Windows Authentication has been supported for some quite time now too. It is also on by default but you need to add the trusted domains. In the URL type: about:config There are 2 types of authentication (GSSAPI on Linux) and SSPI on Windows. Use the one that you need: The options in the console are: Kerberos: network.negotiate-auth.trusted-uris NTLM: network.automatic-ntlm-auth.trusted-uris Specify the URLs/domains just like in Explorer http://www.samuraj-cz.com/clanek/kerberos-sso-nastaveni-internet-exploreru-a-firefoxu/

Creating an account for Apache service in AD In Kerberos principle we know that every service to which you want to log on must have a record (account) in Active Directory. Each application server needs a secret key that can decrypt the communication which will be coming. Since our application server is Linux based we cannot normally include it in the domain but we have to manually create an account and export your encryption key. Furthermore, the described procedure can be used on Windows Sever 2000, 2003, 2008 and 2008 R2. The only difference might be some details, such as supported encryption algorithms. These examples have been tested on Windows Server 2008 R2. The used command Ktpass is available in the Windows 2000 Resource Kit, Windows 2003 Support Tools and on Server 2008 it is a part of the tools that are installed on a domain controller. You always must use a version appropriate for the level of domain. Create a record in DNS We always must have a DNS record for the server / service (web server address, e.g. mujweb.domena.local). Create a user account in AD We need to include our server to a domain, so we will create a computer account. In fact, we are concerned only about the service account that cannot be created separately but we can bind it to a user account. So we create a user account for our server / service. For example, using the Active Directory Users and Computers, create a new user account in AD This account must be placed in the default Users container We choose the same name (not required), as the server name (e.g. mujweb) Of course, no such account may already exist and we must not set the Require Password Changes Setting SPNs and export the keytab file Service Principal Name (SPN) is the service name, as the client will call it (Web browser) when we want to perform Kerberos authentication to the site. SPN is linked to the account (user, computer, group). We can create it by using setspn, but we will use the right ktpass that will ensue the creation of a keytab file. For a web application SPN syntax is HTTP/<hostname> (ig HTTP/mujweb.domena.local), where hostname must match the DNS server address. This is true even if you use HTTPS (it is still HTTP/hostname). This SPN

binds with our user created (mujweb@domena.local). Note: Hostname in SPN must match the DNS A record and not an alias (CNAME). For example, when we have a server web.domena.local with the same name in DNS and you can be an alias www.domena.local, so we have put into SPI web.domena.local, even when users access using an alias. Using ktpass we perform the SPN mapping while exporting the Kerberos keytab file. Syntax and example for our situation: ktpass out <filename> -princ HTTP/<hostname>@<AD DNS DOMAIN NAME AD CAPITAL LETTERS> -mapuser <user name>@<domain name> -mapop set -pass * -ptype KRB5_NT_PRINCIPAL Eg. ktpass out mujweb.keytab -prince HTTP/mujweb.domena.local@DOMENA.LOCAL -mapuser mujweb@domena.local -mapop set -pass * -ptype KRB5_NT_PRINCIPAL The output keytab file (mujweb.keytab) contains SPN and a secret key of the service. Principal Name (parameter princ) consists of the SPN and destination domain against which we authenticate the user (must be entered in capital letters). MapOp determines that the SPN is set to the account (not added a new one). If we want to save the keytab file we have to enter a password. This password is set on a user account (change the original password). When you enter an asterisk the we will be prompted for password. At a time we create a keytab file, the user account must be in the Users container, otherwise you will get an error message below. After you create the keytab we can move the user to any organizational unit. Password set failed! 0x00000020 Aborted. It is important to ensure the safety of the keytab file because it contains information to log on to AD on behalf of the service. Any information can be found in MS articles about Service Principal Names and tools Ktpass. http://www.samuraj-cz.com/clanek/kerberos-sso-v-php-aplikaci-s-apachem-na-linuxu/ So this was the general Kerberos, AD and SSO concept in a few sentences :). Now let me talk about the support in IceWarp Server.

IceWarp Server integration SSO has been fully integrated, implemented and tested. You have to admit that to understand all of the above it took us some time and the implementation took us even longer. Setting up the testing environment was not an easy task. We do have the knowledge now :) In our implementation we had to take in consideration also developers. Not only did we make it possible to use the API SSO (AuthenticateUserSSO()) functions (PHP, COM etc.) but it is also able to use SSO in the Web Service - Security section. What does this mean? Well, developers can use the SSO to check and grant permission to their applications with a just a few lines of code. Webmasters have a choice to not to code the SSO at all and rather setup the web virtual host security and let the authentication and SSO proceed through the web service SSO authentication features. Simply, use the API or let the web service take care of that. In a matter of few seconds you can protect your server web applications by SSO and never request user credentials anymore. We also added a low level API function icewarp_kerberos_authenticate_user() for faster use. Setting up SSO Let s assume we already have a configured AD domain, AD service account and the keytab file. Upload the keytab file to the server and place it to a secure folder so our server has an access to it. We have multiple ways to use SSO. Non-integrated SSO - WebService The non-integrated way means there is system accounts AD integration. No Directory Service AD integration and we do not really care how system users authenticate to the system. We just want to use SSO for independent applications regardless of our system users. For this we only require the SSO service name and the keytab file. Check the SSO authentication and setup the independent SSO settings.

Non-integrated SSO - PHP We use the IceWarp PHP SSO low level function as below. We pass in the token from the browser, domain and keytab file. As a result we get the result associate array which contains error status, negotiate data for the client and more. if($_server['http_authorization']) list($mech,$token)=explode(" ",$_SERVER['HTTP_AUTHORIZATION']); if($mech=="negotiate") $res=icewarp_kerberos_authenticate_user('http/linux.mytestdomain. cz@mytestdomain.cz','c:\temp\linux.keytab',$token); if($res['result']) header('www-authenticate: Negotiate '.$res['negotiate']); header("http/1.1 200 OK"); echo "Kerberosd login OK ".$res['email']; else echo "Kerberos login KO token=$token";

exit; else header("www-authenticate: Negotiate"); header("http/1.1 401 Authorization Required");?> <html> <form> </form> </html> <??> Integrated SSO - Accounts This is the method we will use for WebClient and other clients that need to authenticate to our system accounts. It requires additional domain directory services settings. Assume we already have a properly working AD domain setup. All we need is the SSO now. Just enable SSO, fill in the SSO service name and the keytab file. From now on SSO has been properly configured for your domain.

Integrated SSO - API Analogically as in Non integrated SSO - PHP way we use the IceWarp API function which matches the SSO verification against system accounts. It returns the token if successful. <?php define(sharedlib_path,get_cfg_var('icewarp_sharedlib_path')); include_once SHAREDLIB_PATH.'api/account.php'; include_once SHAREDLIB_PATH.'api/api.php'; if($_server['http_authorization']) list($mech,$token)=explode(" ",$_SERVER['HTTP_AUTHORIZATION']); if($mech=="negotiate") $com= new IceWarpAccount(); $otoken=$com->authenticateusersso($token,$_server['http_host']);

if($otoken) header('www-authenticate: Negotiate '.$otoken); header("http/1.1 200 OK"); echo "Kerberosd login OK ".$com->emailaddress."<br>$otoken"; else echo "Kerberos login KO token=$token"; exit; else header("www-authenticate: Negotiate"); header("http/1.1 401 Authorization Required");?> <html> <form> heslo: <input type="text"> </form> </html> <??> Integrated SSO - WebService No reason to explain more. You authenticate to system accounts. Just check the SSO auth and system accounts.

Kerberos debugging There are kerberos logs in our server that you can enable using the API console. Just search for kerberos. The logs will tell you why authentication failed. Additionally, if there is no response from the client you can use WireShark which can perfectly decode Kerberos protocol. The data exchanged between clients and servers: Client (web browser) requests a page (GET request). The web server responds with HTTP header containing (HTTP/1.1 401 Authorization Required, WWW-Authenticate: Negotiate).That is if the SSO has been enabled for the domain of course If the client supports kerberos it sends the authentication details in the header (service ticket and Authorization: Negotiate encoded stuff). If it does not support Kerberos it justs displays an authentication dialog If everything is ok the server responds with confirmation (HTTP/1.1 302 Found, WWW- Authenticate: Negotiate encoded data from server).

Additional information As you might have noticed there was not a single word about WebClient. It does not support SSO authentication yet. It will be added soon. Additionally, you might be aware of GSSAPI authentication. It is a SASL authentication mechanism supporting Kerberos. This means that any client supporting GSSAPI SASL on SMTP, POP3, IMAP and others can authenticate to Kerberos and use the SSO concept. Our server does not support GSSAPI yet but it is on the list and will be supported soon. Logically, Notifier SSO and the Desktop Client SSO will follow. We realize that in the enterprise environment such features are required and can be considered as a must-have. I hope I explained everything, at least as much as I could. I could have told tell you less but you needed to grasp the concept.