You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
375 lines
9.7 KiB
375 lines
9.7 KiB
.. -*- rst -*- |
|
|
|
============== |
|
OS-TRUST API |
|
============== |
|
|
|
Trusts provide project-specific role delegation between users, with optional impersonation. |
|
|
|
API Resources |
|
============= |
|
|
|
Trusts |
|
------ |
|
|
|
A trust represents a user’s (the `trustor`) authorization to delegate |
|
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 |
|
============ |
|
|
|
.. rest_method:: POST /v3/OS-TRUST/trusts |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts`` |
|
|
|
Creates a trust. |
|
|
|
Relationship: http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts |
|
|
|
Normal response codes: 201 |
|
Error response codes: 413, 415, 405, 404, 403, 401, 400, 503, 409 |
|
|
|
Request |
|
------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust: trust |
|
- 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 |
|
|
|
Request Example |
|
--------------- |
|
|
|
Status: 201 Created |
|
|
|
.. literalinclude:: samples/OS-TRUST/trust-create-request.json |
|
:language: javascript |
|
|
|
Response Parameters |
|
------------------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust: trust |
|
- id: trust_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 |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts`` |
|
|
|
Lists all trusts. |
|
|
|
Normal response codes: 200 |
|
Error response codes: 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: trust_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} |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust`` |
|
|
|
Gets the trust information for ``{trust_id}``. |
|
|
|
Normal response codes: 200 |
|
Error response codes: 400, 401, 403, 404, 405, 413, 503 |
|
|
|
Request |
|
------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust_id: trust_id_path |
|
|
|
Response Parameters |
|
------------------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust: trust |
|
- id: trust_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} |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust`` |
|
|
|
Deletes a trust with ``{trust_id}``. |
|
|
|
Normal response codes: 204 |
|
Error response codes: 400, 401, 403, 404, 405, 409, 413, 415, 503 |
|
|
|
Request |
|
------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust_id: trust_id_path |
|
|
|
Response Example |
|
---------------- |
|
|
|
Status: 204 No Content |
|
|
|
|
|
List roles delegated by a trust |
|
=============================== |
|
|
|
.. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles`` |
|
|
|
Lists roles delegated by a trust with ``{trust_id}``. |
|
|
|
Normal response codes: 200 |
|
Error response codes: 400, 401, 403, 404, 405, 413, 503 |
|
|
|
Request |
|
------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust_id: trust_id_path |
|
|
|
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} |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role`` |
|
|
|
Checks if a role is delegated by a trust. |
|
|
|
Normal response codes: 200 |
|
Error response codes: 400, 401, 403, 404, 405, 413, 503 |
|
|
|
Request |
|
------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust_id: trust_id_path |
|
- role_id: role_id_path |
|
|
|
Response Example |
|
---------------- |
|
|
|
Status: 200 OK |
|
|
|
|
|
Get role delegated by a trust |
|
============================= |
|
|
|
.. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id} |
|
|
|
Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role`` |
|
|
|
Gets a role with delegated by a trust. |
|
|
|
Normal response codes: 200 |
|
Error response codes: 400, 401, 403, 404, 405, 413, 503 |
|
|
|
Request |
|
------- |
|
|
|
.. rest_parameters:: parameters.yaml |
|
|
|
- trust_id: trust_id_path |
|
- role_id: role_id_path |
|
|
|
Response Example |
|
---------------- |
|
|
|
Status: 200 OK |
|
|
|
.. literalinclude:: samples/OS-TRUST/trust-get-role-delegated-response.json |
|
:language: javascript
|
|
|