Awesome
Github Authorized Keys
Use GitHub teams to manage system user accounts and authorized_keys
.
Screenshots
Administrators
- Automatically provision new users to production servers simply by adding them to a designatd GitHub team (e.g.
ssh
). - No need to keep
authorized_keys
up to date because keys are pulled directly from github.com API and optionally cached in etcd - Immediately revoke SSH access to servers by evicting users from the GitHub team
- Easy to deploy
End Users
- Self-administer public SSH keys via the GitHub account settings.
- No need to manage multiple SSH keys
Architecture
This tool consists of three parts:
- User Account / Authorized Keys provisioner which polls GitHub API for users that correspond to a given GitHub Organization & Team using a personal access token. It's responsible for adding or removing users from the system. All commands are templatized to allow it to run on multiple distributions.
- Simple read-only REST API that provides public keys for users, which is used by the
AuthorizedKeysCommand
in thesshd_config
; this allows you to expose the service internally without compromising your Github Token. The public SSH access keys are optionally cached in Etcd for performance and reliability. - An
AuthorizedKeysCommand
script that willcurl
the REST API for a user's public keys.
Getting Started
By far, the easiest way to get up and running is by using the ready-made docker container. The only dependency
is Docker itself. We also provide
a Kubernetes Helm Chart. If you run CoreOS or
use systemd
, there's a sample unit file.
Cloud Posse provides a public image cloudposse/github-authorized-keys that is built using TravisCI or you can build your own from source.
docker build -t cloudposse/github-authorized-keys .
Running GitHub Authorized Keys
All arguments can be passed both as environment variables or command-line arguments, or even mix-and-match them to suit your tastes.
Available configuration options:
Environment Variable | Argument | Description | Default |
---|---|---|---|
GITHUB_API_TOKEN | --github-api-token | GitHub API Token (read-only) | |
GITHUB_ORGANIZATION | --github-organization | GitHub Organization Containing Team | |
GITHUB_TEAM | --github-team | GitHub Team for Membership to Grant SSH Access | |
GITHUB_TEAM_ID | --github-team-id | GitHub Team ID for Membership to Grant SSH Access | |
SYNC_USERS_GID | --sync-users-gid | Default Group ID (aka gid ) of users | |
SYNC_USERS_GROUPS | --sync-users-groups | Default "Extra" Groups | |
SYNC_USERS_SHELL | --sync-users-shell | Default Login Shell | /bin/bash |
SYNC_USERS_ROOT | --sync-users-root | chroot path for user commands | / |
SYNC_USERS_INTERVAL | --sync-users-interval | Interval used to update user accounts | 300 |
ETCD_ENDPOINT | --etcd-endpoint | Etcd endpoint used for caching public keys | |
ETCD_TTL | --etcd-ttl | Duration (in seconds) to cache public keys | 86400 |
ETCD_PREFIX | --etcd-prefix | Prefix for public keys stored in etcd | github-authorized-keys |
LISTEN | --listen | Bind address used for REST API | :301 |
INTEGRATE_SSH | --integrate-ssh | Flag to automatically configure SSH | false |
LOG_LEVEL | --log-level | Ccontrol the logging verbosity. | info |
Quick Start
We recommend that you specify all parameters as environment variables. If using docker
, pass the environment file to the container
using the --env-file
argument.
Obtain the GitHub API Token (aka Personal Access Token) here. Click "Generate new token" and select read:org
.
That's it!
For example, /etc/github-authorized-keys
, might look like this:
GITHUB_API_TOKEN={token}
GITHUB_ORGANIZATION={organization}
GITHUB_TEAM=ssh
SYNC_USERS_GID=500
SYNC_USERS_GROUPS=sudo
SYNC_USERS_SHELL=/bin/bash
SYNC_USERS_ROOT=/host
SYNC_USERS_INTERVAL=300
ETCD_ENDPOINT=http://localhost:2739
ETCD_TTL=86400
ETCD_PREFIX=github-authorized-keys
LISTEN=:301
INTEGRATE_SSH=true
Then you could start it like this:
docker run \
--volume /:/host \
--expose "127.0.0.1:301:301" \
--env-file /etc/github-authorized-keys \
cloudposse/github-authorized-keys:latest
IMPORTANT Remember to expose the REST API so you can retrieve user's public keys. Only public keys belonging to users found in the GitHub team will be returned.
Note: depending on your OS distribution, you might need to tweak the command templates. Keep reading for details.
Usage Examples
Automatically Configure SSH
To leverage the github-authorized-keys
API, we need to make a small tweak to the sshd_config
.
This can be done automatically by passing the --integrate-ssh
flag (or setting INTEGRATE_SSH=true
)
After modifying the sshd_config
, it's necessary to restart the SSH daemon. This happens automatically by calling the SSH_RESTART_TPL
command.
Since this differs depending on the OS distribution, you can change the default behavior by setting the SSH_RESTART_TPL
environment variable (
default: /usr/sbin/service ssh force-reload
). Similarly, you might need to tweak the AUTHORIZED_KEYS_COMMAND_TPL
environment variable to something
compatible with your OS.
Manually Configure SSH
If you wish to manually configure your sshd_config
, here's all you need to do:
AuthorizedKeysCommand /usr/bin/authorized-keys
AuthorizedKeysCommandUser root
Then install a wrapper script to /usr/bin/authorized-keys
.
Note: this command requires curl
to access the REST API in order to fetch authorized keys
Etcd Fallback Cache
The REST API supports Etcd as cache for public keys. This mitigates any connectivity problems with GitHub's API. By default, the caching is disabled.
Command Templates
Due to the vast differences between OS commands, the defaults provided might not work for you flavor of Linux.
Below are some of the settings which can be tweaked.
Environment Variable | Description | Default |
---|---|---|
LINUX_USER_ADD_TPL | Command used to add a user to the system when no default group supplied. | adduser {username} --disabled-password --force-badname --shell {shell} |
LINUX_USER_ADD_WITH_GID_TPL | Command used to add a user to the system when a default primary gid supplied . | `adduser {username} --disabled-password --force-badname --shell {shell} --gid {gid |
LINUX_USER_ADD_TO_GROUP_TPL | Command used to add the user to secondary groups | adduser {username} {group} |
LINUX_USER_DEL_TPL | Command used to delete a user from the system when removed the the team | deluser {username} |
SSH_RESTART_TPL | Command used to restart SSH when INTEGRATE_SSH=true | /usr/sbin/service ssh force-reload |
AUTHORIZED_KEYS_COMMAND_TPL | Command used to fetch a user's authorized_keys from REST API | /usr/bin/github-authorized-keys |
The values in {braces}
are macros that will be automatically substituted at run-time.
Macro | Description |
---|---|
{username} | User's login name |
{shell} | User's login shell |
{group} | User's primary group name |
{gid} | User's primary group id |
Help
Got a question?
File a GitHub issue, send us an email or reach out to us on Gitter.
Contributing
Bug Reports & Feature Requests
Please use the issue tracker to report any bugs or file feature requests.
Developing
If you are interested in being a contributor and want to get involved in developing GitHub Authorized Keys, we would love to hear from you! Shoot us an email.
In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
NOTE: Be sure to merge the latest from "upstream" before making a pull request!
Here's how to get started...
git clone https://github.com/cloudposse/github-authorized-keys.git
to pull down the repositorymake init
to initialize thebuild-harness
- Review the documentation on compiling
License
APACHE 2.0 © 2016-2017 Cloud Posse, LLC
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
About
GitHub Authorized Keys is maintained and funded by Cloud Posse, LLC. Like it? Please let us know at hello@cloudposse.com
We love Open Source Software!
See our other projects or hire us to help build your next cloud-platform.
Contributors
<br/>Erik Osterman | <br/>Igor Rodionov |
---|