Skip to content

Commit 4a362d5

Browse files
Naarcha-AWSnatebower
Naarcha-AWS
and
natebower
authored
Add Security Authentication and Configuration API reference (#9866)
* Add security authentication APIs. Signed-off-by: Archer <naarcha@amazon.com> * Add Configuration APIs Signed-off-by: Archer <naarcha@amazon.com> * Add Configuration APIs. Add intro labels Signed-off-by: Archer <naarcha@amazon.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Fix links. Add technical feedback Signed-off-by: Archer <naarcha@amazon.com> * Fix last two broken links Signed-off-by: Archer <naarcha@amazon.com> * Apply suggestions from code review Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Fix automated marker Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Fix title in metadata. Signed-off-by: Archer <naarcha@amazon.com> --------- Signed-off-by: Archer <naarcha@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
1 parent 859166d commit 4a362d5

File tree

8 files changed

+546
-20
lines changed

8 files changed

+546
-20
lines changed

‎_api-reference/security-apis.md

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎_api-reference/security/authentication/auth-info.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
layout: default
3+
title: Authentication Information API
4+
grand_parent: Security APIs
5+
parent: Authentication APIs
6+
nav_order: 10
7+
---
8+
9+
# Authentication Information API
10+
**Introduced 1.0**
11+
{: .label .label-purple }
12+
13+
The Authentication Information API returns information about the currently authenticated user. This includes the user's name, roles, backend roles, custom attributes, and tenant memberships. This API is useful for debugging authentication issues, verifying user permissions, and building applications that need to understand the current user's access levels.
14+
15+
<!-- spec_insert_start
16+
api: security.authinfo
17+
component: endpoints
18+
-->
19+
## Endpoints
20+
```json
21+
GET /_plugins/_security/authinfo
22+
POST /_plugins/_security/authinfo
23+
```
24+
<!-- spec_insert_end -->
25+
26+
<!-- spec_insert_start
27+
api: security.authinfo
28+
component: query_parameters
29+
-->
30+
## Query parameters
31+
32+
The following table lists the available query parameters. All query parameters are optional.
33+
34+
| Parameter | Data type | Description |
35+
| :--- | :--- | :--- |
36+
| `auth_type` | String | The type of the current authentication request. |
37+
| `verbose` | Boolean | Whether to return a verbose response. |
38+
39+
<!-- spec_insert_end -->
40+
41+
## Example request
42+
43+
The following example request retrieves authentication information for the currently authenticated user:
44+
45+
```bash
46+
GET /_plugins/_security/authinfo
47+
```
48+
{% include copy-curl.html %}
49+
50+
To get verbose information:
51+
52+
```bash
53+
GET /_plugins/_security/authinfo?verbose=true
54+
```
55+
{% include copy-curl.html %}
56+
57+
## Example response
58+
59+
```json
60+
{
61+
"user": "User [name=admin, backend_roles=[admin], requestedTenant=null]",
62+
"user_name": "admin",
63+
"backend_roles": [
64+
"admin"
65+
],
66+
"roles": [
67+
"all_access",
68+
"security_rest_api_access"
69+
],
70+
"tenants": {
71+
"admin": true,
72+
"global_tenant": true
73+
},
74+
"principal": null,
75+
"peer_certificates": "0",
76+
"sso_logout_url": null,
77+
"remote_address": "127.0.0.1:54013"
78+
}
79+
```
80+
81+
For a verbose response, additional fields are included:
82+
83+
```json
84+
{
85+
"user": "User [name=admin, backend_roles=[admin], requestedTenant=null]",
86+
"user_name": "admin",
87+
"backend_roles": [
88+
"admin"
89+
],
90+
"custom_attribute_names": [],
91+
"roles": [
92+
"all_access",
93+
"security_rest_api_access"
94+
],
95+
"tenants": {
96+
"admin": true,
97+
"global_tenant": true
98+
},
99+
"principal": null,
100+
"peer_certificates": "0",
101+
"sso_logout_url": null,
102+
"remote_address": "127.0.0.1:54013",
103+
"size_of_user": "115",
104+
"size_of_backendroles": "28",
105+
"size_of_custom_attributes": "2",
106+
"user_requested_tenant": null
107+
}
108+
```
109+
110+
## Response body fields
111+
112+
The response body is a JSON object with the following fields.
113+
114+
| Property | Data type | Description |
115+
| :--- | :--- | :--- |
116+
| `user` | String | A string representation of the user object, including the username and backend roles. |
117+
| `user_name` | String | The username of the authenticated user. |
118+
| `backend_roles` | Array of strings | The backend roles associated with the user, typically obtained from an external authentication system. |
119+
| `roles` | Array of strings | The OpenSearch Security roles assigned to the user, determining their permissions. |
120+
| `tenants` | Object | The tenants the user has access to, with `true` indicating read-write access and `false` indicating read-only access. |
121+
| `principal` | String | The user's authentication principal, if available. |
122+
| `peer_certificates` | String | The number of peer certificates related to the user's authentication. |
123+
| `sso_logout_url` | String | The logout URL for single sign-on (SSO) authentication, if applicable. |
124+
| `remote_address` | String | The IP address and port of the client making the request. |
125+
126+
When requesting a verbose response, the following additional fields are included.
127+
128+
| Property | Data type | Description |
129+
| :--- | :--- | :--- |
130+
| `custom_attribute_names` | Array of strings | The names of any custom attributes associated with the user. |
131+
| `size_of_user` | String | The size of the user object in memory, in bytes. |
132+
| `size_of_backendroles` | String | The size of the user's backend roles, in bytes. |
133+
| `size_of_custom_attributes` | String | The size of the user's custom attributes, in bytes. |
134+
| `user_requested_tenant` | String | The name of the tenant the user has requested to switch to, if any. |

‎_api-reference/security/authentication/change-password.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
layout: default
3+
title: Change Password API
4+
grand_parent: Security APIs
5+
parent: Authentication APIs
6+
nav_order: 30
7+
---
8+
9+
# Change Password API
10+
**Introduced 1.0**
11+
{: .label .label-purple }
12+
13+
The Change Password API allows users to update their own passwords. Users must provide their current password for verification before the password change is allowed.
14+
15+
<!-- spec_insert_start
16+
api: security.change_password
17+
component: endpoints
18+
-->
19+
## Endpoints
20+
```json
21+
PUT /_plugins/_security/api/account
22+
```
23+
<!-- spec_insert_end -->
24+
25+
<!-- spec_insert_start
26+
api: security.change_password
27+
component: query_parameters
28+
-->
29+
30+
<!-- spec_insert_start
31+
api: security.change_password
32+
component: request_body_parameters
33+
-->
34+
## Request body fields
35+
36+
The request body is __required__. It is a JSON object with the following fields.
37+
38+
| Property | Required | Data type | Description |
39+
| :--- | :--- | :--- | :--- |
40+
| `current_password` | **Required** | String | The current password. |
41+
| `password` | **Required** | String | The new password to set. |
42+
43+
## Example request
44+
45+
```json
46+
PUT /_plugins/_security/api/account
47+
{
48+
"current_password": "old-secure-password",
49+
"password": "new-secure-password"
50+
}
51+
```
52+
{% include copy-curl.html %}
53+
54+
## Example response
55+
56+
A successful response indicates that the password has been changed:
57+
58+
```json
59+
{
60+
"status": "OK",
61+
"message": "Password changed"
62+
}
63+
```
64+
65+
If the current password is incorrect, the API returns an error:
66+
67+
```json
68+
{
69+
"status": "UNAUTHORIZED",
70+
"message": "Invalid credentials"
71+
}
72+
```
73+
74+
## Response body fields
75+
76+
The response body is a JSON object with the following fields.
77+
78+
| Property | Data type | Description |
79+
| :--- | :--- | :--- |
80+
| `status` | String | The status of the request. A successful request returns "OK". |
81+
| `message` | String | A message describing the result of the operation. |
82+
83+
## Password best practices
84+
85+
Proper password management is essential for securing your OpenSearch cluster. When using this API to change a password, keep the following guidelines in mind:
86+
87+
- You can only use this API to change the password of the currently authenticated user.
88+
- Make sure the new password meets any configured password policies.
89+
- Existing authentication tokens remain valid until they expire, even after the password changes.
90+
- Use strong passwords that include a mix of uppercase and lowercase letters, numbers, and special characters.
91+
92+
To enhance security, use a password manager to generate and store complex passwords. Incorporate regular password rotation into your organization's security policy to help protect against unauthorized access.

‎_api-reference/security/authentication/index.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
layout: default
3+
title: Authentication APIs
4+
parent: Security APIs
5+
has_children: true
6+
nav_order: 10
7+
---
8+
9+
# Authentication APIs
10+
11+
Authentication is a fundamental aspect of security in OpenSearch, verifying the identity of users and services before granting access to protected resources. The Security plugin provides several APIs you can use to manage authentication, obtain user information, and handle credentials.
12+
13+
## Available APIs
14+
15+
The Authentication APIs include the following operations:
16+
17+
- [Authentication Information API]({{site.url}}{{site.baseurl}}/api-reference/security/authentication/auth-info/): Returns information about the currently authenticated user, including roles, backend roles, and tenant memberships. Useful for debugging authentication issues, verifying permissions, and retrieving user context for applications.
18+
19+
- [Change Password API]({{site.url}}{{site.baseurl}}/api-reference/security/authentication/change-password/): Lets users update their own passwords securely. Requires verification of the current password and does not require administrator involvement.
20+
21+
## Authentication workflows
22+
23+
These APIs support the following common authentication workflows:
24+
25+
- **User verification**: Confirm a user's identity and permissions before executing sensitive operations.
26+
- **Self-service password management**: Allow users to change their passwords independently.
27+
- **Multi-tenant access**: Determine a user's accessible tenants and associated permissions.
28+
29+
## Authentication methods
30+
31+
The Security plugin supports [multiple authentication methods]({{site.url}}{{site.baseurl}}/security/authentication-backends/authc-index/), including:
32+
33+
- Basic authentication (username and password).
34+
- Token-based authentication.
35+
- Certificate-based authentication.
36+
- Single sign-on (SSO) methods, such as SAML and OpenID Connect.
37+
38+
The APIs in this section are compatible with all supported authentication methods and offer a consistent interface for managing authentication in OpenSearch.

‎_api-reference/security/configuration/index.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
layout: default
3+
title: Configuration APIs
4+
parent: Security APIs
5+
has_children: true
6+
nav_order: 20
7+
---
8+
9+
# Configuration APIs
10+
**Introduced 1.0**
11+
{: .label .label-purple }
12+
13+
The Configuration APIs provide programmatic access for managing, validating, and upgrading Security plugin configuration components. These APIs help ensure that your security settings remain compatible and effective as your OpenSearch cluster evolves.
14+
15+
Security configurations may require updates in the following scenarios:
16+
17+
- Upgrading to a new version of OpenSearch or the Security plugin
18+
- Enabling new features that require updated settings
19+
- Migrating configurations between environments
20+
- Troubleshooting security issues
21+
22+
## When to use
23+
24+
Use the Configuration APIs to perform the following actions:
25+
26+
- Identify outdated or incompatible configuration components.
27+
- Perform automatic upgrades to maintain compatibility.
28+
- Validate the structure and integrity of your security configuration.
29+
- Manage versioning of security settings.
30+
31+
## Available APIs
32+
33+
- [Upgrade Check API]({{site.url}}{{site.baseurl}}/api-reference/security/configuration/upgrade-check/): Checks your current configuration for compatibility with your OpenSearch version and identifies components that need to be upgraded.
34+
35+
- [Upgrade Perform API]({{site.url}}{{site.baseurl}}/api-reference/security/configuration/upgrade-perform/): Applies updates to the security configuration, based on the results of the Upgrade Check API.
36+
37+
## Configuration components
38+
39+
These APIs manage the following configuration components:
40+
41+
- **Roles**: Permissions for actions users can perform
42+
- **Role mappings**: Mappings for users or backend roles with specific roles
43+
- **Action groups**: Collections of permissions used to simplify role definitions
44+
- **Internal users**: User credentials stored directly in OpenSearch
45+
- **Tenants**: Isolated workspaces that support multi-tenancy
46+
- **Security configuration**: Global security settings
47+
48+
## Best practices
49+
50+
When using the Configuration APIs, remember the following best practices:
51+
52+
- Always back up your security configuration before making changes.
53+
- Run the Upgrade Check API before using the Upgrade Perform API.
54+
- Test changes in a non-production environment before deploying to production.
55+
- Integrate these APIs into your regular upgrade and maintenance workflows.
56+
- Validate functionality after applying configuration changes.

0 commit comments

Comments
 (0)