Kerberos Mediator

When a consumer client attempts to invoke a RESTful back-end service that is secured with Kerberos authentication, the client's credentials should be authenticated before passing the client's request to the back-end service. When you have an ESB profile of WSO2 EI to mediate messages between the consumer client and the back-end service, the Kerberos mediator can be used to facilitate the authentication.

Example use case

The following diagram depicts this process:

The steps in the above process are as follows:

Register the client's username (Client Principal Name) and Password (Keytag file) in the KDC.
The client sends a request to the back-end service by invoking the ESB.
The Kerberos mediator in the ESB's receiving endpoint passes the client's username along with the back-end service's Service Principal Name to the KDC.
The KDC authenticates the client's credentials for the back-end service and returns a service token to the Kerberos mediator.
The Kerberos mediator then sets the service token as the authorization header in the client message and passes the message to the back-end service.

Using the Kerberos mediator

To carry out the above use case, the ESB will have a meditation sequence defined using a Proxy Service, a REST API, or an Inbound endpoint. The sequence will contain a Property mediator to filter the client user that is invoking the service, and the Kerberos mediator to authenticate the client's credentials. Shown below is the syntax of the Kerberos mediator.

<kerberosService krb5Config="<Path_To_ConfigFile>/krb5.conf"     
                           spn="<SPN_Of_Back-end_Service>"
                           clientPrincipal="{$ctx:username}"
                           keytabPath="<Path_To_clients.keytab>"
                           loginConfig= "<Path_To_login.conf>"
                           loginContextName="KrbLogin" />

The property values that are applied to the Kerberos mediator are explained below.

Parameter	Description
krb5Config	Specifies the file path to the `krb5.conf` file (Kerberos configuration file), which is `<EI_HOME>/repository/resources/security/`. Be sure to create this file and place it in this directory. A sample file is given below. [libdefaults] default_realm = WSO2.TEST [realms] WSO2.TEST = { kdc = 192.1xx.xx.158:88 } [domain_realm] .wso2.test = WSO2.TEST wso2.test = WSO2.TEST
`spn`	The service principal name (spn) of the back-end service.
`clientPrincipal`	This represents the client principal name that is generated for the consumer client. In the above example, this value is fetched from the Property mediator.
`keytabPath`	This is the file path to the key tab file generated for the consumer client. The password of the client is stored in this file.
loginConfig	By default, the ESB is configured to log into the KDC using minimal configurations. However, if you want to specify additional configurations for creating the connection between the ESB and the KDC, create a configuration file and provide the path to the config file. A sample file is shown below. KrbLogin { com.sun.security.auth.module.Krb5LoginModule required useTicketCache=false refreshKrb5Config=true doNotPrompt=true useKeyTab=true debug=true storeKey=true };
loginContextName	If you have specified a login.config file using the loginConfig parameter shown above, you need to specify the loginContextName.

Testing the Kerberos mediator

To test this mediator, we need a RESTful back-end service that is secured using Kerberos. Let's use a REST API in an ESB server as the RESTful back-end service.
Create a username and password in the Active Directory, which is the KDC.

Create the following proxy service and deploy it in an ESB server.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
      name="testKerberos"
      startOnLoad="true"
      statistics="disable"
      trace="disable"
      transports="http,https">
   <target>
       <inSequence>
           <property name="username" value="<username_value>"/>

           <kerberosService krb5Config="<Path_To_ConfigFile>/krb5.conf"     
                           spn="HTTP/myserver"
                           clientPrincipal="{$ctx:username}"
                           keytabPath="<Path_To_clients.keytab>"
                           loginConfig= "<Path_To_login.conf>"
                           loginContextName="KrbLogin" />            
           <call>
               <endpoint>
                   <http method="GET"   uri-template="http://localhost:8281/HealthCheck/status"/>
               </endpoint>
           </call>
           <respond/>
       </inSequence>
   </target>
   <description/>
</proxy>

Send a request to the proxy service using the client username and password that was registered in step 2 above.