diff --git a/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-is-invalid.json b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-is-invalid.json new file mode 100644 index 0000000000..165e20fb85 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-is-invalid.json @@ -0,0 +1,14 @@ +{ + "ocs": { + "meta": { + "status": "ok", + "statuscode": 100, + "message": "OK", + "totalitems": "", + "itemsperpage": "" + }, + "data": { + "result": false + } + } +} diff --git a/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-is-valid.json b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-is-valid.json new file mode 100644 index 0000000000..bbee8478ce --- /dev/null +++ b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-is-valid.json @@ -0,0 +1,14 @@ +{ + "ocs": { + "meta": { + "status": "ok", + "statuscode": 100, + "message": "OK", + "totalitems": "", + "itemsperpage": "" + }, + "data": { + "result": true + } + } +} diff --git a/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-user-is-not-found.json b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-user-is-not-found.json new file mode 100644 index 0000000000..4cbc1b39e6 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/json/totp-user-is-not-found.json @@ -0,0 +1,14 @@ +{ + "ocs": { + "meta": { + "status": "failure", + "statuscode": 404, + "message": "OK", + "totalitems": "", + "itemsperpage": "" + }, + "data": { + "result": false + } + } +} diff --git a/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-is-invalid.xml b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-is-invalid.xml new file mode 100644 index 0000000000..c74bf893e9 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-is-invalid.xml @@ -0,0 +1,13 @@ + + + + ok + 100 + OK + + + + + + + diff --git a/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-is-valid.xml b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-is-valid.xml new file mode 100644 index 0000000000..93e07b3f75 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-is-valid.xml @@ -0,0 +1,13 @@ + + + + ok + 100 + OK + + + + + 1 + + diff --git a/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-user-is-not-valid.xml b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-user-is-not-valid.xml new file mode 100644 index 0000000000..f4efca459e --- /dev/null +++ b/modules/developer_manual/examples/core/apis/ocs/totp-validation/responses/xml/totp-user-is-not-valid.xml @@ -0,0 +1,13 @@ + + + + failure + 404 + OK + + + + + + + diff --git a/modules/developer_manual/examples/core/scripts/curl/ocs/validate-totp.sh b/modules/developer_manual/examples/core/scripts/curl/ocs/validate-totp.sh new file mode 100644 index 0000000000..510d326c9d --- /dev/null +++ b/modules/developer_manual/examples/core/scripts/curl/ocs/validate-totp.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +USERNAME=admin +PASSWORD={oc-examples-password} +API_PATH="ocs/v1.php/apps/twofactor_totp/api/v1/validate//" +SERVER_URI="{oc-examples-server-url}" + +curl '$SERVER_URI/$API_PATH/' \ + --user "${USERNAME}:${PASSWORD}" diff --git a/modules/developer_manual/nav.adoc b/modules/developer_manual/nav.adoc index e596192363..91da370c50 100644 --- a/modules/developer_manual/nav.adoc +++ b/modules/developer_manual/nav.adoc @@ -23,6 +23,7 @@ **** xref:core/apis/ocs-capabilities.adoc[The OCS REST API] **** xref:core/apis/ocs-recipient-api.adoc[The OCS Recipient API] **** xref:core/apis/ocs-share-api.adoc[The OCS Share API] +**** xref:core/apis/ocs-totp-validation-api.adoc[The OCS TOTP Validation API] **** xref:webdav_api/index.adoc[WebDAV APIs] ***** xref:webdav_api/comments.adoc[The Comments API] ***** xref:webdav_api/groups.adoc[The Custom Groups Management API] diff --git a/modules/developer_manual/pages/core/apis/ocs-totp-validation-api.adoc b/modules/developer_manual/pages/core/apis/ocs-totp-validation-api.adoc new file mode 100644 index 0000000000..aa6d79c3bb --- /dev/null +++ b/modules/developer_manual/pages/core/apis/ocs-totp-validation-api.adoc @@ -0,0 +1,141 @@ += OCS TOTP (Time-based One-time Password) Validation API +:toc: right +:toclevels: 1 +:request-base-path: ocs/v1.php/apps/twofactor_totp/api/v1/validate +:2fa-app-url: https://marketplace.owncloud.com/apps/twofactor_totp +:totp-url: https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm + +== Introduction + +The OCS {totp-url}[TOTP (Time-based One-time Password)] Validation API allows administrator users to validate if a TOTP is valid. + +IMPORTANT: Only admin accounts can use this API. + +IMPORTANT: When {2fa-app-url}[2FA (Two-Factor Authentication)] is activated on an account, authorization with a username and password is not possible. +Requests must authenticate via xref:user_manual:session_management.adoc:app-passwords[app passwords]. + +== Prerequisites + +This API requires {2fa-app-url}[the 2-Factor Authentication app] to be installed and enabled. + +== Validate TOTP + +* Path: `{request-base-path}//` +* Method: `GET` + +=== Request Parameters + +[cols="15%,15%,70%",options="header",width=100%] +|=== +|Attribute +|Type +|Description + +|`userid` +|string +|The user id of the user to validate the TOTP for. + +|`totp` +|string +|The TOTP to validate. +|=== + +=== Code Example + +[tabs] +==== +Curl:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/scripts/curl/ocs/validate-totp.sh[] +---- +-- +==== + +=== Returns + +The request returns either an XML (the default) or a JSON response, along with an `HTTP 200 OK` status code, which show whether: + +. The TOTP is valid +. The TOTP is invalid +. The user was not found + +The status of the TOTP is located in the `ocs/data/result` element. +If the user was not found, then: + +. `ocs/meta/status` will be set to `failure`. +. `ocs/meta/statuscode` will be set to `404`. + +=== Example Responses + +==== TOTP Is Valid + +[tabs] +==== +JSON:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/apis/ocs/totp-validation/responses/json/totp-is-valid.json[] +---- +-- + +XML:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/apis/ocs/totp-validation/responses/json/totp-is-valid.json[] +---- +-- +==== + +==== TOTP Is Not Valid + +[tabs] +==== +JSON:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/apis/ocs/totp-validation/responses/xml/totp-is-valid.xml[] +---- +-- + +XML:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/apis/ocs/totp-validation/responses/xml/totp-is-valid.xml[] +---- +-- +==== + +==== User or Secret Not Found + +[tabs] +==== +JSON:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/apis/ocs/totp-validation/responses/json/totp-user-is-not-valid.json[] +---- +-- + +XML:: ++ +-- +[source,console,subs="attributes+"] +---- +include::{examplesdir}core/apis/ocs/totp-validation/responses/xml/totp-user-is-not-valid.xml[] +---- +-- +==== +