Create APIs for OS-REVOKE

Closes-Bug: 1532223
Change-Id: I20c4b97643bfbe9db052fc9bfc29482090cbcce7

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

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.

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

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"
+        }
+    ]
+}