> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ovh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity & Access Management (IAM)

> Control who can access your OVHcloud account and services with fine-grained IAM policies.

OVHcloud IAM lets you define exactly who can perform which actions on which resources within your account. Instead of sharing your root account credentials, you create identities (users, service accounts, or federated users) and grant them access through policies.

<CardGroup cols={3}>
  <Card title="IAM policies" icon="shield-check" href="https://www.ovh.com/manager/#/iam/policies">
    Create and manage policies in the OVHcloud Control Panel.
  </Card>

  <Card title="IAM API" icon="code" href="https://eu.api.ovh.com/console-preview/?section=%2Fiam&branch=v2">
    Manage policies programmatically using the v2 API.
  </Card>

  <Card title="User management" icon="users" href="https://www.ovh.com/manager/#/iam/users">
    Create and configure local users and user groups.
  </Card>
</CardGroup>

## Core concepts

OVHcloud IAM is built around four concepts: identities, resources, actions, and policies.

### Identities

An identity is any entity that can interact with OVHcloud products:

| Identity type        | Description                                                                                                                 | Best used for                  |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **OVHcloud account** | The root account (NIC handle, e.g. `xx1111-ovh`). Cannot have its rights restricted.                                        | Account owner only             |
| **Local users**      | Human users created under your account, authenticated by login/password.                                                    | Team members                   |
| **Service accounts** | Machine identities authenticated via OAuth2 client credentials.                                                             | Automation and CI/CD           |
| **Federated users**  | Users from an external identity provider (Active Directory, Google Workspace, Azure AD, Okta). Managed through user groups. | Large teams with a central IdP |

<Note>
  We recommend using local users or federated users as soon as more than one person accesses your OVHcloud account. This ensures traceability of all actions performed.
</Note>

### Resources

A resource is any OVHcloud product associated with your account — a VPS, a domain name, a Public Cloud project, a Load Balancer, and so on. Each resource has a unique URN in this format:

```text theme={null}
urn:v1:<plate>:resource:<type>:<identifier>
```

For example:

* `urn:v1:eu:resource:vps:vps-5b48d78b.vps.ovh.net`
* `urn:v1:eu:resource:publicCloudProject:abc123def456`

You can retrieve all resources linked to your account using `GET /iam/resource`.

### Actions

An action is a specific operation on a resource. Action names follow the format `<resourceType>:apiovh:<operation>`. For example:

* `vps:apiovh:reboot` — reboot a VPS
* `vps:apiovh:snapshot/create` — create a VPS snapshot
* `vps:apiovh:*` — all VPS actions (wildcard)
* `*` — all actions on all resources

You can list all available actions using `GET /iam/reference/action` (optionally filtered by `resourceType`).

### Policies

A policy ties identities to resources and specifies which actions are allowed or denied. Policies are additive by default — all actions are denied unless explicitly allowed.

A policy contains:

* **identities** — one or more URNs for users, groups, service accounts, or accounts
* **resources** — one or more resource URNs or resource groups
* **permissions** — allow, deny, and except lists of actions

```json theme={null}
{
  "name": "vps-reboot-snapshot",
  "description": "Allow user1 to reboot VPS and create snapshots",
  "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" }
    ]
  }
}
```

## Creating and managing local users

Local users are human identities linked to your OVHcloud account. They log in with a username and password and are subject to the IAM policies you create.

To create a local user via the Control Panel:

