This is the latest release in the 6.x.x family. For EI 7.0.0, click here.

All docs This doc
||
Skip to end of metadata
Go to start of metadata

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:

Using Kerberos authentication

The steps in the above process are as follows:
  1. Register the client's username (Client Principal Name) and Password (Keytag file) in the KDC.
  2. The client sends a request to the back-end service by invoking the ESB.
  3. 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. 
  4. The KDC authenticates the client's credentials for the back-end service and returns a service token to the Kerberos mediator.
  5. 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.

ParameterDescription
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
spnThe service principal name (spn) of the back-end service.
clientPrincipalThis represents the client principal name that is generated for the consumer client. In the above example, this value is fetched from the Property mediator.
keytabPathThis 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

  1. 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.
  2. Create a username and password in the Active Directory, which is the KDC.
  3. 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>
  4. Send a request to the proxy service using the client username and password that was registered in step 2 above. 
  • No labels