content/apacheds/kerberos-ug/4.2-authenticate-studio.mdtext

Title: 4.2 - Authenticate with Studio
NavPrev: 4.1-authenticate-kinit.html
NavPrevText: 4.1 - Authenticate with kinit on Linux
NavUp: 4-using-kerberos.html
NavUpText: 4 - Using Kerberos
NavNext: 5-interoperability.html
NavNextText: 5 - Interoperability
Notice: Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    .
    http://www.apache.org/licenses/LICENSE-2.0
    .
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

# 4.1 - Authenticate with Studio

We will explain how to use the kerberos server to authentify users on a LDAP server. Let's first define the way we will store data in the LDAP server

<DIV class="info" markdown="1">
We will suppose that the <strong>Kerberos</strong> server is installed on a server which <em>hostName</em> is <strong>example.net</strong> and the <em>realm</em> is <strong>EXAMPLE.COM</strong> in the following paragraphes.
</DIV>

## Servers configuration

We first have to configure the **LDAP** and **Kerberos** server, in order to be able to use the kerberos server to authenticate on the ldap server.

If you have installed the **ApacheDS** package, the simplest way is to start the server, and to connect on it using Studio, using the _uid=admin,ou=system_ user with _secret_ as a password (this password will have to be changed later !).

<DIV align="center">
  <img alt="Admin Connection" src="images/admin-connection.png">
</DIV>

and :

<DIV align="center">
  <img alt="Admin Authentication" src="images/admin-authentication.png">
</DIV>

Once connected, right click on the connection :

<DIV align="center">
  <img alt="Open Configuration" src="images/open-config.png">
</DIV>

On the **Overview** tab, check the **Enable Kerberos Server** box :

<DIV align="center">
  <img alt="Enable Kerberos Server" src="images/enable-kerberos.png">
</DIV>

### LDAP Server configuration

There are a few parameters that are to be set in the **LDAP** configuration :

    * The SASL host must be the local server name (here, example.net)
    * The SASL principal is ldap/example.net@EXAMPLE.COM
    * The Search Base DN should point to the place under which we store users and services (dc=security,dc=example,dc=com)

<DIV class="warning" markdown="1">
The <em>SASL principal</em> instance part (ie, <strong>example.net</strong>) is in lower case, as the hostname is not case sensitive. Sadly, the <em>KrbPrincipalName</em> attributeType is case sensitive, so if the left part is not lowercased, the server won't be able to retrieve the information from the LDAP server.
</DIV>

Here is a snapshot of this configuration :

<DIV align="center">
  <img alt="LDAP configuration" src="images/ldap-config.png" style="width: 100%; height: 100%">
</DIV>


### Kerberos Server configuration

Now, you can switch to the Kerberos tab, where some more configuration must be set :

    * The Primary KDC Realm is EXAMPLE.COM
    * The Search Base DN is the same as for the LDAP server : dc=security,dc=example,dc=com

Here is a Ssnapshot of this configuration :

<DIV align="center">
  <img alt="Kerberos configuration" src="images/kerberos-config.png" style="width: 100%; height: 100%">
</DIV>

The Kerberos server also requires a minimal **krb5.conf** file. The default location of that file is **/etc/krb5.conf**, alternatively you can also put it to **JAVA_HOME/jre/lib/security/krb5.conf**.

    :::text
    [libdefaults]
        default_realm = EXAMPLE.COM

    [realms]
        EXAMPLE.COM = {
            kdc = example.net:60088
        }


Once those modifications have been done, you must restart the server.

### Other configuration

There is one more thing that you need to configure : your domain name (here, example.net_) has to be reachable on your machine. Either you define in on a **DNS** server, or you can also add it in your _/etc/hosts_ file.

Here is a way to add it on a local host :

    :::
    ...
    127.0.0.1 localhost example.net
    ...

<DIV class="warning" markdown="1">
It's largely preferable to declare the server in a DNS.
</DIV>

## LDAP Hierarchy

We will distinguish between **users** and **services** :
* Users are human beings, or applications that can log on a service
* Services are applications on which a user can log in

In our case, the ldap server and the **TGS** are services.

Each user and each service will be declared using an _entry_ in the ldap server.

We will store those entries in a part of the **DIT** where the kerberos server and the ldap server will be able to find them. Assuming we have created our own partition named **dc=example,dc=com**, we will define this hierarchy starting from there :

<DIV align="center">
  <img alt="Authentification hierarchy" src="images/authent-hierarchy.png">
</DIV>

This can be injected in the LDAP server using this LDIF :

    :::text
    dn: dc=security,dc=example,dc=com
    objectClass: top
    objectClass: domain
    dc: security

    dn: ou=services,dc=security,dc=example,dc=com
    objectClass: top
    objectClass: organizationalUnit
    ou: services

    dn: ou=users,dc=security,dc=example,dc=com
    objectClass: top
    objectClass: organizationalUnit
    ou: users

## Users and Service declaration

Now that we have built our container for users and services, we have to declare the users and services so that they can be used through **kerberos**.

### Users

Each user must have the **krb5KDCEntry** objectclass, and the **userPassword** attributeType (which is present in one of the following objectclasses : _dmd_, _domain_, _organization_, _organizationalUnit_, _person_, _posixAccount_, _posixGroup_ and _shadowAccount_, or one of their inheriting objectclass. You can also add it to your own objectclass).

Our users will be _organizationalPerson_, which inherits from _person_.

