From 6564b40641101135c85f25b12e1209d66e816a52 Mon Sep 17 00:00:00 2001 From: Adrian Turjak Date: Wed, 9 Jan 2019 17:53:35 +1300 Subject: Add documentation for Auth Receipts and MFA Adds API ref examples for TOTP and Auth receipts. Adds docs for MFA and changes some of the user options docs. Change-Id: Id5497064e580093e4a2c7d904670a58095833b3b --- api-ref/source/v3/authenticate-v3.inc | 178 ++++++++++++++++++++- api-ref/source/v3/parameters.yaml | 77 ++++++++- .../v3/samples/auth/requests/project-id-totp.json | 20 +++ .../auth/responses/auth-receipt-password.json | 20 +++ .../responses/project-scoped-password-totp.json | 67 ++++++++ api-ref/source/v3/status.yaml | 8 + 6 files changed, 367 insertions(+), 3 deletions(-) create mode 100644 api-ref/source/v3/samples/auth/requests/project-id-totp.json create mode 100644 api-ref/source/v3/samples/auth/responses/auth-receipt-password.json create mode 100644 api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json (limited to 'api-ref') diff --git a/api-ref/source/v3/authenticate-v3.inc b/api-ref/source/v3/authenticate-v3.inc index 45d3f58f8..6e3cc62ab 100644 --- a/api-ref/source/v3/authenticate-v3.inc +++ b/api-ref/source/v3/authenticate-v3.inc @@ -10,7 +10,7 @@ optionally, grants authorization on a specific project, domain, or the deployment system. The body of an authentication request must include a payload that -specifies the authentication method, which is ``password`` or +specifies the authentication methods, which are normally just ``password`` or ``token``, the credentials, and, optionally, the authorization scope. You can scope a token to a project, domain, the deployment system, or the token can be unscoped. You cannot scope a token to multiple scope targets. @@ -18,6 +18,16 @@ the token can be unscoped. You cannot scope a token to multiple scope targets. Tokens have IDs, which the Identity API returns in the ``X-Subject-Token`` response header. +In the case of multi-factor authentication (MFA) more than one authentication +method needs to be supplied to authenticate. As of v3.12 a failure due to MFA +rules only partially being met will result in an auth receipt ID being returned +in the response header ``Openstack-Auth-Receipt``, and a response body that +details the receipt itself and the missing authentication methods. Supplying +the auth receipt ID in the ``Openstack-Auth-Receipt`` header in a follow-up +authentication request, with the missing authentication methods, will result in +a valid token by reusing the successful methods from the first request. This +allows MFA authentication to be a multi-step process. + After you obtain an authentication token, you can: - Make REST API requests to other OpenStack services. You supply the @@ -74,6 +84,10 @@ These authentication errors can occur: | | - The specified ``X-Auth-Token`` header is not valid. | | | | | | - The authentication credentials are not valid. | +| | | +| | - Not all MFA rules were satisfied. | +| | | +| | - The specified ``Openstack-Auth-Receipt`` header is not valid. | +------------------------+----------------------------------------------------------------------+ | ``Forbidden (403)`` | The identity was successfully authenticated but it is not | | | authorized to perform the requested action. | @@ -621,6 +635,168 @@ Example :language: javascript +Multi-Step authentication (2-Factor Password and TOTP example) +============================================================== + +.. rest_method:: POST /v3/auth/tokens + +Authenticates an identity and generates a token. Uses the password +authentication method, then the totp method, with an auth receipt in between. + +This assumes that MFA has been enabled for the user, and a rule has been +defined requiring authentication with both password and totp. + +The first request body must at least include a payload that specifies one of +``password`` or ``totp`` authentication methods which includes the credentials +in addition to an optional scope. If only one method is supplied then an auth +receipt will be returned. Scope is not retained in the receipt and must be +resupplied in subsequent requests. + +While it is very possible to supply all the required auth methods at once, this +example shows the multi-step process which is likely to be more common. + +More than 2 factors can be used but the same process applies to those as well; +either all auth methods are supplied at once, or in steps with one or more auth +receipts in between. + +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens`` + +First Request +------------- + +Parameters +~~~~~~~~~~ + +.. rest_parameters:: parameters.yaml + + - nocatalog: nocatalog + - name: user_name + - auth: auth + - user: user + - scope: scope_string + - password: password + - id: user_id + - identity: identity + - methods: auth_methods_passwd + +Example +~~~~~~~ + +.. literalinclude:: ./samples/auth/requests/project-id-password.json + :language: javascript + +Response +-------- + +Here we are expecting a 401 status, and a returned auth receipt. + +Parameters +~~~~~~~~~~ + +.. rest_parameters:: parameters.yaml + + - Openstack-Auth-Receipt: Openstack-Auth-Receipt + - methods: auth_methods_receipt + - expires_at: receipt_expires_at + - issued_at: receipt_issued_at + - user: user + - required_auth_methods: required_auth_methods + +Status Code +~~~~~~~~~~~ + +.. rest_status_code:: success status.yaml + + - 401: auth_receipt + +.. rest_status_code:: error status.yaml + + - 400 + - 401: auth_failed + - 403 + - 404 + +Auth Receipt Example +~~~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ./samples/auth/responses/auth-receipt-password.json + :language: javascript + +Second Request +-------------- + +Parameters +~~~~~~~~~~ + +.. rest_parameters:: parameters.yaml + + - Openstack-Auth-Receipt: Openstack-Auth-Receipt + - nocatalog: nocatalog + - name: user_name + - auth: auth + - user: user + - scope: scope_string + - totp: totp + - id: user_id + - identity: identity + - methods: auth_methods_totp + +Example +~~~~~~~ + +.. literalinclude:: ./samples/auth/requests/project-id-totp.json + :language: javascript + +Response +-------- + +Parameters +~~~~~~~~~~ + +.. rest_parameters:: parameters.yaml + + - X-Subject-Token: X-Subject-Token + - region_id: region_id_required + - methods: auth_methods_passwd + - roles: roles + - url: endpoint_url + - region: endpoint_region + - token: token + - expires_at: expires_at + - system: system_scope_response_body_optional + - domain: domain_scope_response_body_optional + - project: project_scope_response_body_optional + - issued_at: issued_at + - catalog: catalog + - user: user + - audit_ids: audit_ids + - interface: endpoint_interface + - endpoints: endpoints + - type: endpoint_type + - id: user_id + - name: user_name + +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success status.yaml + + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401: auth_receipt_failure + - 403 + - 404 + +Project-Scoped Password and TOTP Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ./samples/auth/responses/project-scoped-password-totp.json + :language: javascript + + Validate and show information for token ======================================= diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 30b649e1f..e34b425cb 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -1,4 +1,12 @@ # variables in header +Openstack-Auth-Receipt: + description: | + The auth receipt. A partially successful authentication + response returns the auth receipt ID in this header rather than in the + response body. + in: header + required: true + type: string X-Auth-Token: description: | A valid authentication token for an @@ -477,8 +485,8 @@ auth_domain: type: object auth_methods: description: | - The authentication method, which is ``password``, - ``token``, or both methods. Indicates the accumulated set of + The authentication methods, which are commonly ``password``, + ``token``, or other methods. Indicates the accumulated set of authentication methods that were used to obtain the token. For example, if the token was obtained by password authentication, it contains ``password``. Later, if the token is exchanged by using @@ -506,6 +514,19 @@ auth_methods_passwd: in: body required: true type: array +auth_methods_receipt: + description: | + The authentication methods, which are commonly ``password``, + ``totp``, or other methods. Indicates the accumulated set of + authentication methods that were used to obtain the receipt. For + example, if the receipt was obtained by password authentication, it + contains ``password``. Later, if the receipt is exchanged by using + another authentication method one or more times, the + subsequently created receipts could contain both ``password`` and + ``totp`` in their ``methods`` attribute. + in: body + required: true + type: array auth_methods_token: description: | The authentication method. For token @@ -513,6 +534,13 @@ auth_methods_token: in: body required: true type: array +auth_methods_totp: + description: | + The authentication method. For totp + authentication, specify ``totp``. + in: body + required: true + type: array auth_token: description: | A ``token`` object. The token authentication @@ -1433,6 +1461,38 @@ projects: in: body required: true type: array +receipt_expires_at: + description: | + The date and time when the receipt expires. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss.sssZ + + For example, ``2015-08-27T09:49:58.000000Z``. + + A ``null`` value indicates that the receipt never expires. + in: body + required: true + type: string +receipt_issued_at: + description: | + The date and time when the receipt was issued. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss.sssZ + + For example, ``2015-08-27T09:49:58.000000Z``. + in: body + required: true + type: string region_id_not_required: description: | (Since v3.2) The ID of the region that contains @@ -1604,6 +1664,13 @@ request_service_id_registered_limit_body_not_required: in: body required: false type: string +required_auth_methods: + description: | + A list of authentication rules that may be used with the auth receipt + to complete the authentication process. + in: body + required: true + type: list of lists resource_limit: description: | The override limit. @@ -1909,6 +1976,12 @@ token: in: body required: true type: object +totp: + description: | + The ``totp`` object, contains the authentication information. + in: body + required: true + type: object user: description: | A ``user`` object. diff --git a/api-ref/source/v3/samples/auth/requests/project-id-totp.json b/api-ref/source/v3/samples/auth/requests/project-id-totp.json new file mode 100644 index 000000000..fdfcc971e --- /dev/null +++ b/api-ref/source/v3/samples/auth/requests/project-id-totp.json @@ -0,0 +1,20 @@ +{ + "auth": { + "identity": { + "methods": [ + "totp" + ], + "totp": { + "user": { + "id": "ee4dfb6e5540447cb3741905149d9b6e", + "passcode": "123456" + } + } + }, + "scope": { + "project": { + "id": "a6944d763bf64ee6a275f1263fae0352" + } + } + } +} diff --git a/api-ref/source/v3/samples/auth/responses/auth-receipt-password.json b/api-ref/source/v3/samples/auth/responses/auth-receipt-password.json new file mode 100644 index 000000000..40f64f87f --- /dev/null +++ b/api-ref/source/v3/samples/auth/responses/auth-receipt-password.json @@ -0,0 +1,20 @@ +{ + "receipt":{ + "expires_at":"2018-07-05T08:39:23.000000Z", + "issued_at":"2018-07-05T08:34:23.000000Z", + "methods": [ + "password" + ], + "user": { + "domain": { + "id": "default", + "name": "Default" + }, + "id": "ee4dfb6e5540447cb3741905149d9b6e", + "name": "admin" + } + }, + "required_auth_methods": [ + ["totp", "password"] + ] +} diff --git a/api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json b/api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json new file mode 100644 index 000000000..6b84e3efe --- /dev/null +++ b/api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json @@ -0,0 +1,67 @@ +{ + "token": { + "audit_ids": [ + "3T2dc1CGQxyJsHdDu1xkcw" + ], + "catalog": [ + { + "endpoints": [ + { + "id": "068d1b359ee84b438266cb736d81de97", + "interface": "public", + "region": "RegionOne", + "region_id": "RegionOne", + "url": "http://example.com/identity" + }, + { + "id": "8bfc846841ab441ca38471be6d164ced", + "interface": "admin", + "region": "RegionOne", + "region_id": "RegionOne", + "url": "http://example.com/identity" + }, + { + "id": "beb6d358c3654b4bada04d4663b640b9", + "interface": "internal", + "region": "RegionOne", + "region_id": "RegionOne", + "url": "http://example.com/identity" + } + ], + "type": "identity", + "id": "050726f278654128aba89757ae25950c", + "name": "keystone" + } + ], + "expires_at": "2015-11-07T02:58:43.578887Z", + "is_domain": false, + "issued_at": "2015-11-07T01:58:43.578929Z", + "methods": [ + "password", + "totp" + ], + "project": { + "domain": { + "id": "default", + "name": "Default" + }, + "id": "a6944d763bf64ee6a275f1263fae0352", + "name": "admin" + }, + "roles": [ + { + "id": "51cc68287d524c759f47c811e6463340", + "name": "admin" + } + ], + "user": { + "domain": { + "id": "default", + "name": "Default" + }, + "id": "ee4dfb6e5540447cb3741905149d9b6e", + "name": "admin", + "password_expires_at": "2016-11-06T15:32:17.000000" + } + } +} diff --git a/api-ref/source/v3/status.yaml b/api-ref/source/v3/status.yaml index 4cecc2ceb..e026069ac 100644 --- a/api-ref/source/v3/status.yaml +++ b/api-ref/source/v3/status.yaml @@ -27,6 +27,14 @@ 401: default: | User must authenticate before making a request. + auth_failed: | + Authentication attempt has failed. + auth_receipt: | + User has successfully supplied some auth methods, but not enough for full + authentication. + auth_receipt_failure: | + Authentication attempt has failed. Either the auth receipt has expired, or + the additional auth methods supplied were invalid. 403: default: | Policy does not allow current user to do this operation. -- cgit v1.2.1