Complete OS-TRUST API documentation

Updated /v3/OS-TRUST API documentation in api-ref.

Co-Authored-By: Steve Martinelli <s.martinelli@gmail.com>
Closes-Bug: #1601924
Change-Id: Id3e915a72240b8edf2c0ff3c5f5fea32ac159536

api-ref/source/v3-ext/parameters.yaml

@@ -67,6 +67,12 @@ service_id:
   in: path
   required: false
   type: string
+trust_id:
+  description: |
+    The trust ID.
+  in: path
+  required: false
+  type: string
 user_id:
   description: |
     The UUID of the user.
@@ -77,6 +83,14 @@ user_id:
 # variables in query
 
 # variables in body
+allow_redelegation:
+  description: |
+    If set to `true` then a trust between a ``trustor`` and any third-party
+    user may be issued by the ``trustee`` just like a regular trust.
+    If set to `false`, stops further redelegation. `false` by default.
+  in: body
+  required: false
+  type: boolean
 blob:
   description: |
     The policy rule itself, as a serialized blob.
@@ -121,9 +135,13 @@ id_2:
   type: string
 impersonation:
   description: |
-    The impersonation flag. Default is false.
+    If set to `true`, then the user attribute of tokens generated based on the
+    trust will represent that of the ``trustor`` rather than the ``trustee``,
+    thus allowing the ``trustee`` to impersonate the ``trustor``. If impersonation
+    is set to `false`, then the token’s user attribute will represent that of the
+    ``trustee``.
   in: body
-  required: false
+  required: true
   type: boolean
 interface:
   description: |
@@ -138,7 +156,7 @@ interface:
   type: string
 links:
   description: |
-    Trust links.
+    A links object.
   in: body
   required: true
   type: object
@@ -213,6 +231,37 @@ project_id_1:
   in: body
   required: true
   type: string
+redelegated_trust_id:
+  description: |
+    Returned with redelegated trust provides information about the predecessor
+    in the trust chain.
+  in: body
+  required: false
+  type: string
+redelegation_count:
+  description: |
+    Specifies the maximum remaining depth of the redelegated trust chain.
+    Each subsequent trust has this field decremented by `1` automatically.
+    The initial ``trustor`` issuing new trust that can be redelegated, must
+    set ``allow_redelegation`` to `true` and may set ``redelegation_count``
+    to an integer value less than or equal to ``max_redelegation_count``
+    configuration parameter in order to limit the possible length of derivated
+    trust chains. The trust issued by the trustor using a project-scoped token
+    (not redelegating), in which ``allow_redelegation`` is set to `true` (the new
+    trust is redelegatable), will be populated with the value specified in the
+    ``max_redelegation_count`` configuration parameter if ``redelegation_count``
+    is not set or set to `null`. If ``allow_redelegation`` is set to `false`
+    then ``redelegation_count`` will be set to `0` in the trust.
+
+    If the trust is being issued by the ``trustee`` of a redelegatable trust-scoped
+    token (redelegation case) then ``redelegation_count`` should not be set, as it
+    will automatically be set to the value in the redelegatable trust-scoped token
+    decremented by `1`. Note, if the resulting value is `0`, this means that the new
+    trust will not be redelegatable, regardless of the value of ``allow_redelegation``.
+
+  in: body
+  required: false
+  type: integer
 region:
   description: |
     (Deprecated in v3.2) The geographic location of
@@ -222,7 +271,11 @@ region:
   type: string
 remaining_uses:
   description: |
-    Remaining uses flag. Default is null.
+    Specifies how many times the trust can be used to obtain a token. This value
+    is decreased each time a token is issued through the trust. Once it reaches
+    `0`, no further tokens will be issued through the trust. The default value is
+    `null`, meaning there is no limit on the number of tokens issued through the
+    trust. If redelegation is enabled it must not be set.
   in: body
   required: false
   type: boolean
@@ -265,18 +318,61 @@ trust:
   in: body
   required: true
   type: object
