Metadata-Version: 1.1
Name: ssh-ca-server
Version: 0.1.2
Summary: SSH CA Server
Home-page: https://github.com/commercehub-oss/ssh-ca-server
Author: Commerce Technologies, LLC
Author-email: UNKNOWN
License: UNKNOWN
Description: # SSH CA Server
        
        Simple web service to provide SSH key signing.
        
        
        ## 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](https://github.com/commercehub-oss/ssh-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:
            ```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:
        ```json
        {
          "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:
        ```json
        {
          "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:
        ```json
        {
          "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.
        
        ```json
        {
          "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:
        ```json
        {
          "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
        ```
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
