KeyBox Setup

Easy, simple setup. Up and running in minutes!

Note: For EC2Box setup please refer to the README

Prerequisites


To Run Bundled with Jetty

Download keybox-jetty-vXX.XX.tar.gz

Export environment variables

for Linux/Unix/OSX

 export JAVA_HOME=/path/to/jdk
 export PATH=$JAVA_HOME/bin:$PATH

for Windows

 set JAVA_HOME=C:\path\to\jdk
 set PATH=%JAVA_HOME%\bin;%PATH%

Start KeyBox

for Linux/Unix/OSX

    ./startKeyBox.sh

for Windows

    startKeyBox.bat

How to Configure SSL in Jetty (it is a good idea to add or generate your own unique certificate)

http://www.eclipse.org/jetty/documentation/current/configuring-ssl.html


Using KeyBox

Open browser to https://<whatever ip>:8443

Login with

username:admin
password:changeme

Note: When using the AMI instance, the password is defaulted to the <Instance ID>. Also, the AMI uses port 443 as in https://<Instance IP>:443

Steps:

  1. Create systems
  2. Create profiles
  3. Assign systems to profile
  4. Assign profiles to users
  5. Users can login to create sessions on assigned systems
  6. Start a composite SSH session or create and execute a script across multiple sessions
  7. Add additional public keys to systems
  8. Disable any administrative public key forcing key rotation.
  9. Audit session history

Managing SSH Keys

By default KeyBox will overwrite all values in the specified authorized_keys file for a system. You can disable key management by editing KeyBoxConfig.properties file and use KeyBox only as a bastion host. This file is located in the jetty/keybox/WEB-INF/classes directory. (or the src/main/resources directory if building from source)

#set to false to disable key management. If false, the KeyBox public key will be appended to the authorized_keys file (instead of it being overwritten completely).
keyManagementEnabled=false

Also, the authorized_keys file is updated/refreshed periodically based on the relationships defined in the application. If key management is enabled the refresh interval can be specified in the KeyBoxConfig.properties file.

#authorized_keys refresh interval in minutes (no refresh for <=0)
authKeysRefreshInterval=120

By default KeyBox will generated and distribute the SSH keys managed by administrators while having them download the generated private. This forces admins to use strong passphrases for keys that are set on systems. The private key is only available for download once and is not stored on the application side. To disable and allow administrators to set any public key edit the KeyBoxConfig.properties.

#set to true to generate keys when added/managed by users and enforce strong passphrases set to false to allow users to set their own public key
forceUserKeyGeneration=false

Supplying a Custom SSH Key Pair

KeyBox generates its own public/private SSH key upon initial startup for use when registering systems. You can specify a custom SSH key pair in the KeyBoxConfig.properties file.

For example:

#set to true to regenerate and import SSH keys  --set to true
resetApplicationSSHKey=true

#SSH Key Type 'dsa' or 'rsa'
sshKeyType=rsa

#private key  --set pvt key
privateKey=/Users/kavanagh/.ssh/id_rsa

#public key  --set pub key
publicKey=/Users/kavanagh/.ssh/id_rsa.pub

#default passphrase  --leave blank if passphrase is empty
defaultSSHPassphrase=myPa$$w0rd

After startup and once the key has been registered it can then be removed from the system. The passphrase and the key paths will be removed from the configuration file.


Adjusting Database Settings

Database settings can be adjusted in the configuration properties.

#Database user
dbUser=keybox
#Database password
dbPassword=p@$$w0rd!!
#Database JDBC driver
dbDriver=org.h2.Driver
#Connection URL to the DB
dbConnectionURL=jdbc:h2:keydb/keybox;CIPHER=AES;

By default the datastore is set as embedded, but a remote H2 database can supported through adjusting the connection URL.

#Connection URL to the DB
dbConnectionURL=jdbc:h2:tcp://<host>:<port>/~/keybox;CIPHER=AES;

External Authentication

External Authentication can be enabled through the KeyBoxConfig.properties.

For example:

#specify a external authentication module (ex: ldap-ol, ldap-ad).  Edit the jaas.conf to set connection details
jaasModule=ldap-ol

Connection details need to be set in the jaas.conf file

ldap-ol {
	com.sun.security.auth.module.LdapLoginModule SUFFICIENT
	userProvider="ldap://hostname:389/ou=example,dc=keybox,dc=com"
	userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
	authzIdentity="{cn}"
	useSSL=false
	debug=false;
};

Administrators will be added as they are authenticated and profiles of systems may be assigned by full-privileged users.

User LDAP roles can be mapped to profiles defined in KeyBox through the use of the org.eclipse.jetty.jaas.spi.LdapLoginModule.

ldap-ol-with-roles {
    //openldap auth with roles that can map to profiles
    org.eclipse.jetty.jaas.spi.LdapLoginModule required
    debug="false"
    useLdaps="false"
    contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
    hostname="<SERVER>"
    port="389"
    bindDn="<BIND-DN>"
    bindPassword="<BIND-DN PASSWORD>"
    authenticationMethod="simple"
    forceBindingLogin="true"
    userBaseDn="ou=users,dc=keybox,dc=com"
    userRdnAttribute="uid"
    userIdAttribute="uid"
    userPasswordAttribute="userPassword"
    userObjectClass="inetOrgPerson"
    roleBaseDn="ou=groups,dc=keybox,dc=com"
    roleNameAttribute="cn"
    roleMemberAttribute="member"
    roleObjectClass="groupOfNames";
};

Users will be added/removed from defined profiles as they login and when the role name matches the profile name.


Auditing

Auditing is disabled by default and is only a proof of concept. Can be enabled in the KeyBoxConfig.properties.

#enable audit  --set to true to enable
enableInternalAudit=true