Skip to content

Commit 108defd

Browse files
Y0CossY0Coss
authored
Merge pull request #8171 from ovh/dev/gbarideau/iam-condition-api
[IAM] Adding conditions feature description on IAM API documentation
2 parents 94b75fd + b5dce55 commit 108defd

File tree

15 files changed

+1207
-170
lines changed

15 files changed

+1207
-170
lines changed

‎pages/account_and_service_management/account_information/iam-policies-api/guide.de-de.md

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Verwendung von IAM-Richtlinien mit der OVHcloud API (EN)
33
excerpt: "Find out how to give specific access rights to users from an OVHcloud account"
4-
updated: 2024-08-21
4+
updated: 2025-07-17
55
---
66

77
## Objective
@@ -126,6 +126,7 @@ The URNs and actions can end with a `*` wildcard character. This allows referrin
126126
- **deny**: Array of actions explicitely denied for the identities regarding the resources. A denied action will be prevent no matter what others policies could allow
127127
- **except**: Extension of the **allow** parameter. Array of actions not to allow even though they are included in the **allow** actions. For instance, this is useful when there is a wildcard allow action but it is necessary to exclude a specific action that otherwise would be included in the wildcard. Contrary to **deny**, **except** is limited to the current policy scope.
128128
- **permissionsGroups**: List of [permissions groups](/pages/account_and_service_management/account_information/iam-permission-groups) applied to this policy.
129+
- **conditions**: List conditions applied to the policy
129130
- **expiredAt**: Date after which the policy will be disabled.
130131
- **createdAt**: Creation date of the policy.
131132
- **updateAt**: Last update date of the policy.
@@ -288,6 +289,74 @@ Check it via `GET /iam/policy`:
288289

289290
The policies have been created successfully. Now, "***user1***" can **carry out reboots and create snapshots** on the VPS "***urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net***". "***user2***" can **execute any vps action except for the deletion of snapshots** on the VPS "***urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net***".
290291