+trust_expires_at:
+  description: |
+    Specifies the expiration time of the trust. A trust may be revoked ahead of
+    expiration. If the value represents a time in the past, the trust is deactivated.
+    In the redelegation case it must not exceed the value of the corresponding
+    ``expires_at`` field of the redelegated trust or it may be omitted, then the
+    ``expires_at`` value is copied from the redelegated trust.
+  in: body
+  required: false
+  type: string
+trust_links:
+  description: |
+    A trust links object. Includes ``next``, ``previous``, and ``self`` links for trusts.
+  in: body
+  required: true
+  type: object
+trust_project_id:
+  description: |
+    Identifies the project upon which the trustor is delegating authorization.
+  in: body
+  required: false
+  type: string
+trust_roles:
+  description: |
+    Specifies the subset of the trustor’s roles on the ``project_id`` to be granted
+    to the ``trustee`` when the token is consumed. The ``trustor`` must already be
+    granted these roles in the project referenced by the ``project_id`` attribute.
+    If redelegation is used (when trust-scoped token is used and consumed trust has
+    ``allow_redelegation`` set to `true`) this parameter should contain redelegated
+    trust’s roles only.
+
+    Roles are only provided when the trust is created, and are subsequently available
+    as a separate read-only collection. Each role can be specified by either ``id`` or
+    ``name``.
+  in: body
+  required: false
+  type: list
 trustee_user_id:
   description: |
-    The trustee user ID.
+    Represents the user who is capable of consuming the trust.
   in: body
   required: true
   type: string
 trustor_user_id:
   description: |
-    The trustor user ID.
+    Represents the user who created the trust, and who’s authorization is being delegated.
   in: body
   required: true
   type: string
+trusts:
+  description: |
+    An array of trust objects.
+  in: body
+  required: true
+  type: array
 type:
   description: |
     The MIME media type of the serialized policy

api-ref/source/v3-ext/samples/OS-TRUST/trust-auth-redelegated-response.json

@@ -0,0 +1,45 @@
+{
+    "token": {
+        "expires_at": "2013-02-27T18:30:59.999999Z",
+        "issued_at": "2013-02-27T16:30:59.999999Z",
+        "methods": [
+            "password"
+        ],
+        "OS-TRUST:trust": {
+            "id": "fe0aef",
+            "impersonation": false,
+            "redelegated_trust_id": "3ba234",
+            "redelegation_count": 2,
+            "links": {
+                "self": "http://identity:35357/v3/trusts/fe0aef"
+            },
+            "trustee_user": {
+                "id": "0ca8f6",
+                "links": {
+                    "self": "http://identity:35357/v3/users/0ca8f6"
+                }
+            },
+            "trustor_user": {
+                "id": "bd263c",
+                "links": {
+                    "self": "http://identity:35357/v3/users/bd263c"
+                }
+            }
+        },
+        "user": {
+            "domain": {
+                "id": "1789d1",
+                "links": {
+                    "self": "http://identity:35357/v3/domains/1789d1"
+                },
+                "name": "example.com"
+            },
+            "email": "joe@example.com",
+            "id": "0ca8f6",
+            "links": {
+                "self": "http://identity:35357/v3/users/0ca8f6"
+            },
+            "name": "Joe"
+        }
+    }
+}

api-ref/source/v3-ext/samples/OS-TRUST/trust-auth-request.json

@@ -0,0 +1,17 @@
+{
+    "auth": {
+        "identity": {
+            "methods": [
+                "token"
+            ],
+            "token": {
+                "id": "e80b74"
+            }
+        },
+        "scope": {
+            "OS-TRUST:trust": {
+                "id": "de0945a"
+            }
+        }
+    }
+}

api-ref/source/v3-ext/samples/OS-TRUST/trust-auth-trust-response.json

