Skip to content
This repository has been archived by the owner. It is now read-only.
[Deprecated] A service for authorizing SSH certificate signing requests backed by LDAP groups to determine a user's authorization level.
Python Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
conf
ssh_ca_server add santinize function May 2, 2018
.gitignore Support overriding configuration path with environment variable Feb 24, 2017
.travis.yml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE Initial commit Feb 16, 2017
README.md Update README.md to add deprecation notice Sep 4, 2019
RELEASING.md
requirements.txt
runserver.bash
setup.cfg
setup.py
testserver.py Initial code commit Feb 17, 2017

README.md

THIS PROJECT IS DEPRECATED

ssh-ca-server is no longer maintained, and this repository will be removed from GitHub on or after Wednesday, March 4, 2020.

SSH CA Server

Simple web service to provide SSH key signing.

Build Status

Purpose

The SSH CA Server provides a central service for authorizing SSH certificate signing requests. LDAP groups are used to determine a users authorization level. ca-client can be deployed to workstations for interacting with the SSH CA Server.

SSH Background:

SSH permits the use of signed certificates for authenticating. This simplifies the distribution of SSH keys because only the public key of the CA needs to be deployed to remote hosts. All new users just need their public keys signed by the CA to allow access to any remote host authorizing the CA.

Create a new CA

ssh-keygen -f MyCA

Sign key with CA:

ssh-keygen -V +1h -s MyCA -I username -n principal ~/.ssh/id_rsa.pub

-V +1h: Amount of time certificate is valid

-s MyCA: Certificate authority used to sign key

-I username: Signs the certificate with an identifier that will be logged to auth.log by sshd. This allows signing a certificate with a username and allows for uniquely identifying users (helpful for meeting audit requirments).

-n principal: Comma delimited list of principals included in certificate. The signed certificate can only be used for the designated principals. This is helpful when using a single CA for many different teams by using different principals and singing accordingly.

To view the certificate:

ssh-keygen -L -f ~/.ssh/id_rsa-cert.pub

On remote host update /etc/ssh/sshd_config to include: TrustedUserCAKeys /etc/ssh/MyCA.pub

Upload MyCA.pub to /etc/ssh

This approach will grant access to any principal a cert is signed for. The principal must exist on the remote host or access will be denied.

Alternatively you can allow access per principal by updating the authorized_keys for the specific principal.

On remote host update ~/.ssh/authorized_keys for the signed principal. Add the public key of the CA preceded with cert-authority

An example ~/.ssh/authorized_keys:

cert-authority ssh-rsa AAAA5Adk8.....

You can now login to the remote host using your new certificate

While CA signing is a great feature there is an obvious need to protect the CA. The goal of this project is to protect your CA and authorize signing requests using an LDAP directory.

Installation instructions for Ubuntu

  1. Install ssh-ca-server

    pip install ssh-ca-server
    
  2. Create service account and required directories

    # Service account for running ssh-ca-server
    useradd ssh-ca-server
    
    # Required configuration directory
    mkdir /etc/ssh-ca-server
    chown ssh-ca-server:ssh-ca-server /etc/ssh-ca-server
    
    # Location to store all CA public and private keys
    mkdir /etc/ssh-ca-server/cas
    chown ssh-ca-server:ssh-ca-server /etc/ssh-ca-server/cas
    chmod 600 /etc/ssh-ca-server/cas
    
    # Location for log file
    mkdir /var/log/ssh-ca-server
    chown ssh-ca-server:ssh-ca-server /var/log/ssh-ca-server
    
    
  3. Create configuration under /etc/ssh-ca-server/config.json (See server configuration section for available options)

    Example /etc/ssh-ca-server/config.json:

    {
      "ldap_server": "ldap-server.mydomain.com",
      "ldap_domain": "mydomain.com",
      "bind_user": "bind-user",
      "bind_password": "bind-password",
      "base_dn": "DC=mydomain,DC=com",
      "group_dn": "OU=MyGroups,DC=mydomain,DC=com",
      "role_attribute": "extensionAttribute1",
      "role_description": "description",
      "ca_attribute": "extensionAttribute2",
      "principal_attribute": "extensionAttribute3",
      "ca_path": "/etc/ssh-ca-server/cas",
      "cas":
        [
          {
            "name": "production",
            "max_duration": "24h"
          },
          {
            "name": "nonproduction",
            "max_duration": "30d"
          }
        ]
    }
  4. Install gunicorn

    apt-get install gunicorn
    
  5. Create upstart script /etc/init/ssh-ca-server

    setuid ssh-ca-server
    setgid ssh-ca-server
    
    start on runlevel [2345]
    stop on runlevel [06]
    respawn
    respawn limit 20 5
    
    script
     gunicorn -w 4 ssh_ca_server:app -b 0.0.0.0
    end script
    
  6. Start service

    service ssh-ca-server start
    

