Skip to main content

Relocating User Keys

You can relocate authorized keys from users' directories to central root-owned locations on their respective hosts, which prevents regular users from manually modifying authorizations to the host.

Key Manager performs key relocation in stages:

  • Stage 0 - No key relocation has been performed by Key Manager. Note that re-adding a host also resets its relocation stage to 0.

  • Stage 1 - Authorized keys are copied from user directories to a specified directory (authorized-keys directory).

  • Stage 2 - The SSH-server configuration is updated to only use authorized keys under the new authorized-keys directory. Note that the SSH-server configurations of the selected hosts must be in the managed state.

  • Stage 3 - The old authorized keys are removed from user directories. This completes key relocation.

You can perform all these stages at once. Or to allow easier rollback, you may perform key relocation up to a certain stage. For example, you can perform stages 1 and 2 to effectively start using authorized keys from the authorized-keys directory. If you encounter problems in this stage you can revert to using old keys by simply rolling back the SSH-server configuration changes.

The following actions can be used to perform key relocation, either via the Hosts page in the GUI, or using the command-line client:

  • Relocate User Keys: Start key relocation on selected host(s). By default, nothing is performed on hosts where key relocation has already been started.

    Corresponding command-line-client command (described in relocate-user-keys: ssh-mgr-client relocate-user-keys <options>

    note

    Key Manager must have up-to-date host information to successfully perform key relocation. For this reason we recommend running a host scan prior to key-relocation actions.

    On hosts where key relocation has been performed previously, you must enable Force relocating keys on already relocated hosts (force).

    When relocating to a central location, the authorized-keys directory and its contents must be owned by root, with permissions stricter or equal to 755. If relocating keys back to users' directories, these restrictions do not apply.

  • Continue Key Relocation: Continue key relocation on selected host(s) where some key-relocation stages are still to be performed.

    This action only applies to hosts with incomplete key relocation. Also, this action only performs the relocation stages that have yet to be performed on the selected host(s). For example, if you perform a Continue Key Relocation action while only opting to remove old keys, the stage 3 of relocation, operations are performed only on hosts that are at Key relocation stage 2.

    Corresponding command-line-client command (described in continue-key-relocation:

    ssh-mgr-client continue-key-relocation <options>
    note

    For easier key-relocation rollback, we suggest:

    • Using tags to distinguish old and new keys. Provide these tags with the relocation command to make Key Manager automatically tag the appropriate keys.

    • Thoroughly testing authorizations after updating configurations (when in relocation stage 2). Key-relocation rollback becomes harder after removing old authorized keys (stage 3). You may even consider omitting stage 3: by stage 2 old keys are out of configuration, and therefore effectively disabled.

    • If you accidentally relocate keys to a wrong authorized-keys location, we recommend rolling back these action first (instead of directly forcing relocation to the intended location).

Rolling Back Key-Relocation Actions​

This section describes key-relocation rollback. The exact procedures differs depending on the relocation stage of the target host(s).

  • Stage 1: Remove the new authorized keys created by any key-relocation action. We recommend filtering target keys by tag (if you tagged the keys during key relocation).

    Deleting the new keys is optional from a security standpoint: in stage 1 the new keys are out of configuration, and therefore effectively disabled.

    Note that this does not reset the key-relocation stage of the host. To restart key relocation, you need to Relocate User Keys with the Force relocating keys on already relocated hosts option.

  • Stage 2: To revert to using the old authorized keys, run rollback-key-relocation via the command-line client, similarly to:

    $ ssh-mgr-client rollback-key-relocation -i <host_id>

    To update information about key states, also scan the host.

    For more information about the rollback-key-relocation command, see rollback-key-relocation.

  • Stage 3: Restore the old authorized keys to any point in time before they were deleted. This should be done using the Rollback action. We recommend filtering for target keys by tag (if you tagged the keys during key relocation).

    You can initialize an authorized-keys rollback via the command-line client, similarly to:

    $ ssh-mgr-client add-request -d
    'request_type=rollback_keys,auth_key_filter="host_id=99&&tags=old_keys",\
    timepoint=2000-01-01T00:00:00Z'

    Then submit the necessary approvals for executing the request.

    After restoring the old keys, run rollback-key-relocation and scan the host as described in stage 2.

    For more information about the Rollback action, see Roll Back Changes to User Keys.

Key-Relocation Example​

This section describes the results of key relocation with example settings. In this example scenario, complete key relocation is to be performed on the host server01.example.com. The host is already placed in the managed state, and its SSH software configurations have also been placed in the managed state. The Key-relocation stage of the host is 0 - Not relocated.

server01.example.com uses OpenSSH client and server, which have been configured to use SSH keys as follows:

  • Authorized-key locations have been specified in the OpenSSH server-configuration file (usually located at /etc/ssh/sshd_config):

    AuthorizedKeysFile      .ssh/authorized_keys

server01.example.com has the users root, alice, and bob. These users have authorized-key files as follows:

root​

Authorized-key files:

  • /root/.ssh/authorized_keys

alice​

Authorized-key files:

  • /home/alice/.ssh/authorized_keys

bob​

Authorized-keys files:

  • /home/bob/.ssh/authorized_keys

server01.example.com has been selected from the Hosts page. We perform a Relocate User Keys action with the following settings:

  • Authorized keys directory: /opt/ssh_keys/%u

  • Update configurations is enabled.

  • Remove old keys is enabled.

After the key-relocation jobs finish successfully, the users' authorized-key files are relocated to the following locations:

  • root: /opt/ssh_keys/root/authorized_keys

  • alice: /opt/ssh_keys/alice/authorized_keys

  • bob: /opt/ssh_keys/bob/authorized_keys

Because Update configurations is checked, the SSH server configuration is automatically updated to look for authorized keys from the Authorized keys directory location. Also, because Remove old keys is checked, the original authorized-key files are automatically removed from the users' home directories.