diff --git a/specs/keystone/ocata/pci-dss-expired-password.rst b/specs/keystone/ocata/pci-dss-expired-password.rst new file mode 100644 index 00000000..f09ab9ad --- /dev/null +++ b/specs/keystone/ocata/pci-dss-expired-password.rst @@ -0,0 +1,198 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +==================================== +PCI-DSS Query Password Expired Users +==================================== + +Blueprint `pci-dss-query-password-expired-users `_ + +Problem Description +=================== + +Currently, when using the: +``keystone.conf [security_compliance] password_expires_days`` +value, when a user's password expires and then must be reset by an +administrator, there is no way to query a list of users who are in +this state of password expiration. We would like the ability to retrieve +a list of users whose passwords has expired for technical support and +auditing purposes. + +Proposed Change +=============== + +A new query will be added to the existing: +``GET /v3/users`` +API call that would allow an administrator to query a list of users who are +currently locked-out due to password expiration. This will allow operators to +set up jobs to generate necessary audit lists and notifications. + +**Query list of users based on their passwords' expiry time** + +Gets a list of users based on their password expiry time. + +.. code-block:: bash + + GET /v3/users?password_expires_at={operator}:{timestamp} + +Where ``{timestamp}`` is a datetime in the format of ``YYYY-MM-DDTHH:mm:ssZ`` +and ``{operator}`` can be either ``lt`` or ``gt``. Note that +user can also do equality matching via +``/v3/users?password_expires_at={timestamp}``; however, +due to the nature of this query, it may not be as useful. + +http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering + +Examples +======== + +**Query list of users whose password has expired before a given timestamp.** + +.. code-block:: bash + + GET /v3/users?password_expires_at=lt:2016-10-10T15:30:22Z + +**Response** + +.. code-block:: json + + { + "links": { + "next": null, + "previous": null, + "self": "http://example.com/identity/v3/users" + }, + "users": [ + { + "domain_id": "default", + "enabled": false, + "id": "514a66612f53412796952414898a6b99", + "name": "someuser1", + "links": { + "self": "http://example.com/identity/v3/users/514a66612f53412796952414898a6b99" + }, + "password_expires_at": "2016-07-07T15:32:17.000000" + }, + { + "domain_id": "default", + "enabled": true, + "id": "ce8a21d43bc64ce6840346f0a14a7fa9", + "name": "someuser4", + "links": { + "self": "http://example.com/identity/v3/users/ce8a21d43bc64ce6840346f0a14a7fa9" + }, + "password_expires_at": "2016-10-09T00:21:04.000000" + } + ] + } + + +**Query list of users whose password will expire after a given timestamp** + +.. code-block:: bash + + GET /v3/users?password_expires_at=gt:2016-10-14T15:30:22Z + +**Response** + +.. code-block:: json + + { + "links": { + "next": null, + "previous": null, + "self": "http://example.com/identity/v3/users" + }, + "users": [ + { + "domain_id": "default", + "enabled": false, + "id": "514a66612f53412796952414898a6b99", + "name": "someuser1", + "links": { + "self": "http://example.com/identity/v3/users/514a66612f53412796952414898a6b99" + }, + "password_expires_at": "2016-10-17T15:32:17.000000" + } + ] + } + + + +Alternatives +------------ + +Operators can directly query the SQL backend for users whose password has +expired by checking the ``password_expires_at`` field. + +Security Impact +--------------- + +None. The added API change has no additional security impact. + +Notifications Impact +-------------------- + +No additional notification will be added for this query. + +Other End User Impact +--------------------- + +None. There will be no additional end user impact. + +Performance Impact +------------------ + +This call may fail if there is a very large number of users since pagination +is currently not supported. + +Other Deployer Impact +--------------------- + +None. The added API change has no additional deployer impact. + +Developer Impact +---------------- + +None. The added API change has no additional developer impact. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + gagehugo + +Other contributors: + lamt + +Work Items +---------- + +* Implement new user query. +* Implement bindings in ``python-keystoneclient``. +* Implement unit tests. +* Document new user query usage. + +Dependencies +============ + +This blueprint depends on the following: + +* `PCI-DSS blueprint `_ + +Documentation Impact +==================== + +Documentation in `api-ref` will be updated to include the added query +parameter and its usage. + +References +========== + +* `Midcycle Etherpad `_