292+
#### Conditions
293+
294+
It is possible to add conditions to policies. The policy will only be valid if the conditions are met.
295+
Conditions are added to an access policy in the following form:
296+
297+
```json
298+
{
299+
"operator": "AND",
300+
"conditions": [
301+
{
302+
"operator": "MATCH",
303+
"values": {
304+
"resource.Tag(environment)": "prod",
305+
"resource.Type": "dnsZone"
306+
}
307+
},
308+
{
309+
"operator": "NOT",
310+
"conditions": [
311+
{
312+
"operator": "MATCH",
313+
"values": {
314+
"date(Europe/Paris).WeekDay.IN": "Saturday,Sunday"
315+
}
316+
}
317+
]
318+
}
319+
]
320+
}
321+
```
322+
323+
For example, a policy with this condition is valid if the targeted resources are of type **dnsZone** with the tag **"environment:prod"**, except on **Saturday and Sunday** in the Paris time zone.
324+
325+
The operator field specifies how the conditions will be evaluated:
326+
327+
- **AND**: All conditions must be validated
328+
- **NOT**: None of the conditions must be validated
329+
- **OR**: At least one condition must be validated
330+
- **MATCH**: Condition evaluation operator
331+
332+
The available conditions are:
333+
334+
| Condition | Operator | Data Type | Description | Example |
335+
| :--------------------: | :--------------------------------------------------------: | :--------: | :--------------------------------: | :-----------------------------------------: |
336+
| date(location).Date | EQ <br>BEFORE <br>AFTER <br>IN | YYYY-MM-DD | Filter on calendar days | "date.Date(America/New_York)": "2024-12-25" |
337+
| date(location).Hour | EQ <br>BEFORE <br>AFTER <br>GE <br>LE <br>GT <br>LT <br>IN | int | Filter on hours | "date(Europe/Paris).Hour.IN" : "7,8,9" |
338+
| date(location).WeekDay | EQ <br>BEFORE <br>AFTER <br>GE <br>LE <br>GT <br>LT <br>IN | string | Filter on days of the week | "date(Europe/Berlin).WeekDay.AFTER": "monday" |
339+
| resource.Tag(tag_key) | EQ <br>STARTS_WITH <br>ENDS_WITH | string | Filter on tags | "resource.Tag(environment): "dev" |
340+
| resource.Name | EQ <br>IN <br>STARTS_WITH <br>ENDS_WITH | string | Filter on resource names | "resource.Name.Start_with": "vps-" |
341+
| resource.Type | EQ <br>IN <br>STARTS_WITH <br>ENDS_WITH | string | Filter on resource types | "resource.Type.In": "dnsZone,vps" |
342+
| request.IP | EQ <br>IN <br>IN_RANGE | IP v4 | Filter on client source IP | "request.IP.IN_RANGE": "10.23.0.0/16" |
343+
344+
Dates use time zones based on [IANA database names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If not specified, the date will be evaluated in UTC time zone.
345+
346+
The available operators for condition types are:
347+
348+
- **EQ**: The value must exactly match the specified value
349+
- **BEFORE** or **LT** (less than): The value must be strictly less than
350+
- **AFTER** or **GE** (greater or equal): The value must be equal to or greater than
351+
- **GT** (greater than): The value must be strictly greater than
352+
- **LE** (less or equal): The value must be equal to or less than
353+
- **IN**: The value must be included in the list
354+
- **START_WITH**: The value must start with the specified value
355+
- **END_WITH**: The value must end with the specified value
356+
- **IN_RANGE**: The value must be in the specified IP subnet
357+
358+
If not specified, the default operator is **EQ**.
359+
291360
### Identities
292361

293362
Policies apply to users, which can be accounts, users or user groups.
@@ -654,4 +723,4 @@ Here is a part of the output:
654723

655724
## Go further
656725

657-
Join our [community of users](/links/community).
726+
Join our [community of users](/links/community).

‎pages/account_and_service_management/account_information/iam-policies-api/guide.en-asia.md

Lines changed: 76 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: How to use IAM policies using the OVHcloud API
33
excerpt: "Find out how to give specific access rights to users from an OVHcloud account"
4-
updated: 2024-08-21
4+
updated: 2025-07-17
55
---
66

77
## Objective
@@ -42,7 +42,7 @@ Resources, resource groups and actions needed to create a policy will be describ
4242

4343
#### API definition
4444

45-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/policy>
45+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/policy>
4646

4747
|**Method**|**Path**|**Description**|
4848
| :-: | :-: | :-: |
@@ -126,6 +126,7 @@ The URNs and actions can end with a `*` wildcard character. This allows referrin
126126
- **deny**: Array of actions explicitely denied for the identities regarding the resources. A denied action will be prevent no matter what others policies could allow
127127
- **except**: Extension of the **allow** parameter. Array of actions not to allow even though they are included in the **allow** actions. For instance, this is useful when there is a wildcard allow action but it is necessary to exclude a specific action that otherwise would be included in the wildcard. Contrary to **deny**, **except** is limited to the current policy scope.
128128
- **permissionsGroups**: List of [permissions groups](/pages/account_and_service_management/account_information/iam-permission-groups) applied to this policy.
129+
- **conditions**: List conditions applied to the policy
129130
- **expiredAt**: Date after which the policy will be disabled.
130131
- **createdAt**: Creation date of the policy.
131132
- **updateAt**: Last update date of the policy.
@@ -288,6 +289,74 @@ Check it via `GET /iam/policy`:
288289

289290
The policies have been created successfully. Now, "***user1***" can **carry out reboots and create snapshots** on the VPS "***urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net***". "***user2***" can **execute any vps action except for the deletion of snapshots** on the VPS "***urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net***".
290291

292+
#### Conditions
293+
294+
It is possible to add conditions to policies. The policy will only be valid if the conditions are met.
295+
Conditions are added to an access policy in the following form:
296+
297+
```json
298+
{
299+
"operator": "AND",
300+
"conditions": [
301+
{
302+
"operator": "MATCH",
303+
"values": {
304+
"resource.Tag(environment)": "prod",
305+
"resource.Type": "dnsZone"
306+
}
307+
},
308+
{
309+
"operator": "NOT",
310+
"conditions": [
311+
{
312+
"operator": "MATCH",
313+
"values": {
314+
"date(Europe/Paris).WeekDay.IN": "Saturday,Sunday"
315+
}
316+
}
317+
]
318+
}
319+
]
320+
}
321+
```
322+
323+
For example, a policy with this condition is valid if the targeted resources are of type **dnsZone** with the tag **"environment:prod"**, except on **Saturday and Sunday** in the Paris time zone.
324+
325+
The operator field specifies how the conditions will be evaluated:
326+
327+
- **AND**: All conditions must be validated
328+
- **NOT**: None of the conditions must be validated
329+
- **OR**: At least one condition must be validated
330+
- **MATCH**: Condition evaluation operator
331+
332+
The available conditions are:
333+
334+
| Condition | Operator | Data Type | Description | Example |
335+
| :--------------------: | :--------------------------------------------------------: | :--------: | :--------------------------------: | :-----------------------------------------: |
336+
| date(location).Date | EQ <br>BEFORE <br>AFTER <br>IN | YYYY-MM-DD | Filter on calendar days | "date.Date(America/New_York)": "2024-12-25" |
337+
| date(location).Hour | EQ <br>BEFORE <br>AFTER <br>GE <br>LE <br>GT <br>LT <br>IN | int | Filter on hours | "date(Europe/Paris).Hour.IN" : "7,8,9" |
338+
| date(location).WeekDay | EQ <br>BEFORE <br>AFTER <br>GE <br>LE <br>GT <br>LT <br>IN | string | Filter on days of the week | "date(Europe/Berlin).WeekDay.AFTER": "monday" |
339+
| resource.Tag(tag_key) | EQ <br>STARTS_WITH <br>ENDS_WITH | string | Filter on tags | "resource.Tag(environment): "dev" |
340+
| resource.Name | EQ <br>IN <br>STARTS_WITH <br>ENDS_WITH | string | Filter on resource names | "resource.Name.Start_with": "vps-" |
341+
| resource.Type | EQ <br>IN <br>STARTS_WITH <br>ENDS_WITH | string | Filter on resource types | "resource.Type.In": "dnsZone,vps" |
342+
| request.IP | EQ <br>IN <br>IN_RANGE | IP v4 | Filter on client source IP | "request.IP.IN_RANGE": "10.23.0.0/16" |
343+
344+
Dates use time zones based on [IANA database names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If not specified, the date will be evaluated in UTC time zone.
345+
346+
The available operators for condition types are:
347+
348+
- **EQ**: The value must exactly match the specified value
349+
- **BEFORE** or **LT** (less than): The value must be strictly less than
350+
- **AFTER** or **GE** (greater or equal): The value must be equal to or greater than
351+
- **GT** (greater than): The value must be strictly greater than
352+
- **LE** (less or equal): The value must be equal to or less than
353+
- **IN**: The value must be included in the list
354+
- **START_WITH**: The value must start with the specified value
355+
- **END_WITH**: The value must end with the specified value
356+
- **IN_RANGE**: The value must be in the specified IP subnet
357+
358+
If not specified, the default operator is **EQ**.
359+
291360
### Identities
292361

293362
Policies apply to users, which can be accounts, users or user groups.
@@ -296,7 +365,7 @@ This section describes how to retrieve or create user for the policy.
296365

297366
#### API definition
298367

299-
<https://ca.api.ovh.com/console-preview/?section=%2Fme&branch=v1#overview>
368+
<https://api.ovh.com/console-preview/?section=%2Fme&branch=v1#overview>
300369

301370
|**Method**|**Path**|**Description**|
302371
| :-: | :-: | :-: |
@@ -383,7 +452,7 @@ This section describes how to retrieve resources information to use in a policy.
383452

384453
#### API definition
385454

386-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resource>
455+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resource>
387456

388457
|**Method**|**Path**|**Description**|
389458
| :-: | :-: | :-: |
@@ -442,7 +511,7 @@ To ease the policy management for a large number of resources, it is possible to
442511

443512
#### API definition
444513

445-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resourceGroup>
514+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resourceGroup>
446515

447516
|**Method**|**Path**|**Description**|
448517
| :-: | :-: | :-: |
@@ -535,7 +604,7 @@ These actions are specific to every product, such as rebooting a database server
535604

536605
#### API definition
537606

538-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/reference/action>
607+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/reference/action>
539608

540609
|**Method**|**Path**|**Description**|
541610
| :-: | :-: | :-: |
@@ -654,4 +723,4 @@ Here is a part of the output:
654723

655724
## Go further
656725

657-
Join our [community of users](/links/community).
726+
Join our [community of users](/links/community).

‎pages/account_and_service_management/account_information/iam-policies-api/guide.en-au.md

Lines changed: 76 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: How to use IAM policies using the OVHcloud API
33
excerpt: "Find out how to give specific access rights to users from an OVHcloud account"
4-
updated: 2024-08-21
4+
updated: 2025-07-17
55
---
66

77
## Objective
@@ -42,7 +42,7 @@ Resources, resource groups and actions needed to create a policy will be describ
4242

4343
#### API definition
4444

45-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/policy>
45+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/policy>
4646

4747
|**Method**|**Path**|**Description**|
4848
| :-: | :-: | :-: |
@@ -126,6 +126,7 @@ The URNs and actions can end with a `*` wildcard character. This allows referrin
126126
- **deny**: Array of actions explicitely denied for the identities regarding the resources. A denied action will be prevent no matter what others policies could allow
127127
- **except**: Extension of the **allow** parameter. Array of actions not to allow even though they are included in the **allow** actions. For instance, this is useful when there is a wildcard allow action but it is necessary to exclude a specific action that otherwise would be included in the wildcard. Contrary to **deny**, **except** is limited to the current policy scope.
128128
- **permissionsGroups**: List of [permissions groups](/pages/account_and_service_management/account_information/iam-permission-groups) applied to this policy.
129+
- **conditions**: List conditions applied to the policy
129130
- **expiredAt**: Date after which the policy will be disabled.
130131
- **createdAt**: Creation date of the policy.
131132
- **updateAt**: Last update date of the policy.
@@ -288,6 +289,74 @@ Check it via `GET /iam/policy`:
288289

289290
The policies have been created successfully. Now, "***user1***" can **carry out reboots and create snapshots** on the VPS "***urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net***". "***user2***" can **execute any vps action except for the deletion of snapshots** on the VPS "***urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net***".
290291

292+
#### Conditions
293+
294+
It is possible to add conditions to policies. The policy will only be valid if the conditions are met.
295+
Conditions are added to an access policy in the following form:
296+
297+
```json
298+
{
299+
"operator": "AND",
300+
"conditions": [
301+
{
302+
"operator": "MATCH",
303+
"values": {
304+
"resource.Tag(environment)": "prod",
305+
"resource.Type": "dnsZone"
306+
}
307+
},
308+
{
309+
"operator": "NOT",
310+
"conditions": [
311+
{
312+
"operator": "MATCH",
313+
"values": {
314+
"date(Europe/Paris).WeekDay.IN": "Saturday,Sunday"
315+
}
316+
}
317+
]
318+
}
319+
]
320+
}
321+
```
322+
323+
For example, a policy with this condition is valid if the targeted resources are of type **dnsZone** with the tag **"environment:prod"**, except on **Saturday and Sunday** in the Paris time zone.
324+
325+
The operator field specifies how the conditions will be evaluated:
326+
327+
- **AND**: All conditions must be validated
328+
- **NOT**: None of the conditions must be validated
329+
- **OR**: At least one condition must be validated
330+
- **MATCH**: Condition evaluation operator
331+
332+
The available conditions are:
333+
334+
| Condition | Operator | Data Type | Description | Example |
335+
| :--------------------: | :--------------------------------------------------------: | :--------: | :--------------------------------: | :-----------------------------------------: |
336+
| date(location).Date | EQ <br>BEFORE <br>AFTER <br>IN | YYYY-MM-DD | Filter on calendar days | "date.Date(America/New_York)": "2024-12-25" |
337+
| date(location).Hour | EQ <br>BEFORE <br>AFTER <br>GE <br>LE <br>GT <br>LT <br>IN | int | Filter on hours | "date(Europe/Paris).Hour.IN" : "7,8,9" |
338+
| date(location).WeekDay | EQ <br>BEFORE <br>AFTER <br>GE <br>LE <br>GT <br>LT <br>IN | string | Filter on days of the week | "date(Europe/Berlin).WeekDay.AFTER": "monday" |
339+
| resource.Tag(tag_key) | EQ <br>STARTS_WITH <br>ENDS_WITH | string | Filter on tags | "resource.Tag(environment): "dev" |
340+
| resource.Name | EQ <br>IN <br>STARTS_WITH <br>ENDS_WITH | string | Filter on resource names | "resource.Name.Start_with": "vps-" |
341+
| resource.Type | EQ <br>IN <br>STARTS_WITH <br>ENDS_WITH | string | Filter on resource types | "resource.Type.In": "dnsZone,vps" |
342+
| request.IP | EQ <br>IN <br>IN_RANGE | IP v4 | Filter on client source IP | "request.IP.IN_RANGE": "10.23.0.0/16" |
343+
344+
Dates use time zones based on [IANA database names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If not specified, the date will be evaluated in UTC time zone.
345+
346+
The available operators for condition types are:
347+
348+
- **EQ**: The value must exactly match the specified value
349+
- **BEFORE** or **LT** (less than): The value must be strictly less than
350+
- **AFTER** or **GE** (greater or equal): The value must be equal to or greater than
351+
- **GT** (greater than): The value must be strictly greater than
352+
- **LE** (less or equal): The value must be equal to or less than
353+
- **IN**: The value must be included in the list
354+
- **START_WITH**: The value must start with the specified value
355+
- **END_WITH**: The value must end with the specified value
356+
- **IN_RANGE**: The value must be in the specified IP subnet
357+
358+
If not specified, the default operator is **EQ**.
359+
291360
### Identities
292361

293362
Policies apply to users, which can be accounts, users or user groups.
@@ -296,7 +365,7 @@ This section describes how to retrieve or create user for the policy.
296365

297366
#### API definition
298367

299-
<https://ca.api.ovh.com/console-preview/?section=%2Fme&branch=v1#overview>
368+
<https://api.ovh.com/console-preview/?section=%2Fme&branch=v1#overview>
300369

301370
|**Method**|**Path**|**Description**|
302371
| :-: | :-: | :-: |
@@ -383,7 +452,7 @@ This section describes how to retrieve resources information to use in a policy.
383452

384453
#### API definition
385454

386-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resource>
455+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resource>
387456

388457
|**Method**|**Path**|**Description**|
389458
| :-: | :-: | :-: |
@@ -442,7 +511,7 @@ To ease the policy management for a large number of resources, it is possible to
442511

443512
#### API definition
444513

445-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resourceGroup>
514+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resourceGroup>
446515

447516
|**Method**|**Path**|**Description**|
448517
| :-: | :-: | :-: |
@@ -535,7 +604,7 @@ These actions are specific to every product, such as rebooting a database server
535604

536605
#### API definition
537606

538-
<https://ca.api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/reference/action>
607+
<https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/reference/action>
539608

540609
|**Method**|**Path**|**Description**|
541610
| :-: | :-: | :-: |
@@ -654,4 +723,4 @@ Here is a part of the output:
654723

655724
## Go further
656725

657-
Join our [community of users](/links/community).
726+
Join our [community of users](/links/community).

0 commit comments

Comments
 (0)