@@ -0,0 +1,43 @@
+{
+    "token": {
+        "expires_at": "2013-02-27T18:30:59.999999Z",
+        "issued_at": "2013-02-27T16:30:59.999999Z",
+        "methods": [
+            "password"
+        ],
+        "OS-TRUST:trust": {
+            "id": "fe0aef",
+            "impersonation": false,
+            "links": {
+                "self": "http://identity:35357/v3/trusts/fe0aef"
+            },
+            "trustee_user": {
+                "id": "0ca8f6",
+                "links": {
+                    "self": "http://identity:35357/v3/users/0ca8f6"
+                }
+            },
+            "trustor_user": {
+                "id": "bd263c",
+                "links": {
+                    "self": "http://identity:35357/v3/users/bd263c"
+                }
+            }
+        },
+        "user": {
+            "domain": {
+                "id": "1789d1",
+                "links": {
+                    "self": "http://identity:35357/v3/domains/1789d1"
+                },
+                "name": "example.com"
+            },
+            "email": "joe@example.com",
+            "id": "0ca8f6",
+            "links": {
+                "self": "http://identity:35357/v3/users/0ca8f6"
+            },
+            "name": "Joe"
+        }
+    }
+}

api-ref/source/v3-ext/samples/OS-TRUST/trust-create-request.json

@@ -1,14 +1,15 @@
 {
     "trust": {
-        "expires_at": "2014-12-30T23:59:59.999999Z",
+        "expires_at": "2013-02-27T18:30:59.999999Z",
-        "impersonation": false,
+        "impersonation": true,
-        "project_id": "'$PROJECT_ID'",
+        "allow_redelegation": true,
+        "project_id": "ddef321",
         "roles": [
             {
-                "name": "admin"
+                "name": "member"
             }
         ],
-        "trustee_user_id": "'$DEMO_USER_ID'",
+        "trustee_user_id": "86c0d5",
-        "trustor_user_id": "'$ADMIN_USER_ID'"
+        "trustor_user_id": "a0fdfd"
     }
 }

api-ref/source/v3-ext/samples/OS-TRUST/trust-create-response.json

@@ -1,28 +1,29 @@
 {
     "trust": {
-        "expires_at": "2014-12-30T23:59:59.999999Z",
+        "expires_at": "2013-02-27T18:30:59.999999Z",
-        "id": "394998fa61f14736b1f0c1f322882949",
+        "id": "1ff900",
-        "impersonation": false,
+        "impersonation": true,
+        "redelegation_count": 10,
         "links": {
-            "self": "http://localhost:5000/v3/OS-TRUST/trusts/394998fa61f14736b1f0c1f322882949"
+            "self": "http://identity:35357/v3/OS-TRUST/trusts/1ff900"
         },
-        "project_id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
+        "project_id": "ddef321",
         "remaining_uses": null,
         "roles": [
             {
-                "id": "c703057be878458588961ce9a0ce686b",
+                "id": "ed7b78",
                 "links": {
-                    "self": "http://localhost:5000/v3/roles/c703057be878458588961ce9a0ce686b"
+                    "self": "http://identity:35357/v3/roles/ed7b78"
                 },
-                "name": "admin"
+                "name": "member"
             }
         ],
         "roles_links": {
             "next": null,
             "previous": null,
-            "self": "http: //localhost:5000/v3/OS-TRUST/trusts/394998fa61f14736b1f0c1f322882949/roles"
+            "self": "http://identity:35357/v3/OS-TRUST/trusts/1ff900/roles"
         },
-        "trustee_user_id": "269348fdd9374b8885da1418e0730af1",
+        "trustee_user_id": "86c0d5",
-        "trustor_user_id": "3ec3164f750146be97f21559ee4d9c51"
+        "trustor_user_id": "a0fdfd"
     }
 }

api-ref/source/v3-ext/samples/OS-TRUST/trust-get-response.json

@@ -0,0 +1,27 @@
+{
+    "trust": {
+        "id": "987fe8",
+        "expires_at": "2013-02-27T18:30:59.999999Z",
+        "impersonation": true,
+        "links": {
+            "self": "http://identity:35357/v3/OS-TRUST/trusts/987fe8"
+        },
+        "roles": [
+            {
+                "id": "ed7b78",
+                "links": {
+                    "self": "http://identity:35357/v3/roles/ed7b78"
+                },
+                "name": "member"
+            }
+        ],
+        "roles_links": {
+            "next": null,
+            "previous": null,
+            "self": "http://identity:35357/v3/OS-TRUST/trusts/1ff900/roles"
+        },
+        "project_id": "0f1233",
+        "trustee_user_id": "be34d1",
+        "trustor_user_id": "56ae32"
+    }
+}

