cloudposse / github-authorized-keys

Use GitHub teams to manage system user accounts and authorized_keys

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:

1. 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.
2. Simple read-only REST API that provides public keys for users, which is used by the AuthorizedKeysCommand in the sshd_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.
3. An AuthorizedKeysCommand script that will curl 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.

1. Fork the repo on GitHub
2. Clone the project to your own machine
3. Commit changes to your own branch
4. Push your work back up to your fork
5. 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...

1. git clone https://github.com/cloudposse/github-authorized-keys.git to pull down the repository
2. make init to initialize the build-harness
3. 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 [email protected]

We love Open Source Software!

See our other projects or hire us to help build your next cloud-platform.

Contributors

Erik Osterman	Igor Rodionov

github-authorized-keys's Issues

ARM64 build of new releases

Describe the Feature

When creating new releases, build an ARM64 Docker image for those wanting to deploy to AWS ARM64 EC2 instances, ECS or K8s clusters instead of building an image locally and deploying that. For that matter, any major host that supports ARM64 it could be used on.

Expected Behavior

When using Docker build and running an M1/M2 Mac, a native image would be downloaded. Also, it would support deploy to an ARM64 based EC2/ECS/K8s cluster.

Use Case

When using Docker build and running an M1/M2 Mac, a native image would be downloaded. Also, it would support deploy to an ARM64 based EC2/ECS/K8s cluster.

Describe Ideal Solution

No local Docker buildx needed

Alternatives Considered

No response

Additional Context

No response

Will stop working from March 15, 2022 due to Github API changes

Github is sunsetting the deprecated teams API endpoints which this service is using, more details in https://github.blog/changelog/2022-02-22-sunset-notice-deprecated-teams-api-endpoints/

Timeline
Brownouts
March 1, 2022 for 12 hours starting at 14:00 UTC
March 8, 2022 for 24 hours starting at 14:00 UTC
If you make a request to an affected endpoint during the brownouts, GitHub will respond with a client error.

Removal
March 15, 2022 at 14:00 UTC

Today during the first brownout period, the service stopped working as the user sync failed returning a 404/Permission Denied.

{
    "level": "info",
    "msg": "Run syncUsers job on start",
    "time": "2022-03-01T15:51:09Z"
}
{
    "job": "syncUsers",
    "level": "error",
    "msg": "Access denied",
    "subsystem": "jobs",
    "time": "2022-03-01T15:51:10Z"
}

Update to use README.yaml

what

• Convert README.md to README.yaml

why

• So we can better integrate with all of our other repos
• Consistency

ETCDCache Storage: Connection failed

I'm trying to integrate github-authorized-keys with bastion. It's working without the etcd caching. When I enable caching I get the following error (it still works just the key is always requested from github):

{"class":"ETCDCache","level":"error","method":"Set","msg":"Storage: Connection failed","time":"2020-04-03T20:04:22Z"}

etcd is installed on the host Ubuntu 18.04 and is visible in github-authorized-keys docker when running
docker exec -it github-authorized-keys netstat -tlpn
output:

Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 127.0.0.1:2379          0.0.0.0:*               LISTEN      -
tcp        0      0 127.0.0.1:2380          0.0.0.0:*               LISTEN      -

Running etcdctl --endpoints=http://localhost:2379 set foo bar works and returns bar

What am I missing?

Extra groups or removed users don't get synced

Hi,

I've been trying to deploy your application through the provided helm chart, but while it created all the users in my GitHub team on first run, they never get added to the groups I supplied afterwards (as I forgot on first deploy). Upon deletion of the chart, the application seems to remove the ssh keys, but it leaves the users around.
This has as affect that users get left behind on the system of course, but also that upon the next sync/start it finds the user and does not do a full sync of the groups.

Use a separate image for building and for releasing

You are using a single image for building the binary and for releasing it. Its causing the published image to unnecessarily large.

Here is the size of the latest image:

If you look at the golang base image, it alone is 74MB

The binary you produce is only 18MB:

-rwxr-xr-x    1 root     root       18.4M May 19 03:03 github-authorized-keys

This means the images are adding significant overhead. I believe the golang image includes the go source, which can be very large.

Id recommend separating it into two images, one for building and a clean release image with just the binary

Gitea Support

Hi there,

I'm trying to use Gitea as my hosted github inside my Kubernetes for user management.

Gitea supports the github API, and the go-github client supports exchanging the BaseURL and UploadURL for different targets, so it should (theoretically) be possible to use as a target for the github-authorized-keys tool.

I was trying to go get so that I could try to add the functionality, but it doesn't seem to want to pull through the dependencies.

I received the below error:

# github.com/cloudposse/github-authorized-keys/config
config/config.go:51:8: undefined: validation.StructRules
# github.com/cloudposse/github-authorized-keys/api
api/github.go:75:47: c.client.Organizations.ListTeams undefined (type *github.OrganizationsService has no field or method ListTeams)
api/github.go:102:43: not enough arguments in call to c.client.Users.Get
        have (string)
        want (context.Context, string)
api/github.go:113:42: c.client.Organizations.IsTeamMember undefined (type *github.OrganizationsService has no field or method IsTeamMember)
api/github.go:133:55: not enough arguments in call to c.client.Users.ListKeys
        have (string, *github.ListOptions)
        want (context.Context, string, *github.ListOptions)
api/github.go:172:13: undefined: github.OrganizationListTeamMembersOptions
api/github.go:179:52: c.client.Organizations.ListTeamMembers undefined (type *github.OrganizationsService has no field or method ListTeamMembers)

Is there a specific version of the github API I need to build against?

Only the first 30 members of a team are fetched from Github

What

Only the first 30 members of a team are fetched from Github

Reproducing

Create a Git team with more than 30 members, only the first 30 will be provisioned

Comments

Looking at the Github API, it appears they paginate the results: https://developer.github.com/v3/orgs/teams/#list-team-members
The Go library does provide support for requesting specific pages, it also has support for setting a page size: https://godoc.org/github.com/google/go-github/github#ListOptions

You may be able to set an arbitrarily large page size, but the ideal solution will be to iterate over the pages

Username Mappings

Is it possible to create custom username mappings?

For example, let's say my Github username is JoeSmith99 but I am required to SSH into my server as jsmith.

Is this repo still maintained?

See some inactivity here with pull requests and issues, it has not been touched since 2017. Is this repository still maintained?

Fix CI/CD

what

• Builds are failing
• See https://travis-ci.org/cloudposse/github-authorized-keys/builds/402672478#L819

why

• I don't know

references

• #28