Add api-ref for application credentials

bp application-credentials Change-Id: I803cfb2a9bb6502dabc8fd93385dfce29bf3bea5
2018-01-15 18:12:35 +01:00 · 2018-01-15 18:12:35 +01:00 · 0462ff8001
commit 0462ff8001
parent 29280b1f68
10 changed files with 663 additions and 0 deletions
--- a/api-ref/source/v3/application-credentials.inc
+++ b/api-ref/source/v3/application-credentials.inc
@ -0,0 +1,304 @@
+.. -*- rst -*-
+
+=======================
+Application Credentials
+=======================
+
+Application credentials provide a way to delegate a user's authorization to an
+application without sharing the user's password authentication. This is a
+useful security measure, especially for situations where the user's
+identification is provided by an external source, such as LDAP or a
+single-sign-on service. Instead of storing user passwords in config files, a
+user creates an application credential for a specific project, with all or a
+subset of the role assignments they have on that project, and then stores the
+application credential identifier and secret in the config file.
+
+Multiple application credentials may be active at once, so you can easily
+rotate application credentials by creating a second one, converting your
+applications to use it one by one, and finally deleting the first one.
+
+Application credentials are limited by the lifespan of the user that created
+them. If the user is deleted, disabled, or loses a role assignment on a
+project, the application credential is deleted.
+
+Authenticating with an Application Credential
+=============================================
+
+.. rest_method::  POST /v3/auth/tokens
+
+To authenticate with an application credential, specify
+"application_credential" as the auth method. You are not allowed to request a
+scope, as the scope is retrieved from the application credential.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - identity: identity
+   - methods: auth_methods_application_credential
+   - application_credential: request_application_credential_body_required
+   - id: request_application_credential_auth_id_body_not_required
+   - name: request_application_credential_auth_name_body_not_required
+   - secret: request_application_credential_auth_secret_body_required
+   - user: request_application_credential_user_body_not_required
+
+Example
+~~~~~~~
+
+An application credential can be identified by an ID:
+
+.. literalinclude:: samples/admin/auth-application-credential-id-request.json
+   :language: javascript
+
+It can also be identified by its name and a user object:
+
+.. literalinclude:: samples/admin/auth-application-credential-name-request.json
+   :language: javascript
+
+Response
+--------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Subject-Token: X-Subject-Token
+   - domain: domain
+   - methods: auth_methods
+   - user: user
+   - token: token
+   - expires_at: expires_at
+   - project: project
+   - catalog: catalog
+   - roles: roles
+   - audit_ids: audit_ids
+   - issued_at: issued_at
+   - id: user_id
+   - name: user_name
+   - application_credential_restricted: auth_application_credential_restricted_body
+
+Example
+~~~~~~~
+
+.. literalinclude:: samples/admin/auth-application-credential-response.json
+   :language: javascript
+
+A token created with an application credential will have the scope and roles
+designated by the application credential.
+
+Create application credential
+=============================
+
+.. rest_method::  POST /v3/users/{user_id}/application_credentials
+
+Creates an application credential for a user on the project to which they are
+currently scoped.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/application_credentials``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: request_application_credential_user_id_path_required
+   - application_credential: request_application_credential_body_required
+   - name: request_application_credential_name_body_required
+   - secret: request_application_credential_secret_body_not_required
+   - description: request_application_credential_description_body_not_required
+   - expires_at: request_application_credential_expires_at_body_not_required
+   - roles: request_application_credential_roles_body_not_required
+   - unrestricted: request_application_credential_unrestricted_body_not_required
+
+Example
+~~~~~~~
+
+.. literalinclude:: samples/admin/application-credential-create-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - application_credential: response_application_credential_body
+   - id: response_application_credential_id_body
+   - name: response_application_credential_name_body
+   - secret: response_application_credential_secret_body
+   - description: response_application_credential_description_body
+   - expires_at: response_application_credential_expires_at_body
+   - project_id: response_application_credential_project_id_body
+   - roles: response_application_credential_roles_body
+   - unrestricted: response_application_credential_unrestricted_body
+   - links: link_response_body
+
+Example
+~~~~~~~
+
+.. literalinclude:: samples/admin/application-credential-create-response.json
+   :language: javascript
+
+List application credentials
+=============================
+
+.. rest_method::  GET /v3/users/{user_id}/application_credentials
+
+List all application credentials for a user.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/application_credentials``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: request_application_credential_user_id_path_required
+
+Response
+--------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - application_credential: response_application_credential_body
+   - id: response_application_credential_id_body
+   - name: response_application_credential_name_body
+   - description: response_application_credential_description_body
+   - expires_at: response_application_credential_expires_at_body
+   - project_id: response_application_credential_project_id_body
+   - roles: response_application_credential_roles_body
+   - unrestricted: response_application_credential_unrestricted_body
+   - links: link_collection
+
+Example
+~~~~~~~
+
+.. literalinclude:: samples/admin/application-credential-list-response.json
+   :language: javascript
+
+Show application credential details
+===================================
+
+.. rest_method::  GET /v3/users/{user_id}/application_credentials/{application_credential_id}
+
+Show details of an application credential.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/application_credentials``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: request_application_credential_user_id_path_required
+   - application_credential_id: request_application_credential_id_path_required
+
+Response
+--------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - application_credential: response_application_credential_body
+   - id: response_application_credential_id_body
+   - name: response_application_credential_name_body
+   - description: response_application_credential_description_body
+   - expires_at: response_application_credential_expires_at_body
+   - project_id: response_application_credential_project_id_body
+   - roles: response_application_credential_roles_body
+   - unrestricted: response_application_credential_unrestricted_body
+   - links: link_response_body
+
+Example
+~~~~~~~
+
+.. literalinclude:: samples/admin/application-credential-get-response.json
+   :language: javascript
+
+Delete application credential
+=============================
+
+.. rest_method::  DELETE /v3/users/{user_id}/application_credentials/{application_credential_id}
+
+Delete an application credential.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/application_credentials``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: request_application_credential_user_id_path_required
+   - application_credential_id: request_application_credential_id_path_required
+
+Response
+--------
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
--- a/api-ref/source/v3/index.rst
+++ b/api-ref/source/v3/index.rst
@ -26,6 +26,12 @@ For information about Identity API protection, see
 <https://docs.openstack.org/keystone/latest/admin/identity-service-api-protection.html>`_
 in the OpenStack Cloud Administrator Guide.

