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

@@ -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
 =================
 

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.

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"
+        }
+    ]
+}
+

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"
+        }
+    ]
+}

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
 ===========