COmanage Registry can be used to enable users to upload and manage their public SSH keys. Registry can be configured to provision these keys to LDAP so that they may be used by other systems. This recipe describes how COmanage Registry might be configured to accomplish this goal.

Recipe Ingredients

  • This recipe requires COmanage Registry version 3.3.0 or later.
  • Assumes the presence and use of an LDAP server.
Recipe Steps
  1. Install Plugins
    Install the Authenticator Plugin

  2. Configure Authenticator
    Configure an Authenticator for SSH

  3. Enable user feature
    Enable users to add/manage their SSH Key(s)
    1. Via their profile
    2. Via an enrollment flow

  4.  Configure Provisioner
    Provision SSH keys to LDAP

  5.  REF: Configure your system to use stored keys

Like what you see? See our other recipes!

Recipe Steps

1. Install Plugins

COmanage Registry supports several types of plugins in order to easily customize and extend Registry functionality. Plugins may be one of three types, each of which has a different process for being installed and enabled: Supported Core Plugins, Supported Non-core Plugins, and External Plugins.

Step overview

For this recipe, you will need to install and enable the following plugins. Since both of these plugins are Core plugins, they are likely already available for your use.

Plugins needed for this recipe

NAMETYPEPLUGIN CLASSDESCRIPTION
SSH Key AuthenticatorCOREAuthenticatorManages SSH Public Keys for CO People in Registry
LDAP ProvisioningCOREProvisioningProvisions Registry data into an LDAP server
RESOURCES for step 1. Install Plugins

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES

2. Configure Authenticator

All plugins have basic settings that are are related to the plugin’s Class. In addition, some plugins have plugin-specific settings to configure the specifics related to the plugin.

Step overview

The SSH Key Authenticator plugin only uses basic settings. Note that SSH Key Authenticators are multi-valued, so each instantiation (configured version) of the plugin can store multiple SSH Keys. Authenticators are set at the CO level.

Authenticator Basic Settings

FIELDDESCRIPTION
DescriptionUse a descriptive name that users will see when interacting with the authenticator
PluginSelect [ SshKeyAuthenticator ]
StatusSelect [ Active ]

Plugin-specific Settings: [ SshKeyAuthenticator ]

NONE

RESOURCES for step 2. Configure Authenticator

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES

3. Enable Registry to collect SSH Keys

By adding an authenticator via the plugin, you have enabled the collection of public SSH keys on any CO Person record. You may enable users to add their SSH keys to their CO Person record in Registry 1) Via their profile, or 2) Via an enrollment flow

You may also use the Registry API to add SSH keys. Resources for the SshKey API can be found in the [ Recipe Variations and Complements ] section of this document.

3.1 Collect SSH Keys via the user's profile

  1. Sign into Registry and navigate to the CO (if necessary)

  2. Open one's profile for the CO
    The user clicks their name in the upper right corner of the screen to display their user options, The user clicks the "My Profile" button to display their profile


  3. Manage the user's list of Authenticators
    Click the [ Authenticators ] link located in the box on the right side of the window to display a list of authenticator types that the user may add


    Click the [ Manage ] button next to the authenticator that you have configured to display the group of authenticators that are associated with this authenticator configuration. From this list, you may add new keys and [ View ] or[ Delete ] existing ones.

  4. Add a Public SSH Key
    Click the [ Add SSH Key ] link above the table on the right to display a form to add a new authenticator.

    On the form that opens, click the [ Choose File ] button to locate your public SSH key on your computer, and the btn:[UPLOAD] button to add the key to the CO Person profile. This action will check if the uploaded file appears to be a public SHH key before adding it. 

    Note for end users: SSH keys are usually hidden, and could be difficult to find when browsing through a file-picker widget. This article about how to show hidden files and folders on a computer or phone could be a useful resource.

3.2 Collect SSH Keys via an enrollment flow

As of Registry v3.3.0, Authenticators may be collected as part of an Enrollment Flow.

To add SSH key collection to an enrollment flow:

  1. Navigate to the enrollment flow that should manage SSH Key collection
    Click the [ Edit ] button for the enrollment flow to which you would like to add the SSH collection step.

  2. Configure the flow to include SSH Key collection
    Near the bottom of the enrollment flow configuration form, check the [ Establish Authenticators ] checkbox to display the list of active, configured Authenticators. For each Authenticator, select [ Required ], [ Optional ], or [ Not Permitted ] to affect your needs for SSH key upload.


    Although the image above displays three different SSH Key configurations, most implementations will only use one. SSH Authenticators are multi-valued, so multiple keys may be associated with each configuration.

  3. Save your enrollment flow
    Click the [ Save ] button to save your configuration. When the enrollment flow is run, the user will be prompted to upload a public SSH key in the way that you have configured.

