Update api-ref for federated objects in user

Also includes a release note.

Change-Id: I72a5d461488b50f20b59d1288016514a2b8f71e5
Closes-Bug: 1816076

api-ref/source/v3/index.rst

@@ -33,6 +33,7 @@ What's New in Version 3.14 (Ussuri)
 - New attribute ``authorization_ttl`` for identity providers
 - New attribute ``membership_expires_at`` when listing groups for a user
 - Ability to persist group memberships carried through mapping for a federated user
+- Added the ability to create, update and delete federated attributes for a user
 
 ==================================
 What's New in Version 3.13 (Train)

api-ref/source/v3/parameters.yaml

@@ -1021,6 +1021,42 @@ extra_request_body:
   in: body
   required: false
   type: string
+federated_in_request_body:
+  description: |
+    List of federated objects associated with a user. Each object in the list
+    contains the ``idp_id`` and ``protocols``. ``protocols`` is a list of
+    objects, each of which contains ``protocol_id`` and ``unique_id`` of
+    the protocol and user respectively. For example::
+
+      "federated": [
+        {
+          "idp_id": "efbab5a6acad4d108fec6c63d9609d83",
+          "protocols": [
+            {"protocol_id": mapped, "unique_id": "test@example.com"}
+          ]
+        }
+      ]
+  in: body
+  required: false
+  type: list
+federated_in_response_body:
+  description: |
+    List of federated objects associated with a user. Each object in the list
+    contains the ``idp_id`` and ``protocols``. ``protocols`` is a list of
+    objects, each of which contains ``protocol_id`` and ``unique_id`` of
+    the protocol and user respectively. For example::
+
+      "federated": [
+        {
+          "idp_id": "efbab5a6acad4d108fec6c63d9609d83",
+          "protocols": [
+            {"protocol_id": "mapped", "unique_id": "test@example.com"}
+          ]
+        }
+      ]
+  in: body
+  required: false
+  type: list
 group:
   description: |
     A ``group`` object

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

@@ -3,6 +3,17 @@
         "default_project_id": "263fd9",
         "domain_id": "1789d1",
         "enabled": true,
+        "federated": [
+            {
+                "idp_id": "efbab5a6acad4d108fec6c63d9609d83",
+                "protocols": [
+                    {
+                        "protocol_id": "mapped",
+                        "unique_id": "test@example.com"
+                    }
+                ]
+            }
+        ],
         "name": "James Doe",
         "password": "secretsecret",
         "description": "James Doe user",

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

@@ -5,6 +5,17 @@
         "domain_id": "1789d1",
         "email": "jdoe@example.com",
         "enabled": true,
+        "federated": [
+            {
+                "idp_id": "efbab5a6acad4d108fec6c63d9609d83",
+                "protocols": [
+                    {
+                        "protocol_id": "mapped",
+                        "unique_id": "test@example.com"
+                    }
+                ]
+            }
+        ],
         "id": "ff4e51",
         "links": {
             "self": "https://example.com/identity/v3/users/ff4e51"

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

@@ -3,6 +3,7 @@
         "default_project_id": "263fd9",
         "domain_id": "1789d1",
         "enabled": true,
+        "federated": [],
         "id": "9fe1d3",
         "links": {
             "self": "https://example.com/identity/v3/users/9fe1d3"

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

@@ -3,6 +3,7 @@
         "default_project_id": "263fd9",
         "domain_id": "1789d1",
         "enabled": true,
+        "federated": [],
         "id": "ff4e51",
         "links": {
             "self": "https://example.com/identity/v3/users/ff4e51"

api-ref/source/v3/users.inc

@@ -100,6 +100,7 @@ Parameters
    - user: user_object
    - default_project_id: default_project_id_request_body
    - domain_id: user_domain_id_request_body
+   - federated: federated_in_request_body
    - enabled: enabled_user_request_body
    - name: user_name_create_request_body
    - password: password_request_body
@@ -124,6 +125,7 @@ Parameters
    - default_project_id: default_project_id_response_body
    - domain_id: domain_id_response_body
    - enabled: enabled_user_response_body
+   - federated: federated_in_response_body
    - id: id_user_body
    - links: links_user
    - name: user_name_response_body
@@ -182,6 +184,7 @@ Parameters
    - default_project_id: default_project_id_response_body
    - domain_id: domain_id_response_body
    - enabled: enabled_user_response_body
+   - federated: federated_in_response_body
    - id: id_user_body
    - links: links_user
    - name: user_name_response_body
@@ -233,6 +236,7 @@ Parameters
    - default_project_id: default_project_id_update_body
    - domain_id: user_domain_id_update_body
    - enabled: enabled_user_update_body
+   - federated: federated_in_request_body
    - name: user_name_update_body
    - password: user_update_password_body
    - options: user_options_request_body
@@ -255,6 +259,7 @@ Parameters
    - default_project_id: default_project_id_response_body
    - domain_id: domain_id_response_body
    - enabled: enabled_user_response_body
+   - federated: federated_in_response_body
    - id: id_user_body
    - links: links_user
    - name: user_name_response_body

releasenotes/notes/bug-1816076-ba39508e6ade529e.yaml

@@ -0,0 +1,15 @@
+---
+features:
+  - |
+    `GET /v3/users/{user_id}` now returns a federated object associated with
+    the user if any. `POST /v3/users` allows an operator to add a list of
+    federated objects to associate with the user. `PATCH /v3/users` allows the operator
+    to update a users associated federated objects.
+
+upgrade:
+  - |
+    If you have a custom implementation for the shadow users backend, you will
+    need to implement the new methods:
+    ``delete_federated_object``, ``create_federated_object``,
+    ``get_federated_objects``. These methods are needed to support federated
+    attributes via the user API.