{"id":18603639,"url":"https://github.com/cogini/ansible-role-users","last_synced_at":"2025-04-10T19:31:57.461Z","repository":{"id":41953533,"uuid":"116769874","full_name":"cogini/ansible-role-users","owner":"cogini","description":"Ansible role to create user accounts for deploying apps and manage access to them with ssh keys","archived":false,"fork":false,"pushed_at":"2022-04-26T13:40:42.000Z","size":18,"stargazers_count":18,"open_issues_count":1,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-25T03:34:37.156Z","etag":null,"topics":["ansible-role","ssh-keys","users"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cogini.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-09T05:24:32.000Z","updated_at":"2024-06-24T12:00:08.000Z","dependencies_parsed_at":"2022-08-12T00:30:52.728Z","dependency_job_id":null,"html_url":"https://github.com/cogini/ansible-role-users","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogini%2Fansible-role-users","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogini%2Fansible-role-users/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogini%2Fansible-role-users/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogini%2Fansible-role-users/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cogini","download_url":"https://codeload.github.com/cogini/ansible-role-users/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248281415,"owners_count":21077423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible-role","ssh-keys","users"],"created_at":"2024-11-07T02:14:57.794Z","updated_at":"2025-04-10T19:31:56.477Z","avatar_url":"https://github.com/cogini.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Users\n\nThis Ansible role manages user accounts and controls access to them with ssh keys.\n\nIt is used to deploy one or more applications to a server. It supports creating\naccounts used to deploy and run the app, as well as accounts for system admins\nand developers.\n\nIt is basically an opinionated wrapper on the\n[Ansible user module](http://docs.ansible.com/ansible/latest/user_module.html).\n\n## User types\n\nThe role supports creating the following types of user accounts:\n\n* Global system admins / ops team\n\nThese users have their own logins on the server with sudo permissions. We add\nthem to the `wheel` or `admin` group, then allow them to run sudo without a\npassword.\n\nWhen we provision a server, we automatically create accounts for our system\nadmin team, independent of the project.\n\n* Project admins / power users\n\nThese users have the same rights as global admins, but are set up on\nper-project or per-server basis, controlled with inventory host/group vars.\nNormally the tech lead for the project would be an admin.\n\n* Deploy account\n\nThis user account is used to deploy the application to the server.  It owns the\napplication software files and has write permissions to the deploy and config\ndirectories.\n\nThe app and deploy accounts do not have sudo permissions, though we may make a\n`/etc/sudoers.d/` rule to allow them to run commands to e.g. restart the app by\nrunning `systemctl`. That is handled by the role that installs and configures\nthe app, not this role.\n\nFor example, make a file like `/etc/sudoers.d/deploy-foo`:\n\n    deploy ALL=(ALL) NOPASSWD: /bin/systemctl start foo, /bin/systemctl stop foo, /bin/systemctl restart foo, /bin/systemctl status foo\n\n* App account\n\nThe application runs under this user account.\n\nThis account has write access to the directories it needs at runtime, e.g.\nfor logs, and has read-only access to its code and config files.\n\n* Developers\n\nDevelopers may need to access the deploy or app user account to look at the\nlogs and debug it. We add the ssh keys for developers to the accounts, allowing\nthem to log in via ssh.\n\n* Project users\n\nThese users are like admins, but don't have sudo. An example might\nbe an account for a customer to be able to log in and run queries against\nthe db, but they don't need admin rights. You can give them permissions\nto e.g. access the log files for the app by adding them to the app group\nand setting file permissions.\n\n# Configuration\n\nBy default, this role does nothing. You need to add configuration vars to have\nit do something. That would normally be via group vars, e.g.\n`inventory/group_vars/app_servers`, a `vars` section in a playbook, or a combination.\n\nYou can have different settings on a host or group level to e.g. give\ndevelopers login access in the dev environment but not on prod.\n\n## App accounts\n\nThe account that deploys the app.\nOptional, if not specified the deploy user will not be created.\n\n    users_deploy_user: deploy\n    users_deploy_group: deploy\n\nThe account that runs the app.\nOptional, if not specified the app user will not be created.\n\n    users_app_user: foo\n    users_app_group: foo\n\n## User accounts\n\nThe `users_users` defines Unix account names and ssh keys\nfor users.\n\nIt is a list of dicts with four fields:\n\n* `user`: Name of the Unix account\n* `name`: User's name. Optional, for documentation.\n* `key`:  ssh public key file. Put them in e.g. your playbook `files` directory.\n* `github` is the user's GitHub id. The role gets the user keys from\n`https://github.com/{{ github }}.keys`\n\nExample:\n\n```yaml\nusers_users:\n  - user: jake\n    name: \"Jake Morrison\"\n    github: reachfh\n  - user: ci\n    name: \"CI server\"\n    key: ci.pub\n```\n\n## Lists of users\n\nAfter defining the user accounts in `users_users`, configure lists of users,\nspecifying the id used in the `user` key. By default, these are empty, so if\nyou don't specify users, they will not be created.\n\nGlobal admin users with a separate Unix account and sudo permissions.\n\n```yaml\nusers_global_admin_users:\n - jake\n```\n\nProject level admin users with a separate Unix account and sudo permissions.\n\n```yaml\nusers_admin_users:\n - fred\n```\n\nProject users with a separate Unix account but no sudo permission.\n\n```yaml\nusers_regular_users:\n - bob\n```\n\nUsers (ssh keys) who can access the deploy account.\n\n```yaml\nusers_deploy_users:\n - ci\n```\n\nUsers (ssh keys) who can access the app account.\n\n```yaml\nusers_app_users:\n - fred\n```\n\n## Group configuration\n\nYou can specify additional groups which the different types of users will have.\nBy default these lists are empty, but you can use it to fine tune access to the app.\n\nWe normally configure ssh so that a user account must must be a member of a\n`sshusers` group, or ssh will not allow anyone to log in.\n\nAdd this to `/etc/ssh/sshd_config`\n\n    AllowGroups sshusers sftpusers\n\nThen add `sshusers` to the `users_admin_groups`, e.g.\n```yaml\nusers_admin_groups:\n  - sshusers\n```\n\n### Unix groups that admin users should have.\n\nThe role will always be added the `wheel` or `admin` group, depending on the\nplatform. If there are admin users defined, then this role sets up sudo with a\n`/etc/sudoers.d/00-admin` file so that admin users can run sudo without a\npassword.\n\n```yaml\nusers_admin_groups:\n  - sshusers\n```\n\n### Unix groups that regular users should have:\n```yaml\nusers_regular_groups:\n  - sshusers\n```\n\n### Unix groups that the deploy user should have:\n\n```yaml\nusers_deploy_groups:\n  - sshusers\n```\n\n### Unix groups that the app user should have:\n\n```yaml\nusers_app_groups:\n  - sshusers\n```\n\n## Deleting users\n\nThis role defines users that it creates with \"ansible-\" in the comment.\nThis allows it to track when users are added or removed from the lists\nand delete the accounts.\n\nYou can also specify accounts in the `users_delete_users` list and they will be\ndeleted. This is useful for cleaning up legacy accounts.\n\nYou can control whether to delete the user's home directory when deleting the\naccount with the `users_delete_remove` and `users_delete_force` variables.\nSee [the Ansible docs](http://docs.ansible.com/ansible/user_module.html) for details.\nFor safety, these variables are `no` by default, but if you are managing the\nsystem users with this role, you probably want to set them to `yes`.\n\n    users_delete_remove: yes\n    users_delete_force: yes\n\nThe role can optionally remove authorized keys from system users like 'root' or 'ubuntu'.\nThis is useful for security to avoid backup root keys, once you have set up named admin\nusers.\n\n    users_remove_system_authorized_keys: true\n\n## Setup\n\nThe normal sequence is to run this role as the first thing on a new instance.\nThat creates admin users and sets up their keys so that they can run the\nother roles which configure the server. A project specific role is responsible\nfor preparing the server for the app, e.g. creating directories and installing\ndependencies. We normally deploy the app from a build or CI server, without sudo,\nusing the `deploy` user account.\n\nHere is a typical playbook:\n\n```yaml\n- name: Manage users\n  hosts: '*'\n  vars:\n    users_app_user: foo\n    users_app_group: foo\n    users_deploy_user: deploy\n    users_deploy_group: deploy\n    users_users:\n      - user: jake\n        name: \"Jake Morrison\"\n        github: reachfh\n    users_app_users:\n      - jake\n    users_deploy_users:\n      - jake\n  roles:\n    - { role: cogini.users, become: true }\n```\n\nAdd the host to the `inventory/hosts` file.\n\n    [web-servers]\n    web-server-01\n\nAdd the host to `.ssh/config` or a project specific `ssh.config` file.\n\n    Host web-server-01\n        HostName 123.45.67.89\n\nOn a physical server where we start with a root account and no ssh keys, we need\nto bootstrap the server the first time, specifying the password with -k.\n\n    ansible-playbook -k -u root -v -l web-server-01 playbooks/manage-users.yml --extra-vars \"ansible_host=123.45.67.89\"\n\nOn macOS the -k command requires the askpass utility, which is not installed by\ndefault, so it falls back to paramiko, which doesn't understand `.ssh/config`,\nso we specify `ansible_host` manually.\n\nOn following runs, after the admin users are set up, use:\n\n    ansible-playbook -u $USER -v -l web-server-01 playbooks/manage-users.yml\n\n\n## Deleting legacy users\n\nDefine legacy user accounts to delete in the `users_delete_users` list, e.g.:\n\n    ansible-playbook -u $USER -v -l web-servers playbooks/manage-users.yml --extra-vars \"users_delete_users=[fred] users_delete_remove=yes users_delete_force=yes\"\n\n# License\n\nMIT\n\n# Author Information\n\nJake Morrison at [Cogini](http://www.cogini.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogini%2Fansible-role-users","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcogini%2Fansible-role-users","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogini%2Fansible-role-users/lists"}