Configure your platform to use Kerberos

The intelligent agent platform uses Kerberos principals to authenticate users and services throughout the agent platform. Kerberos protocol, developed by Massachusetts Institute of Technology, allows a principal (a user or service) to prove its identity to another service within an insecure network.

Authentication of principals is completed through a centralized server called a key distribution center (KDC). The KDC authenticates a user with a Kerberos ticket. These tickets prove the principal's identity to other services in a network. After a principal is authenticated by these tickets, they can exchange encrypted data with a target service.

The platform uses Kerberos to authenticate user signon and initial platform startup. To use Kerberos to secure your platform, you must either find an existing KDC, or create a working KDC that all parts of the platform will use. Every system running a piece of the platform and every PC running a console that connects to this platform must be configured to use this KDC. You need to list all Kerberos principals in the ableplatform.preferences file that are used by the platform to authenticate users and services. Each platform Java™ Virtual Machine (agent pool) will have a service principal associated with it, and each user logging onto the platform from a console will need a user principal. All of these principals will need to be added to the KDC.

  1. Find or create a usable Kerberos key distribution center (KDC)

    The agent platform does not require a KDC on i5/OS™, a KDC running on any platform will work. If you cannot find an existing KDC to use, you can create your own. Start of changeIn V5R3 or laterEnd of change, i5/OS supports a native Kerberos server in i5/OS PASE. You can configure and manage a Kerberos server from your iSeries™ system. To configure a Kerberos server in i5/OS PASE, complete the following tasks:

    1. In a character-based interface, type: call QP2TERM. This command opens an interactive shell environment that allows you to work with i5/OS PASE applications.
    2. At the command line, enter: export PATH=$PATH:/usr/krb5/sbin. This command points to the Kerberos scripts that are necessary to run the executable files.
    3. At the command line, enter: config.krb5 -S -d iseriesa.myco.com -r MYCO.COM. This command updates the krb5.config file with the domain name and realm for the Kerberos server, creates the Kerberos database within the integrated file system, and configures the Kerberos server in i5/OS PASE. You will be prompted to add a database Master Password and a password for the admin/admin principal which is used to administer the Kerberos server.
    4. At the command line, enter: /usr/krb5/sbin/start.krb5 to start the servers.
  2. Configure systems in your agent environment to use Kerberos

    After you create a Kerberos server (KDC), you need to individually configure each client PC that will attempt to connect to the secure platform, and each iSeries system in your agent platform to point to your Kerberos server (KDC).

    • Configure your client PC

      To configure a client PC, you need to create a text file called krb5.conf in the security folder of the JVM that runs your iSeries Navigator intelligent agents console located here (where C: is the drive your Client Access driver is installed on):

      C:\Program Files\IBM\Client Access\JRE\Lib\Security
      The krb5.conf file tells all JVMs started from this JRE which KDC to use when dealing with Kerberos. The following is an example of what a generic krb5.conf file might look like if the KDC realm was KDC_REALM.PASE.COM and was found on system1.ibm.com:
      Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
      [libdefaults]
 default_realm           = KDC_REALM.PASE.COM
 default_tkt_enctypes    = des-cbc-crc
 default_tgs_enctypes    = des-cbc-crc

[realms]
 KDC_REALM.PASE.COM = {
         kdc = system1.rchland.ibm.com:88
}
        
[domain_realm]
 .rchland.ibm.com = KDC_REALM.PASE.COM
    • Configure your iSeries system

      To point your iSeries system to your KDC, you need to modify the following file:

      /QIBM/userdata/OS400/networkauthentication/ krb5.conf

      The krb5.conf file tells all JVMs started from this JRE which KDC to use when dealing with Kerberos. The following is an example of what a generic krb5.conf file might look like on the server if the KDC realm was KDC_REALM.PASE.COM and was found on system1.ibm.com:

      ??(libdefaults??)                                     
  default_realm = KDC_REALM.PASE.COM                    
??(appdefaults??)                                     
??(realms??)                                          
  KDC_REALM.PASE.COM = {                                
    kdc = system1.rchland.ibm.com:88                  
  }                                                   
??(domain_realm??)                                    
 system1.rchland.ibm.com = KDC_REALM.PASE.COM
  3. Acquire Kerberos user and service principals

    After you configure a KDC, you will need to create the user and service principals you plan to use to secure the platform, and register these principals to the KDC:

    Service Principals:
    Each agent pool (JVM) defined in ableplatform.preferences must have a service principal associated with it. Service principals are specific to the system that they will run on, so they must include that system name and be in the following format: ServicePrincipalName/systemName@KDCRealm. Each of the agent pools on the platform can use the same service principal, or you can specify that each pool use its own service principal. If each of your agent pools have different authority levels, then different principals should be used for each different authority level.
    User Principals:
    Each user that you want to allow to connect to the secure platform through the console will need a user principal. User principals can be associated with each agent definition listed in ableplatform.preferences. A user principal can connect to a platform from the console, regardless of the system the console is running on. Because of this, a user principal only needs to include the principal name and the KDC realm the principal belongs to: UserPrincipalName@KDCRealm.

    You need to add a principal to the KDC for each Service and User principal that your platform will use. The following steps will help you add your principals to your KDC if you are using the native KDC on the server:

    1. In a character-based interface, type: call QP2TERM.
    2. At the command line, enter: export PATH=$PATH:/usr/krb5/sbin. This command points to the Kerberos scripts that are necessary to run the executable files.
    3. At the command line, type: kadmin -p admin/admin, and press Enter.
    4. Sign in with administrator's password.
    5. At the command line:
      • To add service principals for Pools running on an iSeries server:

        addprinc -pw secret servicePrincipalName/iSeries fully qualified host name@REALM

      • To add user principals:

        addprinc -pw secret jonesm. This creates a principal for a user to log in from a console.

      • To add service principals for Pools running on a PC:

        addprinc -requires_preauth -e des-cbc-crc:normal -pw host/pc1.myco.com.

    If you are using the native KDC, see the following topics for more information on how to add principals to your KDC:

    If you are adding Service principals for Pools that will be running on an iSeries server, see: Add i5/OS principals to the Kerberos server.

    If you are adding User principals or Service principals for Pools that will be running on a PC, see: Create Host principals for Windows® 2000 workstations and users

  4. Add service principals to each keytab file

    When starting up a secure platform each agent pool will use the principal that it was defined to start with, and use it to authenticate itself. This requires each Pool JVM to have access to valid Kerberos credentials for the principal it is using. The iSeries Start Agent Services (STRAGTSRV) command will handle this, as long as there is an entry in the keytab file for the principal that is being used. Follow these steps to add an entry to the keytab file for each service principal that is to run on each of your platform systems:

    If you are running the native KDC on an iSeries server:

    1. In a character-based interface, type: STRQSH. This command starts the qsh shell interpreter.
    2. Enter the following command (where ServicePrincipal is the name of the service principal you want to add, system@KDCRealm is the fully qualified system name and Kerberos realm, and where thePassword is the password associated with your service principal): keytab add ServicePrincipal/system@KDCRealm -p thePassword

After you set up your KDC and create your user and service principals, you need to configure security in your ableplatform.preferences file.

Parent topic: Secure your agent environment
Related tasks
Configure a Kerberos server in i5/OS PASE
Configure network authentication
Configure platform security