Authorization Context
This guide outlines how to start using the authorization context login method.
Authorization context login method
The authorization context login method (POST /security/user/authenticate/run_as) dynamically obtains permissions. It enables any authorized user to acquire any desired permissions without assignment to a specific role, bypassing the usual user-role relationships. This requires a precise formalization of the authorization context.
To employ this method, you must first allow a user to use the authorization context (details on creating and enabling a user for authorization context is available in the RESTful API RBAC configuration section). Once you have established the necessary security rules, you must send an authorization context containing all the required information. The system will verify this against the security rules and grant the associated permissions.
The image below outlines the decision process for granting permissions through authorization context, detailing the steps from a user's login attempt to the assignment of permissions based on enabled settings and rule validation.
The command below demonstrates how to authenticate a user using the authorization context feature. Replace <WAZUH_API_USER>
and <WAZUH_API_PASSWORD>
with your credentials:
# curl -k -u <WAZUH_API_USER>:<WAZUH_API_PASSWORD> -X POST https://localhost:55000/security/user/authenticate/run_as -H 'content-type: application/json' -d '{
"name": "Initial_auth",
"auth": {
"name": "Bill",
"office": ["20", "21", "30"]
}
}'
{
"data": {
"token": "<YOUR_JWT_TOKEN>"
}
}
API log for authorization context login method
As explained in the last section, authorization context grants additional permissions to any authorized user. The API logs tag these extra permissions with a unique identifier following the username, linking to the used authorization context.
Here are API log examples for authorization context login and basic login methods:
Authorization context login method:
2022/02/10 11:23:14 INFO: wazuh (66a28efb5f8db2e93da2b5fb107bec35) 127.0.0.1 "POST /security/user/authenticate/run_as" with parameters {"raw": "true"} and body {"name": "Initial_auth", "auth": {"name": "Bill", "office": ["20", "21", "30"]}} done in 0.363s: 200
2022/02/10 11:23:18 INFO: wazuh (66a28efb5f8db2e93da2b5fb107bec35) 127.0.0.1 "GET /" with parameters {} and body {} done in 0.051s: 200
Basic login method:
2022/02/02 08:59:19 INFO: wazuh 127.0.0.1 "POST /security/user/authenticate" with parameters {"raw": "true"} and body {} done in 0.253s: 200
2022/02/02 08:59:23 INFO: wazuh 127.0.0.1 "GET /" with parameters {} and body {} done in 0.039s: 200
If JSON log format is enabled, logs for the authorization context login method will appear as follows:
{
"timestamp": "2022/02/10 11:23:14",
"levelname": "INFO",
"data": {
"type": "request",
"payload": {
"user": "wazuh",
"hash_auth_context": "66a28efb5f8db2e93da2b5fb107bec35",
"ip": "127.0.0.1",
"http_method": "POST",
"uri": "POST /security/user/authenticate/run_as",
"parameters": {
"raw": "true"
},
"body": {
"name": "Initial_auth",
"auth": {
"name": "Bill",
"office": [
"20",
"21",
"30"
]
}
},
"time": "0.352s",
"status_code": 200
}
}
}
{
"timestamp": "2022/02/10 11:23:18",
"levelname": "INFO",
"data": {
"type": "request",
"payload": {
"user": "wazuh",
"hash_auth_context": "66a28efb5f8db2e93da2b5fb107bec35",
"ip": "127.0.0.1",
"http_method": "GET",
"uri": "GET /",
"parameters": {},
"body": {},
"time": "0.159",
"status_code": 200
}
}
}
Rules and roles
A rule defines logical and search operations that apply to an incoming authorization context. Thus, when the Wazuh server API processes an authentication request via an authorization context, it checks all rules against it, granting the user any roles associated with the rules that yield an affirmative result.
Let's use the following authorization context to illustrate each operation within the rules and how it matches up to the examples:
{
"name": "Initial_auth",
"auth": {
"name": "Wazuh",
"office": ["20", "21", "30"]
}
}
Search operations
The search operations in the rules are used to search in the authorization context for a specific object or string.
MATCH: This operation will search in the authorization context the structure indicated inside
MATCH
. An exact match is not necessary. I.e., in the following case, it will try to search forauth
key and, within it, anoffice
key whose value must contain the number 20:{ "MATCH": { "auth": { "office": "20" } } }
MATCH$: This operation is the same as
MATCH
with the difference that it is strict in terms of content. It will be evaluated asFalse
even if the clause is contained in a larger set (list) in the authorization context. The previous example would not be evaluated asTrue
since the content of theauth
key is not an exact match. To get this rule evaluated asTrue
, it would be necessary to use the exact list of values:{ "MATCH$": { "auth": { "office": ["20", "21", "30"] } } }
FIND: This operation is a recursive
MATCH
at all levels of the authorization context. In theMATCH
case, the structure is searched at the root of the authorization context. In theFIND
case, the structure will be searched at all depth levels. In the following example it is unneeded to specify the keyauth
because theFIND
operation will search the keyoffice
inside all the authorization contexts:{ "FIND": { "office": "20" } }
FIND$: This operation is a recursive
MATCH$
at all depth levels of the authorization context. As with theMATCH$
operation, the exact list of values in the office key must be included if we want it to be evaluated as True. Thename
is optional as it depends on how specific it needs to be:{ "FIND$": { "name": "Wazuh", "office": ["20", "21", "30"] } }
Logical operations
In defining rules for authorization contexts, logical operations play a crucial role. Here are the three core logical operations:
AND: Requires all contained clauses to be true for the overall expression to be true. For example:
{ "AND": [ { "MATCH$": { "name": "r'.+'" } }, { "FIND": { "auth": { "office": "20" } } } ] }
OR: The result is true if at least one of the enclosed clauses is satisfied. For example:
{ "OR": [ { "MATCH$": { "name": "NameNotFound" } }, { "FIND$": { "auth": { "name": "Wazuh", "office": ["20", "21", "30"] } } } ] }
NOT: This operation inverts the result of the enclosed clause, resulting in it being true only if the enclosed clause is false. For example:
{ "NOT": { "OR": [ { "MATCH$": { "name": "NameNotFound" } }, { "FIND$": { "auth": { "name": "Wazuh", "office": ["20", "30"] } } } ] } }
Advanced examples
Example 1
Consider the following rule that a user wants to match:
{ "id": "1", "name": "Second", "rules": [{ "OR": [ { "FIND$": { "office": "r'^[0-9]+$'" } }, { "AND": [ { "MATCH": { "authLevel": "administrator", "department": "Technical" } } ] } ] }] }
Using the authorization context below, the user intends to gain the necessary permissions:
{ "name": "Eleventh_auth", "auth": { "test": "New", "department": [ "Technical1" ], "authLevel": [ "basic1" ] }, "authLevel": [ "administrator" ], "department": [ "Technical" ] }
The
OR
operation in the rule contains two sub-operations: aFIND$
operation looking for anoffice
key matching any positive number and anAND
operation requiring aMATCH
on bothauthLevel
asadministrator
anddepartment
asTechnical
. TheFIND$
operation fails due to the absence of theoffice
key in the context, but theAND
operation succeeds as the authorization context directly matches the requiredauthLevel
anddepartment
. Consequently, since one of the conditions within theOR
operation succeeds, the rule matches, allowing the authorization process to proceed.
Example 2
Consider the following rule that a user wants to match:
{ "id": "2", "name": "Second", "rules": [ { "AND": [ { "MATCH": { "office": "r'^[0-9]+$'" } }, { "FIND": { "r'^auth[a-zA-Z]+$'": [ "r'^admin[a-z0-9]+$'" ], "area": [ "agents" ] } }, { "OR": [ { "MATCH$": { "name": "Wazuh", "office": "20" } }, { "OR": [ { "FIND": { "department": [ "Commercial" ] } }, { "MATCH": { "authLevel": [ "administrator" ], "department": [ "Technical" ] } } ] } ] } ] } ] }
For this match, the user utilizes the following authorization context:
{ "name": "First_example", "auth": { "disabled": false, "name": "Wazuh", "office": "20", "department": [ "Technical" ], "bindings": { "authLevel": [ "basic", "advanced-agents", "administrator" ], "area": [ "agents", "syscheck", "syscollector" ] }, "test": { "new": { "test2": [ "new" ], "test3": { "test4": [ "a", "b", "c", "d4" ] } }, "test": "new2" } } }
In this case, the outermost AND
operation passes because the authorization context contains the key-value pair "office": "20"
. The FIND
operation also meets the criteria with the help of the regular expression matching. The concluding OR
operation contains a MATCH$
that is satisfied with the office
value of 20
and the name
of Wazuh
at the root of the context. Since this clause evaluates to true, and it is within an OR
operation, the overall OR
operation yields true. As a result, the user's authorization context satisfies the rule.