+==========================
+What's New in Version 3.10
+==========================
+
+- Introduction of the Application Credentials API.
+
 =========================
 What's New in Version 3.9
 =========================
@ -178,6 +184,7 @@ Identity API Operations
 This page lists the Identity API operations in the following order:

 * `Authentication and token management`_
+* `Application Credentials`_
 * `Credentials`_
 * `Domains`_
 * `Domain configuration`_
@ -197,6 +204,7 @@ This page lists the Identity API operations in the following order:
 .. rest_expand_all::

 .. include:: authenticate-v3.inc
+.. include:: application-credentials.inc
 .. include:: credentials.inc
 .. include:: domains.inc
 .. include:: domains-config-v3.inc
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@ -96,6 +96,18 @@ registered_limit_id_path:
  in: path
  required: true
  type: string
+request_application_credential_id_path_required:
+  description: |
+    The ID of the application credential.
+  in: path
+  required: true
+  type: string
+request_application_credential_user_id_path_required:
+  description: |
+    The ID of the user who owns the application credential.
+  in: path
+  required: true
+  type: string
 role_id:
  description: |
    The role ID.
@ -442,6 +454,13 @@ auth:
  in: body
  required: true
  type: object
+auth_application_credential_restricted_body:
+  description: |
+    Whether the application credential is permitted to be used for creating and
+    deleting additional application credentials and trusts.
+  in: body
+  required: true
+  type: object
 auth_domain:
  description: |
    Specify either ``id`` or ``name`` to uniquely
@ -466,6 +485,13 @@ auth_methods:
  in: body
  required: true
  type: array
+auth_methods_application_credential:
+  description: |
+    The authentication method. To authenticate with an application credential,
+    specify ``application_credential``.
+  in: body
+  required: true
+  type: array
 auth_methods_passwd:
  description: |
    The authentication method. For password
@ -1382,6 +1408,82 @@ registered_limits:
  in: body
  required: true
  type: array
