Configure Single sign-on with Kerberos - SysAdmin

The Kerberos protocol is an authentication method to authenticate users in a joint domain network. In Kerberos environments, the censhare Server, censhare Client, and censhare Web are configured as nodes that authenticate their identity to one another.

Context

The configuration is carried out in the censhare server, in the censhare Admin Client, and in censhare Web.

Prerequisites

• Kerberos SSO requires LDAP. You need the LDAP URL and the SSL certificate from the LDAP server (only for secure protocol connections). To retrieve information from the LDAP server, you need a read-only user for the directory server.

• To use the Kerberos authentication, you must set up a mapping of LDAP attributes to the corresponding censhare user attributes. To set up the mapping, you need the initial user data from the directory. You can use the

For more information, see this ldapsearch command (only UNIX-based OS), see this Jxplorer tool, or export the data from the LDAP server.

Introduction

censhare supports Single Sign-On (SSO) with the Kerberos protocol. Users can log in to the censhare Client and censhare Web with Kerberos SSO. Kerberos SSO connects to an LDAP or Microsoft Active Directory service as identity provider. For more information, see

For more information, see Configure LDAP authentication.

LDAP/AD integration via Kerberos

censhare is able to use the Kerberos protocol to authenticate users, to query user attributes from an LDAP directory, and to automatically create and manage user and group accounts on the censhare system. The Microsoft Active Directory (AD) implementation of LDAP is also supported.

When a user account is created, it remains in the regular master data of the censhare system. When the user logs in to censhare, the account is re-validated and synchronized from the LDAP directory.

Authentication sequence

When a user logs in to censhare Web or the censhare Client via SSL, the following procedure authenticates the user and starts a session:

When a user logs in to censhare, the credentials are passed to the Kerberos server. The Kerberos server authenticates the user at the LDAP server and grants an authentication ticket. If a valid authentication ticket exists, the user does not need to authenticate to log in.

Kerberos basics

Kerberos is supported by most OS, including OS X, Unix, Linux and Windows (2000 or later). Kerberos uses standard TCP and UDP ports for communication. Encryption is handled with

Kerberos is supported by most OS, including OS X, Unix, Linux, and Windows (2000 or later). Kerberos uses standard TCP and UDP ports for communication. Encryption is handled with standard encryption methods. For example, DES, 3DES, AES, or RC4. Checksum methods can also be used. For example, MD5, SHA-1, HMAC, or CRC32.

Realms

A Kerberos realm is equivalent to a domain. To use Kerberos, the involved clients or servers must enter the Kerberos realm of the authentication server.

Principals

In the Kerberos protocol, accounts are called principals. An account is assigned to a specific key (similar to an SSH key). User principals are noted in the following way:

@REALM

Server principals are noted in the following way:

host/@REALM

Service principals are noted in the following way:

service/@REALM

Configuration file

The Kerberos setup uses a configuration file. Under Unix, Linux and OS X, the usual file name and path is /etc/krb5.keytab. An example of the configuration looks as follows:

[libdefaults]
      default_realm = EXAMPLE.ORG
[realms]
      EXAMPLE.ORG = {
            kdc = kerberos.example.org
            admin_server = kerberos.example.org
      }
[domain_realm]
      .example.org = EXAMPLE.ORG

Authentication query

<search dn="dc=win2003,dc=coware,dc=de"
        search-scope="subtree"
        time-limit="0"
        count-limit="0"
        deref-link="false"
        return-obj="false">
   <filter expr="(& (objectClass=person) (userPrincipalName={0}))">
      <arg value="user@DOMAIN"/>
   </filter>
   <attributes-to-return>
      <attr name="displayName"/>
   </attributes-to-return>
</search>

Configure the LDAP service

1. In the censhare Admin Client, go to the Configuration/Services/LDAP directory, and open the Configuration.

2. In the General setup area, select the Service enabled field.

3. In the LDAP setting area, configure the properties for each LDAP service. You can configure multiple LDAP services. Each service can be referenced via its ID.

4. The two sample services can be adjusted to your requirements. To remove a service, click at the top left corner.

5. To add a new service, click   at the bottom left.

6. Enter an ID and an internal Setting name of the service.

7. Selec Use paging, if the LDAP server returns a large number of results in several pages. The default number of pages retrieved in one LDAP call is 100. For more information, see the Pages results control note from Oracle.

8. To add a new property, click at the bottom left inside the panel.

9. The following properties are required:

   • The java.naming.provider.url property with the URL of the LDAP server and the respective port. For example: ldap://myldap.example.com:3268. For more information, see LDAP standard ports.

   • The java.naming.security.principal property with the UID of the principal. For example, myReadUser@EXAMPLE.COM.

   • Thejava.naming.security.authenticationproperty with the valueGSSAPI.

   • For further properties that are required for a specific use case, contact our professional services.

10. In the JVM properties area, leave all properties settings as is.

11. Click OK to save the configuration.