For our sample test, here is a person we will inject in the LDAP server :

    :::text
    dn: uid=hnelson,ou=users,dc=security,dc=example,dc=com
    objectClass: top
    objectClass: krb5KDCEntry
    objectClass: inetOrgPerson
    objectClass: krb5Principal
    objectClass: person
    objectClass: organizationalPerson
    cn: Horatio Nelson
    krb5KeyVersionNumber: 1
    krb5PrincipalName: hnelson@EXAMPLE.COM
    sn: Nelson
    uid: hnelson
    userPassword: secret

This user does not have a password yet.

<DIV class="info" markdown="1">
The import thing is the <em>krb5PrincipalName</em>, which is the one that will be used to bind the user. It has a user login (<strong>hnelson</strong>) and a realm (<strong>EXAMPLE.COM</strong>).
</DIV>

Once the user has been injected, we can see that the server has created some krb5Key attributes :

    :::text
    dn: uid=hnelson,ou=users,dc=security,dc=example,dc=com
    objectClass: top
    objectClass: krb5KDCEntry
    objectClass: inetOrgPerson
    objectClass: krb5Principal
    objectClass: person
    objectClass: organizationalPerson
    cn: Horatio Nelson
    krb5KeyVersionNumber: 0
    krb5PrincipalName: hnelson@EXAMPLE.COM
    sn: Nelson
    krb5Key:: MBGgAwIBA6EKBAj0pxNkimHOWw==
    krb5Key:: MBmgAwIBEaESBBCtIUs4tp38yqzxXzRtQXuQ
    krb5Key:: MCGgAwIBEKEaBBhXB84pUpIsHIy/Q8I9j4xenoz3XT5KXiU=
    krb5Key:: MBmgAwIBF6ESBBCHjYAUYGzaKWd6RO+hNT/H
    uid: hnelson
    userPassword:: e1NTSEF9VnhjYUl4U3JxUnAraWh1dXo2NEhzN1EwbXE0ZHBBQTNsUHJXMGc9P
     Q== 

Those keys have been computed automatically by the Kerberos server. Every time you will change the password, the keys will be updated.

We can add as many users as we want, but keep in mind that the login name should be the first part of the **krb5PrincipalName** attributeType.

### Services

We now have to declare some services : the **krbtgt** service, which delivers tickets, and the **ldap** service.

A user (or a service) which will try to authenticate on the LDAP server will first get a ticket from the **krbtgt** service, then will access the **ldap** service with the provided ticket.

#### krbtgt service

It's pretty much the same operation than for the user : create the entry, define a _krb5PrincipalName_, create a _userPassword_ and inject the entry into the LDAP server. 

Here is the associated LDIF file :

    :::text
    dn: uid=ldap,ou=services,dc=security,dc=example,dc=com
    objectClass: top
    objectClass: organizationalUnit
    objectClass: krb5KDCEntry
    objectClass: uidObject
    objectClass: krb5Principal
    krb5KeyVersionNumber: 0
    krb5PrincipalName: ldap/example.net@EXAMPLE.COM
    uid: ldap
    userPassword: randomKey
    ou: TGT

    dn: uid=krbtgt,ou=services,dc=security,dc=example,dc=com
    objectClass: top
    objectClass: organizationalUnit
    objectClass: krb5KDCEntry
    objectClass: uidObject
    objectClass: krb5Principal
    krb5KeyVersionNumber: 0
    krb5PrincipalName: krbtgt/EXAMPLE.COM@EXAMPLE.COM
    uid: krbtgt
    userPassword:: randomkey
    ou: LDAP

<DIV class="info" markdown="1">
Three important things :
<ul>
<li>- the userPassword is 'randomkey'. The key will not be generated based on a know password, they will use a random key.</li>
<li>- the <em>krb5PrincipalName</em> has one more information, after the / character : <em>EXAMPLE.COM</em> for 
    the <strong>krbtgt</strong> service, and <em>example.net</em> for the <strong>ldap</strong> service. For the <strong>krbtgt</strong> principal, the instance is always the realm name. For the <strong>ldap</strong> principal, the instance is the hostname, in lowercase.</li>
<li>- the krb5KeyVersionNumber is 0</li>
</ul>
</DIV>

Again, once those entries have been injected in the LDAP server, the _krb5Key_ attributeTypes will be created

## Login using Studio

Now that the server is set, and the services and users are stored into it, we can create a new connection using the Kerberos authentication for the created users.

### Create a new connection

On the "Connections" tab, right click and select 'New Connection...'

<DIV align="center">
  <img alt="New Connection" src="images/new-connection.png">
</DIV>

You will now have to set the network parameters, as in the following popup. Typically, set :

    * The connection name (here, Kerberos User)
    * The LDAP server host (example.net)
    * The LDAP server port (10389)
    * The Provider (pick Apache Directory LDAP Client API)

You can check the connection on cliking the 'check network connection' button, you should get back a popup stating that the connection was established successfully.

Here is the screenshot :


<DIV align="center">
  <img alt="Network Parameters" src="images/network-parameters.png">
</DIV>

Then click on Next to setup the authentication part.
Select the following parameters and values :

    * Authentication method : GSSAPI
    * Bind DN : the user name (here, hnelson)
    * Bind password : here, secret
    * Do not change anything in the SASL settings
    * Kerberos settings 
        * Obtain TGT from KDC
        * Use following configuration :
            * Kerberos Realm : EXAMPLE.COM
            * KDC Host : example.net
            * KDC port : 60088

Here is the resulting screen :

<DIV align="center">
  <img alt="Kerberos authentification" src="images/kerberos-authent.png">
</DIV>

Clinking in the 'Check Authentication' button should be succesfull.