Skip to main content
Skip table of contents

Configure Single sign-on with Kerberos

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 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

CODE 
<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 value GSSAPI.

    • 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

Important: If you are not familiar with the censhare domain framework and user configuration, contact censhare solution development for the proper configuration of the internal server 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:

    CODE 
    <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:

CODE 
<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

Important: Before you start with this configuration, verify the following:

(1)The LDAP service is configured correctly.

(2)The server that hosts the censhare Server must be added to the Active Directory (AD) domain. If it is not possible to add the Linux server to the AD domain, you must create the service principal name and key tab file manually. For more information, see How to create a manual SPN for Kerberos SSO.

(3)A service user exists in the LDAP server.

(4)The keytab file is mapped to the service user.

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:

    CODE 
    {
 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

Important: censhare uses GSSAPI for single sign-on. Windows clients must allow access to the TGT Session cache. If you are not sure if this is possible, contact your information security.


  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:

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

  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 has logged in to censhare automatically via SSL.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close