From 0462ff8001f00c6809387daae1a692d028c94c4a Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Mon, 15 Jan 2018 18:12:35 +0100 Subject: [PATCH] Add api-ref for application credentials bp application-credentials Change-Id: I803cfb2a9bb6502dabc8fd93385dfce29bf3bea5 --- api-ref/source/v3/application-credentials.inc | 304 ++++++++++++++++++ api-ref/source/v3/index.rst | 8 + api-ref/source/v3/parameters.yaml | 164 ++++++++++ ...application-credential-create-request.json | 12 + ...pplication-credential-create-response.json | 21 ++ .../application-credential-get-response.json | 20 ++ .../application-credential-list-response.json | 45 +++ ...uth-application-credential-id-request.json | 13 + ...h-application-credential-name-request.json | 16 + .../auth-application-credential-response.json | 60 ++++ 10 files changed, 663 insertions(+) create mode 100644 api-ref/source/v3/application-credentials.inc create mode 100644 api-ref/source/v3/samples/admin/application-credential-create-request.json create mode 100644 api-ref/source/v3/samples/admin/application-credential-create-response.json create mode 100644 api-ref/source/v3/samples/admin/application-credential-get-response.json create mode 100644 api-ref/source/v3/samples/admin/application-credential-list-response.json create mode 100644 api-ref/source/v3/samples/admin/auth-application-credential-id-request.json create mode 100644 api-ref/source/v3/samples/admin/auth-application-credential-name-request.json create mode 100644 api-ref/source/v3/samples/admin/auth-application-credential-response.json diff --git a/api-ref/source/v3/application-credentials.inc b/api-ref/source/v3/application-credentials.inc new file mode 100644 index 0000000000..bb3ab0c857 --- /dev/null +++ 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 diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index aee856ff14..7ade2a0f78 100644 --- 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 `_ 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 diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 5ff631aab6..6ca7fa0c1d 100644 --- 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. diff --git a/api-ref/source/v3/samples/admin/application-credential-create-request.json b/api-ref/source/v3/samples/admin/application-credential-create-request.json new file mode 100644 index 0000000000..3e29cf2964 --- /dev/null +++ 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 + } +} diff --git a/api-ref/source/v3/samples/admin/application-credential-create-response.json b/api-ref/source/v3/samples/admin/application-credential-create-response.json new file mode 100644 index 0000000000..c86a7d1af0 --- /dev/null +++ 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" + } +} diff --git a/api-ref/source/v3/samples/admin/application-credential-get-response.json b/api-ref/source/v3/samples/admin/application-credential-get-response.json new file mode 100644 index 0000000000..e9913288e1 --- /dev/null +++ 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" + } +} diff --git a/api-ref/source/v3/samples/admin/application-credential-list-response.json b/api-ref/source/v3/samples/admin/application-credential-list-response.json new file mode 100644 index 0000000000..2d0a7399ea --- /dev/null +++ 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" + } + ] +} diff --git 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 new file mode 100644 index 0000000000..7526875d30 --- /dev/null +++ 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" + } + } + } +} diff --git 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 new file mode 100644 index 0000000000..15299e9046 --- /dev/null +++ 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" + } + } + } + } +} diff --git a/api-ref/source/v3/samples/admin/auth-application-credential-response.json b/api-ref/source/v3/samples/admin/auth-application-credential-response.json new file mode 100644 index 0000000000..707be50905 --- /dev/null +++ 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" + } +}