How to use IAM policies using the OVHcloud API

Objective

This guide will explain how to provide specific access rights to users of an OVHcloud account.

The access management of OVHcloud is based on a policy management system. It is possible to write different policies that give users access to specific features on the products linked to an OVHcloud account.

In detail, a policy contains:

• One or more identities targeted by this policy.
  • It can be account IDs, users or user groups (like the ones used in Federation).
• One or more resources impacted by this policy.
  • A resource is an OVHcloud product that will be impacted by this policy (a domain name, a Nutanix server, a Load Balancer, etc.).
• One or more actions allowed, denied or excepted by this policy.
  • Actions are the specific rights affected by this policy (reboot a server, create an email account, cancel a subscription, etc.)

For example, we can create a policy to give to a user called John, for a VPS, access to the action "reboot".

This guide explains in detail how these policies can be declared using the OVHcloud API, and how to list the identities, resources and actions available for them.

Requirements

• You have an OVHcloud account.
• You know how to manage account users.
• You have one or more OVHcloud products linked to this OVHcloud account (Load Balancer, domain name, VPS, etc.).

Instructions

Policies

This first part describes how to create and update policies.

Resources, resource groups and actions needed to create a policy will be described in the next sections.

API definition

https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/policy

Retrieve all policies

The following example shows how a policy is built.

Find all policies, including those pregenerated by OVHcloud, by calling the API endpoint: /iam/policy

Example output:

/iam/policy

[
    {
        "id": "69470db1-5372-4e32-acf1-edc2afd84c12",
        "owner": "xx1111-ovh",
        "name": "ovh-default",
        "readOnly": true,
        "identities": [
            "urn:v1:eu:identity:account:xx1111-ovh"
        ],
        "resources": [
            {
                "urn": "urn:v1:eu:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8"
            }
        ],
        "permissions": {
            "allow": [
                {
                    "action": "*"
                }
            ]
        },
        "createdAt": "2023-01-27T11:29:22.197537Z",
        "updatedAt": "2023-01-27T11:29:22.197537Z"
    }
]

In this example, the account "urn:v1:eu:identity:account:xx1111-ovh" can do every action ("action":"*") to the group of resources "urn:v1:eu:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8". This policy is owned by "xx1111-ovh" (it corresponds to the admin role, it is created by OVHcloud and cannot be modified).

Items in policies are defined by URNs. These URNs are defined by the following pattern:

The resources URNs and actions can end with a * wildcard character. This allows referring to multiple resources or actions in a single line.

Example of a resource URN with a wildcard :

urn:v1:eu:resource:vps:* will match any vps resource.

Example of an action with a wildcard :

vps:apiovh:* will match any action of the vps type.

Policy attributes

• id: Unique identifier of the policy. It follows the UUID format.
• owner: The account that created this policy.
• name: The policy name. It's possible to use this name to organize the policies. There is no format to follow (except that the prefix "ovh-" is reserved for OVHcloud policies).
• readOnly: If true, it indicates that the policy cannot be edited. It often represents policies managed by OVHcloud.
• identities: The identities concerned by the policy. They are specified by a URN. account:account-id for the account, user:account-id/username for an account user, group:account-id/username for a user group.
• resources: The resources concerned by the policy. They are specified by a URN. resource for a resource, resourceGroup for a resource group.
• permissions: Can be allow, deny or except:
• allow: Array of actions allowed for the identities regarding the resources. All actions are denied by default.
• 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
• 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.
• permissionsGroups: List of permissions groups applied to this policy.
• conditions: List conditions applied to the policy
• expiredAt: Date after which the policy will be disabled.
• createdAt: Creation date of the policy.
• updateAt: Last update date of the policy.

Create a policy

Create a new policy using this API route:

For example, create a policy to authorise a user named "user1" to do some actions on a VPS:

create policy examples

{
    "description": "VPS - reboot and create snapshot",
    "identities": [
        "urn:v1:eu:identity:user:xx1111-ovh/user1"
    ],
    "name": "vps-reboot-snapshot",
    "permissions": {
        "allow": [
            {
                "action": "vps:apiovh:reboot"
            },
            {
                "action": "vps:apiovh:snapshot/create"
            }
        ]
    },
    "resources": [
        {
            "urn": "urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net"
        }
    ]
}

