openstack/keystone
Code Issues Proposed changes

Migrate identity /v3 docs from api-ref repo

Browse Source 
Docs at [1] have already been converted from WADL (SGML / XML) to RST
using fairy-slipper [2].

This commit polish the results from the conversion and migrate the docs
to our repository under 'api-ref/source' directory. In addition, it
added missing descriptions for access_token_id and consumer_id to
'parameters.yaml'.

Polishing the generated RST files include:
- Removing unnecessary blank lines;
- Removing empty references.

Polishing the generated RST files do not include:
- Modifying their content;
- Modifying file names;
- Wrapping lines at the maximum of 79 chars.

Updating the documentation will be done after this migration step.

This change also adds a tox environment to build the docs using sphinx
under 'api-ref/build', which in turn is added to '.gitignore'.

Lastly, 'os-api-ref' is added as a test requirement. It provides the
sphinx stanzas rest_method and rest_parameter, used to define OpenStack
APIs in RST docs.

[1] https://github.com/openstack/api-site/tree/master/api-ref/source/identity/v3
[2] https://github.com/russell/fairy-slipper

Change-Id: If1b9a3e1b2e4ea7211c337071254c26b881893a3
This commit is contained in:
Samuel de Medeiros Queiroz 2016-05-23 18:07:59 -03:00
parent 5bc7b34f69
commit 9a5395f1b2
146 changed files with 8736 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -9,6 +9,7 @@ vendor
keystone.egg-info/
*.log
.coverage
api-ref/build
coverage.xml
cover/*
covhtml

202
api-ref/source/conf.py Normal file
View File

@ -0,0 +1,202 @@
# -*- coding: utf-8 -*-
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
#
# keystone documentation build configuration file, created by
# sphinx-quickstart on Mon May 23 07:54:13 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import subprocess
import warnings
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.[]
extensions = [
'os_api_ref',
'oslosphinx',
]
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.inc'
# The encoding of source files.
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Identity API Reference'
copyright = u'2010-present, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
from keystone import version as keystone_version
# The short X.Y version.
version = keystone_version.release_string()
# The full version, including alpha/beta/rc tags.
release = keystone_version.release_string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = False
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
"-n1"]
try:
html_last_updated_fmt = subprocess.Popen(
git_cmd, stdout=subprocess.PIPE).communicate()[0]
except Exception:
warnings.warn('Cannot get last updated time from git repository. '
'Not setting "html_last_updated_fmt".')
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'keystonedoc'

34
api-ref/source/index.inc Normal file
View File

@ -0,0 +1,34 @@
.. keystone documentation master file, created by
sphinx-quickstart on Mon May 23 07:54:13 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to keystone's documentation!
====================================
Contents:
.. toctree::
:maxdepth: 2
v3/authenticate-v3.inc
v3/credentials
v3/domains
v3/domains-config-v3
v3/groups
v3/identity_v3_OS-OAUTH1
v3/policies
v3/projects
v3/regions-v3
v3/roles
v3/service-catalog
v3/users
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

433
api-ref/source/v3/authenticate-v3.inc Normal file
View File

@ -0,0 +1,433 @@
.. -*- rst -*-
==================================================
Authentication and token management (auth, tokens)
==================================================
In exchange for a set of authentication credentials, the Identity
service generates tokens. A token represents the authenticated
identity of a user and, optionally, grants authorization on a
specific project or domain.
The body of an authentication request must include a payload that
specifies the authentication method, which is ``password`` or
``token``, the credentials, and, optionally, the authorization
scope. You can scope a token to a project or domain, or the token
can be unscoped. You cannot scope a token to both a project and
domain.
Tokens have IDs, which the Identity API returns in the ``X-Subject-
Token`` response header.
Also, validates an authentication token and lists the domains,
projects, roles, and endpoints to which the token gives access.
Forces the immediate revocation of a token.
After you obtain an authentication token, you can:
- Make REST API requests to other OpenStack services. You supply the
ID of your authentication token in the ``X-Auth-Token`` request
header.
- Validate your authentication token and list the domains, projects,
roles, and endpoints that your token gives you access to.
- Use your token to request another token scoped for a different
domain and project.
- Force the immediate revocation of a token.
- List revoked public key infrastructure (PKI) tokens.
The Identity API treats expired tokens as no longer valid tokens.
The deployment determines how long expired tokens are stored.
These authentication errors can occur:
**Authentication errors**
+------------------------+----------------------------------------------------------------------+
| Response code | Description |
+------------------------+----------------------------------------------------------------------+
| ``Bad Request (400)`` | The Identity service failed to parse the request as expected. One |
| | of the following errors occurred: |
| | |
| | - A required attribute was missing. |
| | |
| | - An attribute that is not allowed was specified, such as an ID on a |
| | POST request in a basic CRUD operation. |
| | |
| | - An attribute of an unexpected data type was specified. |
+------------------------+----------------------------------------------------------------------+
| ``Unauthorized (401)`` | One of the following errors occurred: |
| | |
| | - Authentication was not performed. |
| | |
| | - The specified ``X-Auth-Token`` header is not valid. |
| | |
| | - The authentication credentials are not valid. |
+------------------------+----------------------------------------------------------------------+
| ``Forbidden (403)`` | The identity was successfully authenticated but it is not |
| | authorized to perform the requested action. |
+------------------------+----------------------------------------------------------------------+
| ``Not Found (404)`` | An operation failed because a referenced entity cannot be found by |
| | ID. For a POST request, the referenced entity might be specified in |
| | the request body rather than in the resource path. |
+------------------------+----------------------------------------------------------------------+
| ``Conflict (409)`` | A POST or PATCH operation failed. For example, a client tried to |
| | update a unique attribute for an entity, which conflicts with that |
| | of another entity in the same collection. |
| | |
| | Or, a client issued a create operation twice on a collection with a |
| | user-defined, unique attribute. For example, a client made a POST |
| | ``/users`` request two times for the unique, user-defined name |
| | attribute for a user entity. |
+------------------------+----------------------------------------------------------------------+
Password authentication with unscoped authorization
===================================================
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the password authentication method. Authorization is unscoped.
The request body must include a payload that specifies the
authentication method, which is ``password``, and the user, by ID
or name, and password credentials.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
- auth: auth
- user: user
- password: password
- id: id
- identity: identity
- methods: methods
- nocatalog: nocatalog
Request Example
---------------
.. literalinclude:: ./samples/admin/auth-password-unscoped-request-with-domain.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- domain: domain
- methods: methods
- expires_at: expires_at
- token: token
- extras: extras
- user: user
- audit_ids: audit_ids
- issued_at: issued_at
- id: id
- name: name
Password authentication with scoped authorization
=================================================
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the password authentication method and scopes authorization to a project or domain.
The request body must include a payload that specifies the
``password`` authentication method, the credentials, and the
``project`` or ``domain`` authorization scope.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- auth: auth
- user: user
- scope: scope
- password: password
- id: id
- identity: identity
- methods: methods
- nocatalog: nocatalog
Request Example
---------------
.. literalinclude:: ./samples/admin/auth-password-project-scoped-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- domain: domain
- region_id: region_id
- methods: methods
- roles: roles
- url: url
- region: region
- token: token
- expires_at: expires_at
- project: project
- issued_at: issued_at
- catalog: catalog
- extras: extras
- user: user
- audit_ids: audit_ids
- interface: interface
- endpoints: endpoints
- type: type
- id: id
- name: name
Password authentication with explicit unscoped authorization
============================================================
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the password authentication method with explicit unscoped authorization.
The request body must include a payload that specifies the
``password`` authentication method, the credentials, and the
``unscoped`` authorization scope.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- auth: auth
- user: user
- scope: scope
- password: password
- id: id
- identity: identity
- methods: methods
- nocatalog: nocatalog
Request Example
---------------
.. literalinclude:: ./samples/admin/auth-password-explicit-unscoped-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- domain: domain
- methods: methods
- roles: roles
- expires_at: expires_at
- token: token
- extras: extras
- user: user
- audit_ids: audit_ids
- issued_at: issued_at
- id: id
- name: name
Token authentication with unscoped authorization
================================================
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the token authentication method. Authorization is unscoped.
In the request body, provide the token ID.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- identity: identity
- token: token
- id: id
- auth: auth
- methods: methods
- nocatalog: nocatalog
Request Example
---------------
.. literalinclude:: ./samples/admin/auth-token-unscoped-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- X-Auth-Token: X-Auth-Token
Token authentication with scoped authorization
==============================================
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project or domain.
In the request body, provide the token ID and the ``project`` or
``domain`` authorization scope.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- methods: methods
- auth: auth
- token: token
- audit_ids: audit_ids
- scope: scope
- id: id
- identity: identity
- nocatalog: nocatalog
Request Example
---------------
.. literalinclude:: ./samples/admin/auth-token-scoped-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- X-Auth-Token: X-Auth-Token
Validate and show information for token
=======================================
.. rest_method:: GET /v3/auth/tokens
Validates and shows information for a token, including its expiration date and authorization scope.
Pass your own token in the ``X-Auth-Token`` request header.
Pass the token that you want to validate in the ``X-Subject-Token``
request header.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- X-Auth-Token: X-Auth-Token
- X-Subject-Token: X-Subject-Token
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- X-Auth-Token: X-Auth-Token
- domain: domain
- methods: methods
- links: links
- user: user
- token: token
- expires_at: expires_at
- project: project
- catalog: catalog
- extras: extras
- roles: roles
- audit_ids: audit_ids
- issued_at: issued_at
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/admin/auth-token-unscoped-response.json
:language: javascript
Check token
===========
.. rest_method:: HEAD /v3/auth/tokens
Validates a token.
This call is similar to ``GET /auth/tokens`` but no response body
is provided even in the ``X-Subject-Token`` header.
The Identity API returns the same response as when the subject
token was issued by ``POST /auth/tokens`` even if an error occurs
because the token is not valid. An HTTP ``204`` response code
indicates that the ``X-Subject-Token`` is valid.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- X-Auth-Token: X-Auth-Token
- X-Subject-Token: X-Subject-Token
Revoke token
============
.. rest_method:: DELETE /v3/auth/tokens
Revokes a token.
This call is similar to the HEAD ``/auth/tokens`` call except that
the ``X-Subject-Token`` token is immediately not valid, regardless
of the ``expires_at`` attribute value. An additional ``X-Auth-
Token`` is not required.
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- X-Auth-Token: X-Auth-Token
- X-Subject-Token: X-Subject-Token

202
api-ref/source/v3/credentials.inc Normal file
View File

@ -0,0 +1,202 @@
.. -*- rst -*-
=========================
Credentials (credentials)
=========================
In exchange for a set of authentication credentials that the user
submits, the Identity service generates and returns a token. A
token represents the authenticated identity of a user and,
optionally, grants authorization on a specific project or domain.
You can list all credentials, and create, show details for, update,
and delete a credential.
Create credential
=================
.. rest_method:: POST /v3/credentials
Creates a credential.
The following example shows how to create an EC2-style credential.
The credential blob is a string that contains a JSON-serialized
dictionary with the ``access`` and ``secret`` keys. This format is
required when you specify the ``ec2`` type. To specify other
credentials, such as ``access_key``, change the type and contents
of the data blob.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- credential: credential
- project_id: project_id
- type: type
- blob: blob
- user_id: user_id
Request Example
---------------
.. literalinclude:: ./samples/admin/credential-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- credential: credential
- user_id: user_id
- links: links
- blob: blob
- project_id: project_id
- type: type
- id: id
List credentials
================
.. rest_method:: GET /v3/credentials
Lists all credentials.
Optionally, you can include the ``user_id`` query parameter in the
URI to filter the response by a user.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- user_id: user_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- user_id: user_id
- links: links
- blob: blob
- credentials: credentials
- project_id: project_id
- type: type
- id: id
Response Example
----------------
.. literalinclude:: ./samples/admin/credentials-list-response.json
:language: javascript
Show credential details
=======================
.. rest_method:: GET /v3/credentials/{credential_id}
Shows details for a credential.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- credential_id: credential_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- credential: credential
- user_id: user_id
- links: links
- blob: blob
- project_id: project_id
- type: type
- id: id
Response Example
----------------
.. literalinclude:: ./samples/admin/credential-show-response.json
:language: javascript
Update credential
=================
.. rest_method:: PATCH /v3/credentials/{credential_id}
Updates a credential.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- credential: credential
- project_id: project_id
- type: type
- blob: blob
- user_id: user_id
- credential_id: credential_id
Request Example
---------------
.. literalinclude:: ./samples/admin/credential-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- credential: credential
- user_id: user_id
- links: links
- blob: blob
- project_id: project_id
- type: type
- id: id
Response Example
----------------
.. literalinclude:: ./samples/admin/credential-update-response.json
:language: javascript
Delete credential
=================
.. rest_method:: DELETE /v3/credentials/{credential_id}
Deletes a credential.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- credential_id: credential_id

367
api-ref/source/v3/domains-config-v3.inc Normal file
View File

@ -0,0 +1,367 @@
.. -*- rst -*-
==================================================================
Domain configuration (domains, config) (since v3.4) (EXPERIMENTAL)
==================================================================
You can manage domain-specific configuration options.
Domain-specific configuration options are structured within their
group objects. The API supports only the ``identity`` and ``ldap``
groups. These groups override the default configuration settings
for the storage of users and groups by the Identity server.
You can create, update, and delete domain-specific configuration
options by using the HTTP PUT , PATCH , and DELETE methods. When
updating, it is only necessary to include those options that are
being updated.
To create an option, use the PUT method. The Identity API does not
return options that are considered sensitive, although you can
create and update these options. The only option currently
considered sensitive is the ``password`` option within the ``ldap``
group.
The API enables you to include sensitive options as part of non-
sensitive options. For example, you can include the password as
part of the ``url`` option.
If you try to create or update configuration options for groups
other than the ``identity`` or ``ldap`` groups, the ``Forbidden
(403)`` response code is returned.
For information about how to integrate the Identity service with
LDAP, see `Integrate Identity with LDAP <http://docs.openstack.org
/admin-guide/keystone_integrate_with_ldap.html>`_.
Show domain group option configuration
======================================
.. rest_method:: GET /v3/domains/{domain_id}/config/{group}/{option}
Shows details for a domain group option configuration.
The API supports only the ``identity`` and ``ldap`` groups. For the
``ldap`` group, a valid value is ``url`` or ``user_tree_dn``. For
the ``identity`` group, a valid value is ``driver``.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id
- group: group
- option: option
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-config-group-option-show-response.json
:language: javascript
Update domain group option configuration
========================================
.. rest_method:: PATCH /v3/domains/{domain_id}/config/{group}/{option}
Updates a domain group option configuration.
The API supports only the ``identity`` and ``ldap`` groups. For the
``ldap`` group, a valid value is ``url`` or ``user_tree_dn``. For
the ``identity`` group, a valid value is ``driver``.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
- domain_id: domain_id
- group: group
- option: option
Request Example
---------------
.. literalinclude:: ./samples/admin/domain-config-group-option-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-config-group-option-update-response.json
:language: javascript
Delete domain group option configuration
========================================
.. rest_method:: DELETE /v3/domains/{domain_id}/config/{group}/{option}
Deletes a domain group option configuration.
The API supports only the ``identity`` and ``ldap`` groups. For the
``ldap`` group, a valid value is ``url`` or ``user_tree_dn``. For
the ``identity`` group, a valid value is ``driver``.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id
- group: group
- option: option
Show domain group configuration
===============================
.. rest_method:: GET /v3/domains/{domain_id}/config/{group}
Shows details for a domain group configuration.
The API supports only the ``identity`` and ``ldap`` groups.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id
- group: group
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-config-group-show-response.json
:language: javascript
Update domain group configuration
=================================
.. rest_method:: PATCH /v3/domains/{domain_id}/config/{group}
Updates a domain group configuration.
The API supports only the ``identity`` and ``ldap`` groups. If you
try to set configuration options for other groups, this call fails
with the ``Forbidden (403)`` response code.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
- domain_id: domain_id
- group: group
Request Example
---------------
.. literalinclude:: ./samples/admin/domain-config-group-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-config-group-update-response.json
:language: javascript
Delete domain group configuration
=================================
.. rest_method:: DELETE /v3/domains/{domain_id}/config/{group}
Deletes a domain group configuration.
The API supports only the ``identity`` and ``ldap`` groups.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id
- group: group
Show domain configuration
=========================
.. rest_method:: GET /v3/domains/{domain_id}/config
Shows details for a domain configuration.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-config-show-response.json
:language: javascript
Update domain configuration
===========================
.. rest_method:: PATCH /v3/domains/{domain_id}/config
Updates a domain configuration.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
- domain_id: domain_id
Request Example
---------------
.. literalinclude:: ./samples/admin/domain-config-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- url: url
- driver: driver
- ldap: ldap
- config: config
- user_tree_dn: user_tree_dn
- identity: identity
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-config-update-response.json
:language: javascript
Delete domain configuration
===========================
.. rest_method:: DELETE /v3/domains/{domain_id}/config
Deletes a domain configuration.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id

211
api-ref/source/v3/domains.inc Normal file
View File

@ -0,0 +1,211 @@
.. -*- rst -*-
=======================================
Domains (domains, users, groups, roles)
=======================================
A domain is a collection of users, groups, and projects. Each group
and project is owned by exactly one domain.
Each domain defines a namespace where certain API-visible name
attributes exist, which affects whether those names must be
globally unique or unique within that domain. In the Identity API,
the uniqueness of these attributes is as follows:
- *Domain name*. Globally unique across all domains.
- *Role name*. Globally unique across all domains.
- *User name*. Unique within the owning domain.
- *Project name*. Unique within the owning domain.
- *Group name*. Unique within the owning domain.
List domains
============
.. rest_method:: GET /v3/domains
Lists all domains.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- enabled: enabled
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- name: name
- links: links
- enabled: enabled
- domains: domains
- id: id
- description: description
Response Example
----------------
.. literalinclude:: ./samples/admin/domains-list-response.json
:language: javascript
Create domain
=============
.. rest_method:: POST /v3/domains
Creates a domain.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- enabled: enabled
- description: description
- name: name
Request Example
---------------
.. literalinclude:: ./samples/admin/domain-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
- links: links
- enabled: enabled
- id: id
- description: description
Show domain details
===================
.. rest_method:: GET /v3/domains/{domain_id}
Shows details for a domain.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
- links: links
- enabled: enabled
- id: id
- description: description
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-show-response.json
:language: javascript
Update domain
=============
.. rest_method:: PATCH /v3/domains/{domain_id}
Updates a domain.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain: domain
- enabled: enabled
- description: description
- name: name
- domain_id: domain_id
Request Example
---------------
.. literalinclude:: ./samples/admin/domain-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- domain: domain
- name: name
- links: links
- enabled: enabled
- id: id
- description: description
Response Example
----------------
.. literalinclude:: ./samples/admin/domain-update-response.json
:language: javascript
Delete domain
=============
.. rest_method:: DELETE /v3/domains/{domain_id}
Deletes a domain.
To minimize the risk of accidentally deleting a domain, you must
first disable the domain by using the update domain method.
When you delete a domain, this call also deletes all entities owned
by it, such as users, groups, and projects, and any credentials and
granted roles that relate to those entities.
(Since v3.6) The deletion of a non-leaf domain in a domain
hierarchy tree is not allowed and fails with a ``Bad Request
(400)`` response code.
If you try to delete an enabled domain, this call returns the
``Forbidden (403)`` response code.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- domain_id: domain_id

291
api-ref/source/v3/groups.inc Normal file
View File

@ -0,0 +1,291 @@
.. -*- rst -*-
======================
Groups (groups, users)
======================
A group is a collection of users. Each group is owned by a domain.
When you grant a role to a group, you explicitly associate that
group with a project or domain. This action is equivalent to
granting the role to each group member on that project and domain.
When you grant a role to a group, that role is automatically
granted to any user that you add to the group. When you revoke a
role from a group, that role is automatically revoked from any user
that you remove from the group. Any token that authenticates that
user, project, and domain is revoked.
As with users, a group without any role grants is useless from the
perspective an OpenStack service and has no access to resources.
However, a group without role grants is permitted as a way of
acquiring or loading users and groups from external sources before
mapping them to projects and domains.
Show group details
==================
.. rest_method:: GET /v3/groups/{group_id}
Shows details for a group.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- group_id: group_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group: group
- name: name
- links: links
- domain_id: domain_id
- id: id
- description: description
Response Example
----------------
.. literalinclude:: ./samples/admin/group-show-response.json
:language: javascript
Update group
============
.. rest_method:: PATCH /v3/groups/{group_id}
Updates a group.
If the back-end driver does not support this functionality, the
call returns the ``Not Implemented (501)`` response code.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- group: group
- description: description
- name: name
- domain_id: domain_id
- group_id: group_id
Request Example
---------------
.. literalinclude:: ./samples/admin/group-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group: group