Package: keymaker
Keymaker isthe missing link between SSH and IAM accounts on Amazon AWS. It’s a stateless synchronization engine
that securely manages the process of SSH public key sharing and verification, user and group synchronization, and home
directory sharing (via optionalEFSintegration). You, the AWS account administrator,
define or import user and group identities in IAM, and instances in your account dynamically retrieve and use those
identities to authenticate your users. Keymaker is the modern, minimalistic alternative toLDAPorActive
Directoryauthentication.InstallationRunpip install keymaker.On instances that accept SSH logins:Runkeymaker install.Ensure processes launched by sshd have the IAM permissionsiam:GetSSHPublicKey,iam:ListSSHPublicKeys,iam:GetUser,iam:ListGroups,iam:GetGroup,iam:ListGroupsForUser,iam:GetRole,
andsts:GetCallerIdentity. The easiest way to do this is by runningkeymaker configure--instance-iam-roleINSTANCE_ROLEas a privileged IAM user, which will create and attach a
Keymaker IAM policy to the roleINSTANCE_ROLE(which you should then assign, via an IAM Instance Profile, to any
instances you launch). You can also manually configure these permissions, or attach the IAMReadOnlyAccess managed
policy.Keymaker requires OpenSSH v6.2+, provided by Ubuntu 14.04+ and RHEL7+.UsageRunkeymakerwith no arguments to get usage information. In client mode (running on a computer that you will connect
from), you can runkeymaker <subcommand>, where subcommand is:upload_key          Upload public SSH key for a user. Run this command for each user who will be accessing EC2 hosts.
list_keys           Get public SSH keys for a given or current IAM/SSH user.
disable_key         Disable a given public SSH key for a given or current IAM/SSH user.
enable_key          Enable a given public SSH key for a given or current IAM/SSH user.
delete_key          Delete a given public SSH key for a given or current IAM/SSH user.
configure           Perform administrative configuration tasks on the current AWS account.Usekeymaker <subcommand>--helpto get a full description and list of options for each command.Principle of operationAmazon Web ServicesIAMuser accounts provide the ability to add SSH public keys to
their metadata (up to 5 keys can be added; individual keys can be disabled). Keymaker uses this metadata to authenticate
SSH logins. Keymaker provides an integrated way for a user to upload their public SSH key to their IAM account
withkeymaker upload_key.Runkeymaker installon instances that you want your users to connect to. This installs three components:AnAuthorizedKeysCommandsshd configuration directive, which acts as a login event hook and dynamically retrieves
public SSH keys from IAM for the user logging in, using the defaultboto3credentials (which default to the instance’s IAM role credentials).Apam_execPAM configuration directive, which causes sshd to callkeymaker-create-account-for-iam-userearly
in the login process. This script detects if a Linux user account does not exist for the authenticating principal but
an authorized IAM account exists with the same name, and creates the account on demand. The UID of the account is
computed from a hash of the user’s SSH key, making it stable across instances that run Keymaker.Acron jobthat runs on your instance once an hour and synchronizes IAM group
membership information. Only IAM groups whose names start with a configurable prefix (by default,keymaker_*) are
synchronized as Linux groups.As a result, users who connect to your instances over SSH are given access based on information centralized in your AWS
account. Users must have an active IAM account with active matching SSH public keys in order for authentication to
succeed. Users’ UIDs and group memberships are also synchronized across your instances, so any UID-based checks or
group-based privileges remain current as well.Cross-account authenticationSome AWS security models put IAM users in one AWS account, and resources (EC2 instances, S3 buckets, etc.) in a family of other
federated AWS accounts (for example, a dev account and a prod account). Users then assume roles in those federated accounts,
subject to their permissions, withsts:AssumeRole.
When users connect via SSH to instances running in federated accounts, Keymaker can be instructed to look up the user identity
and SSH public key in the other AWS account (called the “ID resolver” account).Keymaker expects to find this configuration information by introspecting the instance’s own IAM role description. The
description is expected to contain a list of space-separated config tokens, for example,keymaker_id_resolver_account=123456789012 keymaker_id_resolver_iam_role=id_resolver. Forsts:AssumeRoleto work, the
roleid_resolverin account 123456789012 is expected to have a trust policy allowing the instance’s IAM role to
perform sts:AssumeRole onid_resolver.Run the following command in the ID resolver account (that contains the IAM users) to apply this configuration automatically:keymaker configure--instance-iam-rolearn:aws:iam::987654321098:role/INSTANCE_ROLE--cross-account-profileAWS_CLI_PROFILE_NAME.
Here, 987654321098 is the account ID of the federated account where EC2 instances will run, and AWS_CLI_PROFILE_NAME
is the name of theAWS CLI role profilethat you
have set up to access the federated account.Requiring IAM group membershipGroup membership is asserted if the instance’s IAM role description contains the config tokenkeymaker_require_iam_group=prod_ssh_users. The user logging in is then required to be a member of theprod_ssh_usersIAM group. Apply this configuration automatically by runningkeymaker configure--require-iam-groupIAM_GROUP_NAME.Security considerationsIntegrating IAM user identities with Unix user identities has implications for your security threat model. With Keymaker, a
principal with the ability to set SSH public keys on an IAM user account can impersonate that user when logging in to an EC2
instance. As an example, this can expand the scope of a compromised AWS secret key. You can mitigate this threat with an IAM
policy restricting access to theUploadSSHPublicKeymethod.FAQDoes running Keymaker require root access?The answer depends on what you mean by “running Keymaker”.To install keymaker into the sshd config and crontab (keymaker install), you need access to those daemons’ config files, which normally means you need root access.The keymaker authorization hook (runs when sshd logs you in) does not need root access.None of the client-side commands (listed under “Usage” above) need root access.EFS integrationEmailkislyuk@gmail.comfor details on the EFS integration.AuthorsAndrey KislyukLinksProject home page (GitHub)Documentation (Read the Docs)Package distribution (PyPI)BugsPlease report bugs, issues, feature requests, etc. onGitHub.LicenseLicensed under the terms of theApache License, Version 2.0.