+request_application_credential_auth_id_body_not_required:
+  description: |
+    The ID of the application credential used for authentication. If not
+    provided, the application credential must be identified by its name and
+    its owning user.
+  in: body
+  required: false
+  type: string
+request_application_credential_auth_name_body_not_required:
+  description: |
+    The name of the application credential used for authentication. If
+    provided, must be accompanied by a user object.
+  in: body
+  required: false
+  type: string
+request_application_credential_auth_secret_body_required:
+  description: |
+    The secret for authenticating the application credential.
+  in: body
+  required: true
+  type: string
+request_application_credential_body_required:
+  description: |
+    An application credential object.
+  in: body
+  required: true
+  type: object
+request_application_credential_description_body_not_required:
+  description: |
+    A description of the application credential's purpose.
+  in: body
+  required: false
+  type: string
+request_application_credential_expires_at_body_not_required:
+  description: |
+    An optional expiry time for the application credential. If unset, the
+    application credential does not expire.
+  in: body
+  required: false
+  type: string
+request_application_credential_name_body_required:
+  description: |
+    The name of the application credential. Must be unique to a user.
+  in: body
+  required: true
+  type: string
+request_application_credential_roles_body_not_required:
+  description: |
+    An optional list of role objects, identified by ID or name. If not
+    provided, the roles assigned to the application credential will be the
+    same as the roles in the current token.
+  in: body
+  required: false
+  type: array
+request_application_credential_secret_body_not_required:
+  description: |
+    The secret that the application credential will be created with. If not
+    provided, one will be generated.
+  in: body
+  required: false
+  type: string
+request_application_credential_unrestricted_body_not_required:
+  description: |
+    An optional flag to restrict whether the application credential may be
+    used for the creation or destruction of other application credentials or
+    trusts. Defaults to false.
+  in: body
+  required: false
+  type: boolean
+request_application_credential_user_body_not_required:
+  description: |
+    A ``user`` object, required if an application credential is identified by
+    name and not ID.
+  in: body
+  required: false
+  type: object
 resource_limit:
  description: |
    The override limit.
@ -1394,6 +1496,68 @@ resource_name:
  in: body
  required: true
  type: string
+response_application_credential_body:
+  description: |
+    The application credential object.
+  in: body
+  type: object
+  required: true
+response_application_credential_description_body:
+  description: |
+    A description of the application credential's purpose.
+  in: body
+  type: string
+  required: true
+response_application_credential_expires_at_body:
+  description: |
+    The expiration time of the application credential, if one was specified.
+  in: body
+  type: string
+  required: true
+response_application_credential_id_body:
+  description: |
+    The ID of the application credential.
+  in: body
+  type: string
+  required: true
+response_application_credential_name_body:
+  description: |
+    The name of the application credential.
+  in: body
+  type: string
+  required: true
+response_application_credential_project_id_body:
+  description: |
+    The ID of the project the application credential was created for and that
+    authentication requests using this application credential will be scoped
+    to.
+  in: body
+  type: string
+  required: true
+response_application_credential_roles_body:
+  description: |
+    A list of one or more roles that this application credential has
+    associated with its project. A token using this application credential
+    will have these same roles.
+  in: body
+  type: array
+  required: true
+response_application_credential_secret_body:
+  description: |
+    The secret for the application credential, either generated by the server
+    or provided by the user. This is only ever shown once in the response to a
+    create request. It is not stored nor ever shown again. If the secret is
+    lost, a new application credential must be created.
+  in: body
+  type: string
+  required: true
+response_application_credential_unrestricted_body:
+  description: |
+    A flag indicating whether the application credential may be used for
+    creation or destruction of other application credentials or trusts.
+  in: body
+  type: boolean
+  required: true
 response_body_project_tags_required:
  description: |
    A list of simple strings assigned to a project.
