From 863b9da54fea609534de795e74c391ce3b87e364 Mon Sep 17 00:00:00 2001 From: Steve Martinelli Date: Wed, 13 Jul 2016 06:27:19 -0700 Subject: [PATCH] Create APIs for OS-REVOKE Closes-Bug: 1532223 Change-Id: I20c4b97643bfbe9db052fc9bfc29482090cbcce7 --- api-ref/source/v3-ext/index.rst | 2 + api-ref/source/v3-ext/parameters.yaml | 111 ++++++++++++++++++ api-ref/source/v3-ext/revoke.inc | 73 ++++++++++++ .../OS-REVOKE/list-revoke-response.json | 22 ++++ 4 files changed, 208 insertions(+) create mode 100644 api-ref/source/v3-ext/revoke.inc create mode 100644 api-ref/source/v3-ext/samples/OS-REVOKE/list-revoke-response.json diff --git a/api-ref/source/v3-ext/index.rst b/api-ref/source/v3-ext/index.rst index 178ab01ea5..24d9135496 100644 --- a/api-ref/source/v3-ext/index.rst +++ b/api-ref/source/v3-ext/index.rst @@ -10,6 +10,7 @@ This page describes these Identity API v3 extensions: * `OS-INHERIT API`_ * `OS-OAUTH1 API`_ * `OS-TRUST API`_ +* `OS-REVOKE API`_ .. rest_expand_all:: @@ -17,3 +18,4 @@ This page describes these Identity API v3 extensions: .. include:: inherit.inc .. include:: oauth.inc .. include:: trust.inc +.. include:: revoke.inc diff --git a/api-ref/source/v3-ext/parameters.yaml b/api-ref/source/v3-ext/parameters.yaml index 8064fafe56..c8f64c6338 100644 --- a/api-ref/source/v3-ext/parameters.yaml +++ b/api-ref/source/v3-ext/parameters.yaml @@ -76,6 +76,15 @@ user_id: # variables in query +since: + description: | + A timestamp used to limit the list of results to events + that occurred on or after the specified time. + (RFC 1123 format date time) + in: query + required: false + type: string + # variables in body blob: description: | @@ -232,6 +241,108 @@ requested_project_id: in: body required: true type: string +revoke_audit_chain_id: + description: | + Specifies a group of tokens based upon the ``audit_id`` of the + first token in the chain. + + If a revocation event specifies the ``audit_chain_id`` any + token that is part of the token chain (based upon the original + token at the start of the chain) will be revoked, including + the original token at the start of the chain. + + If an event is issued for ``audit_chain_id`` then the event cannot + contain an ``audit_id``. + in: body + required: true + type: string +revoke_audit_id: + description: | + Specifies the unique identifier (UUID) assigned to the token + itself. + + This will revoke a single token only. This attribute mirrors + the use of the Token Revocation List (the mechanism used + prior to revocation events) but does not utilize data that + could convey authorization (the token id). + + If an event is issued for ``audit_id`` then the event cannot + contain an ``audit_chain_id``. + in: body + required: true + type: string +revoke_consumer_id: + description: | + Revoke tokens issued to a specific OAuth consumer, as part + of the OS-OAUTH1 API extension. + in: body + required: true + type: string +revoke_domain_id: + description: | + Revoke tokens scoped to a particular domain. + in: body + required: true + type: string +revoke_events: + description: | + List of recovation events. + in: body + required: true + type: string +revoke_expires_at: + description: | + Specifies the exact expiration time of one or more tokens to + be revoked. + + This attribute is useful for revoking chains of tokens, such + as those produced when re-scoping an existing token. When a + token is issued based on initial authentication, it is given + an expires_at value. When a token is used to get another + token, the new token will have the same expires_at value as + the original. + in: body + required: true + type: string +revoke_issued_before: + description: | + (string, ISO 8601 extended format date time with + microseconds). + + Tokens issued before this time are considered revoked. + + This attribute can be used to determine how long the + expiration event is valid. It can also be used in + queries to filter events, so that only a subset that + have occurred since the last request are returned. + in: body + required: true + type: string +revoke_project_id: + description: | + Revoke tokens scoped to a particular project. + in: body + required: true + type: string +revoke_role_id: + description: | + Revoke tokens issued with a specific role. + in: body + required: true + type: string +revoke_trust_id: + description: | + Revoke tokens issued as the result of a particular + trust, as part of the OS-TRUST API extension. + in: body + required: true + type: string +revoke_user_id: + description: | + Revoke tokens expressing the identity of a particular user. + in: body + required: true + type: string roles: description: | A roles object. diff --git a/api-ref/source/v3-ext/revoke.inc b/api-ref/source/v3-ext/revoke.inc new file mode 100644 index 0000000000..6766292600 --- /dev/null +++ b/api-ref/source/v3-ext/revoke.inc @@ -0,0 +1,73 @@ +.. -*- rst -*- + +=============== + OS-REVOKE API +=============== + +This API provides a list of token revocations. Each event expresses a set of +criteria which describes a set of tokens that are no longer valid. +Requires v3.2+ of the Identity API. + +What’s New in v1.1 +================== + +* Use of expires_at has been deprecated in favor of using audit_id and audit_chain_id. +* Revocation events can use audit_id to revoke an individual token. +* Revocation events can use audit_chain_id to revoke all related tokens. + A related token is defined by the first (non-rescoped) token. All tokens in the + chain will have the same audit_chain_id. + +API Resources +============= + +Revocation Events +----------------- + +Revocation events are objects that contain criteria used to evaluate token validity. +Tokens that match all the criteria of a revocation event are considered revoked, +and should not be accepted as proof of authorization for the user. + +Revocation events do not have a unique identifier (id). + +List revocation events +====================== + +.. rest_method:: GET /v3/OS-REVOKE/events + +List revocation events. + +The HTTP Date header returned in the response reflects the timestamp of the +most recently issued revocation event. Clients can then use this value in the +since query parameter to limit the list of events in subsequent requests. + +Normal response codes: 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - since: since + +Request Example +--------------- + +.. literalinclude:: samples/OS-REVOKE/list-revoke-response.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - events: revoke_events + - issued_before: revoke_issued_before + - user_id: revoke_user_id + - audit_id: revoke_audit_id + - audit_chain_id: revoke_audit_chain_id + - domain_id: revoke_domain_id + - project_id: revoke_project_id + - role_id: revoke_role_id + - OS-TRUST:trust_id: revoke_trust_id + - OS-OAUTH1:consumer_id: revoke_consumer_id + - expires_at: revoke_expires_at diff --git a/api-ref/source/v3-ext/samples/OS-REVOKE/list-revoke-response.json b/api-ref/source/v3-ext/samples/OS-REVOKE/list-revoke-response.json new file mode 100644 index 0000000000..400691168c --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-REVOKE/list-revoke-response.json @@ -0,0 +1,22 @@ +{ + "events": [ + { + "issued_before": "2014-02-27T18:30:59.999999Z", + "user_id": "f287de" + }, + { + "audit_id": "VcxU2JYqT8OzfUVvrjEITQ", + "issued_before": "2014-02-27T18:30:59.999999Z" + }, + { + "audit_chain_id": "VcxU2JYqT8OzfUVvrjEITQ", + "issued_before": "2014-02-27T18:30:59.999999Z", + "project_id": "976bf9" + }, + { + "domain_id": "be2c70", + "issued_before": "2014-02-2805:15:59.999999Z", + "user_id": "f287de" + } + ] +}