Server Configuration

By default configuration is loaded from /etc/ca-server/config.json. To change this behavior set environment variable SSHCA_CONFIG_PATH to the full path of the configuration file.

Parameter Default Description
ldap_server - FQDN of LDAP server
ldap_domain - Domain name of LDAP server used to derive UPN for bind_user
bind_user - Username of LDAP service account for validating group membership
bind_password - Password for bind_user
base_dn - Base DN used to find authenticating user
group_dn - Base DN used to find groups with role definitions
role_attribute extensionAttribute1 LDAP attribute that must be set to ca-role to filter groups
role_description description LDAP attribute that stores the role description
ca_attribute extensionAttribute2 LDAP attribute that stores a comma delimited list of allowed CA names
principal_attribute extensionAttribute3 LDAP attribute that stores a comma delimited list of allowed principals
ca_path /etc/ca-server/certs Location to store CA public and private keys
cas - List of supported CAs (See available CA parameters below)
log_level INFO Log level (ERROR, INFO, DEBUG)
log_file /var/log/ca-server/server.log Location of log file

cas is a list of certificate authorities supported by the CA server and supports the following parameters:

Parameter Default Description
name - Name of CA
max_duration 7d Expriation for key signing

HTTP Endpoint

/

This endpoint can be used to validate the basic health of the service and returns an empty payload.

All responses include the following attributes:

  • message: String value of an error response
  • version: The API version
  • payload: The payload returned by a successful request
  • error: Boolean value indicating an error occurred, if True message should always have a user friendly message.

It returns a JSON body like this:

{
  "message": "",
  "version": "1.01",
  "payload": "",
  "error": false
}

/list/cas

This endpoint is hit with a GET and returns a complete list of available certificate authorities.

It returns a json body like this:

{
  "message": "",
  "version": "1.01",
  "payload":
     [
        {
          "max_duration": "24h",
          "name": "production"
        },
        {
          "max_duration": "30d",
          "name": "nonproduction"
        }
      ],
  "error": false
}

/list/roles

This endpoint is hit with a GET and returns a complete list of roles for a given user. Use the ?user= query parameter to filter the role list to a given user.

It returns a json body like this:

{
  "message": "",
  "version": "1.01",
  "payload":
    [
      {
        "allowed_principals": "admin",
        "allowed_cas": "nonproduction,production",
        "ldap_group": "ssh-admin-group",
        "description": "Super Admin Role",
        "name": "ssh-admin-group"
      }
    ],
  "error": false
}

/get/<ca_name>

This endpoint is hit with a GET and returns the certificate authority public key for the ca_name provided in the path.

{
  "message": "",
  "version": "1.01",
  "payload": "94ABaQZ....",
  "error": false
}

/sign

This endpoint is hit with a POST and returns a signed certificate. The desired certificate authority is provided using the ?ca= query parameter.

Basic HTTP Authentication is used and requires the users LDAP username and password.

The file POST field should contain the users public key as multipart/form-data

Example request:

curl -u username -F file=@my_ssh_key.pub https://ca-server.mydomain.com/sign?ca=nonproduction

It returns a json body like this:

{
  "message": "",
  "version": "1.01",
  "payload": "ssh-rsa-cert-v01@openssh.com AC1Et...",
  "error": false
}

The returned signed SSH certificate will include all authorized principals plus the requesters username. The Key ID value is what will appears in the authlog of the remote node.

The below examples shows the result of a successfully signed SSH certificate:

$ ssh-keygen -L -f ~/.ssh/nonproduction_rsa-cert.pub

~/.ssh/nonproduction_rsa-cert.pub:
        Type: ssh-rsa-cert-v01@openssh.com user certificate
        Public key: RSA-CERT 3c:3d:47:...
        Signing CA: RSA 2b:2a:23:...
        Key ID: "username"
        Serial: 12515602213705584981
        Valid: from 2017-02-06T17:03:00 to 2017-03-08T17:04:44
        Principals:
                username
                admin
        Critical Options: (none)
        Extensions:
                permit-X11-forwarding
                permit-agent-forwarding
                permit-port-forwarding
                permit-pty
                permit-user-rc
You can’t perform that action at this time.