Kerberos Security

Kerberos is an authentication protocol which can be used to secure communications in web services. Kerberos enables us to exchange user credentials securely. Thus it also provides mutual authentication in which server can also authenticate it self to the client.

Kerberos protocol uses a trusted third party called “Key Distribution Center” (KDC). KDC consists 2 logical parts. They are,

1. Authentication Server
2. Ticket Granting Server

Actual user credentials are stored within the "Authentication Server". Communicating parties will retrieve a Kerberos ticket from "Ticket Granting Server". TGS validates ticket requesting users credentials with "Authentication Server".

Kerberos Security within "WSO2 Identity Server"

"WSO2 Identity Server" uses ApacheDS based LDAP server user store. It also has an ApacheDS based on KDC implementation. Users can use "WSO2 Identity Server" as a KDC and implement Kerberos security to secure communications between services and clients.

Enable KDC within "WSO2 Identity Server"

To use KDC in "Identity Server" you need to use embedded LDAP which ships with "WSO2 Identity Server". Thus, by default KDC server is disabled. To enable KDC server you need to enable KDS server in two places. First locate the configuration section "UserStoreManager" in repository/conf/user-mgt.xml and set the property "kdcEnabled" to true. Then go to "Identity Server" home directory and navigate to repository/conf folder. There you will find a file called embedded-ldap.xml. Open embedded-ldap.xml and find <KDCServer/> XML tag. You will configuration XML element called "enabled". Set its value to "true". After modifying, the XML configuration should looks like follows,

<!-- 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. Thus the services are associated with a service name. In Kerberos context we call this service name as “Service Principal Name” (SPN). Before we assign a SPN to a service we need to define “Service Principal Name” in KDC.

Users can use this screen to do operations on service principals.

List Service Principals

List Service Principals

Figure 1:List Service Principals

You can list all service principals by selecting Configure -> Kerberos KDC -> Service Principals in left hand menu.

  • 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 you can carry on a selected service principal.
    • You may delete existing service principal or you can change password associated with a service principal.

    Add Service Principal

    Add Service Principal

    Figure 2:Add Service Principal

    Figure 2, describes how you can add a service principal.

  • Service Principal Name – Name of the service principal. This usually takes following format;
    • <Service Name>/<Host where service is running>. This field is mandatory. E.g :- EchoService/127.0.0.1
  • Password – This is the password given service principal. You would use this password in appropriate service's rampart configuration. Thus appropriate service will provide password given in rampart configuration to KDC, when it needs to authenticate it self 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.
  • Description – Brief description about the service principal. This field is not mandatory.

    • Change Password of a Service Principal

    Change Password of a Service Principal

    Figure 3:Change Password of a Service Principal

    To change password of a service principal; chose service principal and click Change Password hyperlink in "Actions" column. (See Figure 3) Then you will see a screen as depicted in Figure 4. To change password, enter existing password and the new password.

    Change Password of a Service Principal

    Figure 4:Change Password of a Service Principal

    Delete Service Principal

    Delete Service Principal

    Figure 5:Delete Service Principal

    Figure 5, describes how you can delete a service principal. In the "Actions" column select Delete hyperlink to delete a particular service principal.