Managing Key Trustee Server Organizations

Organizations allow you to configure Key Trustee for use in a multi-tenant environment. Using the keytrustee-orgtool utility, you can create organizations
and administrators for multiple organizations. Organization administrators can then approve or deny the registration of clients, depending on the registration method.

The keytrustee-orgtool Utility

keytrustee-orgtool is a command-line utility for administering organizations. The keytrustee-orgtool command must be run as
the root user.

The following table explains the various keytrustee-orgtool commands and parameters. Run keytrustee-orgtool --help to view
this information at the command line.

Usage for keytrustee-orgtool

Operation

Usage

Description

Add

keytrustee-orgtool add [-h] –n name –c contacts

Adds a new organization and administrators for the organization.

List

keytrustee-orgtool list

Lists current organizations, including the authorization secret, all administrators, the organization creation date,
and the organization expiration date.

Disable client

keytrustee-orgtool disable-client [-h] -–fingerprint fingerprint

Disables a client that has already been activated by the organization administrator.

Enable client

keytrustee-orgtool enable-client [-h] –-fingerprint fingerprint

Enables a client that has requested activation but has not yet been approved by the organization administrator.

Set authorization Code

keytrustee-orgtool set-auth [-h] –n name –s secret

Sets the authorization code to a new string, or to blank to allow automatic approvals without the code.

Create Organizations

Each new Key Trustee tenant needs its own organization. You can create new organizations using the keytrustee-orgtool add command. For example, to create a
new organization for the Disaster Recovery group and add two administrators, Finn and Jake:

Do not use spaces or special characters in the organization name. Use hyphens or underscores instead.

Do not use spaces between email addresses (when adding multiple administrators to an organization). Use a comma to separate email addresses, without any space (as shown in the example
above).

Each contact email address added when creating the organization receives a notification email,
as detailed below.

Once an organization exists, use the keytrustee-orgtool add command to add new administrators to the organization. For example, to add an administrator
to the disaster-recov organization:

keytrustee-orgtool add -n disaster-recov -c marceline@example.com

Note: You cannot remove contacts from an organization with the keytrustee-orgtool utility.

List Organizations

After creating an organization, verify its existence with the keytrustee-orgtool list command. This command lists details for all existing organizations.
The following is the entry for the disaster-recov organization created in the example:

Change the Authorization Code

When an organization is created, an authorization code is automatically generated. When you run the keytrustee-orgtool list command, the code is
displayed in the auth_secret field. To register with a Key Trustee Server, the client must have the authorization code along with the organization name. To set a new
auth_secret, run the following command:

$ keytrustee-orgtool set-auth -n disaster-recov -s ThisISAs3cr3t!

Run the keytrustee-orgtool list command again, and confirm the updated auth_secret field:

If you do not want to use an authorization code, set the auth_secret field to an empty string:

$ keytrustee-orgtool set-auth -n disaster-recov -s ""

Cloudera recommends requiring an authorization code.

Notification Email and GPG Keys

Whenever an administrator is added to an organization, the Key Trustee Server sends an automated email message (subject: “KeyTrustee Contact Registration”) to the newly added
administrator:

Hello, this is an automated message from your Cloudera keytrustee Server.
Welcome to Cloudera keytrustee! You have been listed as an administrator contact
for keytrustee services at your organization [test-org]. As an administrator,
you may be contacted to authorize the activation of new keytrustee clients.
We recommend that you register a GPG public key for secure administration of
your clients. To do so, visit the link below and follow the instructions.
https://keytrustee01.example.com:11371/?q=CnRV6u0nbm7zB07BQEpXCXsN0QJFBz684uC0lcHMoWL
This link will expire in 12 hours, at Thu Sep 3 00:08:25 2015 UTC.

Cloudera recommends that an organization's administrators:

Register the GPG public key by following the link contained in the notification email. Registering the GPG public key is optional, but if you choose to register your public key:

Complete the process within 12 hours, before the link expires.

Upload the entire key, including the BEGIN and END strings, as shown here:

Import the Key Trustee Server’s public GPG key to verify that the server is the sender.

The organization's administrators are notified by email when new clients are registered to the Key Trustee Server using the mail transfer agent (as discussed in Configuring a Mail Transfer Agent for Key Trustee Server). However, if the server does not have access to email, you can use a local system mail address,
such as username@hostname, where hostname is the system hostname and username is a valid system user. If
you use a local system email address, be sure to regularly monitor the email box.

If this documentation includes code, including but not limited to, code examples, Cloudera makes this available to you under the terms of the Apache License, Version 2.0, including any required
notices. A copy of the Apache License Version 2.0 can be found here.