api-ref/source/v3-ext/samples/OS-TRUST/trust-get-role-delegated-response.json

@@ -0,0 +1,9 @@
+{
+    "role": {
+        "id": "c1648e",
+        "links": {
+            "self": "http://identity:35357/v3/roles/c1648e"
+        },
+        "name": "manager"
+    }
+}

api-ref/source/v3-ext/samples/OS-TRUST/trust-list-response.json

@@ -0,0 +1,25 @@
+{
+    "trusts": [
+        {
+            "id": "1ff900",
+            "expires_at": "2013-02-27T18:30:59.999999Z",
+            "impersonation": true,
+            "links": {
+                "self": "http://identity:35357/v3/OS-TRUST/trusts/1ff900"
+            },
+            "project_id": "0f1233",
+            "trustee_user_id": "86c0d5",
+            "trustor_user_id": "a0fdfd"
+        },
+        {
+            "id": "f4513a",
+            "impersonation": false,
+            "links": {
+                "self": "http://identity:35357/v3/OS-TRUST/trusts/f45513a"
+            },
+            "project_id": "0f1233",
+            "trustee_user_id": "86c0d5",
+            "trustor_user_id": "3cd2ce"
+        }
+    ]
+}

api-ref/source/v3-ext/samples/OS-TRUST/trust-list-roles-delegated-response.json

@@ -0,0 +1,18 @@
+{
+    "roles": [
+        {
+            "id": "c1648e",
+            "links": {
+                "self": "http://identity:35357/v3/roles/c1648e"
+            },
+            "name": "manager"
+        },
+        {
+            "id": "ed7b78",
+            "links": {
+                "self": "http://identity:35357/v3/roles/ed7b78"
+            },
+            "name": "member"
+        }
+    ]
+}

api-ref/source/v3-ext/trust.inc

@@ -4,23 +4,91 @@
  OS-TRUST API
 ==============
 
-Creates a trust.
+Trusts provide project-specific role delegation between users, with optional impersonation.
 
-A trust is an OpenStack Identity extension that enables delegation
+API Resources
-and, optionally, impersonation through ``keystone``. A trust
+=============
-extension defines a relationship between a trustor and trustee. A
-trustor is the user who delegates a limited set of their own rights
-to another user, known as the trustee, for a limited time.
 
-The trust can eventually enable the trustee to impersonate the
+Trusts
-trustor. For security reasons, some safety measures are added. For
+------
-example, if a trustor loses a given role, the API automatically
+
-revokes any trusts and the related tokens that the user issued with
+A trust represents a user’s (the `trustor`) authorization to delegate
-that role.
+roles to another user (the `trustee`), and optionally allow the trustee
+to impersonate the trustor. After the trustor has created a trust, the
+trustee can specify the trust’s id attribute as part of an authentication
+request to then create a token representing the delegated authority of the trustor.
+
+The trust contains constraints on the delegated attributes. A token created
+based on a trust will convey a subset of the trustor’s roles on the specified
+project. Optionally, the trust may only be valid for a specified time period,
+as defined by ``expires_at``. If no ``expires_at`` is specified, then the trust is
+valid until it is explicitly revoked.
+
+The ``impersonation`` flag allows the trustor to optionally delegate impersonation
+abilities to the trustee. To services validating the token, the trustee will
+appear as the trustor, although the token will also contain the ``impersonation`` flag
+to indicate that this behavior is in effect.
+
+A ``project_id`` may not be specified without at least one role, and vice versa.
+In other words, there is no way of implicitly delegating all roles to a trustee, in
+order to prevent users accidentally creating trust that are much more broad in scope
+than intended. A trust without a ``project_id`` or any delegated roles is unscoped,
+and therefore does not represent authorization on a specific resource.
+
+Trusts are immutable. If the trustee or trustor wishes to modify the attributes
+of the trust, they should create a new trust and delete the old trust. If a trust
+is deleted, any tokens generated based on the trust are immediately revoked.
+
+If the trustor loses access to any delegated attributes, the trust becomes immediately
+invalid and any tokens generated based on the trust are immediately revoked.
+
+Trusts can also be chained, meaning, a trust can be created by using a trust scoped
+token.
 
 For more information, see `Use trusts <http://docs.openstack.org
 /admin-guide/keystone_use_trusts.html>`_.
 
