Update api-ref to include user options

This commit formally adds resources options for users to the
identity API reference. Descriptions of the behavior provided
by each option is left to the administrator guide, but the
examples here at least show how to access and use the options
implemented for users.

Co-Authored-By: Lance Bragstad <lbragstad@gmail.com>
Closes-Bug: #1792026
Change-Id: I5af3761e42dfe544431ae0bd4b2c032391023bcc

api-ref/source/v3/parameters.yaml

@@ -1977,6 +1977,25 @@ user_object:
   in: body
   required: true
   type: object
+user_options_request_body:
+  description: |
+    The resource options for the user. Available resource options are
+    ``ignore_change_password_upon_first_use``, ``ignore_password_expiry``,
+    ``ignore_lockout_failure_attempts``, ``lock_password``,
+    ``multi_factor_auth_enabled``, and ``multi_factor_auth_rules``.
+  in: body
+  required: false
+  type: object
+user_options_response_body:
+  description: |
+    The resource options for the user. Only present in the response if set on
+    the user entity. Available resource options are
+    ``ignore_change_password_upon_first_use``, ``ignore_password_expiry``,
+    ``ignore_lockout_failure_attempts``, ``lock_password``,
+    ``multi_factor_auth_enabled``, and ``multi_factor_auth_rules``.
+  in: body
+  required: false
+  type: object
 user_password_update_body:
   description: |
     The new password for the user.

api-ref/source/v3/samples/admin/user-create-request.json

@@ -6,6 +6,9 @@
         "name": "James Doe",
         "password": "secretsecret",
         "description": "James Doe user",
-        "email": "jdoe@example.com"
+        "email": "jdoe@example.com",
+        "options": {
+            "ignore_password_expiry": true
+        }
     }
 }

api-ref/source/v3/samples/admin/user-create-response.json

@@ -10,6 +10,9 @@
             "self": "https://example.com/identity/v3/users/ff4e51"
         },
         "name": "James Doe",
+        "options": {
+            "ignore_password_expiry": true
+        },
         "password_expires_at": "2016-11-06T15:32:17.000000"
     }
 }

api-ref/source/v3/samples/admin/user-update-request.json

@@ -1,6 +1,9 @@
 {
     "user": {
         "default_project_id": "263fd9",
-        "enabled": true
+        "enabled": true,
+        "options": {
+            "ignore_lockout_failure_attempts": true
+        }
     }
 }

api-ref/source/v3/samples/admin/user-update-response.json

@@ -8,6 +8,9 @@
             "self": "https://example.com/identity/v3/users/ff4e51"
         },
         "name": "jamesdoe",
+        "options": {
+            "ignore_lockout_failure_attempts": true
+        },
         "password_expires_at": "2016-11-06T15:32:17.000000"
     }
 }

api-ref/source/v3/users.inc

@@ -104,6 +104,7 @@ Parameters
    - name: user_name_create_request_body
    - password: password_request_body
    - extra: extra_request_body
+   - options: user_options_request_body
 
 Example
 ~~~~~~~
@@ -127,6 +128,7 @@ Parameters
    - links: links_user
    - name: user_name_response_body
    - password_expires_at: password_expires_at
+   - options: user_options_response_body
 
 Status Codes
 ~~~~~~~~~~~~
@@ -233,6 +235,7 @@ Parameters
    - enabled: enabled_user_update_body
    - name: user_name_update_body
    - password: user_update_password_body
+   - options: user_options_request_body
 
 Example
 ~~~~~~~
@@ -256,6 +259,7 @@ Parameters
    - links: links_user
    - name: user_name_response_body
    - password_expires_at: password_expires_at
+   - options: user_options_response_body
 
 Status Codes
 ~~~~~~~~~~~~

releasenotes/notes/bug-1792026-2de8345a89e2256b.yaml

@@ -0,0 +1,9 @@
+---
+fixes:
+  - |
+    [`bug 1792026 <https://bugs.launchpad.net/keystone/+bug/1792026>`_]
+    Formal documentation for user resource options has been added to the
+    administrator guide and the API reference. This documentation helps
+    describe how user options can improve user experience, namely for
+    deployments looking to offer flexibility around PCI-DSS security
+    requirements, among other things.