{"id":13506048,"url":"https://github.com/telefonicaid/fiware-keystone-spassword","last_synced_at":"2025-04-19T12:10:23.928Z","repository":{"id":4826684,"uuid":"40300843","full_name":"telefonicaid/fiware-keystone-spassword","owner":"telefonicaid","description":"Keystone SPASSWORD is an OpenStack Keystone extension that enables some extra security checks over user passwords, as force the usage of strong passwords, expiration time for a password, number of bad login attempts before user account became temporarily blocked, a recover procedure password, second factor authentication (2FA), etc.","archived":false,"fork":false,"pushed_at":"2024-12-12T16:45:22.000Z","size":1352,"stargazers_count":3,"open_issues_count":19,"forks_count":1,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-12-12T17:36:49.335Z","etag":null,"topics":["keystone","ldap","openstack-keystone-extension","security"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telefonicaid.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-06T11:14:32.000Z","updated_at":"2024-11-28T16:00:44.000Z","dependencies_parsed_at":"2023-01-11T16:36:48.195Z","dependency_job_id":"e9a5314c-5716-4acf-a54a-85950a008132","html_url":"https://github.com/telefonicaid/fiware-keystone-spassword","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-keystone-spassword","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-keystone-spassword/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-keystone-spassword/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-keystone-spassword/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telefonicaid","download_url":"https://codeload.github.com/telefonicaid/fiware-keystone-spassword/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235233242,"owners_count":18957066,"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":["keystone","ldap","openstack-keystone-extension","security"],"created_at":"2024-08-01T01:00:33.713Z","updated_at":"2025-04-19T12:10:23.921Z","avatar_url":"https://github.com/telefonicaid.png","language":"Python","funding_links":[],"categories":["FIWARE Catalogue"],"sub_categories":["Security"],"readme":"# Keystone SPASSWORD extension\n\n[![FIWARE Security](https://nexus.lab.fiware.org/static/badges/chapters/security.svg)](https://www.fiware.org/developers/catalogue/)\n[![License: Apache 2.0](https://img.shields.io/github/license/telefonicaid/fiware-keypass.svg)](https://opensource.org/licenses/Apache-2.0)\n\u003cbr\u003e\n[![Quay badge](https://img.shields.io/badge/quay.io-fiware%2Fkeystone--spassword-grey?logo=red%20hat\u0026labelColor=EE0000)](https://quay.io/repository/fiware/keystone-spassword)\n[![Docker badge](https://img.shields.io/badge/docker-telefonicaiot%2Ffiware--keystone--spassword-blue?logo=docker)](https://hub.docker.com/r/telefonicaiot/fiware-keystone-spassword)\n\u003cbr/\u003e\n![Status](https://nexus.lab.fiware.org/static/badges/statuses/incubating.svg)\n\nKeystone SPASSWORD is an OpenStack Keystone extension that enables\nsome extra security checks over user passwords, as force the usage of strong passwords,\nexpiration time for a password, number of bad login attempts before user account became temporarily blocked,\na recover procedure password, a second factor authentication (2FA)  and so on.\n\n\n## Keystone based versions\n- 1.4.X uses keystone Liberty\n- 1.5.X uses keystne Mitaka\n- 1.6.0 uses keystone Newton\n- 1.7.0 uses keystone Pike\n- 1.8.0 uses keystone Queens\n- 1.9.0 uses keystone Rocky\n- 1.10.0 to 1.17.0 uses keystone Stein\n- 1.18.x uses keystone Xena\n- 1.19.x to 1.21.0 uses keystone Antelope\n\n\n## Installing and Configuration\n\n### RPM installing on RDO Openstack\n\nInstalling from RPM is pretty straightforward:\n\n```sh\nrpm -Uvh keystone-spassword-*.noarch.rpm\n```\n\nOnce installed you can fine-tune options (out-of-the box the\ninstallation configures default values for that options at /etc/keystone/keystone.conf).\n\n\n```\n[spassword]\nenabled = true\npwd_exp_days = 365\npwd_max_tries = 5\npwd_block_minutes = 30\npwd_user_blacklist = user_id_list\nsmtp_server = '0.0.0.0'\nsmtp_port = 587\nsmtp_tls = true\nsmtp_user = 'smtpuser@yourdomain.com'\nsmtp_password = 'yourpassword'\nsmtp_from = 'smtpuser'\n```\n* `enabled` is a boolean which enables (true) or disables (false) if Keystone Spassword plugin feature is available in Keystone instance.\n* `pwd_exp_days` indicates the time in days in which user password will be expired if user password is not changed before.\n* `pwd_max_tries` indicate max number of bad login tries before user ccount is blocked (no login/token request is allowed)\n* `pwd_block_minutes` indicate the time in minutes in whcih and user account would be blocked.\n* `pwd_user_blacklist` list of user ids separated by `,` excluded by spassword.\n\nkeystone-spassword enables two new authentication and identity plugins, which extends\ndefault provided plugins to ensure the use of strong passwords, to check expiration time\nand to control the number of tries that an user can use badly their password before be blocked.\nThis way keystone-spassword extend token data returned from keystone to user by\n\"POST /v3/auth/tokens\", including new fields in 'extra' dictionary of 'token':\n\n```\n \"extras\": {\n     \"password_creation_time\": \"2016-12-01T08:55:34Z\",\n     \"pwd_user_in_blacklist\": false,\n     \"password_expiration_time\": \"2017-12-01T08:55:34Z\",\n     \"last_login_attempt_time\": \"2017-05-01T06:45:00Z\"\n     },\n```\n\n\n```\n[auth]\npassword=keystone_spassword.contrib.spassword.SPassword\n```\nand\n```\n[identity]\ndriver=keystone_spassword.contrib.spassword.backends.sql.Identity\n```\n\n```\n[filter:spassword_checker]\npaste.filter_factory = keystone_spassword.contrib.spassword.routers:PasswordExtension.factory\n\n[filter:spassword_time]\npaste.filter_factory = keystone_spassword.contrib.spassword:PasswordMiddleware.factory\n```\n\n\nRestart Keystone server:\n\n```\nsudo service openstack-keystone restart\n```\n\n### TGZ installaton\n\nUncompress tgz file plugin into python site-packages directory.\nMake a soft link from keystone contrib directory to that directory.\nFor more details see [RPM spec steps ][./keystone-spassword.spec).\n\n\n### Install Keystone\n\nThere is a complete guide to install step by step keystone for development purposes:\n\nhttps://github.com/telefonicaid/fiware-pep-steelskin/blob/master/keystoneInstallation.md\n\n\n### Docker Installation\nThre is a docker container image which includes keystone + keystone scim plugin + keystone spassword plugin:\nhttps://hub.docker.com/repository/docker/telefonicaiot/fiware-keystone-spassword\n\nThere are some [env vars  for configuration](docs/DOCKER.md)\n\n#### Upgrade from a older version:\nHow to upgrade to latest (1.18.0) docker release:\nBefore upgrade to 1.18.0 verison you should upgrade first to 1.17.0 version. Depending on the starting version some steps should be performed before.\n\nNormal procedure is stop container, update version in docker-compose and then up container; then container will be recreated.\nBut, if starting version is between 1.4.X and 1.6.X then some steps should be done to achieve that.\nAnyway, ensure you have a proper backup of mysql keystone database:\n```\nmysqldump -u root -p keystone  \u003e keystone_backup.sql\n```\nAnd check in each step of migration that keystone works properly (i.e. is able to authenticate)\n\nAnother way to create a copy of keystone database could be:\n```\ncreate database new_keystone\" | mysql -u root -p\nmysqldump -u root --password=\u003cpwd\u003e keystone | mysql -u root -p new_keystone\n```\n\n\n##### Upgrade from 1.4.X\n-\u003e needs be upgrade to 1.5.4 version before and then perform the steps described for that version.\nIn this step is important to use and SQL schema created by Keystone, not just recover from the scratch a sql dump backup, since and sql dump backup has not all required data to migration 1.4.x to 1.5.x will be successfully executed. More info about this issue is found at https://github.com/telefonicaid/fiware-keystone-spassword/issues/194\n\n\n##### Upgrade from 1.5.X or 1.6.0\n-\u003e needs a workaround:\nBefore update image in docker-compose the following commands should be executed:\n\nBackup `keystone.spassword` table\n```\nmysqldump -u root -p keystone spassword \u003e table_spassword.sql\n```\nExec the following commands\n```\nmysql -h iot-mysql -u root -p\nuse keystone;\ndrop table spassword;\ndelete from migrate_version where repository_id='keystone_spassword';\n```\nThen stop container and update image in docker-compose and up again container; then container will be recreated.\n\nAfter check that keystone works properly then you can optionally recover keystone.spassword table using previous spassword backup table.\n```\nmysql -u root -p keystone \u003c table_spassword.sql\n```\nRestart again keystone container\n\n##### Upgrade from 1.7.0 or upper to 1.17.0\n-\u003e no workaround needed\n\n##### Upgrade from 1.17.0 to 1.18.0\n-\u003e no workaround needed\n\n##### Upgrade from 1.18.0 to 1.19.0\n-\u003e no workaround needed\nTo upgrade to 1.19.0 version make sure upgrade first to 1.18.x version before.\n\n\n#### Migrate from MySQL to PostgreSQL\nSince version 1.21.0, Keystone SPASSWORD allows migration from MySQL to PostgreSQL.\n\n##### Prerequisites\nDefault auth plugin in MySQL 8 is `caching_sha2_password` which is not supported by pgloader tool needed by this procedure. During this procedure MySQL should use `mysql_native_password` plugin. To achieve that set in `[mysqld]` section add:\n\n    default-authentication-plugin=mysql_native_password\n\nThen restart your MySQL server and execute:\n\n    ALTER USER 'youruser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';\n\n##### Procedure\n1. Create new Keystone database and user in PostgreSQL:\n```sh\nPGPASSWORD=postgresUser psql -h 172.17.0.1 -p 5432 -U postgresPass \u003c\u003cEOF\nCREATE DATABASE keystoneDb;\nCREATE USER keystoneUser WITH PASSWORD 'keystonePass';\nGRANT ALL PRIVILEGES ON DATABASE keystoneDb TO keystoneUser;\nALTER DATABASE keystoneDb OWNER TO keystoneUser;\nEOF\n```\n\n\n2. Migrate with [pgloader](https://pgloader.io/) which is commonly available in linux distributions like Debian.\n```sh\npgloader mysql://keystoneUser:keystonePass@172.17.0.1:3306/keystoneDb postgresql://keystoneUser:keystonePass@172.17.0.1:5432/keystoneDb\n```\n\n3. Restart Keystone Docker container\n```sh\ndocker restart keystone\n```\n\n## Usage\n\nSPASSWORD extension reuses the authentication and authorization mechanisms provided\nby Keystone. This document assumes that the reader has previous experience\nwith Keystone, but as a reference you can read more about the Keystone\nAuthentication and Authorization mechanism in it's\n[official documentation](https://github.com/openstack/identity-api/blob/master/v3/src/markdown/identity-api-v3.md).\n\n\nMoreover keystone-spassword adds a new API to retrieve all project roles for a user (aka Grants):\n        \n**GET '/v3/users/{user_id}/project_roles'**\n\nThis call uses a x-auth-token associated to \u003cuser_id\u003e user.\n\n```\n[\n    {\n        \"domain\": \"8960989b51164eaeaa42200ecc79a47a\",\n        \"project_name\": \"/smartcity/gardens\",\n        \"project\": \"031149af6c5147a782e9cf4c56e1fe11\",\n        \"role_name\": \"8960989b51164eaeaa42200ecc79a47a#SubServiceAdmin\",\n        \"role\": \"e0da2d91e8154a32980ed4c5a717fd91\",\n        \"user\": \"bace4fd6bd9b49fda5727eb83a714a3c\",\n        \"user_name\": \"user1\"\n    },\n  ....\n]\n```\n\n\n- Get user password expiration black list membership.\n\n  **GET '/v3/users/\u003cuser_id\u003e/black'**\n\n  This call needs a x-auth-token associated to \u003cuser_id\u003e user. Returns a json about if user is in black list membership `{\"black\": true}` or not `{\"black\": true}`. Additionally this json response includes password expiration date for current user (i.e.: `{\"pwd_expiration_time\": \"2035-02-11T09:29:28.000000\"}`.\n\n- Modify configuration for password expiration black list membership for an user, allowing enable or disable it.\n\n  **POST '/v3/users/\u003cuser_id\u003e/black'**\n\n  This call needs a x-auth-token associated to \u003cuser_id\u003e user. The payload for this request is either `{\"enable\":true}` to enable password expiration black list membership or `{\"enable\":false}` to disable it.\n\n\n## Building and packaging\n\nIn any OS (Linux, OSX) with a sane build environment (basically with `rpmbuild`\ninstalled), the RPM package can be built invoking the following command:\n\n```\nsh ./package-keystone-spassword.sh\n```\n\n## Fernet keys and HA\n\nSince version 1.10 keystone-spassword is based on Keystone Stein and therefore uses Fernet keys. Full detail about these token could be found at [this faq](https://docs.openstack.org/keystone/stein/admin/fernet-token-faq.html).\n\nSumarizing the implications for HA enviroment we can say:\n- Fernet keys are stored in /etc/keystone/fernet-keys folder\n- Fernet keys should periodically rotated\n- Fernet keys should be the same for all nodes of an HA environment.\n\nTo achieve that there are some options:\n- Use a volumen for fernet keys folder content in docker based deployments.\n- Distribute fernet keys folder content with a `rsync` command abroad all keystone nodes\n- Ensure keystone Load Balancer is using sticky sessions [example for ha proxy](https://thisinterestsme.com/haproxy-sticky-sessions)\n\nFor non production environments there is another option: disable fernet keys rotation (i.e. by setting env var `ROTATE_FERNET_KEYS=False` in spassword 1.12.0+)\n\n## Hacking\n\nLocal development (by default using `sqlite`). Running a local development\nserver is useful to test a full featured Keystone server with SPASSWORD extension,\nand installation is straightforward following these steps:\n\nSetup a virtualenv (highly recommended).\n\n```sh\nvirtualenv .venv\n```\n\nActivate virtualenv\n\n```sh\nsource .venv/bin/activate\n```\n\nDownload dependencies\n\n```sh\npip install -r requirements.txt\npip install -r test-requirements.txt\npip install tox\n```\n\nRunning tests (functional and unit tests)\n\n```sh\ntox -e py27\n```\n\nSetting up local development server. First populate database (remember that\nthis will use `sqlite`).\n\n(until spassword 1.9.0)\n\n```sh\nkeystone-manage db_sync --extension spassword\n```\n\n(from spassword 1.10.0)\n\n```sh\nkeystone-manage db_sync\n```\n\nLaunch server\n\n```sh\nPYTHONPATH=.:$PYTHONPATH keystone-all --config-dir etc\n```\n## Docker env vars\n\nDocumented [here](docs/DOCKER.md)\n\n## Integrations\n\n* [LDAP integration](docs/iotp_ldap.md)\n* [Second Factor Authentication](docs/second_factor_auth.md)\n* [Federation as IDP integration](docs/iotp_saml_idp.md)\n* [Trust Token Flow](docs/trust_token.md)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelefonicaid%2Ffiware-keystone-spassword","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelefonicaid%2Ffiware-keystone-spassword","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelefonicaid%2Ffiware-keystone-spassword/lists"}