12. If censhare connects to the LDAP server via SSL (ldaps://), you must add the certificate to the censhare truststore. For more information, see How to Manage the Truststore to Trust SSL Certificates.

13. Update the server configuration. If necessary, synchronize the remote servers.

Configure the internal server module

The Login by Kerberos/LDAPinternal server module is stored in the Configuration/Modules/Server Internal Modulesdirectory of the censhare Admin Client. In the standard configuration, the module inserts the configuration from the Synchronize Party with LDAP preferences module and does not require configuration.

Configure the Synchronize Party with LDAP preferences module

The Synchronize party module maps the LDAP/AD attributes to the censhare user attributes. To set up the mapping, do the following:

1. In the censhare Admin Client, go to the Configuration/Modules/LDAP directory and open the Synchronize Party with LDAP Preferences configuration.

2. In the dialog, click Edit XML file.

3. Add the search queries and filter parameters. censhare performs a 2-stage query. The retrieved values can be restricted to query-specified attributes from the LDAP server using attributes-to-return elements. For example:

   <search dn="dc=win2003,dc=coware,dc=de"
           search-scope="subtree"
           time-limit="0"
           count-limit="0"
           deref-link="false"
           return-obj="false">
      <filter expr="(& (objectClass=person) (userPrincipalName={0}))">
         <arg value="user@DOMAIN"/>
      </filter>
      <attributes-to-return>
         <attr name="displayName"/>
      </attributes-to-return>
   </search>

   • Edit the element: This element queries the user login (the principal) and user attributes.

   • Optionally, you can add additional elements. The first successful result is used.

   To reference a specific LDAP, add a setting-id="[ID]" attribute.

4. Edit the section with the user attribute mappings. The mapping defines all required and optional attributes to create or synchronize a censhare user. For more information, see User attribute mapping for LDAP & Kerberos SSO.

   • The element maps the LDAP principal name to the corresponding censhare party.

   • The element maps the LDAP user attributes to the corresponding censhare user attributes and sets the defaults.

5. Click OK to save your changes and close the XML editor.

   Click OK to save your configuration.

The result of the query is an XML snippet from the LDAP server. Here is an example:

<result>
   <binding name="CN=Peter Maier,CN=Users"
          dn="CN=Peter Maier,OU=Developer,DC=win2003,DC=coware,DC=de">
      <attr name="displayName" value="Peter Maier"/>
      <attr name="mail" value="pm@coware.de"/>
      <attr name="memberOf"
         value="CN=Admins,CN=Builtin,DC=win2003,DC=coware,DC=de"/>
   </binding>
</result>

Configure the censhare Server

The censhare Server must be registered in the Kerberos realm with a Service Principal Name (SPN). To register the server, proceed as follows:

1. Search for usable SPN's:

   {
    keytabfile=/etc/krb5.keytab
    for SPN
     in $(klist -k $keytabfile | grep '@' | awk '{ print $2 }' | sort | uniq)
     do kinit -V -k -t $keytabfile $SPN 2>/dev/null &&
         {
          echo "Found usable SPN: $SPN"
          kdestroy 2>/dev/null
         }
   done
   }

2. Create a custom jaas.conf file:

   [system-user]$ cp ~/censhare-Server/app/config/jaas.conf 
   

3. Open the custom jaas.conf file and enter the correct path and name of the principal and the keytab file:
   principal="host/censhare-server@EXAMPLE.COM"
keyTab="/etc/krb5.keytab"

4. In the censhare Admin Client, open the Configuration/Server directory and open the General configuration.

5. Search the property java.security.krb5.conf and enter the path to the keytab file.

6. Search the property java.security.auth.login.conf and check the correct path to the jaas.conf file that you created in step 2. The default path is @current.runtime.dir@config/jaas.conf.

Configure the censhare Client login

1. On macOS clients, the identical krb5.conf file as on the Linux server can be used.

2. On Windows clients, to grant access to the session key and the ticket cache, add the following registry entry:

   HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\ParametersValue 
   Name: AllowTgtSessionKeyValue 
   Type: REG_DWORD
   Value: 1  ( default is 0 )

   For more information, see the Microsoft support article 308339.

3. To define the LDAP service as default login method to the censhare Client, open the hosts configuration of the client computer under the path ~/Users/[USER]/Library/Preferences/censhare/hosts.xml.

   In the <host> entry of the desired server, set the attribute authentication-method="kerberos".

4. Users can select the Kerberos authentication method in the Files > Preferences > Servers dialog of the censhare Client.

Configure censhare Web login

The login method for censhare Web is configured in the System asset. You can select multiple login methods. Each login method can be used explicitly through a URL parameter. To force the login via Kerberos, use [censhare-base-url]/?auth=kerberos.

To use Kerberos SSO to login to censhare Web, do the following:

1. Log in to censhare Web with administrator credentials, and open the System asset.

2. Edit the System properties widget.

3. Go to the Authentication section, and in the Methods field, select Kerberos.

4. Click OK to close the dialog, and SAVE, to save your changes.

5. Restart the censhare server.

Result

When a user logs in to censhare Web or the censhare Client, the credentials from the LDAP are used. If the user is already logged in to a service within the Kerberos domain, the user is logged in to censhare automatically via SSL.