From 9d9dc5f077fc3aebd9a544e0b271d171bcfdb01b Mon Sep 17 00:00:00 2001 From: Ihor Aleksandrychiev Date: Wed, 7 Aug 2024 14:40:36 +0300 Subject: [PATCH] Added Two-factor authentication API documentation Ticket: ENT-10838 Signed-off-by: Ihor Aleksandrychiev --- .../two-factor-authentication.markdown | 256 ++++++++++++++++++ api/enterprise-api-ref/users-rbac.markdown | 13 +- 2 files changed, 266 insertions(+), 3 deletions(-) create mode 100644 api/enterprise-api-ref/two-factor-authentication.markdown diff --git a/api/enterprise-api-ref/two-factor-authentication.markdown b/api/enterprise-api-ref/two-factor-authentication.markdown new file mode 100644 index 000000000..4dbca439f --- /dev/null +++ b/api/enterprise-api-ref/two-factor-authentication.markdown @@ -0,0 +1,256 @@ +--- +layout: default +title: Two-factor authentication API +published: true +--- +The Two-factor authentication API enables users to add an extra layer of security to their accounts +by requiring a TOTP (time-based one-time password) in addition to their primary credentials. + +Once two-factor authentication is enabled, requests to obtain an OAuth token, change a password, or +disable two-factor authentication must include an additional header: `Cf-2fa-Token: `. +Basic authentication also requires this header each time it is used. + +Currently, only TOTP (Time-based One-Time Password) two-factor authentication +is supported, providing users with a time-sensitive code for enhanced security. + +## Start two-factor authentication configuration + +First, you need to request two-factor authentication secrets to complete the configuration. +The secret token should be added to a third-party authentication app such as Google Authenticator or Authy. +A 6-digit code should then be obtained from the application to complete the action. + +**URI:** https://hub.cfengine.com/api/2fa/totp/configure + +**Method:** GET + +**Example request (curl):** + +```console +curl --user : \ + -X GET \ + https://hub.cfengine.com/api/2fa/totp/configure +``` + +**Successful response example:** + +``` +HTTP 200 Ok +{ + "secret": "SYSZJJVQUIOG5ITA6HPH5PZWLZ3VUP52", + "2faUrl": "otpauth://totp/Mission%20Portal:admin?secret=SYSZJJVQUIOG5ITA6HPH5PZWLZ3VUP52&issuer=Mission%20Portal&algorithm=SHA1&digits=6&period=30", + "algorithm": "sha1", + "digits": 6, + "period": 30, + "issuer": "Mission Portal", + "holder": "admin" +} +``` + +**Output:** + +* **secret** + The secret key used to generate the one-time password (OTP) +* **2faUrl** + The URL that can be converted into QR code and scanned with an authenticator app to set up two-factor authentication +* **algorithm** + The cryptographic algorithm used to generate the OTP +* **digits** + The number of digits in the generated OTP code +* **period** + The time period in seconds for which the OTP code is valid +* **issuer** + The name of the service that is providing the two-factor authentication +* **holder** + The username for whom the two-factor authentication is being configured + +**Responses:** + +| HTTP response code | Description | +|---------------------------|----------------------------------------| +| 200 OK | 2FA configuration successfully created | +| 500 Internal server error | Internal server error | + + + +## Complete two-factor authentication configuration + +**URI:** https://hub.cfengine.com/api/2fa/totp/configure + +**Method:** POST + +**Parameters:** + +* **code** *(string)* + 6-digit code from the authentication application + +**Example request (curl):** + +```console +curl --user : \ + -X POST \ + https://hub.cfengine.com/api/2fa/totp/configure \ + --data-raw '{"code": "000000"}' +``` + +**Successful response example:** + +``` +HTTP 200 Ok +2FA successfully enabled for this user. +``` + +**Responses:** + +| HTTP response code | Description | +|---------------------------|-----------------------------| +| 200 OK | 2FA successfully configured | +| 400 Bad request | 2FA verification failed. | +| 500 Internal server error | Internal server error | + + +## Disable two-factor authentication for the current user + +**URI:** https://hub.cfengine.com/api/2fa/totp/disable + +**Method:** POST + +**Headers:** + +* **Cf-2FA-Token** *(string)* + 6-digit code from the authentication application + +**Example request (curl):** + +```console +curl --user : \ + -X POST \ + https://hub.cfengine.com/api/2fa/totp/disable \ + --header 'Cf-2FA-Token: 537987' +``` + +**Successful response example:** + +``` +HTTP 200 Ok +2FA successfully disabled for this user. +``` + +**Responses:** + +| HTTP response code | Description | +|---------------------------|----------------------------------------| +| 200 OK | 2FA successfully disabled | +| 401 Unauthorized | Invalid two-factor authentication code | +| 409 Conflict | 2FA is not enabled for this user | +| 500 Internal server error | Internal server error | + +## Disable two-factor authentication for other users + +In case if a regular user loses access to the authentication application, specific users (admin role by default) +with the `Disable 2FA for any user` RBAC role (alias `2fa.any-user.disable`) will be able to +disable two-factor authentication for that user. + +**URI:** https://hub.cfengine.com/api/2fa/totp/disable/user/:username + +**Method:** POST + +**Example request (curl):** + +```console +curl --user : \ + -X POST \ + https://hub.cfengine.com/api/2fa/totp/disable/user/giorgio +``` + +**Successful response example:** + +``` +HTTP 200 Ok +2FA successfully disabled for `giorgio` user. +``` + +**Responses:** + +| HTTP response code | Description | +|---------------------------|----------------------------------------| +| 200 OK | 2FA successfully disabled | +| 401 Unauthorized | Invalid two-factor authentication code | +| 409 Conflict | 2FA is not enabled for this user | +| 500 Internal server error | Internal server error | + + + +## Verify two-factor authentication code + +This API endpoint verifies the authentication code. If OAuth authentication is used and the code is valid, +your authorization token will be flagged as verified for 5 minutes. During this 5-minute period after successful +verification, you will not need to provide the authorization code from the authentication application. + +**URI:** https://hub.cfengine.com/api/2fa/totp/verify + +**Method:** POST + +**Parameters:** + +* **code** *(string)* + 6-digit code from the authentication application + +**Example request (curl):** + +```console +curl --user : \ + -X POST \ + https://hub.cfengine.com/api/2fa/totp/veify \ + --data-raw '{"code": "000000"}' +``` + +**Successful response example:** + +``` +HTTP 200 Ok +2FA successfully verified. +``` + +**Responses:** + +| HTTP response code | Description | +|---------------------------|----------------------------------| +| 200 OK | 2FA successfully verified | +| 409 Conflict | 2FA is not enabled for this user | +| 500 Internal server error | Internal server error | + + +## Check if verification is needed + +This API endpoint checks if 2FA verification is needed. Only needed for OAuth authentication method +as for the Basic authentication is needed every time. + +**URI:** https://hub.cfengine.com/api/2fa/verification-needed + +**Method:** GET + + +**Example request (curl):** + +```console +curl -X GET \ + https://hub.cfengine.com/api/2fa/verification-needed \ + --header 'Authorization: Bearer 627135e5a0b142cfdc738c38ad0c0067bc0960e5' +``` + +**Successful response example:** + +``` +HTTP 200 Ok +{ + "result": true +} +``` + +**Responses:** + +| HTTP response code | Description | +|---------------------------|----------------------------------| +| 200 OK | 2FA successfully checked | +| 409 Conflict | 2FA is not enabled for this user | +| 500 Internal server error | Internal server error | diff --git a/api/enterprise-api-ref/users-rbac.markdown b/api/enterprise-api-ref/users-rbac.markdown index 19aaec8ea..5b8809577 100644 --- a/api/enterprise-api-ref/users-rbac.markdown +++ b/api/enterprise-api-ref/users-rbac.markdown @@ -40,7 +40,8 @@ API call allowed only for administrator. "admin", "cf_remoteagent" ], - "external": false + "external": false, + "two_factor_enabled": true }, { "id": "admin", @@ -50,7 +51,8 @@ API call allowed only for administrator. "admin", "cf_remoteagent" ], - "external": false + "external": false, + "two_factor_enabled": false }, { "id": "user_1", @@ -74,6 +76,8 @@ API call allowed only for administrator. List of assigned RBAC roles. * **external** Is user from external source (LDAP/AD). +* **two_factor_enabled** + If a user has enabled two-factor authentication **Example usage:** `Example: Listing users` @@ -105,7 +109,8 @@ API call allowed only for administrator. "linux_team" ], "external": false, - "time_zone": "Europe/Oslo" + "time_zone": "Europe/Oslo", + "two_factor_enabled": false } ] } @@ -123,6 +128,8 @@ API call allowed only for administrator. Is user from external source (LDAP/AD). * **time_zone** Time zone +* **two_factor_enabled** + If a user has enabled two-factor authentication **Example usage:** `Example: Retrieving a user`