+Consuming a trust
+=================
+
+.. rest_method::  POST /v3/auth/tokens
+
+Consuming a trust effectively assumes the scope as delegated in the trust. No
+other scope attributes may be specified.
+
+The user specified by authentication must match the trust’s ``trustee_user_id``
+attribute.
+
+If the trust has the ``impersonation`` attribute set to `true`, then the resulting
+token’s user attribute will also represent the trustor, rather than the
+authenticating user (the trustee).
+
+Request Example
+----------------
+
+.. literalinclude:: samples/OS-TRUST/trust-auth-request.json
+   :language: javascript
+
+A token created from a trust will have an ``OS-TRUST:trust`` section containing the
+``id`` of the trust, the ``impersonation`` flag, the ``trustee_user_id`` and the
+``trustor_user_id``.
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-TRUST/trust-auth-trust-response.json
+   :language: javascript
+
+A token created from a redelegated trust will have an ``OS-TRUST:trust`` section
+containing the same fields as a regular trust token, only ``redelegated_trust_id`` and
+``redelegation_count`` are added.
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-TRUST/trust-auth-redelegated-response.json
+   :language: javascript
+
 
 Create trust
 ============
@@ -29,26 +97,32 @@ Create trust
 
 Creates a trust.
 
-Error response codes:201,413,415,405,404,403,401,400,503,409,
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts
+
+Response codes: 201, 400, 401, 403, 404, 405, 409, 413, 415, 503
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
-   - impersonation: impersonation
    - trust: trust
-   - trustor_user_id: trustor_user_id
+   - impersonation: impersonation
-   - name: name
-   - roles: roles
-   - oauth_expires_at: oauth_expires_at
-   - remaining_uses: remaining_uses
    - trustee_user_id: trustee_user_id
-   - project_id: project_id
+   - trustor_user_id: trustor_user_id
+   - allow_redelegation: allow_redelegation
+   - expires_at: trust_expires_at
+   - project_id: trust_project_id
+   - redelegated_trust_id: redelegated_trust_id
+   - redelegation_count: redelegation_count
+   - remaining_uses: remaining_uses
+   - roles: trust_roles
 
 Request Example
 ---------------
 
+Status: 201 Created
+
 .. literalinclude:: samples/OS-TRUST/trust-create-request.json
    :language: javascript
 
@@ -57,15 +131,236 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - impersonation: impersonation
-   - roles_links: roles_links
    - trust: trust
-   - trustor_user_id: trustor_user_id
-   - name: name
-   - links: links
-   - oauth_expires_at: oauth_expires_at
-   - remaining_uses: remaining_uses
-   - trustee_user_id: trustee_user_id
-   - roles: roles
-   - project_id: project_id
    - id: id
