Add "v2 overview" docs to APIs

Migrate the content from [1] over to the in-tree API.

Do not include extensions or versions since those are already
documented.

[1] http://specs.openstack.org/openstack/keystone-specs/#v2-0-api

Change-Id: If31f86d93b0b3c44295d969d8f5bd408a18705fb
This commit is contained in:
Steve Martinelli 2016-07-13 11:10:11 -07:00
parent 7923a46692
commit 8517caa07b
2 changed files with 273 additions and 0 deletions

View File

@ -9,3 +9,4 @@
.. include:: identity-api-extensions.inc
.. include:: identity-auth.inc
.. include:: versions.inc
.. include:: overview.inc

View File

@ -0,0 +1,272 @@
.. -*- rst -*-
===========
API Details
===========
Overview
========
The OpenStack Identity API is implemented using a RESTful web service
interface. All requests to authenticate and operate against the
OpenStack Identity API should be performed using HTTPS.
OpenStack Identity enables clients to obtain tokens that permit access
to OpenStack cloud services.
Intended audience
-----------------
This reference is for software developers who develop applications that
use the Identity API for authentication.
This reference assumes that the reader is familiar with RESTful web
services, HTTP/1.1, and JSON serialization formats.
Identity concepts
-----------------
To use OpenStack Identity, you must be familiar with these key concepts:
**User**
A digital representation of a person, system, or service that uses
OpenStack cloud services. OpenStack Identity authentication services
validate that an incoming request is being made by the user who
claims to be making the call.
Users have a login and may be assigned tokens to access resources.
Users may be directly assigned to a particular tenant and behave as
if they are contained in that tenant.
**Token**
An arbitrary bit of text that is used to access resources. Each
token has a scope that describes which resources are accessible with
it. A token may be revoked at anytime and is valid for a finite
duration.
While OpenStack Identity supports token-based authentication, the
intention is for it to support additional protocols in the future.
The intent is for it to be an integration service foremost, and not
aspire to be a full-fledged identity store and management solution.
**Credentials**
Data that belongs to, is owned by, and generally only known by a
user that the user can present to prove their identity.
Examples include:
- A matching username and password
- A matching username and API key
- A token that was issued to you
**Authentication**
In the context of the OpenStack Identity Service, the act of confirming
the identity of a user or the truth of a claim. OpenStack Identity
confirms that an incoming request is being made by the user who
claims to be making the call by validating a set of identity information
provided by the user.
These claims are initially in the form of a set of credentials
(username & password, or username and API key). After initial
confirmation, OpenStack Identity issues the user a token, which the
user can then provide to demonstrate that their identity has been
authenticated when making subsequent requests.
**Tenant**
A container used to group or isolate resources and/or identity
objects. Depending on the service operator, a tenant can map to a
customer, account, organization, or project.
**Service**
An OpenStack service, such as Compute (Nova), Object Storage
(Swift), or Image Service (Glance). A service provides one or more
endpoints through which users can access resources and perform
operations.
**Endpoint**
A network-accessible address, usually described by a URL, where a
service may be accessed. If using an extension for templates, you
can create an endpoint template, which represents the templates of
all the consumable services that are available across the regions.
**Role**
A personality that a user assumes when performing a specific set of
operations. A role includes a set of rights and privileges. A user
assuming that role inherits those rights and privileges.
In OpenStack Identity, a token that is issued to a user includes the
list of roles that user can assume. Services that are being called
by that user determine how they interpret the set of roles a user
has and to which operations or resources each role grants access.
It is up to individual services such as the Compute service and
Image service to assign meaning to these roles. As far as the
Identity service is concerned, a role is an arbitrary name assigned
by the user.
Paginated collections
=====================
To reduce load on the service, list operations return a maximum number
of items at a time. The maximum number of items returned is determined
by the Identity provider. To navigate the collection, you can set the
*``limit``* and *``marker``* parameters in the URI. For example,
?\ *``limit``*\ =100&\ *``marker``*\ =1234. The *``marker``* parameter
is the ID of the last item in the previous list. Items are sorted by
update time. When an update time is not available they are sorted by ID.
The *``limit``* parameter sets the page size. Both parameters are
optional. If the client requests a *``limit``* beyond that which is
supported by the deployment a ``413`` response code may be thrown. A
marker with an invalid ID returns a ``404`` response code.
.. note::
Paginated collections will never return a ``404`` error when the
collection is empty - clients should expect an empty collection.
For convenience, collections contain atom "next" and "previous" links.
The first page in the list does not contain a ``previous`` link, the
last page in the list does not contain a ``next`` link. The following
examples illustrate three pages in a collection of tenants. The first
page was retrieved through a **GET** to
``http://identity.api.openstack.org/v2.0/1234/tenants?limit=1``. In
these examples, the *``limit``* parameter sets the page size to a single
item. Subsequent ``next`` and ``previous`` links honor the initial page
size. Thus, a client might follow links to traverse a paginated
collection without having to input the *``marker``* parameter.
**Example: Tenant collection, first page:**
.. code:: javascript
{
"tenants": [
{
"id": "1234",
"name": "ACME corp",
"description": "A description ...",
"enabled": true
}
],
"tenants_links": [
{
"rel": "next",
"href": "http://identity.api.openstack.org/v2.0/tenants?limit=1&marker=1234"
}
]
}
**Example: Tenant collection, second page:**
.. code:: javascript
{
"tenants": [
{
"id": "3645",
"name": "Iron Works",
"description": "A description ...",
"enabled": true
}
],
"tenants_links": [
{
"rel": "next",
"href": "http://identity.api.openstack.org/v2.0/tenants?limit=1&marker=3645"
},
{
"rel": "previous",
"href": "http://identity.api.openstack.org/v2.0/tenants?limit=1"
}
]
}
**Example: Tenant collection, last page:**
.. code:: javascript
{
"tenants": [
{
"id": "9999",
"name": "Bigz",
"description": "A description ...",
"enabled": true
}
],
"tenants_links": [
{
"rel": "previous",
"href": "http://identity.api.openstack.org/v2.0/tenants?limit=1&marker=1234"
}
]
}
Paginated collections contain a values property that contains the items in the
collections. Links are accessed via the links property. The approach allows for
extensibility of both the collection members and of the paginated collection
itself. It also allows collections to be embedded in other objects as
illustrated below. Here, a subset of groups are presented within a user.
Clients must follow the "next" link to continue to retrieve additional groups
belonging to a user.
**Example: Paginated roles in user:**
.. code:: javascript
{
"user": {
"OS-ROLE:roles": [
{
"tenantId": "1234",
"id": "Admin"
},
{
"tenantId": "1234",
"id": "DBUser"
}
],
"OS-ROLE:roles_links": [
{
"rel": "next",
"href": "http://identity.api.openstack.org/v2.0/tenants/1234/users/u1000/roles?marker=Super"
}
],
"id": "u1000",
"username": "jqsmith",
"email": "john.smith@example.org",
"enabled": true
}
}
Request and response formats
============================
The OpenStack Identity API only supports JSON data serialization request and
response formats.
Use the ``Content-Type`` request header to specify the request format.
This header is required for operations that have a request body.
The syntax for the ``Content-Type`` header is:
.. code::
Content-Type: application/json
Use the ``Accept`` header to specify the response format:
.. code::
Accept: application/json
If you do not specify a response format, the ``Accept`` header will be
set to ``application/json`` by default.