Configure platform security

Before you begin, ensure that you have configured your Kerberos key distribution center (KDC).

When security is turned on, ableplatform.preferences acts as a policy file for the security of the platform it defines. The following steps provide examples for how principals, trust levels, and permissions could be configured:

Define User and Service principals
After you acquire user and service principals, and register them with your KDC, you need to add these principals to ableplatform.preferences . When security is turned on, a user must be defined with a valid Kerberos user principal to gain access to the platform, and all agent services and agent pools must have a valid Kerberos service principal assigned to them. Add the user or service principals you have registered with your KDC, and specify an alias for each principal (the alias can be any unique name you want to use):
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
```
#----------------------------------------------------------------------
# Principals
#----------------------------------------------------------------------
Principal.1.Alias     = servicePrincipal1
Principal.1.Principal = name1/systemName@REALM

Principal.2.Alias     = servicePrincipal2
Principal.2.Principal = name2/systemName@REALM

Principal.3.Alias     = userPrincipal1
Principal.3.Principal = name1@REALM

Principal.4.Alias     = userPrincipal2
Principal.4.Principal = name2@REALM
```
Define trust levels
After you add user and service principals, you need to define the trust level associated with each principal. A trust level is associated with a principal to help define the capabilities of a user or service on the platform. Associating a trust level with a principal is also a way to group principals. The same trust level can be associate with multiple user and service principals. Add the principal alias you assigned to your service and user principals in step 1, (comma delineated), to the trust level you want to associate it with, and provide a unique name for trust level alias:
```
#----------------------------------------------------------------------
# Trust Levels
#----------------------------------------------------------------------
TrustLevel.1.Alias      = HighlyTrusted
TrustLevel.1.Principals = servicePrincipal1,userPrincipal1

TrustLevel.2.Alias      = SomewhatTrusted
TrustLevel.2.Principals = servicePrincipal2,userPrincipal2
```

Associate service principals with Agent Pools

A distributed platform can span multiple ports on multiple systems. Each agent pool defines where one part (JVM) or the platform will run. Each agent pool entry contains an alias, an IP Address, a port, and a service principal alias. The principal alias specifies what service principal this pool will be associated with. Add the service principal alias you defined above that you want to associate with your agent pool:

#----------------------------------------------------------------------
# Agent Pools (Java Virtual Machines)
#----------------------------------------------------------------------
AgentPool.1.Alias     = Pool1
AgentPool.1.IpAddress = systemname.ibm.com
AgentPool.1.Port      = 55551
AgentPool.1.Principal = servicePrincipal1

AgentPool.2.Alias     = Pool2
AgentPool.2.IpAddress = systemname.ibm.com
AgentPool.2.Port      = 55552
AgentPool.2.Principal = servicePrincipal1

AgentPool.3.Alias     = Pool3
AgentPool.3.IpAddress = systemname.ibm.com
AgentPool.3.Port      = 55553
AgentPool.3.Principal = servicePrincipal2

Define agent start-up authority

Define which users have the capability to start each of the agents defined on your secure platform. Add one or more user principal aliases to the EligiblePrincipal parameter:

#----------------------------------------------------------------------
# Permitted Agents
#----------------------------------------------------------------------
Agent.1.Alias=Agent1
Agent.1.AutonomyLevel=Medium
Agent.1.ClassName=com.ibm.able.platform.examples.EServerTemplateAgent
Agent.1.ConstructorArgs=String:AgentName1
Agent.1.EligiblePrincipals=userPrincipal1,userPrincipal2
Agent.1.EligibleAgentPools=Pool2,Pool3
Agent.1.InitArgs=
Agent.1.LastChangedDate=January 11, 2003 11:11am
Agent.1.Type=Tester1
Agent.1.Vendor=IBM1
Agent.1.Version=1.1

Define the algorithm and provider

You need to define the algorithm and provider of the KeyPairs the platform will use. By default, the preferences file will contain the following setting:

#----------------------------------------------------------------------
# Cryptography parameters
#----------------------------------------------------------------------
CryptographyAlgorithm = DSA
CryptographyProvider  = IBMJCE

After you add the necessary security data to ableplatform.preferences, save your changes. Turning on security for the platform once it is correctly configured is as simple as opening able.preferences that defines your platform, and changing the Security property to Security=on. If you are running an unsecured platform, you will need to end and restart the agent platform for security changes to take effect.