+   - impersonation: impersonation
+   - trustee_user_id: trustee_user_id
+   - trustor_user_id: trustor_user_id
+   - allow_redelegation: allow_redelegation
+   - expires_at: trust_expires_at
+   - project_id: trust_project_id
+   - redelegated_trust_id: redelegated_trust_id
+   - redelegation_count: redelegation_count
+   - remaining_uses: remaining_uses
+   - roles: trust_roles
+   - roles_links: roles_links
+   - links: trust_links
+
+Response Example
+----------------
+
+Status: 201 Created
+
+.. literalinclude:: samples/OS-TRUST/trust-create-response.json
+   :language: javascript
+
+List trusts
+===========
+
+.. rest_method:: GET /v3/OS-TRUST/trusts
+
+Lists all trusts.
+
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts
+
+Response codes: 200, 400, 401, 403, 404, 405, 413, 503
+
+The following optional query strings are supported:
+
+- ``page``
+- ``per_page`` (default 30)
+- ``trustor_user_id``
+- ``trustee_user_id``
+
+In order to list trusts for a given trustor, filter the collection using a query string
+(e.g., ``?trustor_user_id={user_id}``).
+
+::
+
+   GET /v3/OS-TRUST/trusts?trustor_user_id=a0fdfd
+
+In order to list trusts for a given trustee, filter the collection using a query string
+(e.g., ``?trustee_user_id={user_id}``).
+
+::
+
+   GET /v3/OS-TRUST/trusts?trustee_user_id=86c0d5
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust: trust
+   - id: id
+   - impersonation: impersonation
+   - trustee_user_id: trustee_user_id
+   - trustor_user_id: trustor_user_id
+   - allow_redelegation: allow_redelegation
+   - expires_at: trust_expires_at
+   - project_id: trust_project_id
+   - redelegated_trust_id: redelegated_trust_id
+   - redelegation_count: redelegation_count
+   - remaining_uses: remaining_uses
+   - roles: trust_roles
+   - roles_links: roles_links
+   - links: trust_links
+
+Response Example
+----------------
+
+Status: 200 OK
+
+.. literalinclude:: samples/OS-TRUST/trust-list-response.json
+   :language: javascript
+
+
+Get trust
+=========
+
+.. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}
+
+Gets the trust information for ``{trust_id}``.
+
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust
+
+Response codes: 200, 400, 401, 403, 404, 405, 413, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust_id: trust_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust: trust
+   - id: id
+   - impersonation: impersonation
+   - trustee_user_id: trustee_user_id
+   - trustor_user_id: trustor_user_id
+   - allow_redelegation: allow_redelegation
+   - expires_at: trust_expires_at
+   - project_id: trust_project_id
+   - redelegated_trust_id: redelegated_trust_id
+   - redelegation_count: redelegation_count
+   - remaining_uses: remaining_uses
+   - roles: trust_roles
+   - roles_links: roles_links
+   - links: trust_links
+
+Response Example
+----------------
+
+Status: 200 OK
+
+.. literalinclude:: samples/OS-TRUST/trust-get-response.json
+   :language: javascript
+
+
+Delete trust
+============
+
+.. rest_method:: DELETE /v3/OS-TRUST/trusts/{trust_id}
+
+Deletes a trust with ``{trust_id}``.
+
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust
+
+Response codes: 204, 400, 401, 403, 404, 405, 409, 413, 415, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust_id: trust_id
+
+Response Example
+----------------
+
+Status: 204 No Content
+
+
+List roles delegated by a trust
+===============================
+
+.. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles
+
+Lists roles delegated by a trust with ``{trust_id}``.
+
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles
+
+Response codes: 200, 400, 401, 403, 404, 405, 413, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust_id: trust_id
+
+Response Example
+----------------
+
+Status: 200 OK
+
+.. literalinclude:: samples/OS-TRUST/trust-list-roles-delegated-response.json
+   :language: javascript
+
+
+Check if a role is delegated by a trust
+=======================================
+
+.. rest_method:: HEAD /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}
+
+Checks if a role is delegated by a trust.
+
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role
+
+Response Codes: 200, 400, 401, 403, 404, 405, 413, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust_id: trust_id
+   - role_id: role_id
+
+Response Example
+----------------
+
+Status: 200 OK
+
+
+Get role delegated by a trust
+=============================
+
+.. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}
+
+Gets a role with delegated by a trust.
+
+Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role
+
+Response Codes: 200, 400, 401, 403, 404, 405, 413, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - trust_id: trust_id
+   - role_id: role_id
+
+Response Example
+----------------
+
+Status: 200 OK
+
+.. literalinclude:: samples/OS-TRUST/trust-get-role-delegated-response.json
+   :language: javascript