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:
parent
7923a46692
commit
8517caa07b
|
@ -9,3 +9,4 @@
|
|||
.. include:: identity-api-extensions.inc
|
||||
.. include:: identity-auth.inc
|
||||
.. include:: versions.inc
|
||||
.. include:: overview.inc
|
|
@ -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.
|
Loading…
Reference in New Issue