Service Principal Management

Kerberos is an authentication protocol used to secure communication and enable secure user credential exchange in Web services. It also provides mutual authentication where a server can authenticate itself to the client. Kerberos protocol uses a trusted third-party called 'Key Distribution Center' (KDC), which consists two logical parts as follows.

Authentication Server
Ticket Granting Server

Actual user credentials are stored in the 'authentication server' and the communicating parties retrieve Kerberos tickets from the 'ticket granting server', which validates ticket-requesting user credentials with the authentication server.

The Kerberos Security feature uses ApacheDS based LDAP server user store. It also has an ApacheDS based on KDC implementation. Users can use a running Carbon instance with this feature installed as a KDC and implement Kerberos security to secure communications between services and clients.

Enabling key distribution center

Embedded LDAP shipped by default with WSO2 Carbon-based products can be used for KDC, which is disabled by default. KDC can be enabled by changing configurations in two places as follows.

1. Locate the configuration section "UserStoreManager" in $CARBON_HOME/repository/conf/user-mgt.xml and set the property "kdcEnabled" to true.

<Property name="kdcEnabled">true</Property>

2. Locate the <KDCServer/> XML tag in $CARBON_HOME/repository/conf/embedded-ldap.xml and set "enabled" to "true".

<!-- KDC configurations -->
<KDCServer>
   <Property name="name">defaultKDC</Property>
   <Property name="enabled">true</Property>
   <Property name="protocol">UDP</Property>
   <Property name="host">localhost</Property>
   <Property name="port">8000</Property>
   <Property name="maximumTicketLifeTime">8640000</Property>
   <Property name="maximumRenewableLifeTime">604800000</Property>
   <Property name="preAuthenticationTimeStampEnabled">true</Property>
</KDCServer>

Service principals

The KDC Server issues tickets to access a particular service. Therefore, the services are associated with a service name. In Kerberos context, the service name is called as Service Principal Name (SPN). Before assigning a SPN to a service, define Service Principal Name in KDC. Follow the instructions below to add a new service principle.

1. Log on to the product's Management Console and select "Configure -> Kerberos KDC -> Service Principals."

2. The "Service Principal Management" page appears. Click on the "Add New Service Principal" link to begin.

Service Principal Name : Name of the service principal. This usually takes following format; <Service Name>/<Host where service is running>. E.g :- hello/localhost
Description : Brief description about the service principal. This field is not mandatory.
Actions : This column lists the actions available for a service principal. Click the respective links associated with a service principle to either delete it or change its password.

3. In the "Add Service Principal" window that appears, enter the required details and click "Finish" to complete.

Service Name : Name of the service principal. This usually takes the format: <Service Name>/<Host where service is running>. For example, EchoService/127.0.0.1. This field is mandatory.
Description : Brief explanation about the service principal. This field is optional.
Password : This is the password given to the service principal. This password can be used in appropriate service's rampart configuration. Therefore, appropriate services will provide password given in rampart configuration to KDC, when it needs to authenticate itself to KDC. This field is mandatory.
Re-Type Password : Re-type password provided in 'Password' section to make sure given password is accurate. This field is mandatory.

4. The newly-added service principle will be displayed in the 'Service Principle Management' window. You can change its password or delete it by clicking the respective links associated with each principle.