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 setup a mapping of LDAP attributes to the corresponding censhare user attributes. To setup 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), the
For more information, 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 this article [LINK:4837945]

.

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

For more information, see this standard encryption methods

. For example, DES, 3DES, AES, or RC4.

For more information, see this 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

Key steps

For more information, see the anchor [LINK:configure_ldap_service]
For more information, see the anchor [LINK:server_module]
For more information, see the anchor [LINK:configure_sync_party]
Configure the censhare Client login
Configure the censhare Web login
For more information, see the anchor [LINK:configure_cs_server]
For more information, see the anchor [LINK:configure_login]

Configure the LDAP service

To enable and configure the LDAP service, do the following:

In the censhare Admin Client, go to the Configuration/Services/LDAP directory, and open the Configuration.
In the General setup area, select the Service enabled field.
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.
The two sample services can be adjusted to you requirements. To remove a service, click icon at the top left corner.
To add a new service, click icon at the bottom left.
Enter an ID and an internal Setting name for the service.
Select the Use paging field, 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
For more information, see this Pages results control note from Oracle
.
To add a new property, click icon at the bottom left inside the panel.
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
  For more information, see the anchor [LINK:ldap_ports]
  .
- The java.naming.security.principal property with the UID of the principal. For example: myReadUser@EXAMPLE.COM.
- The java.naming.security.authentication property with the value
  For more information, see the anchor [LINK:censhare_client]
  .
- For further properties that are required for a specific use case, contact our professional services.
In the JVM properties area, leave all properties settings as is.
Click OK to save the configuration.
If censhare connects to the LDAP server via SSL (ldaps://), you must add the certificate to the censhare truststore. For more information, see
For more information see this article [LINK:2521107]
.
Update the server configuration. If necessary, synchronize the remote servers.

Configure the internal server module

The Login by Kerberos/LDAP internal server module is stored in the Configuration/Modules/Server Internal Modules directory of the censhare Admin Client. In the standard configuration, the module inserts the configuration from the

For more information, see the anchor [LINK:configure_sync_party]

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 setup the mapping, do the following:

In the censhare Admin Client, go to the Configuration/Modules/LDAP directory and open the Synchronize Party with LDAP Preferences configuration.
In the dialog, click Edit XML file.
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:
```
                               
```
- 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.
Note: To reference a specific LDAP (see
For more information, see the anchor [LINK:configure_ldap_service]
), add a setting-id="[ID]" attribute.
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
For more information see this article [LINK:4846241]
.
- 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.
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:

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 keytab file manually. For more information, see

For more information see this article [LINK:2633011]

.

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

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 }

Create a custom jaas.conf file:

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

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"
```
In the censhare Admin Client, open the Configuration/Server directory and open the General configuration.
Search the property java.security.krb5.conf and enter the path to the keytab file.
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

For more information, see this 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.

On macOS clients, the identical krb5.conf file as on the Linux server can be used.
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
For more information, see this Microsoft support article 308339
.
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 entry of the desired server, set the attribute authentication-method="kerberos".
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:

Log in to censhare Web with administrator credentials, and open the System asset.
Edit the System properties widget.
Go to the Authentication section, and in the Methods field, select Kerberos.
Click OK to close the dialog, and SAVE, to save your changes.
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, th user is logged in to censhare automatically via SSL.

Page tree