Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ENT-10841: Updated Settings and Users APIs documentations #3340

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

ENT-10841: Updated Settings and Users APIs documentations #3340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b37ffa6
Updated Settings API documentation
aleksandrychev Sep 5, 2024
7e31bd7
Added the Unlock users endpoint
aleksandrychev Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 30 additions & 18 deletions api/enterprise-api-ref/status-settings.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,29 +88,23 @@ API call allowed only for administrator.
},
"data": [
{
"hostIdentifier": "default.sys.fqhost",
"rbacEnabled": true,
"logLevel": "error",
"ldapEnabled": true,
"blueHostHorizon": 900,
"sameHostsNumberOfRuns": 3
"blueHostHorizon": 2400,
"enforce2FA": false,
"hostIdentifier": "default.sys.fqhost",
"hostsCollisionsThreshold": 3,
"logLevel": "error",
"minPasswordLength": 8,
"passwordComplexity": 3,
"passwordExpirationAfterResetHours": 48,
"rbacEnabled": true
}
]
}
```

**Output**:

* **rbacEnabled** *(boolean)*
Whether RBAC is applied to requests.
* **hostIdentifier** *(string)*
The identfying string for hosts, such as name or IP.
* **ldapEnabled** *(boolean)*
Whether external authentication is activated.
* **logLevel** *("emergency", "alert", "critical", "error", "warning", "notice", "info", "debug")*
Syslog filter specifying the severity level at which messages produced by the API should be emitted to syslog and apache.log. (default: error).
* **sameHostsNumberOfRuns** *(integer)*
Number of samples used to identify a duplicate identity. Default value is 3.
See [Update settings][Status and settings REST API#Update settings] field section for output descriptions


**Example usage:** `Example: Viewing settings`
Expand Down Expand Up @@ -138,7 +132,21 @@ administrator.
Threshold in minutes that hosts are unreachable before they are considered a health issue.
* **sameHostsNumberOfRuns** *(integer)*
Number of samples used to identify a duplicate identity. Default value is 3.

* **enforce2FA** *(boolean)*
Determines if two-factor authentication (2FA) is mandatory for all users.
If set to `true`, users must enable 2FA; otherwise, they will be locked out within 48 hours after the first login.
Default value: `false`
* **minPasswordLength** *(integer)*
Sets the minimum required length for user passwords.
The value represents the number of characters.
Default value: `8`
* **passwordComplexity** *(integer)*
Defines the level of password complexity required.
The range is from 0 to 4, where zero turns of the password complexity check and four turns on the maximum level.
Default value: `3`
* **passwordExpirationAfterResetHours** *(integer)*
Specifies the number of hours after which a password must expire following a reset.
Default value: `48`

**Example Request Body:**

Expand All @@ -149,7 +157,11 @@ administrator.
"logLevel": "error",
"ldapEnabled": true,
"blueHostHorizon": 900,
"sameHostsNumberOfRuns": 5
"sameHostsNumberOfRuns": 5,
"minPasswordLength": 12,
"passwordComplexity": 4,
"passwordExpirationAfterResetHours": 24,
"enforce2FA": true
}
```

Expand Down
27 changes: 27 additions & 0 deletions api/enterprise-api-ref/users-rbac.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,3 +367,30 @@ API call allowed only for administrator.

Remove role definition.
API call allowed only for administrator.

## Unlock user

If a system enforces using two-factor authentication (2FA),
users must configure it after their first login within 48 hours.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually it's whatever passwordExpirationAfterResetHours is set to which happens to default to 48 hours right?

I think 48 hours reads more easily but I think referring to the setting that contains the actual value is a bit more specific and correct.

This endpoint unlocks users who have been locked out due to this reason
and grants an additional 48 hours to complete the 2FA setup.

Note: to be able to perform this action related RBAC rule (alias `user.unlock`) should be enabled.
craigcomstock marked this conversation as resolved.
Show resolved Hide resolved

**URI:** https://hub.cfengine.com/api/user/:username/unlock

**Method:** POST

**Example request (curl):**

```console
curl --user <username>:<password> \
-X POST \
https://hub.cfengine.com/api/user/tom/unlock
```

**Example response:**

```
HTTP 202 ACCEPTED
```
Loading