From 1eb38e46e7ac079c1089f6e2e49758d7d43588bd Mon Sep 17 00:00:00 2001 From: Samuel Pilla Date: Fri, 9 Dec 2016 10:22:49 -0600 Subject: [PATCH] API Documentation for user password expires The api documentation for the following queries: /v3/users?password_expires_at={operator}:{timestamp} /v3/groups/{group_id}/users?password_expires_at={operator}:{timestamp} The acceptable operators are lt, lte, gt, gte, eq, and neq. They allow for querying for a range of timestamps rather than an exact time for password expiration. Examples: - GET /v3/users?password_expires_at=lt:2016-11-06T15:32:17Z - GET /v3/groups/079c578fd99b428ab61fcd4c9bd88ecd/users?password_expires_at=gt:2016-12-08T22:02:00Z Partially-Implements: bp pci-dss-query-password-expired-users Parent-Id: If0b9cc3c8af92b2ea5d41a0e8afeb78e12b7689c Change-Id: I737dd6b703cc5af16b3d748ebaeebe0fbada039e --- api-ref/source/v3/groups.inc | 75 ++++++++++++++++++ api-ref/source/v3/parameters.yaml | 26 +++++- .../users-in-group-list-password-expired.json | 20 +++++ .../admin/users-list-password-expired.json | 79 +++++++++++++++++++ api-ref/source/v3/users.inc | 72 +++++++++++++++++ 5 files changed, 270 insertions(+), 2 deletions(-) create mode 100644 api-ref/source/v3/samples/admin/users-in-group-list-password-expired.json create mode 100644 api-ref/source/v3/samples/admin/users-list-password-expired.json diff --git a/api-ref/source/v3/groups.inc b/api-ref/source/v3/groups.inc index 8620b05679..7f89349465 100644 --- a/api-ref/source/v3/groups.inc +++ b/api-ref/source/v3/groups.inc @@ -310,6 +310,81 @@ Response Example :language: javascript +List users in group based on password expiration time +===================================================== + +.. rest_method:: GET /v3/groups/{group_id}/users?password_expires_at={operator}:{timestamp} + +List users that belong to a group with a password expiring in relation +to the `timestamp` given based on the `operator`. Similar to listing +users based on password expiration time, but also filtering by +the specified group. + +The operators are: + +- lt: expiration time lower than the timestamp +- lte: expiration time lower than or equal to the timestamp +- gt: expiration time higher than the timestamp +- gte: expiration time higher than or equal to the timestamp +- eq: expiration time equal to the timestamp +- neq: expiration time not equal to the timestamp + +For example:: + + GET /v3/groups/079c578fd99b428ab61fcd4c9bd88ecd/users?password_expires_at=lt:2016-12-08T22:02:00Z + +The example would return a list of users that belong to the group with +ID `079c578fd99b428ab61fcd4c9bd88ecd1 and whose password has expired +before the given timestamp `2016-12-08T22:02:00Z`. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + - 501 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - group_id: group_id_path + - operator: operator_query + - timestamp: timestamp_query + +Response Parameters +------------------- + +Responses will contain a list of users in the group, each +represented with the response parameters described below. + +.. rest_parameters:: parameters.yaml + + - default_project_id: default_project_id_response_body + - domain_id: domain_id_response_body + - enabled: enabled_user_response_body + - id: id_user_body + - links: links_user + - name: user_name_response_body + - password_expires_at: password_expires_at + +Response Example +---------------- + +.. literalinclude:: ./samples/admin/users-in-group-list-password-expired.json + :language: javascript + + Add user to group ================= diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 9409601933..6250fa0417 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -237,7 +237,7 @@ is_domain_query: included. in: query required: false - type: boolean + type: boolen min_version: 3.6 name_user_query: description: | @@ -253,6 +253,13 @@ nocatalog: in: query required: false type: string +operator_query: + description: | + Filter used in the password_expire_at query on list users to compare time + ranges. Can be lt, lte, gt, gte, eq, or neq. + in: query + required: false + type: string parent_id_query: description: | Filters the response by a parent ID. @@ -285,6 +292,14 @@ parents_as_list: required: false type: key-only, no value expected min_version: 3.4 +password_expires_at_query: + description: | + Filter used in the user list call to determine which user passwords + expire. It can be paired with an operator for a range of time in + which passwords will expire. + in: query + required: false + type: string policy_type_query: description: | Filters the response by a MIME media type for the @@ -298,7 +313,7 @@ project_enabled_query: other than ``0`` (including no value) will be interpreted as true. in: query required: false - type: boolean + type: boolen project_name_query: description: | Filters the response by a project name. @@ -369,6 +384,13 @@ subtree_as_list: required: false type: key-only, no value expected min_version: 3.4 +timestamp_query: + description: | + Filters the response for when a user's password expires. + A valid timestamp is formatted as ``YYYY-MM-DDTHH:mm:ssZ``. + in: query + required: false + type: string user_id_query: description: | Filters the response by a user ID. diff --git a/api-ref/source/v3/samples/admin/users-in-group-list-password-expired.json b/api-ref/source/v3/samples/admin/users-in-group-list-password-expired.json new file mode 100644 index 0000000000..f9a3d1349a --- /dev/null +++ b/api-ref/source/v3/samples/admin/users-in-group-list-password-expired.json @@ -0,0 +1,20 @@ +{ + "links": { + "next": null, + "previous": null, + "self": "http://192.168.56.101/identity/v3/groups/079c578fd99b428ab61fcd4c9bd88ecd/users?password_expires_at=gt:2016-12-08T22:02:00.000000" + }, + "users": [ + { + "domain_id": "default", + "enabled": true, + "id": "b79bf79fe1f148639ab5ecec5e66e343", + "links": { + "self": "http://192.168.56.101/identity/v3/users/b79bf79fe1f148639ab5ecec5e66e343" + }, + "name": "newuser", + "password_expires_at": "2016-12-09T22:02:00.000000" + } + ] +} + diff --git a/api-ref/source/v3/samples/admin/users-list-password-expired.json b/api-ref/source/v3/samples/admin/users-list-password-expired.json new file mode 100644 index 0000000000..6f0b7f421b --- /dev/null +++ b/api-ref/source/v3/samples/admin/users-list-password-expired.json @@ -0,0 +1,79 @@ +{ + "links": { + "next": null, + "previous": null, + "self": "http://example.com/identity/v3/users" + }, + "users": [ + { + "domain_id": "default", + "enabled": true, + "id": "4ab84ab39de54f4d96eaff8f2145a7cd", + "links": { + "self": "http://example.com/identity/v3/users/4ab84ab39de54f4d96eaff8f2145a7cd" + }, + "name": "swiftusertest1", + "password_expires_at": "2016-11-06T15:32:17.000000" + }, + { + "domain_id": "default", + "enabled": true, + "id": "5acb638d15da44fc8de41b9a4bd41875", + "links": { + "self": "http://example.com/identity/v3/users/5acb638d15da44fc8de41b9a4bd41875" + }, + "name": "alt_demo", + "password_expires_at": "2016-11-06T15:32:17.000000" + }, + { + "domain_id": "default", + "enabled": true, + "id": "7596e862b1af473c8ed6ae99d35b51e3", + "links": { + "self": "http://example.com/identity/v3/users/7596e862b1af473c8ed6ae99d35b51e3" + }, + "name": "demo", + "password_expires_at": "2016-11-06T15:32:17.000000" + }, + { + "domain_id": "592ab0800d3745baaf45c610fa41950a", + "enabled": true, + "id": "9aca3883784647fe9aff3a50d922489a", + "links": { + "self": "http://example.com/identity/v3/users/9aca3883784647fe9aff3a50d922489a" + }, + "name": "swiftusertest4", + "password_expires_at": "2016-11-06T15:32:17.000000" + }, + { + "domain_id": "default", + "enabled": true, + "id": "a1251b011f9345e68c2458b841152034", + "links": { + "self": "http://example.com/identity/v3/users/a1251b011f9345e68c2458b841152034" + }, + "name": "swiftusertest3", + "password_expires_at": "2016-11-06T15:32:17.000000" + }, + { + "domain_id": "default", + "enabled": true, + "id": "ed214dc1c2c6468b926c96eca6c8aee9", + "links": { + "self": "http://example.com/identity/v3/users/ed214dc1c2c6468b926c96eca6c8aee9" + }, + "name": "glance-swift", + "password_expires_at": "2016-11-06T15:32:17.000000" + }, + { + "domain_id": "default", + "enabled": true, + "id": "f4f6587b058a4f46a00242549b430d37", + "links": { + "self": "http://example.com/identity/v3/users/f4f6587b058a4f46a00242549b430d37" + }, + "name": "swiftusertest2", + "password_expires_at": "2016-11-06T15:32:17.000000" + } + ] +} diff --git a/api-ref/source/v3/users.inc b/api-ref/source/v3/users.inc index ed6985f225..d49c94ee76 100644 --- a/api-ref/source/v3/users.inc +++ b/api-ref/source/v3/users.inc @@ -47,6 +47,7 @@ Request Parameters - domain_id: domain_id_query - enabled: enabled_user_query - name: name_user_query + - password_expires_at: password_expires_at_query Response Parameters ------------------- @@ -70,6 +71,77 @@ Response Example :language: javascript +List users based on password expiration time +============================================ + +.. rest_method:: GET /v3/users?password_expires_at={operator}:{timestamp} + +List users with a password expiring in relation to the `timestamp` given +based on the `operator`. + +The operators are: + +- lt: expiration time lower than the timestamp +- lte: expiration time lower than or equal to the timestamp +- gt: expiration time higher than the timestamp +- gte: expiration time higher than or equal to the timestamp +- eq: expiration time equal to the timestamp +- neq: expiration time not equal to the timestamp + +For example:: + + GET /v3/users?password_expires_at=lt:2016-11-06T15:32:17Z + +The example would return a list of users whose password has +expired before the given timestamp `2016-11-06T15:32:17Z`. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + - 501 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - operator: operator_query + - timestamp: timestamp_query + +Response Parameters +------------------- + +Responses will contain a list of users, each represented with the +response parameters described below. + +.. rest_parameters:: parameters.yaml + + - default_project_id: default_project_id_response_body + - domain_id: domain_id_response_body + - enabled: enabled_user_response_body + - id: id_user_body + - links: links_user + - name: user_name_response_body + - password_expires_at: password_expires_at + +Response Example +---------------- + +.. literalinclude:: ./samples/admin/users-list-password-expired.json + :language: javascript + + Create user ===========