Using IAM policies with OVHcloud API

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.

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

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:

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:

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

Example of a resource URN with a wildcard:

urn:v1:us: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 or except:
• allow: Array of actions allowed for the identities regarding the resources. All actions are denied by default.
• deny: Array of actions explicitly denied for the identities regarding the resources. A denied action will be prevented no matter what other policies might 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's 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.
• permissionGroups: List of permission 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 authorize a user named "user1" to do some actions on a VPS:

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:snapshot/create"
            }
        ]
    },
    "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**".

{
    "description": "VPS - all except delete snapshot",
    "identities": [
        "urn:v1:us: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:us: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.us except for the permission to delete a snapshot.

The policy will be created with this JSON as the body for the call:

Check it via:

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: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:us:identity:user:xx1111-ovh/user2"
        ],
        "resources": [
            {
                "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us"
            }
        ],
        "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:us:resource:vps:vps-5b48d78b.vps.ovh.us". "user2" can execute any vps action except for the deletion of snapshots on the VPS "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us".

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": "vps"
      }
    },
    {
      "operator": "NOT",
      "conditions": [
        {
            "operator": "MATCH",
            "values": {
                "date(America/New_York).WeekDay.IN": "Saturday,Sunday"
          }
        }
      ]
    }
  ]
}

For example, a policy with this condition is valid if the targeted resources are of type vps with the tag "environment:prod", except on Saturday and Sunday in the New York 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.

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

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

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

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

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

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

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

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

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