1. Go to **Identity, Security & Operations** > **Identities** in the [OVHcloud Control Panel](https://www.ovh.com/manager/).
2. Click **Create user**.
3. Fill in the login, email address, and password.

To create a user via the API:

```bash theme={null}
POST /me/identity/user
```

```json theme={null}
{
  "login": "john.doe",
  "email": "john.doe@example.com",
  "password": "<secure-password>",
  "description": "DevOps engineer"
}
```

The user's URN for use in policies takes the form:

```text theme={null}
urn:v1:eu:identity:user:xx1111-ovh/john.doe
```

You can also organise users into **user groups** to simplify policy management:

```bash theme={null}
POST /me/identity/group
```

```json theme={null}
{
  "name": "devops-team",
  "description": "DevOps engineers",
  "role": "REGULAR"
}
```

A group's URN: `urn:v1:eu:identity:group:xx1111-ovh/devops-team`

## Creating your first IAM policy

<Steps>
  <Step title="Open the IAM section">
    Go to [IAM Policies](https://www.ovh.com/manager/#/iam/policies) in the OVHcloud Control Panel. Click **Create a policy**.
  </Step>

  <Step title="Name the policy">
    Enter a unique name for the policy (no spaces allowed). Add an optional description to explain its purpose.
  </Step>

  <Step title="Select identities">
    Choose the users, groups, or service accounts this policy applies to. You can mix identity types in a single policy.
  </Step>

  <Step title="Select product types and resources">
    Choose the product type (e.g. **VPS**) and then select the specific resources to target. You can also use resource groups to target multiple resources at once.
  </Step>

  <Step title="Define actions">
    Choose how to define permissions. You have four options:

    * **Authorise all actions** — grant all current and future actions for the selected products
    * **Permission groups** — use OVHcloud-managed groups like `globalAdmin` or product-specific read/write groups
    * **Add actions manually** — type action names with optional wildcards (e.g. `vps:apiovh:ips/*`)
    * **Select from list** — browse available actions by category (Read, Create, Edit, Delete, Operate)
  </Step>

  <Step title="Save the policy">
    Click **Create** to activate the policy immediately.
  </Step>
</Steps>

<Warning>
  Be careful not to remove all policies that grant access to IAM itself. If you lose the ability to modify policies, you cannot restore access without contacting OVHcloud support. Always test restrictive policies on non-production users before applying them broadly.
</Warning>

## Creating IAM policies via the API

You can also create policies programmatically using the v2 IAM API:

```bash theme={null}
POST /iam/policy
```

```json theme={null}
{
  "name": "vps-all-but-delete-snapshot",
  "description": "Full VPS access except snapshot deletion",
  "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" }
    ]
  }
}
```

The `except` list narrows down a wildcard allow without creating a hard deny. A hard `deny` takes precedence over any `allow`, even in other policies.

To list all existing policies:

```bash theme={null}
GET /iam/policy
```

To update or delete a policy:

```bash theme={null}
PUT  /iam/policy/{policyId}
DELETE /iam/policy/{policyId}
```

### Policy conditions

You can add conditions to make a policy valid only when specific criteria are met — for example, restricting access to business hours or a specific IP range:

```json theme={null}
{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "operator": "MATCH",
        "values": {
          "request.IP.IN_RANGE": "10.23.0.0/16"
        }
      },
      {
        "operator": "NOT",
        "conditions": [
          {
            "operator": "MATCH",
            "values": {
              "date(Europe/Paris).WeekDay.IN": "Saturday,Sunday"
            }
          }
        ]
      }
    ]
  }
}
```

This example allows access only from a specific IP range and only on weekdays (Paris time).

## OVHcloud-managed permission groups

OVHcloud provides predefined permission groups that you can use in policies instead of listing individual actions. These groups are maintained by OVHcloud and automatically include new actions as products evolve.

Common permission groups:

| Group URN                                       | Description                          |
| ----------------------------------------------- | ------------------------------------ |
| `urn:v1:eu:permissionsGroup:ovh:globalAdmin`    | Full access to all OVHcloud products |
| `urn:v1:eu:permissionsGroup:ovh:globalReadOnly` | Read-only access to all products     |

To list all available permission groups:

```bash theme={null}
GET /iam/permissionsGroup
```

To use a permission group in a policy:

```json theme={null}
{
  "name": "readonly-all",
  "identities": ["urn:v1:eu:identity:user:xx1111-ovh/auditor"],
  "resources": [{ "urn": "urn:v1:eu:resource:account:xx1111-ovh" }],
  "permissions": { "allow": [] },
  "permissionsGroups": [
    { "urn": "urn:v1:eu:permissionsGroup:ovh:globalReadOnly" }
  ]
}
```

## Service accounts

Service accounts are machine identities for automated processes. They authenticate via OAuth2 client credentials and have no time-limited tokens tied to a user session.

### Creating a service account

```bash theme={null}
POST /me/api/oauth2/client
```

```json theme={null}
{
  "callbackUrls": [],
  "flow": "CLIENT_CREDENTIALS",
  "name": "terraform-provisioner",
  "description": "Used in CI/CD pipeline to provision infrastructure"
}
```

The response contains a `clientId` and `clientSecret`. Save the `clientSecret` immediately — it cannot be retrieved again.

Retrieve the service account's IAM URN:

```bash theme={null}
GET /me/api/oauth2/client/{clientId}
```

The `identity` field returns a URN like:

```text theme={null}
urn:v1:eu:identity:credential:xx11111-ovh/oauth2-0f0f0f0f0f0f0f0f
```

Use this URN as an identity in an IAM policy to grant the service account specific rights. See [OVHcloud API — Service accounts and OAuth2](/manage/api#service-accounts-and-oauth2) for the full authentication flow.

### Example: attach a policy to a service account

```json theme={null}
{
  "name": "service-account-vps-mgmt",
  "description": "Allow automation script to manage VPS",
  "identities": [
    "urn:v1:eu:identity:credential:xx11111-ovh/oauth2-0f0f0f0f0f0f0f0f"
  ],
  "resources": [
    { "urn": "urn:v1:eu:resource:vps:*" }
  ],
  "permissions": {
    "allow": [
      { "action": "vps:apiovh:*" }
    ]
  }
}
```

## SSO federation

If your organisation uses a central identity provider (IdP), you can federate it with OVHcloud so that your team logs in with their existing corporate credentials. Federated users are managed as user groups in OVHcloud IAM.

<AccordionGroup>
  <Accordion title="Microsoft Active Directory (ADFS)">
    OVHcloud supports SAML 2.0 federation with Active Directory Federation Services (ADFS).

    To configure federation:

    1. In the OVHcloud Control Panel, go to **Identity, Security & Operations** > **Identities** > **SSO**.
    2. Download the OVHcloud service provider metadata XML.
    3. In ADFS, create a Relying Party Trust using the OVHcloud metadata.
    4. Configure claim rules to pass the user's group membership in the SAML assertion.
    5. In OVHcloud, upload the ADFS IdP metadata and map ADFS group names to OVHcloud user groups.

    Refer to the [ADFS federation guide](https://help.ovhcloud.com/csm/en-gb-account-connect-saml-adfs) for step-by-step instructions.
  </Accordion>

  <Accordion title="Azure Active Directory">
    OVHcloud supports SAML 2.0 federation with Azure AD (now Microsoft Entra ID).

    To configure federation:

    1. In the Azure portal, create an Enterprise Application.
    2. Configure the SAML single sign-on settings using OVHcloud's entity ID and reply URL.
    3. Add group claims to the SAML token.
    4. In OVHcloud, add the Azure AD IdP metadata and map Azure AD groups to OVHcloud user groups.

    Refer to the [Azure AD federation guide](https://help.ovhcloud.com/csm/en-gb-account-connect-saml-azure-ad) for step-by-step instructions.
  </Accordion>

  <Accordion title="Google Workspace">
    OVHcloud supports SAML 2.0 federation with Google Workspace.

    To configure federation:

    1. In the Google Admin console, create a custom SAML application for OVHcloud.
    2. Configure the ACS URL and Entity ID with OVHcloud values.
    3. Map user attributes (including groups) to SAML attributes.
    4. In OVHcloud, upload the Google IdP metadata and map Google groups to OVHcloud user groups.

    Refer to the [Google Workspace federation guide](https://help.ovhcloud.com/csm/en-gb-account-connect-saml-google-workspace) for step-by-step instructions.
  </Accordion>

  <Accordion title="Okta">
    OVHcloud supports SAML 2.0 federation with Okta.

    To configure federation:

    1. In Okta, create a new SAML 2.0 application.
    2. Set the Single Sign-On URL and Audience URI using OVHcloud values.
    3. Configure group attribute statements to pass Okta group membership.
    4. In OVHcloud, upload the Okta IdP metadata and map Okta groups to OVHcloud user groups.

    Refer to the [Okta federation guide](https://help.ovhcloud.com/csm/en-gb-account-connect-saml-okta) for step-by-step instructions.
  </Accordion>
</AccordionGroup>

<Tip>
  When federation is active, IAM policies that target groups apply to federated users automatically as long as the group names match. You do not need to manage individual federated users in OVHcloud.
</Tip>

## Enabling IAM logs forwarding

You can forward IAM-related events to [Logs Data Platform](/manage/observability) for auditing, security monitoring, and compliance. There are three categories of account logs available:

| Log type               | API endpoint                           | Content                                                       |
| ---------------------- | -------------------------------------- | ------------------------------------------------------------- |
| **Audit logs**         | `POST /me/logs/audit/log/subscription` | Login events, password changes, MFA activity                  |
| **Activity logs**      | `POST /me/api/log/subscription`        | All API calls and Control Panel actions                       |
| **Access policy logs** | `POST /iam/log/subscription`           | IAM policy evaluations — which actions were allowed or denied |

To enable access policy log forwarding to a Logs Data Platform stream:

```bash theme={null}
POST /iam/log/subscription
```

```json theme={null}
{
  "streamId": "ab51887e-0b98-4752-a514-f2513523a5cd",
  "kind": "default"
}
```

Replace `streamId` with the ID of your target LDP data stream. You can find this in the OVHcloud Control Panel under **Logs Data Platform** > **Data streams** > **Copy stream ID**.

Once enabled, you can query IAM access policy logs in Graylog. To find all denied actions for a specific user:

```text theme={null}
identities_array:*john.doe* AND unauthorized_actions_array:*
```

See [Observability & Monitoring](/manage/observability) for how to set up your first log stream.

## Troubleshooting IAM policies

### A user gets a 403 Forbidden error

When an API call is denied by IAM, the HTTP 403 response includes the name of the missing action:

```json theme={null}
{
  "class": "Client::Forbidden",
  "message": "User not granted for this request",
  "details": {
    "unauthorizedActionsByAuthentication": "",
    "unauthorizedActionsByIAM": "vps:apiovh:reboot"
  }
}
```

Copy the action name from `unauthorizedActionsByIAM` and add it to the relevant IAM policy.

If you are troubleshooting a 403 that occurs in the Control Panel rather than via API, open your browser's developer tools, go to the **Network** tab, and look for requests returning a `403` status. Inspect the response body to find `unauthorizedActionsByIAM`.

### Finding missing actions via logs

If you have enabled IAM log forwarding, you can search Graylog for all unauthorized action attempts by a user:

```text theme={null}
identities_array:*<username>* AND unauthorized_actions_array:*
```

The results show exactly which actions the user attempted and which were denied, making it straightforward to update the policy.

### Common mistakes

| Problem                                           | Cause                                                   | Fix                                                                             |
| ------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Policy exists but user is still denied            | Policy targets a different resource URN or identity URN | Verify URNs in `GET /iam/policy/{id}`                                           |
| Wildcard `*` action does not cover a new API call | New product API introduced after policy creation        | Use `permissionsGroups` instead of manual wildcards                             |
| Service account token rejected                    | Service account's IAM policy was deleted or modified    | Check `GET /iam/policy` and re-attach the policy                                |
| Federated user cannot log in                      | Group mapping not configured                            | Verify group attribute is included in the SAML assertion and mapped in OVHcloud |

<Warning>
  Do not delete the default OVHcloud policy (`ovh-default`). This read-only policy grants your root account full access and is required for account management. If you accidentally create a policy that blocks your own access, contact OVHcloud support.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="OVHcloud API" icon="code" href="/manage/api">
    Create API credentials and service accounts to use with your IAM policies.
  </Card>

  <Card title="Observability & Monitoring" icon="chart-line" href="/manage/observability">
    Forward IAM audit logs to Logs Data Platform for security monitoring.
  </Card>
</CardGroup>