Using IAM Policies with OVHcloud API – Articles

Learn 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.
- Identities 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 the server, create an email account, terminate a product, etc.)

For instance, we can create a policy to give a VPS user, named John, 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

To set up a policy, you will require:

an OVHcloud account
to know how to manage account users
some 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

API Call	Description
GET /iam/policy	Retrieve all policies
POST /iam/policy	Create a new policy
GET /iam/policy/{policyId}	Retrieve the given policy
PUT /iam/policy/{policyId}	Update an existing policy
DELETE /iam/policy/{policyId}	Delete the given policy

Retrieve all policies

The following example shows how a policy is built.

Find all policies, including those pre-generated by OVHcloud, by calling the API call: GET /iam/policy

Example output:

/iam/policy

[
    {
        "id": "69470db1-5372-4e32-acf1-edc2afd84c12",
        "owner": "xx1111-ovh",
        "name": "ovh-default",
        "readOnly": true,
        "identities": [
            "urn:v1:us:identity:account:xx1111-ovh"
        ],
        "resources": [
            {
                "urn": "urn:v1:us: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:us:identity:account:xx1111-ovh" can do every action ("action":"*") to the group of resources "urn:v1:us:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8". This policy is owned by "xx1111-ovh" (it corresponds to the admin role, is created by OVHcloud, and cannot be modified).

Items in policies are defined by URNs. The URN can use a * wildcard at the beginning or at the end of it. These URNs are defined by the following pattern:

	urn	:	version	:	plate	:	type	:	sub-type	:	id
Description	immutable prefix	:	version of the IAM system	:	Plate where the urn is located	:	Type of the current urn	:	(optional) Subtype for identity or resource type	:	Unique identifier associated to the urn
Possible values	urn	:	v1	:	eu, ca, us	:	identity, resource, resourceGroup	:	For identity type: account, user, group For resource type: any resourceType	:	Alphanumerical value
Account ID Example	urn	:	v1	:	us	:	identity	:	account	:	xx1111-ovh
User group Example	urn	:	v1	:	us	:	identity	:	group	:	xx1111-ovh/admin@mycompany.com
VPS Example	urn	:	v1	:	us	:	resource	:	vps	:	vps-5b48d78b.vps.ovh.us
Resource Group Example	urn	:	v1	:	us	:	resourceGroup			:	aa0713ab-ed13-4f1a-89a5-32aa0cb936d8

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 or except:
allow: Array of actions allowed for the identities regarding the resources. All actions are denied by default.
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's necessary to exclude a specific action that otherwise would be included in the wildcard.
createdAt: Creation date of the policy.
updateAt: Last update date of the policy.

Create a policy

Create a new policy using this API route: POST /iam/policy

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

NOTE: This example is specific to VPS. To see other possible resources you can use, see the Resources section.

create policy example

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

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

The policy will be created with this JSON as the body for the POST /iam/policy call.

Check it via GET /iam/policy:

GET /iam/policy

[
    {
        "id": "69470db1-5372-4e32-acf1-edc2afd84c12",
        "owner": "xx1111-ovh",
        "name": "ovh-default",
        "readOnly": true,
        "identities": [
            "urn:v1:us:identity:account:xx1111-ovh"
        ],
        "resources": [
            {
                "urn": "urn:v1:us: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:us:identity:user:xx1111-ovh/user1"
        ],
        "resources": [
            {
                "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us"
            }
        ],
        "permissions": {
            "allow": [
                {
                    "action": "vps:apiovh:reboot"
                },
                {
                    "action": "vps:apiovh:createSnapshot"
                }
            ]
        },
        "createdAt": "2023-02-07T15:24:57.680037Z"
    }
]

The policy has been created successfully. Now, "user1" can carry out reboots and create snapshots on the VPS "urn:v1:us:resource:vps:b96ffed4-3467-4129-b8be-39a3eb3a0a93".

Identities

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

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

API definitions

API Call	Description
GET /me/identity/user	Retrieve all users of this account
POST /me/identity/user	Create a new user
GET /me/identity/user/{user}	Get details of this specific user
PUT /me/identity/user/{user}	Alter a user
DELETE /me/identity/user/{user}	Delete a user
GET /me/identity/group	Retrieve all groups of this account
POST /me/identity/group	Create a new group
GET /me/identity/group/{group}	Get details of this specific group
PUT /me/identity/group/{group}	Alter a group
DELETE /me/identity/group/{group}	Delete a group

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:us: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:us: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"
}

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

API Call	Description
GET /iam/resource	List all resources
GET /iam/resource/{resourceId}	Retrieve a resource

Example

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

/iam/resource

[
  {
    "id": "b96ffed4-3467-4129-b8be-39a3eb3a0a93",
    "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us",
    "name": "vps-5b48d78b.vps.ovh.us",
    "displayName": "vps-5b48d78b.vps.ovh.us",
    "type": "vps",
    "owner": "xx1111-ovh"
  },
  {
    "id": "c24ace5e-6c9c-436b-9a73-515db8df6250",
    "urn": "urn:v1:us:resource:emailDomain:acme.com",
    "name": "acme.com",
    "displayName": "acme.com",
    "type": "emailDomain",
    "owner": "xx1111-ovh"
  },
  {
    "id": "8d70a49b-7a8b-4ec0-ad4b-756da802d994",
    "urn": "urn:v1:us: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 three resources available (a VPS, an email domain, and a CDN). Each of these 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 policy management for a large number of resources, it is possible to set up a resource group that aggregates several resources to a unique URN.

API definitions

API Call	Description
GET /iam/resourceGroup	Retrieve all resource groups
POST /iam/resourceGroup	Create a new resource group
GET /iam/resourceGroup/{groupId}	Retrieve the given resource group
PUT /iam/resourceGroup/{groupId}	Update an existing resource group
DELETE /iam/resourceGroup/{groupId}	Delete the given resource group

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:us: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"
    }
]

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

API definition

API Call	Description
POST /iam/resourceGroup	Create a new resource group

Example

The following example creates a resource group called "Test_environment" containing two 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

API Call	Description
GET /iam/reference/action	Retrieve all actions

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:

API Call	Description
GET /iam/permissionsGroup	Retrieve all permission groups

{
    "id": "00000000-0000-0000-0001-000000000001",
    "urn": "urn:v1:us: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:us:permissionsGroup:ovh:globalAdmin"
      }
  ],
  "resources": [...]
}

Resource types

API definition

API Call	Description
GET /iam/reference/resource/type	Retrieve all resource types

Example

Here is a part of the output:

/iam/reference/resource/type

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

Go further

For more information and tutorials, please see our other IAM support guides or explore the guides for other OVHcloud products and services.

Articles in this section

Requirements

Instructions

Policies

API definition

Retrieve all policies

Policy attributes

Create a policy

Identities

API definitions

Create users

Create user groups

With SSO connection enabled

Resources

API definition

Example

Resource attributes

Resource Groups

API definitions

Retrieve a resource group

Resource group attributes

Create a resource group

Action

API definition

Example

Action attributes

Permission group

Resource types

API definition

Example

Go further

Related articles