This policy is not for an account but for a user, so the identity URN corresponds to the format "urn:v1:eu:identity:user:account-id/username**".

{
    "description": "VPS - all except delete snapshot",
    "identities": [
        "urn:v1:eu:identity:user:xx1111-ovh/user2"
    ],
    "name": "vps-all-but-delete-snapshot",
    "permissions": {
        "allow": [
            {
                "action": "vps:apiovh:*"
            }
        ],
        "except": [
            {
                "action": "vps:apiovh:snapshot/delete"
            }
        ]
    },
    "resources": [
        {
            "urn": "urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net"
        }
    ]
}

This policy uses a wildcard with an except. This allows you to easily give a large set of permissions. Here the user user2 will have all permissions of the vps type on vps-5b48d78b.vps.ovh.net except for the permission to delete a snapshot.

With these POST /iam/policy requests, the policies will be created.

Check it via GET /iam/policy:

GET /iam/policies

[
    {
        "id": "69470db1-5372-4e32-acf1-edc2afd84c12",
        "owner": "xx1111-ovh",
        "name": "ovh-default",
        "readOnly": true,
        "identities": [
            "urn:v1:eu:identity:account:xx1111-ovh"
        ],
        "resources": [
            {
                "urn": "urn:v1:eu:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8"
            }
        ],
        "permissions": {
            "allow": [
                {
                    "action": "*"
                }
            ]
        },
        "createdAt": "2023-01-27T11:29:22.197537Z",
        "updatedAt": "2023-01-27T11:29:22.197537Z"
    },
    {
        "id": "9dfe6a03-1937-4287-8ab7-866224d333b1",
        "owner": "xx1111-ovh",
        "name": "vps-reboot-snapshot",
        "readOnly": false,
        "description": "VPS - reboot and create snapshot",
        "identities": [
            "urn:v1:eu:identity:user:xx1111-ovh/user1"
        ],
        "resources": [
            {
                "urn": "urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net"
            }
        ],
        "permissions": {
            "allow": [
                {
                    "action": "vps:apiovh:reboot"
                },
                {
                    "action": "vps:apiovh:snapshot/create"
                }
            ]
        },
        "createdAt": "2023-02-07T15:24:57.680037Z"
    },
    {
        "id": "73a220d0-8346-4d4a-bdab-c0f671d62368",
        "owner": "xx1111-ovh",
        "name": "vps-all-but-delete-snapshot",
        "readOnly": false,
        "description": "VPS - all except delete snapshot",
        "identities": [
            "urn:v1:eu:identity:user:xx1111-ovh/user2"
        ],
        "resources": [
            {
                "urn": "urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net"
            }
        ],
        "permissions": {
            "allow": [
                {
                    "action": "vps:apiovh:*"
                }
            ],
            "except": [
                {
                    "action": "vps:apiovh:snapshot/delete"
                }
            ]
        },
        "createdAt": "2023-02-07T15:32:18.957023Z"
    }
]

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".

Conditions

It is possible to add conditions to policies. The policy will only be valid if the conditions are met. Conditions are added to an access policy in the following form:

{
  "operator": "AND",
  "conditions": [
    {
        "operator": "MATCH",
        "values": {
            "resource.Tag(environment)": "prod",
            "resource.Type": "dnsZone"
      }
    },
    {
      "operator": "NOT",
      "conditions": [
        {
            "operator": "MATCH",
            "values": {
                "date(Europe/Paris).WeekDay.IN": "Saturday,Sunday"
          }
        }
      ]
    }
  ]
}

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.

The operator field specifies how the conditions will be evaluated:

• AND: All conditions must be validated
• NOT: None of the conditions must be validated
• OR: At least one condition must be validated
• MATCH: Condition evaluation operator

The available conditions are:

Dates use time zones based on IANA database names. If not specified, the date will be evaluated in UTC time zone.

The available operators for condition types are:

• EQ: The value must exactly match the specified value
• BEFORE or LT (less than): The value must be strictly less than
• AFTER or GE (greater or equal): The value must be equal to or greater than
• GT (greater than): The value must be strictly greater than
• LE (less or equal): The value must be equal to or less than
• IN: The value must be included in the list
• START_WITH: The value must start with the specified value
• END_WITH: The value must end with the specified value
• IN_RANGE: The value must be in the specified IP subnet

If not specified, the default operator is EQ.

Policies targeting other OVHcloud customer accounts

Access policies can target other OVHcloud customer accounts.
The targeted account of this policy will be able to manage the rights received that way on its own policies, but will never be able to override the rights set on the access policy.

For example, an account xx1111-ovh gives rights on vps:apiovh:ips/* to account xx2222-ovh:
Account xx2222-ovh will be able to give the right vps:apiovh:ips/delete to its own users, but will never be able to grant the right vps:apiovh:reboot.

Access to the support will still be reserved to the owner of the resource.

Identities

Policies apply to users, which can be accounts, users or user groups.

This section describes how to retrieve or create user for the policy.

API definition

https://api.ovh.com/console-preview/?section=%2Fme&branch=v1#overview

Create users

List all the current users related to the account by calling:

/me/identity/user

[
  "user1",
  "user2"
]

These users can be used on policies with the URN format: urn:v1:eu:identity:user:xx1111-ovh/user1

To create a new user, call the API route with the following body:

post /me/identity/user

{
  "description": "string",
  "email": "string",
  "group": "string",
  "login": "string",
  "password": ""
}

Create user groups

List all the current user groups related to the account by calling:

/me/identity/group

[
  "ADMIN",
  "DEFAULT",
  "UNPRIVILEGED",
  "admin@mycompany.com"
]

These user groups can be used on policies with the URN format: urn:v1:eu:identity:group:xx1111-ovh/admin@mycompany.com

To create a new user group, call the API route with the following body:

post /me/identity/group

{
  "description": "string",
  "name": "string",
  "role": "REGULAR"
}

For more information, refer to the documentation for user management.

With SSO connection enabled

If the federation is enabled through the SSO connection, policies only apply to user groups as described in the previous section.

Resources

Policies refer to resources. The resources are all OVHcloud products subscribed to by the OVHcloud account that can be controlled by this account.

This section describes how to retrieve resources information to use in a policy.

API definition

https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resource

Example

See all the resources linked to the OVHcloud account by calling:

/iam/resource

[
  {
    "id": "b96ffed4-3467-4129-b8be-39a3eb3a0a93",
    "urn": "urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net",
    "name": "vps-5b48d78b.vps.ovh.net",
    "displayName": "vps-5b48d78b.vps.ovh.net",
    "type": "vps",
    "owner": "xx1111-ovh"
  },
  {
    "id": "c24ace5e-6c9c-436b-9a73-515db8df6250",
    "urn": "urn:v1:eu:resource:emailDomain:acme.com",
    "name": "acme.com",
    "displayName": "acme.com",
    "type": "emailDomain",
    "owner": "xx1111-ovh"
  },
  {
    "id": "8d70a49b-7a8b-4ec0-ad4b-756da802d994",
    "urn": "urn:v1:eu:resource:cdn:cdn-46.105.198.89-12969",
    "name": "cdn-46.105.198.89-12969",
    "displayName": "cdn-46.105.198.89-12969",
    "type": "cdn",
    "owner": "xx1111-ovh"
  }
]

In this example, the account has 3 resources available (a VPS, an email domain and a CDN). Each of this resources has a set of attributes to identify them on policies.

Resource attributes

• id: Unique identifier of the resource. It follows the UUID format.
• urn: Resource URN.
• name: The resource name.
• displayName: The resource name as displayed in the user interface.
• type: The resource type (vps, publicCloudProject, dnsZone, domain, emailDomain, etc.)
• owner: The resource owner (Account ID)

Resource Groups

To ease the policy management for a large number of resources, it is possible to set up a resource group which aggregates several resources to a unique URN.

API definition

https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/resourceGroup

Retrieve a resource group

List all resource groups by calling /iam/resourceGroup.

This API route can be called with a query-string parameter "details" to expand the results with all the attributes of the returned resources.

Example output:

/iam/resourceGroup

[
    {
        "id": "aa0713ab-ed13-4f1a-89a5-32aa0cb936d8",
        "urn": "urn:v1:eu:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8",
        "readOnly": true,
        "name": "myVPS",
        "owner": "xx1111-ovh",
        "resources": [
            {
                "id": "b96ffed4-3467-4129-b8be-39a3eb3a0a93"
            },
            {
                "id": "7a19dbca-7da5-460f-a59b-69d56e57bf9d"
            },
            {
                "id": "50423397-8984-4d44-8505-fdd489c2c9fb"
            }
        ],
        "updatedAt": "2023-01-27T11:29:22.197537Z",
        "createdAt": "2023-01-27T11:29:22.197537Z"
    }
]

In the example, we can see that this resource group "urn:v1:eu:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8" has 3 resources. It means that a policy applied to this resource group will be applied on those 3 resources.

Resource group attributes

• id: Unique identifier of the resource group. It follows the UUID format.
• urn: Resource group URN to use on the policy.
• readOnly: Cannot be modified if true. The default resource groups are read-only.
• name: The resource group name.
• owner: The resource group owner (Account ID).
• resources:
  • If details = false: Array of resources UUID.
  • If details = true: The resources will be expanded with their attributes (as the result we have via the resource API).
• createdAt: Creation date of the resource group.
• updateAt: Last update date of the resource group.

Create a resource group

Create a resource group with this API route:

The following example creates a resource group called "Test_Envrionment" containing 2 resources:

{
  "name": "Test_environment",
  "resources": [
    {
      "id": "b10611a9-7cc1-40b7-8475-18aabcdffc62"
    },
    {
      "id": "53f815b1-c020-4e5d-8239-fbbcaaca1742"
    }
  ]
}

Action

Policies contain a list of Actions that will be allowed or denied to users.

These actions are specific to every product, such as rebooting a database server, ordering an upgrade, restoring a snapshot, etc.

API definition

https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#get-/iam/reference/action

Example

List all the actions available for policies with the API, for example:

action example

{
    "action": "vps:apiovh:reboot",
    "description": "Request a reboot of the machine",
    "resourceType": "vps",
    "categories": [
        "OPERATE"
    ]
}

This action is "vps:apiovh:reboot", it targets the ability to reboot a VPS.

The call to /iam/reference/action will list all of the available actions (WARNING: This contains a huge amount of items).

It is strongly recommended to specify the resourceType as a query-string parameter for this API call (see the next section).

Action attributes

• action: The action itself
• description: The action description
• resourceType: The resource type targeted by this action
• categories: The categories of this action (CREATE, READ, EDIT, OPERATE, DELETE)

Permission group

OVHcloud provides permission groups that group together all of the actions required for specific use cases.

Permission groups are accessible via the following API:

{
    "id": "00000000-0000-0000-0001-000000000001",
    "urn": "urn:v1:eu:permissionsGroup:ovh:globalAdmin",
    "name": "globalAdmin",
    "owner": "ovh",
    "description": "Give global admin access across all OVHcloud products",
    "permissions": {
        "allow": [
        {
            "action": "*"
        }
        ]
    },
    "createdAt": "2023-03-14T09:10:57.40418Z",
    "updatedAt": null
},

These permission groups can then be used in addition to or in place of unitary actions in access policies:

{
  "description": "",
  "identities": [...],
  "name": "",
  "permissions": {
    "allow": [
      {
        "action": "..."
      },
    ]
  },
  "permissionsGroups": [
      {
        "urn": "urn:v1:eu:permissionsGroup:ovh:globalAdmin"
      }
  ],
  "resources": [...]
}

A full description of the permission groups can be found in our dedicated documentation.

Resource types

API definition

Example

Here is a part of the output:

/iam/reference/resource/type

[
    "account",
    "packXdsl",
    "cloudDB",
    "loadbalancer",
    "mxplanAccount",
    "publicCloudProject",
    "voipSmsvn",
    "vps",
]

Go further

Join our community of users.