--- a/api-ref/source/v3/samples/admin/application-credential-create-request.json
+++ b/api-ref/source/v3/samples/admin/application-credential-create-request.json
@ -0,0 +1,12 @@
+{
+    "application_credential": {
+        "name": "monitoring",
+        "secret": "rEaqvJka48mpv",
+        "description": "Application credential for monitoring.",
+        "expires_at": "2018-02-27T18:30:59Z",
+        "roles": [
+            {"name": "Reader"}
+        ],
+        "unrestricted": false
+    }
+}
--- a/api-ref/source/v3/samples/admin/application-credential-create-response.json
+++ b/api-ref/source/v3/samples/admin/application-credential-create-response.json
@ -0,0 +1,21 @@
+{
+  "application_credential": {
+    "description": "Application credential for monitoring.",
+    "roles": [
+      {
+        "id": "6aff702516544aeca22817fd3bc39683",
+        "domain_id": null,
+        "name": "Reader"
+      }
+    ],
+    "links": {
+      "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
+    },
+    "expires_at": "2018-02-27T18:30:59.000000",
+    "unrestricted": false,
+    "secret": "rEaqvJka48mpv",
+    "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
+    "id": "58d61ff8e6e34accb35874016d1dba8b",
+    "name": "monitoring"
+  }
+}
--- a/api-ref/source/v3/samples/admin/application-credential-get-response.json
+++ b/api-ref/source/v3/samples/admin/application-credential-get-response.json
@ -0,0 +1,20 @@
+{
+  "application_credential": {
+    "description": "Application credential for monitoring.",
+    "roles": [
+      {
+        "id": "6aff702516544aeca22817fd3bc39683",
+        "domain_id": null,
+        "name": "Reader"
+      }
+    ],
+    "links": {
+      "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
+    },
+    "expires_at": "2018-02-27T18:30:59.000000",
+    "unrestricted": false,
+    "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
+    "id": "58d61ff8e6e34accb35874016d1dba8b",
+    "name": "monitoring"
+  }
+}
--- a/api-ref/source/v3/samples/admin/application-credential-list-response.json
+++ b/api-ref/source/v3/samples/admin/application-credential-list-response.json
@ -0,0 +1,45 @@
+{
+    "links": {
+        "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials",
+        "previous": null,
+        "next": null
+    },
+    "application_credentials": [
+        {
+            "description": "Application credential for backups.",
+            "roles": [
+                {
+                    "domain_id": null,
+                    "name": "Writer",
+                    "id": "6aff702516544aeca22817fd3bc39683"
+                }
+            ],
+            "links": {
+                "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/308a7e905eee4071aac5971744c061f6"
+            },
+            "expires_at": "2018-02-27T18:30:59.000000",
+            "unrestricted": false,
+            "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
+            "id": "308a7e905eee4071aac5971744c061f6",
+            "name": "backups"
+        },
+        {
+            "description": "Application credential for monitoring.",
+            "roles": [
+                {
+                    "id": "6aff702516544aeca22817fd3bc39683",
+                    "domain_id": null,
+                    "name": "Reader"
+                }
+            ],
+            "links": {
+                "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
+            },
+            "expires_at": "2018-02-27T18:30:59.000000",
+            "unrestricted": false,
+            "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
+            "id": "58d61ff8e6e34accb35874016d1dba8b",
+            "name": "monitoring"
+        }
+    ]
+}
--- a/api-ref/source/v3/samples/admin/auth-application-credential-id-request.json
+++ b/api-ref/source/v3/samples/admin/auth-application-credential-id-request.json
@ -0,0 +1,13 @@
+{
+    "auth": {
+        "identity": {
+            "methods": [
+                "application_credential"
+            ],
+            "application_credential": {
+                "id": "423f19a4ac1e4f48bbb4180756e6eb6c",
+                "secret": "rEaqvJka48mpv"
+            }
+        }
+    }
+}
--- a/api-ref/source/v3/samples/admin/auth-application-credential-name-request.json
+++ b/api-ref/source/v3/samples/admin/auth-application-credential-name-request.json
@ -0,0 +1,16 @@
+{
+    "auth": {
+        "identity": {
+            "methods": [
+                "application_credential"
+            ],
+            "application_credential": {
+                "name": "monitoring",
+                "secret": "rEaqvJka48mpv",
+                "user": {
+                    "id": "423f19a4ac1e4f48bbb4180756e6eb6c"
+                }
+            }
+        }
+    }
+}
--- a/api-ref/source/v3/samples/admin/auth-application-credential-response.json
+++ b/api-ref/source/v3/samples/admin/auth-application-credential-response.json
@ -0,0 +1,60 @@
+{
+    "token": {
+        "is_domain": false,
+        "methods": [
+            "application_credential"
+        ],
+        "roles": [
+            {
+                "id": "df8b7e3bf6fb49e9ba19122da2bae916",
+                "name": "Member"
+            }
+        ],
+        "expires_at": "2018-01-15T22:14:05.000000Z",
+        "project": {
+            "domain": {
+                "id": "default",
+                "name": "Default"
+            },
+            "id": "231c62fb0fbd485b995e8b060c3f0d98",
+            "name": "demo"
+        },
+        "catalog": [
+            {
+                "endpoints": [
+                    {
+                        "region_id": "RegionOne",
+                        "url": "http://example.com/identity",
+                        "region": "RegionOne",
+                        "interface": "admin",
+                        "id": "81737f23cd8f45169fcd700cb658c8ad"
+                    },
+                    {
+                        "region_id": "RegionOne",
+                        "url": "http://example.com/identity",
+                        "region": "RegionOne",
+                        "interface": "public",
+                        "id": "a7b9155184ed4607853304408e7e8d32"
+                    }
+                ],
+                "type": "identity",
+                "id": "408af8b8554248fc8d686bef54ae3bf6",
+                "name": "keystone"
+            }
+        ],
+        "application_credential_restricted": true,
+        "user": {
+            "password_expires_at": null,
+            "domain": {
+                "id": "default",
+                "name": "Default"
+            },
+            "id": "fd786d56402c4d1691372e7dee0d00b5",
+            "name": "demo"
+        },
+        "audit_ids": [
+            "9JsolhssRzKfyayTIiCRUg"
+        ],
+        "issued_at": "2018-01-15T21:14:05.000000Z"
+    }
+}