4. Configure Provisioner

Once Public SSH Keys are stored within Registry, they may be provisioned via any provisioner plugin that supports they keys. The LDAP Provisioner is one of these plugins.

Step overview

Required additions to the LDAP server

The following schemas must be enabled on the LDAP server (if not already):

  • posixAccount (RFC 2307)
  • ldapPublicKey

Configure the LDAP Provisioner to include the SSH Key(s) 

COmanage Registry enables you to provision stored public SSH key to the ldapPublicKey objectClass in LDAP through the LDAP Provisioner plugin:

  1. Navigate to the Provisioning Targets area using Configuration > Provisioning Targets menu

  2. Either create or update the configuration of your LDAP Provisioner


  3. In the [ Attributes ] section of the configuration, scroll to the ldapPublicKey objectclass. Check this checkbox to include the sshPublicKeys.

LDAP attribute to configure to store the SSH Key(s)

AttributeObject ClassData ModelMultiple Values Exported?
sshPublicKeyldapPublicKeycm_ssh_keysYES

Test your LDAP Configuration

To test your LDAP configuration, you will manually provision someone whose Public Key(s) are not yet present in LDAP and then confirm that the keys were copied into LDAP as expected.

  1. Choose a CO Person record from your CO population to use for test
    This record must have one or more associated public keys. (You may use one of the SSH key collection methods above to add a key to the CO Person record.)

  2. Check this record in your LDAP system
    Use either your LDAP system's user interface or by using the ldapSearch command-line tool. If a record exists for this person, ensure that no SSH Keys have been associated with the LDAP record. A documentation link for ldapSearch can be found in the "OTHER RESOURCES" section in the resources box on the right >>.

  3. Manually provision the CO Person record
    • From the CO Person record that you would like to provision, click the [ Provisioned Services ] link from the menu on the right. This action will display the configured provisioning rules that you can run manually.

    • Select the configured LDAP Provisioner and click the [ Reprovision ] button to provision the latest information to LDAP.

  4. Re-check this record in your LDAP system
    Search for this user again using the method you used in the step above. This record should now include the public SSH Key(s) from Registry in the sshPublicKey attribute from the ldapPublicKey objectClass
RESOURCES for step 4. Configure Provisioner

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES

OTHER RESOURCES

5. Configure your systems to use the stored keys (REFERENCE ONLY)

FOR REFERENCE ONLY

These instructions in this section are NOT intended to provide instruction or guidance on system, security, or LDAP configurations.

At all times, you should consult your security guidelines and seek the advice of experts to implement a solution that achieves your security and access goals. The resources in this section are designed ONLY to provide links to what might be helpful references.

5.1 Dynamically supply public keys using a command instead of a file

REFERENCE: AuthorizedKeysCommand

The AuthorizedKeys Command configuration in sshd_config issues a command to dynamically retrieve public keys rather than read them from the authorized_keys file. This command may be leveraged to retrieve the user's public key(s) that have been stored in LDAP during the previous recipe steps. The command may be issued in the form of a script.

RESOURCES for step 5.1
The following article provides an excellent background and justification for this approach to dynamically accessing a user's authorized keys:  SSH Authentication with AuthorizedKeysCommand (Ryan Canty, Feb 18, 2018).

5.2 Retrieve information from LDAP via the command line

REFERENCE: ldapsearch Command-Line Tool

The ldapsearch Command processes one or more searchers in an LDAP directory server. Note that the criteria for the search request can be specified in a number of different ways, some of which may provide additional security or flexibility for your needs.

RESOURCES for step 5.2
There are several examples of how the ldapsearch might be used to retrieve the sshPublicKey value(s) for the current subject, for example, SSH key authentication using LDAP and SSH Public Keys in OpenLDAP.
If you want to update your sshd_config to allow password authentication from internal RFC1918 networks, you may also find this thread to be helpful: Only allow password authentication to SSH server from internal network

5.3 Using the ssh-ldap-helper

REFERENCE: ssh-ldap-helper

Instead of directly querying LDAP using ldapsearch, it may be possible to use a helper program supported by OpenSSH to retrieve the keys. Enabling ssh-ldap-helper may allow you to set the AuthorizedKeysCommand to a specific value (/usr/libexec/openssh/ssh-ldap-wrapper) instead of writing a script yourself.

5.4 Storing LDAP configurations

REFERENCE: ssh-ldap.conf | ldap.conf

If you use the ssh-ldap-helper, you may also need to specify an LDAP configuration file as described in the reference links above.


Recipe Variations and Complements

SSH Key API

You may explore the _experimental_ SshKey API for managing SSH keys. For additional information, see the following resources:

Managing UNIX Clusters

A common use case for collecting and provisioning SSH Keys is for their use in UNIX clusters by the end user. The following resources provide additional information: